Metadata-Version: 2.4
Name: opentrash
Version: 0.1.0
Summary: Open-source cloud-native geospatial Python package for residential waste collection analytics.
Author: Mohamad Alsheikh Yassin
Maintainer: Mohamad Alsheikh Yassin
License: Apache-2.0
Project-URL: Homepage, https://opentrash.app/
Project-URL: Documentation, https://opentrash.app/
Project-URL: Course, https://airesearchcorps.org/opentrash/
Project-URL: Changelog, https://github.com/malsheikhyass/opentrash/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/malsheikhyass/opentrash/issues
Keywords: geospatial,waste-management,telematics,duckdb,geopandas,civic-technology,gis
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: pandas
Requires-Dist: pyarrow
Requires-Dist: duckdb>=1.0
Requires-Dist: geopandas
Requires-Dist: shapely
Requires-Dist: pyproj
Requires-Dist: openpyxl
Provides-Extra: geotab
Requires-Dist: mygeotab; extra == "geotab"
Requires-Dist: pytz; extra == "geotab"
Provides-Extra: postgres
Requires-Dist: psycopg2-binary; extra == "postgres"
Requires-Dist: sqlalchemy>=2.0; extra == "postgres"
Requires-Dist: pytz; extra == "postgres"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Dynamic: license-file

# opentrash

> Open-source, cloud-native geospatial Python package for residential waste
> collection analytics. Turn months of vehicle telematics into per-parcel
> service signatures and per-day interactive route maps.

[![PyPI](https://img.shields.io/pypi/v/opentrash.svg)](https://pypi.org/project/opentrash/)
[![Python](https://img.shields.io/pypi/pyversions/opentrash.svg)](https://pypi.org/project/opentrash/)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
[![Docs](https://img.shields.io/badge/docs-opentrash.app-2563eb)](https://opentrash.app/)

`opentrash` is a Python package for waste-collection agencies, civic
technologists, and researchers studying urban operations. It ingests GPS
telematics + parcel polygons + route polygons + facility locations,
performs one disciplined spatial-join pass (the **engine**), and then
produces two analytical products on top:

- **Patterns** — per-parcel service signatures (weekly1, weekly2, biweekly)
  derived from months or years of pings. Answers "for this parcel, who
  shows up regularly, on what day, at what hour?"
- **RouteView** — a self-contained interactive HTML map for one
  (route, day, vehicle). Shows the truck's trail as colored GPS dots,
  parcels colored served vs. missed, the patterns expectation overlaid
  on today's reality. Drop it on a USB stick, email it, host it static.

The architecture is "spatial joins are infrastructure; products are
calculations." Everything downstream of the engine is pure aggregation
on enriched pings.

## Install

```bash
pip install opentrash
```

Optional extras for specific data sources:

```bash
pip install "opentrash[geotab]"     # Geotab GPS adapter
pip install "opentrash[postgres]"   # PostgreSQL/PostGIS GPS adapter
pip install "opentrash[dev]"        # pytest, ruff for development
```

Requires Python 3.11 or newer.

## Quickstart

```python
from datetime import date
from opentrash.engine.enrichment import enrich_pings
from opentrash.patterns.runner import run_patterns
from opentrash.routeview.runner import render_routeview

# 1. Enrich GPS pings with routes, parcels, facilities (one spatial-join pass).
enrich_pings(
    gps_cache_root="cache/",
    parcels_wkb_path="prep/parcels_wkb.parquet",
    routes_path="prep/routes.parquet",
    facilities_path="prep/facilities.parquet",
    out_root="enriched/",
    day="2026-01-18",
)

# 2. Detect per-parcel patterns over the past year.
run_patterns(
    enriched_root="enriched/",
    parcels_wkb_path="prep/parcels_wkb.parquet",
    out_root="patterns/",
    period="past_year",
)

# 3. Render an interactive HTML for one route + day + vehicle.
render_routeview(
    enriched_root="enriched/",
    segments_root="segments/",
    parcels_wkb_path="prep/parcels_wkb.parquet",
    routes_path="prep/routes.parquet",
    facilities_path="prep/facilities.parquet",
    out_root="routeview/",
    route_id="11722",
    day=date(2026, 1, 18),
    vehicle_id="815001",
    patterns_root="patterns/",
    patterns_window="2025-01-18_to_2026-01-18",
)
```

The output is a single self-contained `.html` file at
`routeview/2026-01-18/11722__815001.html`. Open it in any browser.

## Architecture

```
GPS ingest  →  cache  →  engine (the only spatial-join layer)
                            │
                            ↓ enriched pings
                            │
                ┌───────────┴───────────┐
                ↓                       ↓
        patterns (macro)          segments (timeline)
        per-parcel signatures           │
        across the window              ↓
                                  RouteView (micro)
                                  one (route, day, vehicle)
                                  as an interactive HTML
```

Patterns is the **macro** view; RouteView is the **micro** view. Together
they form a validation loop: the long-period patterns predict who should
show up; the single-day RouteView shows who actually did.

## Documentation

- **Docs site:** https://opentrash.app/
- **Course (12 lessons from notebook to package):** https://airesearchcorps.org/opentrash/
- **Issue tracker / discussions:** TBD (the repository is currently
  private; this section will be updated once it's public)

## How it's built

`opentrash` uses [DuckDB](https://duckdb.org/) for the heavy aggregations
(set-based SQL, chunked + idempotent for large datasets),
[GeoPandas](https://geopandas.org/) + [Shapely](https://shapely.readthedocs.io/)
for in-memory geometry work, [PyProj](https://pyproj4.github.io/pyproj/)
for projections, and [MapLibre GL JS](https://maplibre.org/) for the
rendered HTML maps. No commercial dependencies, no tile-provider lock-in.

## License

Apache License 2.0 — see [LICENSE](LICENSE) and [NOTICE](NOTICE).

You may use, modify, and redistribute `opentrash` for any purpose,
including commercial use, provided you retain the license and copyright
notices. Maximum adoption is the goal — spreading the knowledge.

## Citation

If you use `opentrash` in academic work, please cite it via the metadata
in [CITATION.cff](CITATION.cff) (also available as a "Cite this repository"
button on GitHub once the repository is public).

## Acknowledgments

Built by Mohamad Alsheikh Yassin under [AI Research Corps (AIRC)](https://airesearchcorps.org/),
a 501(c)(3) nonprofit. The original system was prototyped during my time
at the City of San Diego; the open-source rewrite, documentation, and
course material were produced independently at AIRC.
