Merge pull request #74 from UCL/intro-docs

Basic guide and some tidying up

.github/workflows/static.yaml

@@ -17,7 +17,7 @@ jobs:
         with:
           python-version: '3.9'
       # Install dependencies and package
-      - run: pip install .[tests]
+      - run: pip install .[dev]
       # Run linting and style check
       - run: flake8 src/
       # Check import order

.github/workflows/tests.yaml

@@ -20,6 +20,6 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
       # Install dependencies and package
-      - run: pip install .[tests]
+      - run: pip install .[dev]
       # Run tests
       - run: pytest

LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 University College London
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1 +1,97 @@
 # hivpy
+
+This repository contains a Python package for running simulations
+of the transmission of HIV across a population, and related quantities.
+
+The code is under active development. While you are welcome to use it,
+be aware that the structure, behaviour and interface (inputs and outputs)
+are all likely to change.
+
+More extensive documentation for this package is under development.
+
+TODO: Link to publications using hiv-synthesis model and other pages
+
+## Getting started
+### Prerequisites
+This code requires Python 3.7 or newer.
+
+We recommend that you use a virtual environment to install the package.
+See the offical Python guide for [creating](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment)
+and [activating](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/#activating-a-virtual-environment) virtual environments.
+
+If you are using Python through anaconda, see
+[their guide for managing environments](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html).
+
+
+### Installing the package
+Once you have activated the relevant virtual environment (if desired),
+you can install the package by running the following command
+from the top level of this repository (the location of this README file):
+```bash
+pip install .
+```
+(if you are planning to make changes to the code, see the
+developer instructions below)
+
+This will install the libraries that the package requires, and make available
+the command-line tool for running simulations.
+
+In the future, we plan to make the package available through the
+[Python Package Index](https://pypi.org/). Until then, installing from source
+is the only way to access the code.
+
+## Running simulations
+Simulations can be run from the terminal with `run_model`:
+```bash
+run_model <configuration file>
+```
+The command takes as its argument the path to a YAML file,
+which contains various settings for the simulation, such as
+the start and end dates and the size of the population.
+For an example, see the [sample file](./hivpy.yaml)
+included in this repository.
+
+When the simulation runs, it will produce a CSV file with outputs.
+The file contains one row per time step and a column for each quantity
+that is being tracked or computed.
+The file name reflects the date and time that the simulation was launched,
+for example `simulation_output_20220826-163116.csv`.
+
+
+## Support
+If you notice something that appears wrong, please let us know by
+[opening an issue](https://github.com/UCL/hivpy/issues/new/choose)
+on this repository.
+
+## Developer instructions
+### Installation
+If you are planning to make changes to the package code,
+use the following command to install the package instead:
+```bash
+pip install -e .[dev]
+```
+This will install some additional libraries and tools for development, and also create an "editable" installation; this means that any changes you make will be applied automatically, without needing to reinstall the package.
+
+### Testing
+The package comes with unit tests. To run them, simply run
+`pytest` from the top level (this directory). The `pytest` package and command
+are installed during the package installation if the `[dev]` extra option
+is supplied, as above.
+
+### Contributions
+If you want to make changes to the code, we recommend the following workflow:
+- Create a new git branch
+- Make the relevant changes
+- Ideally, implement unit test(s) to verify the correctness of your changes
+- Run the tests (old and new)
+- Run a linter (`flake8 src/`) to check for issues related to code style
+-  [Open a pull request](https://github.com/UCL/hivpy/compare) to merge your changes
+
+### Extending the model
+The exact steps will change depending on the nature of the changes,
+but this is a rough outline of the actions needed:
+
+- Add variables to the population to track measures of interest.
+- Find which model modules are affected; if adding new behaviour, consider whether it belongs in an existing module or is better placed in a new one.
+- If needed, add outputs to be tracked in [`simulation.py`](src/hivpy/simulation.py).
+- Implement one or more tests to cover your new changes, and run the whole test suite.

setup.cfg

@@ -32,7 +32,7 @@ exclude =
 hivpy.data = *.yaml
 
 [options.extras_require]
-tests =
+dev =
     pytest
     pytest-mock
     flake8
@@ -42,7 +42,6 @@ tests =
 [options.entry_points]
 console_scripts =
     run_model = hivpy.cli:run_model
-    register_parameters = hivpy.cli:register_parameters
 
 [flake8]
 max-line-length = 100

src/hivpy/cli.py

@@ -5,16 +5,6 @@
 
 from .experiment import create_experiment, run_experiment
 
-'''
-Maybe we may want to register parameters/properties in future?
-'''
-# def register_parameters():
-#     parser = argparse.ArgumentParser(description="register model parameters")
-#     parser.add_argument("parameters", type=pathlib.Path,
-#                         help="register_parameters parameters.csv")
-#     args = parser.parse_args()
-#     parameter_filepath = args.parameters
-
 
 def run_model():
     '''