User guide

docs/api/overview.md

@@ -0,0 +1,8 @@
+## Overview
+
+`titan-model` includes a number of "internal" and "external" classes and functions.
+Typically, users will interact through the `run_titan.py` script, though some utility
+may be found through using the more internal functions, such as creating a population
+with the `Population` class or a model with the `TITAN` class. This API 
+information is intended as reference for users to understand how the model works
+under the hood.

docs/contributing.md

@@ -1,5 +1,38 @@
 We welcome issues and pull requests to help improve the TITAN model.  We use the following guidelines to ensure standards are met.
 
+## Development Setup
+
+Planning to help work on the titan codebase? Here are the tools and processes you need to know about:
+
+### Git/Github
+
+We use [git](https://git-scm.com/) for version control and GitHub for our remote repository. To get started, clone the repository to your local machine.
+
+```
+git clone https://github.com/pph-collective/TITAN.git
+```
+
+We use angular commits to standardize our commits and encourage better messages. [Commitizen](https://pypi.org/project/commitizen/) makes this easy.  Once installed (would recommend doing this globally as opposed to just for this project), run `cz commit` instead of `git commit`.
+
+### Poetry
+
+[Poetry](https://python-poetry.org/) is a python packaging and dependency management tool.  We use this to install/add/remove dependencies, build our package, and publish it to pypy.  Install poetry per [the install instructions](https://python-poetry.org/docs/#installation), then complete the below steps.
+
+```
+poetry install -E linting -E docs
+```
+
+The `-E` flags tell poetry that we want the optional dependencies that we use for linting (mypy, black, flake8) and for building documentation.
+
+We recommend using a recent python version for development (check out [pyenv](https://github.com/pyenv/pyenv) for a way to manage different python versions).  You may need to tell poetry which installation of python to use - see [their instructions](https://python-poetry.org/docs/managing-environments/).
+
+Poetry installs all of the dependencies into a virtual environment so that they are isolated from other projects you are working on.  To run any shell commands in the environment, prefix them with `poetry run` (e.g. `poetry run run_titan -p my_params.yml` or `poetry run pytest`) or start a poetry shell with `poetry shell`.
+
+### pypy
+
+pypy is a JIT compiled version of python which generally makes code faster.  It is important that titan remain installable/usable with pypy and we test for this with GitHub actions.  However, pypy doesn't play well with some of our linting tools, so we don't typically use it for development.
+
+
 ## GitHub Workflow
 
 When working on TITAN, make a branch from `develop` to make changes in, then make a pull request to `develop` when ready for review.
@@ -26,16 +59,13 @@ Then use `cz commit` where you would have previously done `git commit`.
 
 We strive to have test coverage for all of the features of TITAN.  When adding a new feature or fixing a bug, add tests for the new feature or that test the bug condition to make sure that the bug doesn't crop up agin.
 
-`pytest` is the library used for testing.
-
-To run all of the tests:
-```
-python -m pytest
-```
+[Pytest](https://docs.pytest.org/en/stable/) is our test runner.  It runs all of our unit and integration tests and reports back any errors or failures.  These should almost always pass (the almost refers to our stochastic integration tests which have some element of randomness in their success).
 
-To run only the unit tests:
 ```
-python -m pytest -m unit
+poetry run pytest # runs all tests
+poetry run pytest -m unit # only unit tests
+poetry run pytest -m integration_deterministic # only deterministic integration tests
+poetry run pytest -m integration_stochastic # only stochastic integration tests
 ```
 
 ### Code Style

docs/run_local.md → docs/running.md

@@ -1,16 +1,27 @@
+## Installation
+
+To get started, install titan using a local python (version 3.6 or later) install or virtual env using `pip`.
+
+```
+pip install titan-model
+```
+
+!!! tip
+    Running a large job locally? Look into using [pypy](https://www.pypy.org/) instead of python for MOAR performance. Otherwise, all of the instructions hold, just using pypy and pypy's pip.
+
 ## Running the Model
 
 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.
 
-### run_titan.py
+### run_titan
 
-To run the model, execute the `run_titan.py` program within the `/titan/` directory. See [TITAN params](https://pph-collective.github.io/titan-params-app) for documentation on how to set and use parameters.
+To run the model after pip install, use the command `run_titan` from the command line. See [the walkthrough](walkthrough.md) for documentation on how to set and use parameters, as well as a step-by-step guide to running the model with your custom parameters.
 
 Results of the model are generated and aggregated into the `/results/` directory by default. If the model is re-run, the existing results will be overwritten.
 
 #### Usage
 
-Below are the results of `python run_titan.py --help`.  It highlights all of the command line arguments that can be passed to the script.
+Below are the results of `run_titan --help`.  It highlights all of the command line arguments that can be passed to the script.
 
 ```
 usage: run_titan.py [-h] [-n [NMC]] [-S SETTING] -p PARAMS [-o OUTDIR]
@@ -56,7 +67,7 @@ optional arguments:
 
 ### Running Interactively
 
-The model can also be run interactively in the repl.  Start a `python` session from the root directory of `TITAN`, and follow along!
+The model can also be run interactively in the repl. Please see the developer installation instructions in [installation](contributing.md) for information on installing dependencies with poetry.  Start a `python` session in [poetry](https://python-poetry.org/) from the root directory of `TITAN` via `poetry run python`, and follow along!
 
 We'll use the sample params file `tests/params/basic.yml` in all of these examples, but feel free to use a different one.
 
@@ -123,4 +134,4 @@ model3.run(outdir)
 
 To make sure everything is working, run the tests.  A few of the tests (marked `integration_stochastic`) sometimes fail as they are testing for general behavior and not specific correctness, but all other tests should always pass.
 
-`python -m pytest`
+`poetry run pytest`

docs/walkthrough.md

@@ -0,0 +1,71 @@
+# Walkthrough
+For documentation on `run_titan.py`, as well as information for running the model interactively, see the [Running TITAN](running.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](https://pph-collective.github.io/titan-params-app/#/params#classes-1) or agent [demographics](https://pph-collective.github.io/titan-params-app/#/params#demographics-1)), a model feature (e.g. [syringe services](https://pph-collective.github.io/titan-params-app/#/params#syringe_services-1)), or an exposure (e.g. [hiv](https://pph-collective.github.io/titan-params-app/#/params#hiv-1)). Parameters may be set up in one YAML file or a folder of YAML files.
+
+This guide will walk through creating a params file to augment the existing Atlanta setting, creating a small population to practice running. In order to best follow the next steps of the guide, users are encouraged to set this up as a single parameter file entitled `my_params.yml` in your working directory.
+
+### Model parameters
+To start, we want to edit the parameter file to run a smaller model over less time so that it will run quickly locally. To do this, we will update [model parameters](https://pph-collective.github.io/titan-params-app/#/params#model-1) to change population size and number of timesteps. In addition, we can set the random seed to provide reproducibility. To achieve this, add the following to your `my_params.yml` file (without comments):
+```
+model:
+  seed: # random seed
+    ppl: 1234  # set random seed for population initiation
+    run: 1234  # set random seed for the run
+  num_pop: 100  # create small population
+  time:
+    num_steps: 12  # number of steps in model run
+    burn_steps: 0  # number of "burn-in" steps (negative time)
+```
+
+### Demographic parameters
+Your parameter file can also be used to update [demographic](https://pph-collective.github.io/titan-params-app/#/params#demographics-1) 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):
+```
+demographics:
+  black:
+    ppl: 0.5
+  white:
+    ppl: 0.5
+```
+
+### 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:
+```
+features:
+  random_trial: true
+```
+We can then change the parameters for the trial. Let's make it select agents randomly:
+```
+random_trial:
+  choice: all
+```
+
+### Other parameters
+Full reference for all parameters in TITAN can be found in our [parameter web app](https://pph-collective.github.io/titan-params-app).
+
+## Running your params file
+To run your new params file, you can simply use the command:
+```
+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.
+
+## Sweeping parameters
+TITAN can also sweep over a set of parameters, either stepwise from the command
+line or from a CSV defining a set of parameters. For either method, use 
+`.`-separated parameters. For example, you might change the probability of
+components being treated in the random trial module using [random_trial.prob](https://pph-collective.github.io/titan-params-app/#/params#random_trial-1).
+
+To run this from the command line, use `param:start:stop:step`. For example, to
+vary the random trial probability from 0.5 to 1 with steps of size 0.1, you can
+run:
+```
+run_titan -p my_params.yml -S atlanta -w random_trial.prob:0.5:1.0:0.1
+```
+
+To sweep from values with a file, create a CSV with columns named as the `.`-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:
+```
+run_titan -p my_params.yml -S atlanta -W sweep_file.csv -R 1:10
+```
+In either of the above examples, your results directory now contains a report with outputs using all 10 values, as well as a file linking each run's id with its value for the probability.

mkdocs.yml

@@ -28,10 +28,9 @@ markdown_extensions:
 
 nav:
   - Overview: index.md
-  - Getting Started:
-    - Installation: getting_started.md
-    - Running locally: run_local.md
-    - Running on Oscar: run_oscar.md
+  - User Guide:
+    - Running TITAN: running.md
+    - Walkthrough: walkthrough.md
     - Contributing: contributing.md
   - API Reference:
     - Agent: api/agent.md