Merge pull request #523 from mapswipe/update_docu

Draft: Documentation update

Author: ElJocho

docs/source/_static/img/ChangeDetection_screenshot.jpeg

@@ -1,10 +1,10 @@
 # Command Line Interface
 
-THIS DOCUMENT IS OUTDATED: Please use the `--help` flag of the CLI.
+The Mapswipe Backend provides a Command Line Interface(CLI) with which the users can interact with the program.
+They can be used for example to create projects, which were uploaded to the [manager-dashboard](for_mapswipe_managers.html),
+or to export statistics on the finished projects. To get a comprehensible lists of the available commands use the ```--help``` flag.
 
----
-
-This document describes how to use the command line interface of MapSwipe Worker.
+```mapswipe_workers --help``` would get you all possible commands, while e.g. ```mapswipe_workers archive --help``` would get you additional information on how to use that command.
 
 In our current deployment setup the commands of the MapSwipe Workers CLI are hard-coded in the Docker-Compose File.
 
@@ -13,148 +13,3 @@ You can run these commands also using docker-compose:
 ```
 docker-compose run mapswipe_workers mapswipe_workers --help
 ```
-
-
-```
-Usage: mapswipe_workers [OPTIONS] COMMAND [ARGS]...
-
-Options:
-  -v, --verbose
-  --version      Show the version and exit.
-  --help         Show this message and exit.
-
-Commands:
-  create-projects
-  create-tutorial
-  firebase-to-postgres
-  generate-stats
-  run
-  user-management
-```
-
-
-## Create projects from submitted project drafts
-
-```
-Usage: mapswipe_workers create-projects [OPTIONS]
-
-Options:
-  -s, --schedule [m|h|d]  Will create projects every 10 minutes (m), every
-                          hour (h) or every day (d).
-  --help                  Show this message and exit.
-```
-
-
-## Transfer data from Firebase to Postgres
-
-```
-Usage: mapswipe_workers firebase-to-postgres [OPTIONS]
-
-Options:
-  -s, --schedule [m|h|d]  Will update and transfer relevant data (i.a. users
-                          and results) from Firebase into Postgres every 10
-                          minutes (m), every hour (h) or every day (d).
-  --help                  Show this message and exit.
-```
-
-
-## Generate Statistics
-
-```
-Usage: mapswipe_workers generate-stats [OPTIONS]
-
-Options:
-  -s, --schedule [m|h|d]  Generate stats every 10 minutes (m), every hour (h)
-                          or every day (d).
-  --project_id_list TEXT  provide project id strings as a list stats will be
-                          generated only for these projects.
-                          Use it like '["project_a", "project_b"]'
-  --help                  Show this message and exit.
-```
-
-## Generate Statistics for all projects
-
-Ideally you run this using a separate docker container. e.g. like this:
-
-```
-docker-compose run mapswipe_workers mapswipe_workers generate-stats-all-projects
-```
-
-```
-Usage: mapswipe_workers generate-stats-all-projects [OPTIONS]
-
-Options:
-  -s, --schedule [m|h|d]  Generate stats every 10 minutes (m), every hour (h)
-                          or every day (d).
-  --help                  Show this message and exit.
-```
-
-## User Management
-
-```
-Usage: mapswipe_workers user-management [OPTIONS]
-
-Options:
-  --email TEXT       The email of the MapSwipe user.  [required]
-  --manager BOOLEAN  Set option to grant or remove project manager
-                     credentials. Use true to grant credentials. Use false to
-                     remove credentials.
-  --help             Show this message and exit.
-```
-
-## Archive Projects
-
-```
-Usage: mapswipe_workers archive [OPTIONS]
-
-  Archive projects in Postgres. Delete groups, tasks and results from
-  Firebase.
-
-Options:
-  -i, --project-id TEXT  Archive project with giving project id
-  --project-ids TEXT     Archive multiple projects. Provide project id strings
-                         as a list: '["project_a", "project_b"]'
-
-  --help                 Show this message and exit.
-
-```
-
-You can get the project ids for the projects to be archive either from the manager dashboard or query directly in postgres. For example:
-
-```
-SELECT project_id
-FROM projects
-WHERE status = 'finished' AND created < '2020-09-01'
-```
-
-## Delete Projects
-
-```
-Usage: mapswipe_workers delete [OPTIONS]
-
-  Delete tasks, groups, project and results.
-
-Options:
-  -i, --project-id TEXT  Delete project with giving project id
-  --project-ids TEXT     Delete multiple projects. Provide project id strings
-                         as a list: '["project_a", "project_b"]'
-
-  --help                 Show this message and exit.
-```
-
-
-## Create Tutorial from json file (e.g. provided in sample data)
-
-```
-Usage: mapswipe_workers create-tutorial [OPTIONS]
-
-Options:
-  --input_file TEXT  The json file with your tutorial information.  [required]
-  --help             Show this message and exit.
-
-```
-
-## Run a script which requires mapswipe_workers library
-```
-docker-compose run mapswipe_workers python3 python_scripts/add_project_geometries_to_api.py
-```

