User guide #223
User guide #223
Conversation
We use poetry for package management, so running with `python` won't necessarily work due to missing or incorrect packages
Codecov Report
@@ Coverage Diff @@
## develop #223 +/- ##
========================================
Coverage 97.55% 97.55%
========================================
Files 32 32
Lines 2531 2531
========================================
Hits 2469 2469
Misses 62 62
Flags with carried forward coverage won't be shown. Click here to find out more. Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here. |
| @@ -2,15 +2,15 @@ | |||
|
|
|||
| The model has a wrapper script called `run_titan.py` that makes running a full simulation easy. TITAN can also be run from an interactive repl or a custom script. | |||
There was a problem hiding this comment.
I'd consider renaming this file
docs/user_guide.md
Outdated
| @@ -1,15 +1,15 @@ | |||
| # Getting Started | |||
| # User Guide | |||
There was a problem hiding this comment.
I thought we'd discussed turning this more into a developer's guide instead of a user guide, then moving the install instructions to somewhere more prominent
docs/walkthrough.md
Outdated
| @@ -0,0 +1,59 @@ | |||
| # Walkthrough | |||
| For documentation on `run_titan.py`, as well as information for running the model interactively, see the [user guide](user_guide.md). | |||
There was a problem hiding this comment.
What is the walk through for? needs an intro before linking people to go elsewhere
There was a problem hiding this comment.
I'd think this would be more the user guide and should maybe be folded in with run_local
docs/walkthrough.md
Outdated
| For documentation on `run_titan.py`, as well as information for running the model interactively, see the [user guide](user_guide.md). | ||
|
|
||
| ## Parameter setup | ||
| TITAN uses the [`paraml`](https://pypi.org/project/paraml/) package for parameter management using YAML. In TITAN, parameters are sub-divided, with each parameter set referring to a main model parameter type (e.g. classes or agent demographics), a model feature (e.g. syringe services), or an exposure (e.g. hiv). Parameters may be set up in one YAML file or a folder of YAML files. |
There was a problem hiding this comment.
maybe include a screenshot of a folder of yaml files here?
docs/walkthrough.md
Outdated
| ``` | ||
|
|
||
| ### Demographic parameters | ||
| Your parameter file can also be used to update demographic information and distributions for agents in the model. Here, we will change the percentage of agents of each race (white and Black) in the model. Add the following to `my_params.yml` (or play around with the numbers yourself! Just make sure they add up to 1): |
There was a problem hiding this comment.
instead of capitalizing Black here I'd make them code blocks so it clearly references the demographic classes white and black
There was a problem hiding this comment.
for each of these sections, I'd more links out where people could learn more about the params, or the features available, etc.
| features: | ||
| random_trial: true | ||
| ``` | ||
| We can then change the parameters for the trial. Let's make it select agents randomly: |
There was a problem hiding this comment.
link out to the param options here
| ``` | ||
|
|
||
| ### Adding a random trial | ||
| Features can also be added to the model via params. To turn on the random trial feature, first we need to activate it: |
There was a problem hiding this comment.
link features out to somewhere
| ``` | ||
| run_titan -p my_params.yml -S atlanta | ||
| ``` | ||
| This will save the results of your model in a newly-made `results` directory, or overwrite previous results in an existing `results` directory. |
There was a problem hiding this comment.
screenshots might be useful in showing what the expected state should be
docs/walkthrough.md
Outdated
| This will save the results of your model in a newly-made `results` directory, or overwrite previous results in an existing `results` directory. | ||
|
|
||
| ## Sweeping parameters | ||
| TITAN can also sweep over a set of parameters defined by a CSV file. To use this feature, create a CSV with columns named as `.`-separated parameters. For example, you might change the probability of componenets being treated in the random trial module by using the column name `random_trial.prob` in a `sweep_val.csv` file and populating rows with random numbers between 0 and 1. To run this sweep over the first 10 rows of your CSV, you would use the command: |
There was a problem hiding this comment.
doesn't have to be csv, right? should this mention the command line version and then maybe do the csv as a tip add on?
… sweeps; link params app more
Updates to the user guide
Closes #220, Closes #221, Closes #218