Merge pull request #25 from vagechirkov/pilot-3B

Refactor readme and add checklist before study
LBrinkmann · Mar 28, 2023 · 4417e55 · 4417e55
2 parents 444d427 + 564101b
commit 4417e55
Show file tree

Hide file tree

Showing 3 changed files with 93 additions and 87 deletions.
diff --git a/README.md b/README.md
@@ -1,70 +1,11 @@
 # Reward Network III
 
-## Admin API
-
-### Create a new study
-
-`POST https://rn-iii-backend.eks-test-default.mpg-chm.com/admin/config`
-
-#### Pilot 1A
-
-```json
-
-{
-  "active": true,
-  "redirect_url": "https://app.prolific.co/submissions/complete?cc=<code>",
-  "experiment_type": "rn-iii-pilot-1a",
-  "rewrite_previous_data": false,
-  "n_generations": 1,
-  "n_sessions_first_generation": 10,
-  "n_ai_players": 0,
-  "n_sessions_per_generation": 10,
-  "n_advise_per_session": 5,
-  "n_session_tree_replications": 1,
-  "n_social_learning_trials": 2,
-  "n_individual_trials": 6,
-  "n_demonstration_trials": 2
-}
-
-```
-
-#### Pilot 1B
-
-```json
-
-{
-  "active": true,
-  "redirect_url": "https://app.prolific.co/submissions/complete?cc=<code>",
-  "experiment_type": "rn-iii-pilot-1a",
-  "rewrite_previous_data": false,
-  "n_generations": 2,
-  "n_sessions_first_generation": 10,
-  "n_ai_players": 10,
-  "n_sessions_per_generation": 10,
-  "n_advise_per_session": 5,
-  "n_session_tree_replications": 1,
-  "n_social_learning_trials": 2,
-  "n_individual_trials": 6,
-  "n_demonstration_trials": 2
-}
-
-```
-
-### Get the current study configuration
-
-`GET https://rn-iii-backend.eks-test-default.mpg-chm.com/admin/config`
-
-### Get the current study session tree
-
-`GET https://rn-iii-backend.eks-test-default.mpg-chm.com/progress/`
-
-### Get all results in the database
-
-`GET https://rn-iii-backend.eks-test-default.mpg-chm.com/results/sessions`
-
-### Get results for a specific experiment
+## Deployment
 
