Merge pull request #107 from ImperialCollegeLondon/24-repo-structure

Repo structure

AUTHORS.md

@@ -0,0 +1,5 @@
+# Developers
+
+* Barnaby Dobson `b.dobson - at - imperial.ac.uk`
+* Taher Chegini
+* Diego Alonso Alvarez

CODE_OF_CONDUCT.md

@@ -0,0 +1,133 @@
+
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+`b.dobson -at- imperial.ac.ak`.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

CONTRIBUTING.md

@@ -0,0 +1,139 @@
+# Contributing to `SWMManywhere`
+
+Thank you for considering contributing to `SWMManywhere`.
+
+## Bugs
+
+Please create a new issues (insert link when published)
+if you may have found a bug.
+Please describe the bug and instructions on recreating it (including OS and
+Python version). Label the issue with `bug`.
+
+## New behaviour
+
+Our intention with `SWMManywhere` is that a high level of customisation to suit
+your needs may be achieved by adding new `graphfcns` or new `metrics`, see
+below. Other new behaviour may be tagged with `enhancement`, though please
+check existing issues (insert link when published)
+to see if something similar already exists.
+
+### Take a graph give a graph: `graphfcns`
+
+All transformations that take place do so on graph functions, you can change
+the order in which these are executed and add new ones. If you want a
+`graphfcn` that does a new thing, please create an issue to discuss with the
+label `graphfcn`. If a single new `graphfcn` is not sufficient to capture the
+transformations that you'd like to apply, more may be needed. If this is the
+case, please first create an issue labelled with `enhancement` detailing the
+thing that you would like to capture, where we will discuss what `graphfcns`
+are needed, and use this issue to coordinate.
+
+### Evaluate against real data with: `metrics`
+
+We have provided a large set of metrics against which a synthetic graph's
+performance may be evaluated if a real network is provided. If you want to
+create a new `metric`, please create an issue to discuss with the label
+`metric`.
+
+## Installation for development
+
+To install `SWMManywhere` in development mode, first you will need a virtual
+environment. Here we use a `conda` environment which let us use the version of
+python we want to use, but you can use any other tool you are familiar with.
+Just make sure you use a version of Python compatible with SWMManywhere.
+
+```bash
+conda create --name swmmanywhere python=3.10
+conda activate swmmanywhere
+```
+
+Once in the environment, you need to clone the `SWMManywhere` GitHub repository
+locally and move into the right folder. You will need `git` for that, installed
+either following the [official instructions](https://git-scm.com/downloads) or
+with `conda install git`, if you use `conda`.
+
+```bash
+git clone https://github.com/ImperialCollegeLondon/SWMManywhere.git
+cd swmmanywhere
+```
+
+We use [`pip-tools`](https://pip-tools.readthedocs.io/en/latest/) to ensure
+consistency in the development process, ensuring all people contributing to
+`SWMManywhere` uses the same versions for all the dependencies, which minimiese
+the conflicts. To install the development dependencies and then `SWMManywhere`
+in development mode run:
+
+```bash
+pip install -r dev-requirements.txt
+pip install -e .
+```
+
+## Quality assurance and linting
+
+`SWMManywhere` uses a collection of tools that ensure that a specific code
+style and formatting is follow throughout the software. The tools we used for
+that are [`ruff`](https://docs.astral.sh/ruff/),
+[`markdownlint`](https://github.com/igorshubovych/markdownlint-cli),
+[`mypy`](https://github.com/pre-commit/mirrors-mypy),
+[`refurb`](https://github.com/dosisod/refurb),
+[`codespell`](https://github.com/codespell-project/codespell),
+[`pyproject-fmt`](https://github.com/tox-dev/pyproject-fmt).
+You do not need to run them manually - unless you want to - but rather they are
+run automatically every time you make a commit thanks to `pre-commit`.
+If you want to run them manually before committing, you can do so with:
+
+```bash
+pre-commit run --all-files
+```
+
+`pre-commit` should already have been installed when installing the `dev`
+dependencies, if you followed the instructions above, but you need to activate
+the hooks that `git` will run when making a commit. To do that just run:
+
+```bash
+pre-commit install
+```
+
+You can customise the checks that `ruff`, `mypy`, and `refurb` will make with
+the settings in `pyproject.toml`. For `markdownlint`, you need to edit the
+arguments included in the .`pre-commit-config.yaml` file.
+
+## Testing and coverage
+
+`SWMManywhere` uses `pytests` as testing suite. You can run tests by navigating
+to the folder and running:
+
+```bash
+pytest # run all tests
+pytest tests/test_file.py # run a specific file's tests
+```
+
+By default the `tests/tests_prepare_data.py` does not test the actual downloads
+themselves (since this relies on external APIs actually working at the time of
+testing), however downloads can be enabled when testing:
+
+```bash
+pytest tests/tests_prepare_data.py -m downloads
+```
+
+You can check the coverage for these tests by running:
+
+```bash
+coverage run -m pytest
+coverage report
+```
+
+And generate a new coverage html for the documentation with
+
+```bash
+coverage html
+```
+
+## Changing dependencies
+
+Is as the development process moves forward you find you need to add a new
+dependency, just add it to the relevant section of the `pyproject.toml` file
+and then run `pip-compile` as required to regenerate the different
+`requirements.txt` files. Read the
+[`pip-tools` documentation](https://pip-tools.readthedocs.io/en/latest/) for
+more information on the process.

LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2022, barneydobson
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

swmmanywhere/HISTORY.md

@@ -0,0 +1,5 @@
+# History
+
+## 0.1.0 (date)
+
+- First release goes here