Metadata-Version: 2.4
Name: spatioClimata
Version: 0.1.0
Summary: Copernicus climate and hydrology data pipeline toolkit with analytics-ready outputs.
Author-email: Nethum Perera <nethumsemithaperera@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/nethumperera/spatioClimata
Project-URL: Repository, https://github.com/nethumperera/spatioClimata
Project-URL: Issues, https://github.com/nethumperera/spatioClimata/issues
Keywords: copernicus,era5,glofas,climate,hydrology,geospatial,xarray,pipeline
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Classifier: Topic :: Scientific/Engineering :: Hydrology
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cdsapi>=0.7.3
Requires-Dist: xarray>=2024.1.0
Requires-Dist: numpy>=1.25.0
Requires-Dist: netcdf4>=1.6.0
Requires-Dist: h5netcdf>=1.3.0
Requires-Dist: python-dotenv>=1.0.1
Requires-Dist: typer>=0.12.3
Requires-Dist: pydantic>=2.6.0
Provides-Extra: dask
Requires-Dist: dask[distributed]>=2024.4.1; extra == "dask"
Requires-Dist: fsspec>=2024.3.1; extra == "dask"
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Requires-Dist: mypy>=1.9.0; extra == "dev"
Dynamic: license-file

# spatioClimata

spatioClimata is a Python package for requesting, validating, downloading, and transforming Copernicus climate and hydrology datasets into analytics-ready outputs.

It is designed for ERA5, GloFAS, and extensible CDS/EWDS datasets, with an opinionated data engineering pipeline and optional Dask acceleration.

## Why spatioClimata

- Unified access to CDS and EWDS with one API key workflow.
- Dataset capability checks before large downloads.
- Hourly and daily workflows with optional frequency conversion.
- Resumable, idempotent download pipeline for long-running jobs.
- Analytics-ready outputs as xarray Dataset with NetCDF/Zarr export.
- Optional Dask integration for chunked processing at scale.

## Installation

```bash
pip install spatioClimata
```

For Dask-enabled workflows:

```bash
pip install "spatioClimata[dask]"
```

For development:

```bash
pip install "spatioClimata[dev,dask]"
```

## Quick Start

```python
from spatioclimata import (
    AreaBBox,
    TimeRange,
    FetchRequest,
    fetch,
)

request = FetchRequest(
    dataset="derived-era5-single-levels-daily-statistics",
    variables=["total_precipitation", "2m_temperature"],
  time_range=TimeRange.from_strings("2020-01-01", "2020-12-31"),
  area=AreaBBox.from_sequence([6.22, 80.41, 5.91, 80.64]),
    frequency="daily",
    output_dir="./outputs",
)

result = fetch(request, open_browser_on_missing_key=True)
print(result.saved_files)
```

## CLI Usage

Initialize credentials:

```bash
spatioclimata auth init --open-browser
```

List datasets:

```bash
spatioclimata datasets list
```

Run a download:

```bash
spatioclimata fetch \
  --dataset derived-era5-single-levels-daily-statistics \
  --variables total_precipitation,2m_temperature \
  --start 2020-01-01 \
  --end 2020-12-31 \
  --area 6.22,80.41,5.91,80.64 \
  --frequency daily \
  --output-dir ./outputs
```

## Account and API Key Onboarding

The package needs a Copernicus API key.

- `spatioclimata auth init --open-browser` opens signup and API key pages.
- Credentials are saved to a local config file with restricted permissions when possible.
- Environment variables are also supported:
  - `SPATIOCLIMATA_API_KEY`
  - `ERA5_Key`

## Project Layout

- `src/spatioclimata/`: package source
- `tests/`: unit tests
- `examples/`: runnable usage examples
- `docs/`: architecture and usage guides
- `.github/workflows/`: CI
- `website/`: static project website (GitHub Pages source)
- `scripts/`: helper scripts for repo bootstrap, website sync, and releases

## Documentation Index

- [Quickstart](docs/quickstart.md)
- [Architecture](docs/architecture.md)
- [Pipeline Guide](docs/pipeline.md)
- [Dataset Support](docs/dataset-support.md)
- [Release and Deploy](docs/release-deploy.md)

## Status

Current release is an MVP foundation intended to be expanded with additional dataset adapters and transformations.

## Release and Deployment

### PyPI Publish

- Workflow: `.github/workflows/publish-pypi.yml`
- Trigger: push a version tag (example: `v0.1.0`)
- Recommended: configure PyPI Trusted Publishing for this repository

### Website Deploy

- Workflow: `.github/workflows/deploy-pages.yml`
- Source folder: `website/`
- Trigger: push to `main` when website files change
- GitHub setting required: enable GitHub Pages with "GitHub Actions" as source

## License

MIT