-`GET https://rn-iii-backend.eks-test-default.mpg-chm.com/results/sessions?experiment_type=rn-iii-pilot-1a&finished=true`
+- Frontend
+  URL:  [https://rn-iii-frontend.eks-test-default.mpg-chm.com](https://rn-iii-frontend.eks-test-default.mpg-chm.com)
+- Backend
+  URL: [https://rn-iii-backend.eks-test-default.mpg-chm.com](https://rn-iii-backend.eks-test-default.mpg-chm.com)
 
 ## DB models
 
@@ -119,6 +60,13 @@ docker-compose -f docker-compose-dev.yml down --volumes
 
 ```
 
+### Links when the docker-compose-dev.yml is running
+
+- React: http://localhost:9000/
+- Storybook: http://localhost:6006/
+- FastAPI: http://localhost:5000/
+- Swagger UI FastAPI: http://localhost:5000/docs
+
 ### Run pytest
 
 Create the virtual environment in the backend folder:
@@ -172,29 +120,7 @@ docker system prune --volumes --force # clean up unused volumes
 
 ```
 
-### Links for development
-
-- React: http://localhost:9000/
-- Storybook: http://localhost:6006/
-- Swagger UI FastAPI: http://localhost:5000/docs
-
-## Deployment
-
-GitLab repo is available
-at [https://gitlab.gwdg.de/mpib/chm/hci/reward-networks/reward-network-iii](https://gitlab.gwdg.de/mpib/chm/hci/reward-networks/reward-network-iii)
-
-- Frontend
-  URL:  [https://rn-iii-frontend.eks-test-default.mpg-chm.com](https://rn-iii-frontend.eks-test-default.mpg-chm.com)
-- Backend
-  URL: [https://rn-iii-backend.eks-test-default.mpg-chm.com](https://rn-iii-backend.eks-test-default.mpg-chm.com)
-
-### Logs in New Relic
-
-- Frontend pod
-  logs: [https://onenr.io/0vwBm6lgoQp](https://onenr.io/0vwBm6lgoQp)
-- Backend pod logs: [https://onenr.io/0gR7DGq3xjo](https://onenr.io/0gR7DGq3xjo)
-
-### Deployment notes
+## Deployment notes
 
 - Frontend and backend pipelines are triggered by the parent
   pipeline [`.gitlab-ci.yml`](.gitlab-ci.yml).

diff --git a/docs/CHECKLIST-BEFORE-RUNNING-EXPERIMENT.md b/docs/CHECKLIST-BEFORE-RUNNING-EXPERIMENT.md
@@ -0,0 +1,11 @@
+# Checklist before running an experiment
+
+1. Prolific study
+   1. Study URL includes `PROLIFIC_PID` parameter
+   2. Participants from the previous study have been excluded
+   3. Participants are prescreened based on the approval rate
+2. Config is correct and updated on the server ([config docs](../docs/EXPERIMENT-CONFIG.md))
+   1. `redirect_url` is set to the correct value from the Prolific
+   2. ⚠️`rewrite_previous_data` is set to `false` ⚠️
+   3. Check that the study is empty (can be checked here: https://rn-iii-backend.eks-test-default.mpg-chm.com/progress/)
+   4. Optional: Use `GET https://rn-iii-backend.eks-test-default.mpg-chm.com/admin/config` to double-check the config
diff --git a/docs/EXPERIMENT-CONFIG.md b/docs/EXPERIMENT-CONFIG.md
@@ -0,0 +1,69 @@
+# How to configure the experiment settings
+
+There are multiple admin routes that can be used to configure the experiment. It is most convenient to use Postman RN-III config collection to configure the experiment.
+
+### Get the current study configuration
+
+`GET https://rn-iii-backend.eks-test-default.mpg-chm.com/admin/config`
+
+### Create a new study
+
+`POST https://rn-iii-backend.eks-test-default.mpg-chm.com/admin/config`
+
+### Get the current study session tree (open in the Browser for visualization)
+
+`GET https://rn-iii-backend.eks-test-default.mpg-chm.com/progress/`
+
+### Get all results in the database
+
+`GET https://rn-iii-backend.eks-test-default.mpg-chm.com/results/sessions`
+
+### Get results for a specific experiment
+
+`GET https://rn-iii-backend.eks-test-default.mpg-chm.com/results/sessions?experiment_type=DB_COLLECTION_NAME&finished=true`
+
+### Study configuration examples
+
+#### Pilot 1A
+
+```json
+
+{
+  "active": true,
+  "redirect_url": "https://app.prolific.co/submissions/complete?cc=<code>",
+  "experiment_type": "rn-iii-pilot-1a",
+  "rewrite_previous_data": false,
+  "n_generations": 1,
+  "n_sessions_first_generation": 10,
+  "n_ai_players": 0,
+  "n_sessions_per_generation": 10,
+  "n_advise_per_session": 5,
+  "n_session_tree_replications": 1,
+  "n_social_learning_trials": 2,
+  "n_individual_trials": 6,
+  "n_demonstration_trials": 2
+}
+
+```
+
+#### Pilot 1B
+
+```json
+
+{
+  "active": true,
+  "redirect_url": "https://app.prolific.co/submissions/complete?cc=<code>",
+  "experiment_type": "rn-iii-pilot-1a",
+  "rewrite_previous_data": false,
+  "n_generations": 2,
+  "n_sessions_first_generation": 10,
+  "n_ai_players": 10,
+  "n_sessions_per_generation": 10,
+  "n_advise_per_session": 5,
+  "n_session_tree_replications": 1,
+  "n_social_learning_trials": 2,
+  "n_individual_trials": 6,
+  "n_demonstration_trials": 2
+}
+
+```