Merge branch 'documentation' into 'master'

docs: adding open source documentation and readme file for better outside communication

See merge request !12

CODE_OF_CONDUCT.md

+# Code of Conducts
+
+The goal is to maintain a diverse community that's pleasant for everyone. That's why we would greatly appreciate it if everyone contributing to and interacting with the community also followed this Code of Conduct.
+
+The Code of Conduct covers our behavior as members of the community, in any forum, mailing list, wiki, website, Internet relay chat (IRC), public meeting or private correspondence.
+
+_Our Code of Conduct is heavily based on the [Celery Code of Conduct](https://github.com/celery/celery/blob/master/CONTRIBUTING.rst#community-code-of-conduct)_.
+
+## Be considerate
+Your work will be used by other people, and you in turn will depend on the work of others. Any decision you take will affect users and colleagues, and we expect you to take those consequences into account when making decisions. Even if it's not obvious at the time, our contributions to PROVEE will impact the work of others. For example, changes to code, infrastructure, policy, documentation and translations during a release may negatively impact others' work.
+
+## Be respectful
+The PROVEE community and its members treat one another with respect. Everyone can make a valuable contribution to PROVEE. We may not always agree, but disagreement is no excuse for poor behavior and poor manners. We might all experience some frustration now and then, but we cannot allow that frustration to turn into a personal attack. It's important to remember that a community where people feel uncomfortable or threatened isn't a productive one. We expect members of the PROVEE community to be respectful when dealing with other contributors as well as with people outside the PROVEE project and with users of PROVEE.
+
+## Be collaborative
+Collaboration is central to PROVEE and to the larger free software community. We should always be open to collaboration. Your work should be done transparently and patches from PROVEE should be given back to the community when they're made, not just when the distribution releases. If you wish to work on new code for existing upstream projects, at least keep those projects informed of your ideas and progress. It many not be possible to get consensus from upstream, or even from your colleagues about the correct implementation for an idea, so don't feel obliged to have that agreement before you begin, but at least keep the outside world informed of your work, and publish your work in a way that allows outsiders to test, discuss, and contribute to your efforts.
+
+## When you disagree, consult others
+Disagreements, both political and technical, happen all the time and the PROVEE community is no exception. It's important that we resolve disagreements and differing views constructively and with the help of the community and community process. If you really want to go a different way, then we encourage you to make a derivative distribution or alternate set of packages that still build on the work we've done to utilize as common of a core as possible.
+
+## When you're unsure, ask for help
+Nobody knows everything, and nobody is expected to be perfect. Asking questions avoids many problems down the road, and so questions are encouraged. Those who are asked questions should be responsive and helpful. However, when asking a question, care must be taken to do so in an appropriate forum.
+
+##  Step down considerately
+Developers on every project come and go and PROVEE is no different. When you leave or disengage from the project, in whole or in part, we ask that you do so in a way that minimizes disruption to the project. This means you should tell people you're leaving and take the proper steps to ensure that others can pick up where you left off.

COMPARISON.md

+# Comparison
+
+As mentioned before, PROVEE is a user-friendly system for 2D embedding projections. 
+
+However, PROVEE is not the only library that aims to visualize embeddings. To build the optimal embedding projector we have looked at existing tools and examined what worked well using these tools. But most importantly: what was missing? Other's mistakes can be a fruitful sources of information. Mistakes can only imPROVEE our library!
+
+There are several libraries and tools that try to visualize embeddings, but there are only a few tools where visualization of embeddings is the main purpose. 
+
+The most important libraries/tools we have looked at to create PROVEE:
+- Vec2graph
+- Tensorflow Embedding Projector
+- Whatlies 
+- Parallax 
+
+Libraries and tools were examined for their scalability, user-friendliness, responsiveness and advantages and disadvantages. We were also interested in their back-end and data storage and transfer.
+
+##### Vec2graph
+Vec2graph is a library by [Katricheva et al.(2020)][vec2graph]  for visualizing word embeddings as graphs. The 2D graph is created based on cosine similarity between points and between neighbours. Graphs can contain nodes that link to other graphs and are displayed using an .html file. Vec2graph shines in the ease of use, but the projections are not suited to display many data points at once. 
+ 
+##### Whatlies
+[Whatlies][df1] is a project developed by Rasa. The goal of the project is to create an API that supports many languages, such as SpaCy, Gensim and FastText to display word or sentence embeddings. Whatlies enables users to easily display data in interactive 2D graphs. The axes can be defined by dimension reduction methods, such as PCA or UMAP, but also special queries. For instance, 'man' can be the y-axis and 'woman' can be the x-axis. The special thing about Whatlies is the support for vector arithmetic on embeddings, which can be visualized directly in the interactive plots. It has a high scalability of the input, but the overall goal is to visualize smaller groups of words. The drawback is that the library depends on a lot of backends, which can be problematic when packages get updated. Furthermore, the tool requires little programming knowledge, but has a clear documentation on their Github.io page.
+
+##### Tensorflow Embedding Projector
+The [Embedding Projector][tens] is part of the Tensorboard. It can graphically represent embeddings in a 2D or 3D space. These embeddings can be anything, as long as they can be converted to a tab separated file. The tool has a high scalability and is suited to display many data points at once. The user can interactively explore the embedding space, varying many parameters, easily switching from PCA to UMAP, 2D to 3D. A disadvantage of the tool is the limitation of dimensionality reduction methods as preprocessing method to display the data points. 
+
+##### Parallax
+Last but not least, there is [Parallax][par]. Parallax is a tool to display word embedding spaces, suited for many embeddings with high dimensions. The tool is suited to display many data points at once. Most interesting is the article accompanying the tool of [Molino et al. (2019)][parallax]. The axes can be obtained using PCA or t-SNE, but they propose a Cartesian approach to the specification of the axes: axes that are the result of algebraic formulas on these vectors. This results in axes that can be the average of two words or the most frequently occuring word in the data set. The major drawback of the tool is the slow loading and reaction time when using >10.000 points. Another difficulty of the tool is the required programming exprience. Some knowledge of programming is required. 
+
+## PROVEE
+
+Our current project PROVEE tries to overcome all the major drawbacks of the studied tools, by designing a user-friendly, responsive tool, suitable for many embeddings with high dimensionality. The embeddings can be anything. Not only word embeddings, but image embeddings, DNA embeddings, sentence embeddigns, you name it. Programming experience is not required, which makes the tool easy to use. 
+
+
+
+[//]: # (These are reference links used in the body of this note and get stripped out when the markdown processor does its job)
+
+   [parallax]: <https://arxiv.org/abs/1905.12099>
+   [tens]: <https://projector.tensorflow.org/>
+   [par]: <https://github.com/uber-research/parallax>
+   [df1]: <https://rasahq.github.io/whatlies/>
+   [vec2graph]: <https://link.springer.com/chapter/10.1007/978-3-030-39575-9_20>
+

CONTRIBUTING.md

+# Introduction
+
+First off, thank you for considering contributing to Provee! Most likely that means that you came across some limitations of other systems or you 
+just want to play around with the coolest newest technology (like we do 😎). 
+
+### BUT why should I read this!??!
+
+Our contribution guidelines helps to communicate that you respect the time of the developers managing and developing this open source project. In return, they should reciprocate that respect in addressing your issue, assessing changes, and helping you finalize your pull requests.
+
+
+### Which kind of contributions we are searching for.
+
+PROVEE is an open source project with academic background. We love to receive contributions from our community — you! Generally, all contributions are more than welcome. Ideas for non-conventional contributions can be writing tutorials or blog posts, improving the documentation, submitting bug reports and feature requests or writing code which can be incorporated into Provee itself.
+
+
+<!-- ### Explain contributions you are NOT looking for (if any).
+
+Again, defining this up front means less work for you. If someone ignores your guide and submits something you don’t want, you can simply close it and point to your policy.
+
+> Please, don't use the issue tracker for [support questions]. Check whether the #pocoo IRC channel on Freenode can help with your issue. If your problem is not strictly Werkzeug or Flask specific, #python is generally more active. Stack Overflow is also worth considering.
+
+[source: [Flask](https://github.com/pallets/flask/blob/master/CONTRIBUTING.rst)] **Need more inspiration?** [1] [cucumber-ruby](https://github.com/cucumber/cucumber-ruby/blob/master/CONTRIBUTING.md#about-to-create-a-new-github-issue) [2] [Read the Docs](http://read-the-docs.readthedocs.org/en/latest/open-source-philosophy.html#unsupported) -->
+
+# Code of Conducts
+
+Please find our Code of Conduct here. We that this serious! [Code of Conduct for more fun and happiness in PROVEE](../CODE_OF_CONDUCT.md)
+
+
+# Your First Contribution
+
+> Unsure where to begin contributing to Atom? You can start by looking through `beginner` and `help-wanted` issues:
+
+```
+Beginner issues - issues which should only require a few lines of code, and a test or two.
+Help wanted issues - issues which should be a bit more involved than beginner issues.
+```
+
+Issue lists can be sorted by total number of comments. While not perfect, number of comments is a reasonable proxy for impact a given change will have.
+
+
+### Never contributed to open source before? No problemo
+Here are a couple of friendly tutorials: http://makeapullrequest.com/ and http://www.firsttimersonly.com/ or use this *free* series, [How to Contribute to an Open Source Project on GitHub](https://egghead.io/series/how-to-contribute-to-an-open-source-project-on-github).
+
+At this point, you're ready to make your changes! Feel free to ask for help; everyone is a beginner at first :smile_cat:
+If a maintainer asks you to `rebase` your PR, they're saying that a lot of code has changed, and that you need to update your branch so it's easier to merge.
+
+# Getting started
+For something that is bigger than a one or two line fix:
+
+1. Create your own fork of the code
+2. Do the changes in your fork
+3. If you like the change and think the project could use it:
+    * Be sure you have followed the code style for the project.
+    <!-- * Sign the Contributor License Agreement, CLA, with the jQuery Foundation. -->
+    * Note the Provee Code of Conduct.
+    * Send a pull request.
+
+<!-- [source: [Requirejs](http://requirejs.org/docs/contributing.html)] **Need more inspiration?** [1] [Active Admin](https://github.com/activeadmin/activeadmin/blob/master/CONTRIBUTING.md#1-where-do-i-go-from-here) [2] [Node.js](https://github.com/nodejs/node/blob/master/CONTRIBUTING.md#code-contributions) [3] [Ember.js](https://github.com/emberjs/ember.js/blob/master/CONTRIBUTING.md#pull-requests) -->
+
+Small contributions such as fixing spelling errors, where the content is small enough to not be considered intellectual property, can be submitted by a contributor as a patch.  
+As a rule of thumb, changes are obvious fixes if they do not introduce any new functionality or creative thinking. As long as the change does not affect functionality, some likely examples include the following:
+* Spelling / grammar fixes
+* Typo correction, white space and formatting changes
+* Comment clean up
+* Bug fixes that change default return values or error codes stored in constants
+* Adding logging messages or debugging output
+* Changes to ‘metadata’ files like Gemfile, .gitignore, build scripts, etc.
+* Moving source files from one directory or package to another
+
+
+# Code, commit message and labeling conventions
+These sections should streamline the contributions you make to PROVEE.
+
+## Preferred style for code.
+
+TDB
+
+## Commit message conventions.
+
+We are using semantic versioning [semver](semver.org) and particularly [semantic-release](https://github.com/semantic-release/semantic-release#readme) in this project. Release Notes and Changelogs are automatically generated. It is important that you obey the [Angular Commit Message Conventions](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#-git-commit-guidelines)
+
+```
+<type>(<scope>): <subject>
+<BLANK LINE>
+<body>
+<BLANK LINE>
+<footer>
+```
+**Type** must be one of the following:
+
+- feat: A new feature
+- fix: A bug fix
+- docs: Documentation only changes
+- style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
+- refactor: A code change that neither fixes a bug nor adds a feature
+- perf: A code change that improves performance
+- test: Adding missing or correcting existing tests
+- chore: Changes to the build process or auxiliary tools and libraries such as documentation generation
+
+
+## Labeling conventions for issues.
+
+We try to follow the [StandardIssueLabels](https://github.com/wagenet/StandardIssueLabels#standardissuelabels) for open source projects
+
+# How to report a bug
+### Security FIRST!
+Any security issues should be submitted directly to m.behrisch at uu.nl  
+In order to determine whether you are dealing with a security issue, ask yourself these two questions:
+ * Can I access something that's not mine, or something I shouldn't have access to?
+ * Can I disable something for other people?
+
+If the answer to either of those two questions are "yes", then you're probably dealing with a security issue. Note that even if you answer "no" to both questions, you may still be dealing with a security issue, so if you're unsure, just email us at m.behrisch at uu.nl.
+
+### How to file a bug report.
+When filing an issue, make sure to answer these five questions:
+
+1. What version of PROVEE are you using (VERSION.txt file)?
+2. What operating system and browser are you using?
+3. What did you do?
+4. What did you expect to see?
+5. What did you see instead?
+General questions should go to the provee mailing list instead of the issue tracker. The provee-community will directly answer or ask you to file an issue if you've tripped over a bug.
+
+# How to suggest a feature or enhancement
+If you find yourself wishing for a feature that doesn't exist in PROVEE, you are probably not alone. There are bound to be others out there with similar needs. Many of the features that PROVEE has today have been added because our users saw the need. Open an issue on our issues list on GitLAB which describes the feature you would like to see, why you need it, and how it should work.
+
+# Code review process
+
+The core team looks at Pull Requests on a regular basis in a weekly triage meeting that we hold in a public Teams meeting (link in the [README](../README.md) under contributing).  
+After feedback has been given we expect responses within two weeks. After two weeks we may close the pull request if it isn't showing any activity.
+
+<!-- # Community
+
+You can chat with the core team on https://gitter.im/cucumber/cucumber. We try to have office hours on Fridays.
+
+[source: [cucumber-ruby](https://github.com/cucumber/cucumber-ruby/blob/master/CONTRIBUTING.md#talking-with-other-devs)] **Need more inspiration?**
+ [1] [Chef](https://github.com/chef/chef/blob/master/CONTRIBUTING.md#-developer-office-hours) [2] [Cookiecutter](https://github.com/audreyr/cookiecutter#community)
+ -->

DEPLOYMENTGUIDE.md

+<p align="center">
+  <a href="" rel="noopener">
+ <img width=200px height=200px src="https://i.imgur.com/6wj0hh6.jpg" alt="Project logo"></a>
+</p>
+
+<h3 align="center">PROVEE - PROgressiVe Explainable Embeddings</h3>
+
+<div align="center">
+
+
+[![Status](https://img.shields.io/badge/status-active-success.svg)]()
+
+[![GitHub Issues](https://img.shields.io/github/issues/kylelobo/The-Documentation-Compendium.svg)](https://github.com/kylelobo/The-Documentation-Compendium/issues)
+![Gitlab pipeline status](https://img.shields.io/gitlab/pipeline/vig/provee/master?gitlab_url=https%3A%2F%2Fgit.science.uu.nl)
+![Gitlab pipeline status](https://git.science.uu.nl/vig/provee/dummy-vue-grpc/badges/master/pipeline.svg)
+![Gitlab coverage](https://git.science.uu.nl/vig/provee/dummy-vue-grpc/badges/master/coverage.svg)
+
+[![GitHub Issues](https://img.shields.io/github/issues/kylelobo/The-Documentation-Compendium.svg)](https://github.com/kylelobo/The-Documentation-Compendium/issues)
+[![GitHub Pull Requests](https://img.shields.io/github/issues-pr/kylelobo/The-Documentation-Compendium.svg)](https://github.com/kylelobo/The-Documentation-Compendium/pulls)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](/LICENSE)
+
+</div>
+
+---
+
+<p align="center"> 
+
+Deep Neural Networks (DNNs), and their resulting **latent or embedding data spaces, are key to analyzing big data** in various domains such as vision, speech recognition, and natural language processing (NLP). However, embedding spaces are high-dimensional and abstract, thus not directly understandable. We aim to develop a software framework to visually explore and explain how embeddings relate to the actual data fed to the DNN. This enables both DNN developers and end-users to understand the currently black-box working of DNNs, leading to better-engineered networks, and explainable, transparent DNN systems whose behavior can be trusted by their end-users. 
+
+Our central aim is to open DNN black-boxes, making complex data understandable for data science novices, and raising trust/transparency are core topics in VA and NLP research. PROVEE will advertise and apply VA in a wider scope with impact across sciences (medicine, engineering, biology, physics) where researchers use big data and deep learning.
+</p>
+
+## 📝 Table of Contents
+
+- [Deployment Guide](#guide)
+- [Hardware](#hardware)
+- [Software](#software)
+
+## 🧐 Deployment Guide <a name = "guide"></a>
+
+empty for now
+
+
+## 🧰 Hardware Requirements <a name = "hardware"></a>
+
+empty for now
+
+
+## 💾 Software Requirements <a name = "software"></a>
+
+empty for now
\ No newline at end of file

README.md

-# PROVEE
+<p align="center">
+  <a href="" rel="noopener">
+ <img width=200px height=200px src="https://i.imgur.com/6wj0hh6.jpg" alt="Project logo"></a>
+</p>
 
-## Development
+<h3 align="center">PROVEE - PROgressiVe Explainable Embeddings</h3>
 
-Run both [backend](backend/README.md) and [frontend](frontend/README.md).
+<div align="center">
+
+
+[![Status](https://img.shields.io/badge/status-active-success.svg)]()
+
+[![GitHub Issues](https://img.shields.io/github/issues/kylelobo/The-Documentation-Compendium.svg)](https://github.com/kylelobo/The-Documentation-Compendium/issues)
+![Gitlab pipeline status](https://img.shields.io/gitlab/pipeline/vig/provee/master?gitlab_url=https%3A%2F%2Fgit.science.uu.nl)
+![Gitlab pipeline status](https://git.science.uu.nl/vig/provee/dummy-vue-grpc/badges/master/pipeline.svg)
+![Gitlab coverage](https://git.science.uu.nl/vig/provee/dummy-vue-grpc/badges/master/coverage.svg)
+
+[![GitHub Issues](https://img.shields.io/github/issues/kylelobo/The-Documentation-Compendium.svg)](https://github.com/kylelobo/The-Documentation-Compendium/issues)
+[![GitHub Pull Requests](https://img.shields.io/github/issues-pr/kylelobo/The-Documentation-Compendium.svg)](https://github.com/kylelobo/The-Documentation-Compendium/pulls)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](/LICENSE)
+
+</div>
+
+---
+
+<p align="center"> 
+
+Deep Neural Networks (DNNs), and their resulting **latent or embedding data spaces, are key to analyzing big data** in various domains such as vision, speech recognition, and natural language processing (NLP). However, embedding spaces are high-dimensional and abstract, thus not directly understandable. We aim to develop a software framework to visually explore and explain how embeddings relate to the actual data fed to the DNN. This enables both DNN developers and end-users to understand the currently black-box working of DNNs, leading to better-engineered networks, and explainable, transparent DNN systems whose behavior can be trusted by their end-users. 
+
+Our central aim is to open DNN black-boxes, making complex data understandable for data science novices, and raising trust/transparency are core topics in VA and NLP research. PROVEE will advertise and apply VA in a wider scope with impact across sciences (medicine, engineering, biology, physics) where researchers use big data and deep learning.
+</p>
+
+## 📝 Table of Contents
+
+- [About](#about)
+- [Getting Started](#getting_started)
+- [Feature/Performance Comparison](../COMPARISON.md)
+- [Deployment](#deployment)
+- [Usage](#usage)
+- [Built Using](#built_using)
+- [TODO](../TODO.md)
+- [Contributing](../CONTRIBUTING.md)
+- [Authors](#authors)
+- [Acknowledgments](#acknowledgement)
+
+## 🧐 About <a name = "about"></a>
+
+In this repository you will find PROVEE, short for Progressive Explainable Embeddings, a visual-interactive system for representing the embedding data spaces in a user-friendly 2D projection. The idea behind [Progressive Analytics](https://arxiv.org/abs/1607.05162), such as described e.g. by Fekete and Primet, is to provide a rapid data exploration pipeline with a feedback loop from the system to the analyst with a latency below about 10 seconds. Research has shown that when performing exploratory analysis humans need a latency below about 10 seconds to remain focused and use their short-term memory efficiently. Therefore, PROVEE's goals are (1) to provide increasingly meaningful partial results as the algorithms execute, (2) provide visualizations that minimize distractions by not changing views excessively, (3) will provide cues to indicate where new results have been found by analytics, (4) should provide an interface for users to specify where analytics should focus, as well as the portions of the problem space that should be ignored. _Note that these goals are adapted from the aforementioned publication._
+
+PROVEE's architecture includes (1) back-end analysis algorithms (particularly, incremental projection algoritms), (2) intuitive, web-based user interfaces/visualizations and (3) intermediate data storage and transfer. Core to our system is an innovative, progressive analysis workflow targeting a human-algorithm feedback-loop with a latency under ~10 seconds to maintain the user's efficiency during exploration tasks. PROVEE will be scalable to big data; generic (handle data from many application domains); and easy to use (requires no specialist programming from the user). Please also refer to our [Performance and feature comparison](../COMPARISON.md) to available (visualization and analysis) tools 
+
+
+## 🏁 Getting Started <a name = "getting_started"></a>
+
+These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See [deployment](#deployment) for notes on how to deploy the project on a live system.
+
+### Prerequisites
+
+<!-- What things you need to install the software and how to install them. -->
+
+```
+Docker, Kubernetes
+```
+
+### Installing
+
+To install the backend please refer to the [backend README](backend/README.md) and for the frontend to the [frontend README](frontend/README.md).
 
 Generate gRPC service classes whenever [protos](protos/README.md) change.
+
+clone the latest Provee directory from Gitlab
+```
+git clone https://git.science.uu.nl/vig/provee/dummy-vue-grpc
+```
+
+cd to the cloned provee backend directory
+```
+cd dummy-vue-grpc/backend
+```
+
+run docker-compose to start all backend services
+```
+docker-compose up
+```
+
+cd to the cloned provee frontend directory
+```
+cd dummy-vue-grpc/frondent
+```
+
+ensure Node.js and yarn are installed
+
+build the frontend
+
+```
+yarn install
+yarn build
+```
+
+<!-- A step by step series of examples that tell you how to get a development env running.
+
+Say what the step will be
+
+```
+Give the example
+```
+
+And repeat
+
+```
+until finished
+``` 
+End with an example of getting some data out of the system or using it for a little demo.
+-->
+
+## 🔧 Running the tests <a name = "tests"></a>
+
+Explain how to run the automated tests for this system.
+
+### Break down into end to end tests
+
+Explain what these tests test and why
+
+```
+Give an example
+```
+
+### Basic Unit Tests
+
+We use [Jest](https://jestjs.io/) for JavaScript based Unit Tests, 
+
+```
+npm run tests
+```
+
+
+
+## 🎈 Usage <a name="usage"></a>
+
+Notes about how to use the system are TBD, Video coming soon.
+
+## 🚀 Deployment <a name = "deployment"></a>
+
+If you want to deploy a live system refer to the [Deployment Guide](../DEPLOYMENTGUIDE.md).
+
+## ⛏️ Built Using <a name = "built_using"></a>
+
+- [VueJs](https://vuejs.org/) - Web Framework
+- [NodeJs](https://nodejs.org/en/) - Server Environment
+- [PixiJS](https://www.pixijs.com/) - Visualization
+- [D3js](https://www.d3js.org/) - Visualization
+
+## ✍️ Authors <a name = "authors"></a>
+
+- [Michael Behrisch](https://michael.behrisch.info) - Idea & Initial work
+- [Simen van Herpt](https://github.com/IsolatedSushi) - Backend & Infrastructure
+- [Jan Zak](https://zakjan.cz/) - Vis coding
+
+See also the list of [contributors](https://git.science.uu.nl/vig/provee/dummy-vue-grpc/-/graphs/master) who participated in this project.
+
+## 🎉 Acknowledgements <a name = "acknowledgement"></a>
+
+- Hat tip to anyone whose code was used

README_old.md

+# PROVEE
+
+## Development
+
+Run both [backend](backend/README.md) and [frontend](frontend/README.md).
+
+Generate gRPC service classes whenever [protos](protos/README.md) change.