Best Practices

Running maps

Checklist to run through when running a map on cholera-mapping-pipeline.

Before launching a run

1. You and at least one other member of the team should review the config file that will be run.
2. Commit the reviewed config file to cholera-configs.
3. Check which branch you are on in cholera-configs, cholera-mapping-pipeline, and cholera-covariates in the directories from which the model will be run.
4. Git pull in cholera-configs, cholera-mapping-pipeline, and cholera-covariates in the directories from which the model will be run.
5. Revert uncommitted changes to files git reset --hard
6. Remove uncommitted files git clean -fxd
7. Re-create database_api_key.R
8. Review the cholera-configs Github Kanban board and issues for notes on the run you plan to launch.
9. Reinstall taxdat.
10. Check for and remove old data files in the data folder that might be related to your model run.
11. Review the shell (.sh) script that will be used to launch your model run.

After launching a run

1. Record the branch name(s) for all repos, commit hash for cholera-mapping-pipeline, the config settings, and other model launch notes in the Github issue of the cholera-configs Kanban board.
2. Update the Kanban board status

After the run is done

1. Review the model logs to see if the run finished successfully.
2. Commit the model logs to the appropriate cholera-configs folder.
3. Commit the Stan-generated model files to the appropriate cholera-mapping-output folder (Only perform this step for report/manuscript final runs).
4. Update the Kanban board status

After the model diagnostic reports are run

As of 25 Feb 2022, model diagnostic reports include: data comparison report and country data report RMD files

1. Commit the html diagnostic files to the appropriate cholera-configs folder.
2. Commit intermediate model output files to the appropriate cholera-mapping-output folder (Only perform this step for report/manuscript final runs). There may not be intermediate model output files for the model diagnostic reports. However, there were intermediate model output files generated in the creation of the Dec 2021 Gavi report and these should be committed to cholera-mapping-output.
3. Update the Kanban board status
4. Post the diagnostic reports in cholera-taxonomy Slack channel.

Triangular workflow and merging Github branches

Checklist for Github workflow and merging branches. For additional detail, we are roughly following the Integration-Manager workflow described here except individuals work on branches and not forks. For the following checklist, assume that dev is the production branch and you're making updates on dev_a. You will start by making a new branch called dev_a from dev. All of your code changes will be made in dev_a. Test that dev_a works as expected, ideally by writing unit tests or running a map or both.

1. Submit a PR for dev into dev_a and review changes. After reviewing and resolving conflicts, merge dev into dev_a.
2. Submit a PR for dev_a into dev and review changes.
3. Test that dev_a works as expected, ideally by running unit tests, integration tests, a map, or one or more of the above.
4. If tests produce the expected results, merge the pull request.
5. If you no longer intend to make changes to dev_a, delete the branch. If there are more changes to make, continue working in dev_a and follow these steps again from the top when ready to merge.