docs/source/_static/img/footprint_screenshot.jpeg

@@ -13,15 +13,24 @@ In following chapters configuration values and keys are discussed for each part
 All configuration values for MapSwipe Workers are stored in environment variables.
 
 Required environment variables are:
+### Firebase
 - FIREBASE_API_KEY
 - FIREBASE_DB
+- FIREBASE_TOKEN
+- GOOGLE_APPLICATION_CREDENTIALS
+
+### Postgres DB
 - POSTGRES_DB
 - POSTGRES_HOST
 - POSTGRES_PASSWORD
 - POSTGRES_PORT
 - POSTGRES_USER
 
-Optional environment variables are:
+### OSMCha
+
+- OSMCHA_API_KEY
+
+### Optional environment variables:
 - SLACK_CHANNEL
 - SLACK_TOKEN
 - SENTRY_DSN
@@ -34,19 +43,16 @@ For satellite imagery access to at least one provider is needed. Define the API
 - IMAGE_ESRI_API_KEY
 - IMAGE_ESRI_BETA_API_KEY
 
-In addition to get access to Firebase a Service Account Key is required.
-The path the Service Account Key is defined in:
-- GOOGLE_APPLICATION_CREDENTIALS
-
 > Notes: When deploying using `docker` or `docker-compose` `POSTGRES_HOST` should have the value `postgres` and the Service Account Key (`serviceAccountKey.json`) should be copied to `mapswipe_workers/serviceAccountKey.json` so that during the build of the image the file can by copied by Docker.
 
-
 ### Elaboration
 
 **Firebase**: MapSwipe Workers use the Firebase Python SDK and the Firebase REST API. Both require the database name (`FIREBASE_DB`) and the API-Key from the Firebase instance. The Firebase Python SDK does also need a Service Account Key. The path to this file is set in the `GOOGLE_APPLICATION_CREDENTIALS` environment variable.
 
 **Postgres**: MapSwipe Workers writes data to a Postgres database and generate files for the API based data in Postgres.
 
