{"id":349137,"name":"POOPy","description":"Object Oriented Python package for interfacing with English Water Companies Event Duration Monitoring data.","url":"https://github.com/alexlipp/poopy","last_synced_at":"2026-05-27T20:30:19.103Z","repository":{"id":215294179,"uuid":"728261466","full_name":"AlexLipp/POOPy","owner":"AlexLipp","description":"Object Oriented Python package for interfacing with English Water Companies EDM data","archived":false,"fork":false,"pushed_at":"2026-05-19T09:03:37.000Z","size":20938,"stargazers_count":12,"open_issues_count":8,"forks_count":2,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-05-19T11:53:50.604Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AlexLipp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"license.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-12-06T15:12:46.000Z","updated_at":"2026-05-19T09:03:42.000Z","dependencies_parsed_at":"2024-02-29T15:51:33.298Z","dependency_job_id":"7a313962-7413-4a6d-9ae5-2055d587f6c1","html_url":"https://github.com/AlexLipp/POOPy","commit_stats":null,"previous_names":["alexlipp/poopy"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/AlexLipp/POOPy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlexLipp%2FPOOPy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlexLipp%2FPOOPy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlexLipp%2FPOOPy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlexLipp%2FPOOPy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AlexLipp","download_url":"https://codeload.github.com/AlexLipp/POOPy/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlexLipp%2FPOOPy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33225185,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-19T15:49:41.270Z","status":"ssl_error","status_checked_at":"2026-05-19T15:49:22.917Z","response_time":58,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"owner":{"login":"AlexLipp","name":"Alex Lipp","uuid":"10188895","kind":"user","description":"Earth \u0026 Environmental Scientist at the University of Oxford","email":"","website":"https://alexlipp.github.io/","location":"Oxford, UK","twitter":"alexglipp","company":"Merton College, Oxford","icon_url":"https://avatars.githubusercontent.com/u/10188895?u=1fd8259773f92ccbcdf784bd64dc9f93d302bef5\u0026v=4","repositories_count":4,"last_synced_at":"2024-12-06T20:26:19.774Z","metadata":{"has_sponsors_listing":false},"html_url":"https://github.com/AlexLipp","funding_links":[],"total_stars":null,"followers":24,"following":20,"created_at":"2022-11-14T09:59:11.240Z","updated_at":"2024-12-06T20:26:19.774Z","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AlexLipp","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AlexLipp/repositories"},"packages":[],"commits":{"id":11029055,"full_name":"alexlipp/poopy","default_branch":"master","total_commits":170,"total_committers":7,"total_bot_commits":3,"total_bot_committers":1,"mean_commits":24.285714285714285,"dds":0.14117647058823535,"past_year_total_commits":30,"past_year_total_committers":3,"past_year_total_bot_commits":3,"past_year_total_bot_committers":1,"past_year_mean_commits":10.0,"past_year_dds":0.16666666666666663,"last_synced_at":"2026-05-25T20:01:00.465Z","last_synced_commit":"6837ea2c75116703ae9f919917ba6acc07d6569e","created_at":"2025-09-09T03:15:58.170Z","updated_at":"2026-05-25T20:00:48.750Z","committers":[{"name":"Alex Lipp","email":"alex@lipp.org.uk","login":"AlexLipp","count":146},{"name":"Alex Lipp","email":"alexander.lipp@merton.ox.ac.uk","login":null,"count":10},{"name":"Clement","email":"clementmawby@gmail.com","login":"qlemm","count":4},{"name":"jethro","email":"jethroyates@pm.me","login":"JTC-0","count":3},{"name":"copilot-swe-agent[bot]","email":"198982749+Copilot","login":"Copilot","count":3},{"name":"alex","email":"alex@alex-lipp.es.ucl.ac.uk","login":null,"count":3},{"name":"Sudhir Balaji","email":"sud.balaji@gmail.com","login":"sudhir-b","count":1}],"past_year_committers":[{"name":"Alex Lipp","email":"a.lipp@ucl.ac.uk","login":"AlexLipp","count":25},{"name":"copilot-swe-agent[bot]","email":"198982749+Copilot","login":"Copilot","count":3},{"name":"alex","email":"alex@alex-lipp.es.ucl.ac.uk","login":null,"count":2}],"commits_url":"https://commits.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexlipp%2Fpoopy/commits","host":{"name":"GitHub","url":"https://github.com","kind":"github","last_synced_at":"2026-05-26T00:00:10.885Z","repositories_count":6242210,"commits_count":883039103,"contributors_count":34925514,"owners_count":1157760,"icon_url":"https://github.com/github.png","host_url":"https://commits.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://commits.ecosyste.ms/api/v1/hosts/GitHub/repositories"}},"issues_stats":{"full_name":"AlexLipp/POOPy","html_url":"https://github.com/AlexLipp/POOPy","last_synced_at":"2026-05-19T17:05:16.030Z","status":"active","issues_count":17,"pull_requests_count":53,"avg_time_to_close_issue":5780297.6,"avg_time_to_close_pull_request":720351.72,"issues_closed_count":10,"pull_requests_closed_count":50,"pull_request_authors_count":5,"issue_authors_count":3,"avg_comments_per_issue":0.8823529411764706,"avg_comments_per_pull_request":0.20754716981132076,"merged_pull_requests_count":50,"bot_issues_count":0,"bot_pull_requests_count":0,"past_year_issues_count":2,"past_year_pull_requests_count":14,"past_year_avg_time_to_close_issue":null,"past_year_avg_time_to_close_pull_request":184666.92307692306,"past_year_issues_closed_count":0,"past_year_pull_requests_closed_count":13,"past_year_pull_request_authors_count":2,"past_year_issue_authors_count":2,"past_year_avg_comments_per_issue":0.0,"past_year_avg_comments_per_pull_request":0.14285714285714285,"past_year_bot_issues_count":0,"past_year_bot_pull_requests_count":0,"past_year_merged_pull_requests_count":13,"created_at":"2025-08-29T14:32:57.592Z","updated_at":"2026-05-19T17:05:16.031Z","repository_url":"https://issues.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlexLipp%2FPOOPy","issues_url":"https://issues.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlexLipp%2FPOOPy/issues","issue_labels_count":{"enhancement":1},"pull_request_labels_count":{},"issue_author_associations_count":{"OWNER":15,"NONE":1,"CONTRIBUTOR":1},"pull_request_author_associations_count":{"OWNER":46,"CONTRIBUTOR":3,"NONE":2,"COLLABORATOR":2},"issue_authors":{"AlexLipp":15,"JTC-0":1,"jderrfuss":1},"pull_request_authors":{"AlexLipp":46,"sudhir-b":2,"qlemm":2,"JTC-0":2,"Copilot":1},"host":{"name":"GitHub","url":"https://github.com","kind":"github","last_synced_at":"2026-05-23T00:00:30.079Z","repositories_count":14677630,"issues_count":34098301,"pull_requests_count":111617090,"authors_count":11271398,"icon_url":"https://github.com/github.png","host_url":"https://issues.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://issues.ecosyste.ms/api/v1/hosts/GitHub/repositories","owners_url":"https://issues.ecosyste.ms/api/v1/hosts/GitHub/owners","authors_url":"https://issues.ecosyste.ms/api/v1/hosts/GitHub/authors"},"past_year_issue_labels_count":{},"past_year_pull_request_labels_count":{},"past_year_issue_author_associations_count":{"NONE":1,"OWNER":1},"past_year_pull_request_author_associations_count":{"OWNER":13,"CONTRIBUTOR":1},"past_year_issue_authors":{"AlexLipp":1,"jderrfuss":1},"past_year_pull_request_authors":{"AlexLipp":13,"Copilot":1},"maintainers":[{"login":"AlexLipp","count":61,"url":"https://issues.ecosyste.ms/api/v1/hosts/GitHub/authors/AlexLipp"},{"login":"sudhir-b","count":2,"url":"https://issues.ecosyste.ms/api/v1/hosts/GitHub/authors/sudhir-b"}],"active_maintainers":[{"login":"AlexLipp","count":14,"url":"https://issues.ecosyste.ms/api/v1/hosts/GitHub/authors/AlexLipp"}]},"events":{"total":{"PullRequestEvent":29,"ForkEvent":1,"IssuesEvent":2,"WatchEvent":3,"IssueCommentEvent":2,"PushEvent":37,"PullRequestReviewEvent":5,"PullRequestReviewCommentEvent":1,"CreateEvent":9},"last_year":{"PullRequestEvent":5,"IssuesEvent":1,"IssueCommentEvent":1,"PushEvent":15,"PullRequestReviewEvent":3,"CreateEvent":3}},"keywords":[],"dependencies":[{"ecosystem":"pypi","filepath":"setup.py","sha":null,"kind":"manifest","created_at":"2024-01-08T16:43:10.141Z","updated_at":"2024-01-08T16:43:10.141Z","repository_link":"https://github.com/AlexLipp/POOPy/blob/main/setup.py","dependencies":[{"id":15500569663,"package_name":"Cython","ecosystem":"pypi","requirements":"*","direct":true,"kind":"runtime","optional":false},{"id":15500569664,"package_name":"matplotlib","ecosystem":"pypi","requirements":"*","direct":true,"kind":"runtime","optional":false},{"id":15500569665,"package_name":"numpy","ecosystem":"pypi","requirements":"*","direct":true,"kind":"runtime","optional":false},{"id":15500569666,"package_name":"pandas","ecosystem":"pypi","requirements":"*","direct":true,"kind":"runtime","optional":false},{"id":15500569667,"package_name":"pooch","ecosystem":"pypi","requirements":"*","direct":true,"kind":"runtime","optional":false},{"id":15500569668,"package_name":"geojson","ecosystem":"pypi","requirements":"*","direct":true,"kind":"runtime","optional":false},{"id":15500569669,"package_name":"gdal","ecosystem":"pypi","requirements":"*","direct":true,"kind":"runtime","optional":false},{"id":15500569670,"package_name":"requests","ecosystem":"pypi","requirements":"*","direct":true,"kind":"runtime","optional":false}]},{"ecosystem":"pypi","filepath":"pyproject.toml","sha":null,"kind":"manifest","created_at":"2024-02-29T15:51:33.255Z","updated_at":"2024-02-29T15:51:33.255Z","repository_link":"https://github.com/AlexLipp/POOPy/blob/main/pyproject.toml","dependencies":[]}],"score":4.941642422609304,"created_at":"2026-03-21T12:34:42.769Z","updated_at":"2026-05-27T20:30:19.104Z","avatar_url":"https://github.com/AlexLipp.png","language":"Python","category":"Natural Resources","sub_category":"Water Supply and Quality","monthly_downloads":0,"total_dependent_repos":0,"total_dependent_packages":0,"readme":"[![Black](https://img.shields.io/badge/code%20style-black-000000?logo=python\u0026logoColor=white)](https://github.com/psf/black)\n[![Ruff](https://img.shields.io/badge/lint-Ruff%20(E%2C%20F%2C%20I%2C%20D%2C%20N%2C%20UP)-blueviolet?logo=python\u0026logoColor=white)](https://github.com/astral-sh/ruff)\n[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit\u0026logoColor=white)](https://pre-commit.com/)\n![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)\n\n# POOPy\n\n**POOPy** = **P**ollution discharge monitoring with **O**bject **O**riented **Py**thon\n\n- [Description](#description)\n- [Installation](#installation)\n  - [Dependencies](#dependencies)\n  - [Testing](#testing)\n- [Usage](#usage)\n    - [Examples](#examples)\n    - [Gallery](#gallery)\n- [Contributing](#contributing)\n- [Credit](#credit)\n- [Disclaimer](#disclaimer)\n\n\n## Description\n\nThis is a Python package for interfacing with live data from Event Duration Monitoring (EDM) devices maintained by English and Welsh Water Companies. This package was ostensibly developed to provide the back-end for [SewageMap.co.uk](https://github.com/AlexLipp/thames-sewage) but may be generically useful for those **exploring the impact of sewage discharges on rivers**. More information can be found in our [preprint](https://eartharxiv.org/repository/view/9773/).\n\n Currently, `POOPy` supports data from all of the major water and sewerage companies: \n\n| Water Company                        | `WaterCompany` Object Name  |\n|------------------------------------|-----------------------|\n| Thames Water  | `ThamesWater`        |\n| Welsh Water/Dŵr Cymru   | `WelshWater`    |\n| Southern Water | `SouthernWater` | \n| Anglian Water | `AnglianWater` |\n| United Utilities | `UnitedUtilities` |\n| Severn Trent | `SevernTrent` |\n| Yorkshire Water | `YorkshireWater` |\n| Northumbrian Water | `NorthumbrianWater` |\n| South West Water | `SouthWestWater` |\n| Wessex Water | `WessexWater` |\n| Scottish Water| `ScottishWater` |\n\n\nDifferent water companies share their [live EDM data](https://www.streamwaterdata.co.uk/pages/storm-overflows-data) via APIs with different formats. This is obviously confusing and means that **it is hard to access national data simultaneously** and ultimately understand their potential impact on the environment. `POOPy` solves this problem by **encapsulating** relevant information about EDM monitors maintained by different water companies into a **standardised interface**. This interface (represented by the `WaterCompany` and `Monitor` classes) makes it very easy to, for instance, quickly identify monitors that are discharging, have discharged in the last 48 hours or are offline. `POOPy` combines this information with **key meta-data about the monitor** such as location and the watercourse it discharges into. Additionally, `POOPy` provides a basic approache to explore the 'impact' of discharges on the environment, using a simple hydrological model to identify **river sections downstream of sewage discharges** in real-time. `POOPy` could easily be extended to consider more complicated ways of exploring the 'impact' of sewage spills (e.g., [dynamic river flow](https://github.com/AlexLipp/thames-sewage/issues/31)).\n\nWhere historical information on CSO discharges are available (currently only provided as an API by Thames Water), `POOPy` processes this information making it very **easy to query the spill history of a particular monitor**. For instance, to calculate the total hours of sewage discharge from a given monitor over a given timeframe. Experimentally, `POOPy` also has **capabilities to 'build' histories of sewage spills** from repeated queries to the current status of a monitor, _even if (in the case of most water companies) this information is not made readily accessible_.   \n\n## Installation\n\nPOOPy is designed to be installed using the [conda](https://docs.conda.io/en/latest/) package manager. The following instructions were designed for UNIX systems (Linux, mac) but should also work on a Windows operating system by using Anaconda prompt.  \n\nFirst, download the code-base from this repository to a sensible location on your computer. This is easiest done using the following `git` command but you can also download the repository manually if you prefer.\n```bash\ngit clone https://github.com/AlexLipp/POOPy.git [LOCAL DIRECTORY]\n```\nNavigate into the directory which contains the source code (it should contain a `setup.py` file). Next, we will create a conda environment with the required dependencies installed using the provided `.yaml` file. Run the following code from your `base` conda environment. \n```bash\nconda env create -f environment.yaml\n```\nThis creates an environment called `poopy` that automatically installs POOPy's dependencies. Now, activate that environment: \n```bash\nconda activate poopy\n```\nFinally, we can actually install POOPy by running: \n```bash\npip install .\n```\nIf install has happened correctly you should see something like `Successfully built poopy` printed to your terminal. If you'd like to install an editable version of the package simply run: `pip install -e .` instead.  \n\n### Testing \n\nA test script is provided in the `tests` folder. To run the tests, you will need to install the [`pytest` package](https://docs.pytest.org/en/stable/). If installed, the tests can be run from the command line by navigating to the folder in which the package is installed and simply running the command: \n\n```bash\npytest --disable-warnings\n```\nThis will run the tests and provide a summary of the results. If all tests pass, the package has been installed correctly and behaving as expected. Note that the `--disable-warnings` flag is used to suppress the many warnings that `POOPy` generates, these are mostly informative rather than disastrous (e.g., indicating when an input data-stream is ambiguous), but can be overwhelming _en masse_. \n\n\n## Usage\n\nOnce installed, the package can be imported into Python scripts using standard import commands, such as:\n```python\nimport poopy\n```\nor \n```python\nfrom poopy.companies import ThamesWater\n```\n\n### Examples\n\nExamples of how to use the package (using the `ThamesWater` class as an example) are given in the `examples` folder in the form of interactive python Jupyter noteboooks. Note that whilst `ThamesWater` is used as an example, the same operations apply to **all** of the water companies supported by `POOPy` (with the exception of the historical data operations which are currently only supported by Thames Water):\n- [Investigating the *current* status of sewer overflow spilling](https://github.com/AlexLipp/POOPy/blob/main/examples/current_status.ipynb)\n- [Investigating the *historical* status of sewer overflow spilling](https://github.com/AlexLipp/POOPy/blob/main/examples/historical_status.ipynb)\n\n### Gallery\n\n`POOPy` can be used to be really easily make figures like...\n\n... this one showing the stretches of the Thames downstream of active sewage discharges at the shown time...\n\n```\nfrom poopy.companies import ThamesWater\ntw=ThamesWater()\ntw.plot_current_status()\n```\n![map](https://github.com/AlexLipp/POOPy/assets/10188895/395732dc-54c1-403e-b681-be3bece7f7e7)\n\n...or this one which shows the discharge history of a specific monitor...\n```\nfrom poopy.companies import ThamesWater\ntw=ThamesWater()\nmonitor=tw.active_monitors[\"Bourton-On-The_water\"]\nmonitor.plot_history()\n```\n![bourton_on_the_water](https://github.com/AlexLipp/POOPy/assets/10188895/feeb6035-78f0-4c48-b3f2-bd1d18f2ce96)\n\n...or this one which shows the number of live monitors deployed by Thames Water through time and whether they were discharging...\n\n![image](https://github.com/AlexLipp/POOPy/assets/10188895/8c631231-bf9c-406e-a393-4d1a72d355b3)\n\n## Contributing \n\nContributions are very welcome! Take a look at the issues tab, or reach to us if you have suggestions or features. Or, just dive straight in.\n\n### Code Style \u0026 Formatting\nThis repository uses automatic code formatting and linting. To ensure consistency in the codebase, tools are run automatically on pre-commit. Before you commit, the following hooks will automatically run:\n\n- [Black](https://github.com/psf/black): Automatically formats your code to adhere to the Black code style.\n- [Ruff](https://github.com/astral-sh/ruff): Automatically runs a linter on your code to catch style issues, errors, and potential bugs.\n\nTo set up the pre-commit hooks and ensure your code is formatted and linted before committing, run the following:\n1. Install pre-commit if you haven’t already: `pip install pre-commit`\n2. Install the hooks: `pre-commit install`\nNow the checks will automatically run when you `commit`, but you can: \n3. Test them manually with:  `pre-commit run --all-files`\n\nThe settings for these linters is detailed in `.pre-commit-config.yaml`.\n\n\n## Credit\n\nIf you use these scripts, or the data, please reference its source. For instance: \n\n\u003e \"Data generated using the POOPy software (`github.com/AlexLipp/POOPy`)\"\n\n## Disclaimer\nWhilst every effort has been made to ensure accuracy, this is experimental software and errors may occur and I assume no responsibility or liability for any such errors. If you see any issues please contact me, or raise an `Issue' above. This code is [licensed under the GNU General Public License 3.0](https://github.com/AlexLipp/poopy?tab=GPL-3.0-1-ov-file#readme)\n","funding_links":[],"readme_doi_urls":[],"works":{},"citation_counts":{},"total_citations":0,"keywords_from_contributors":["digital-elevation-model"],"project_url":"https://ost.ecosyste.ms/api/v1/projects/349137","html_url":"https://ost.ecosyste.ms/projects/349137"}