From de40e5172350d1c81897d10eb83508846ddc846b Mon Sep 17 00:00:00 2001 From: Anastasis Georgoulas Date: Thu, 29 Sep 2022 21:51:07 +0100 Subject: [PATCH 1/6] Add MIT license --- LICENSE.txt | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) create mode 100644 LICENSE.txt diff --git a/LICENSE.txt b/LICENSE.txt new file mode 100644 index 00000000..2ad69235 --- /dev/null +++ b/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. \ No newline at end of file From ab7c6c55beba8a983e764fdcfc21010790ab5ffb Mon Sep 17 00:00:00 2001 From: Anastasis Georgoulas Date: Thu, 29 Sep 2022 23:11:52 +0100 Subject: [PATCH 2/6] Record some instructions for getting set up --- README.md | 80 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 80 insertions(+) diff --git a/README.md b/README.md index e72d7dc8..a97382c6 100644 --- a/README.md +++ b/README.md @@ -1 +1,81 @@ # 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. + +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 +TODO: +- Command +- Config file +- Outputs + +## Support +If you notice something that appears wrong, please le 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 .[tests] +``` +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 + +### 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. From 09a289e1c3a3c9eea39d21c5e5630c19c2cf5285 Mon Sep 17 00:00:00 2001 From: Anastasis Georgoulas Date: Fri, 30 Sep 2022 09:17:55 +0100 Subject: [PATCH 3/6] Describe how to run simulations --- README.md | 24 +++++++++++++++++++----- 1 file changed, 19 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index a97382c6..59fcc776 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,8 @@ 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 @@ -39,13 +41,25 @@ In the future, we plan to make the package available through the is the only way to access the code. ## Running simulations -TODO: -- Command -- Config file -- Outputs +Simulations can be run from the terminal with `run_model`: +```bash +run_model +``` +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 le us know by +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. From 3d70381b333d54c6056ee502c6441987633f2731 Mon Sep 17 00:00:00 2001 From: Anastasis Georgoulas Date: Fri, 30 Sep 2022 09:18:45 +0100 Subject: [PATCH 4/6] Remove unused CLI entry point --- setup.cfg | 1 - src/hivpy/cli.py | 10 ---------- 2 files changed, 11 deletions(-) diff --git a/setup.cfg b/setup.cfg index 895ab38e..771400cb 100644 --- a/setup.cfg +++ b/setup.cfg @@ -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 diff --git a/src/hivpy/cli.py b/src/hivpy/cli.py index 024d9671..05ceb2fe 100644 --- a/src/hivpy/cli.py +++ b/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(): ''' From dcb743b24d413fae76eda0fcf9f4099d2bd1e163 Mon Sep 17 00:00:00 2001 From: Anastasis Georgoulas Date: Sun, 2 Oct 2022 11:33:43 +0100 Subject: [PATCH 5/6] Fix phrasing per review suggestion --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 59fcc776..89071eb5 100644 --- a/README.md +++ b/README.md @@ -74,7 +74,9 @@ This will install some additional libraries and tools for development, and also ### 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 +`pytest` from the top level (this directory). The `pytest` package and command +are installed during the package installation if the `[tests]` extra option +is supplied, as above. ### Contributions If you want to make changes to the code, we recommend the following workflow: From e6c5f712c3cf281d22f32923124fb7ed6f82ff6b Mon Sep 17 00:00:00 2001 From: Anastasis Georgoulas Date: Thu, 13 Oct 2022 18:32:39 +0100 Subject: [PATCH 6/6] Use more accurate name for extra dependencies It's not just tests but also other tools, including documentation. --- .github/workflows/static.yaml | 2 +- .github/workflows/tests.yaml | 2 +- README.md | 4 ++-- setup.cfg | 2 +- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/.github/workflows/static.yaml b/.github/workflows/static.yaml index 7f5b67a9..88bf3548 100644 --- a/.github/workflows/static.yaml +++ b/.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 diff --git a/.github/workflows/tests.yaml b/.github/workflows/tests.yaml index fff0a323..8b54133e 100644 --- a/.github/workflows/tests.yaml +++ b/.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 diff --git a/README.md b/README.md index 89071eb5..0f0cf7fa 100644 --- a/README.md +++ b/README.md @@ -68,14 +68,14 @@ on this repository. If you are planning to make changes to the package code, use the following command to install the package instead: ```bash -pip install -e .[tests] +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 `[tests]` extra option +are installed during the package installation if the `[dev]` extra option is supplied, as above. ### Contributions diff --git a/setup.cfg b/setup.cfg index 771400cb..2a090d4e 100644 --- a/setup.cfg +++ b/setup.cfg @@ -32,7 +32,7 @@ exclude = hivpy.data = *.yaml [options.extras_require] -tests = +dev = pytest pytest-mock flake8