+**OSMCha**: MapSwipe Workers enriches some Projects with data from OSM changelogs which are requested from OSMCha. Create an account, you will find you api key in your profile e.g. `Token 589adf125234a`
+
 **Sentry (optional)**: MapSwipe workers use sentry to capture exceptions. You can find your project’s DSN in the “Client Keys” section of your “Project Settings” in Sentry. Check [Sentry's documentation](https://docs.sentry.io/error-reporting/configuration/?platform=python) for more information.
 
 **Slack (optional)**: The MapSwipe workers send messages to slack when a project has been created successfully, the project creation failed or an exception gets raised. refer to [Python slackclient's documentation](https://github.com/slackapi/python-slackclient) how to get a Slack Token.
@@ -80,13 +86,26 @@ The Service Account Key (`serviceAccountKey.json`) should be saved to `postgres/
 
 ## Manager Dashboard
 
+Please refer to the official [documentation](https://firebase.google.com/docs/web/learn-more#config-object) if you set up your own firebase. 
+Otherwise you can request guidance on the settings from the mapswipe team. The structure of your app.js should look like below.
+
 `manager_dashboard/manager_dashboard/js/app.js`
 
 ```
-TODO
+// Your web app's Firebase configuration
+var firebaseConfig = {
+    apiKey: "",
+    authDomain: "",
+    databaseURL: "",
+    projectId: "",
+    storageBucket: "",
+    messagingSenderId: "",
+    appId: ""
+};
+// Initialize Firebase
+firebase.initializeApp(firebaseConfig);
 ```
 
-
 ## NGINX
 
 `nginx/nginx.conf`:

docs/source/cli.md

@@ -31,7 +31,7 @@ Attributes:
 
 
 ## Aggregated Results
-This gives you the unfiltered MapSwipe results. This is most suited if you want to apply some custom data processing with the MapSwipe data, e.g. select only specific tasks for machine learning. If you want to use MapSwipe data in the Tasking Manager you might look for the data explained below.
+This gives you the unfiltered MapSwipe results. This is most suited if you want to apply some custom data processing with the MapSwipe data, e.g. select only specific tasks for machine learning. If you want to use MapSwipe data in the Tasking Manager you might look for the data described below.
 
 Files:
 - `aggregated_results_{project_id}.csv`, e.g. [agg\_results\_-M56eeMCZ5VeOHjJN4Bx.csv](https://apps.mapswipe.org/api/agg_results/agg_results_-M56eeMCZ5VeOHjJN4Bx.csv)
@@ -51,11 +51,13 @@ Files:
 | 2_share | float | 2_count divived by total_count. This gives you the share of all users who marked as 2. |
 | 3_share | float | 3_count divived by total_count. This gives you the share of all users who marked as 3. |
 | agreement | float | This is defined as [Scott's Pi](https://en.wikipedia.org/wiki/Scott%27s_Pi) and gives you an understanding of inter-rater reliability. The value is 1.0 if all users agree, e.g. all users classify as "building". If users disagree this value will be lower. |
- | geom | string | The geometry of this task as WKT geometry. |
+| geom | string | The geometry of this task as WKT geometry. |
 
+Additionally, project type specific data can be found here. E.g. footprint projects which were created based on OSM data, will have data describing the original OSM object included.
 
- ## HOT Tasking Manager Geometries
- This gives you filtered MapSwipe data ready to be imported to the HOT Tasking Manager. Currently, the geometries in this dataset consist of maximum 15 MapSwipe Tasks, where at least 35% of all users indicated the presence of a building by classifying as "yes" or "maybe". 
+
+## HOT Tasking Manager Geometries
+This gives you filtered MapSwipe data ready to be imported to the HOT Tasking Manager. Currently, the geometries in this dataset consist of maximum 15 MapSwipe Tasks, where at least 35% of all users indicated the presence of a building by classifying as "yes" or "maybe". 
 
  Files:
  - `hot_tm_{project_id}.geojson`, e.g. [hot\_tm\_-M56eeMCZ5VeOHjJN4Bx.geojson](https://apps.mapswipe.org/api/hot_tm/hot_tm_-M56eeMCZ5VeOHjJN4Bx.geojson)
@@ -67,4 +69,15 @@ Files:
 
 <img src="_static/img/tasking_manager_geometries_example.png" width="600px">
 
- 
+## Users
+
+This gives you data on the users which contributed to a project.
+
+| Name                      | Type    | Description                                                                                                                                                      |
+|---------------------------|---------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| idx                       | integer | -                                                                                                                                                                |
+| groups_completed          | integer | Number of groups completed                                                                                                                                       |
+| total_contributions       | integer | Number of tasks completed                                                                                                                                        |
+| agreeing_contributions    | integer | Tasks with the same result as the final result (e.g. Tile has buildings).                                                                                        |
+| disagreeing_contributions | integer | Tasks with other result as the final result.                                                                                                                     |
+| simple_agreement_score    | float   | Share of tasks which had the same result as the final result. E.g. 0.8 would mean that the user labeled 80% of the tiles the same way as the majority of voters. |