Metadata-Version: 2.4
Name: diurnalize
Version: 0.1.0a1
Summary: Mean-preserving diurnal disaggregation with Bayesian spatial-temporal shape modeling.
Author: Diurnalize contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/abcnishant007/diurnalize
Project-URL: Repository, https://github.com/abcnishant007/diurnalize
Project-URL: Issues, https://github.com/abcnishant007/diurnalize/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
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
Requires-Python: <3.13,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: scipy
Requires-Dist: scikit-learn
Requires-Dist: pyyaml
Requires-Dist: typer
Provides-Extra: model
Requires-Dist: arviz; extra == "model"
Requires-Dist: jinja2; extra == "model"
Requires-Dist: matplotlib; extra == "model"
Requires-Dist: netcdf4; extra == "model"
Requires-Dist: pymc; extra == "model"
Requires-Dist: xarray; extra == "model"
Provides-Extra: dev
Requires-Dist: arviz; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: jinja2; extra == "dev"
Requires-Dist: matplotlib; extra == "dev"
Requires-Dist: netcdf4; extra == "dev"
Requires-Dist: pymc; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: xarray; extra == "dev"
Dynamic: license-file

# Diurnalize

Diurnalize provides a reusable implementation of mean-preserving diurnal disaggregation. It decomposes a positive environmental variable into a spatial baseline level `B(x)` and a local time-of-day multiplier `S(x,k)`:

```text
Y(x,k) = B(x) * S(x,k)
```

The hierarchical shape model uses wrapped Gaussian temporal bases, low-rank spatial RBF bases with k-means centers and QR projection, sensor-specific bias, sensor-specific noise, and a time softmax so each predicted daily shape has mean 1.

## Quick Start

```bash
pip install "diurnalize[model]"
diurnalize generate-demo --output /tmp/diurnalize_demo --scenario null_shape --n-sensors 6 --n-days 2 --grid-resolution 5
diurnalize fit --config /tmp/diurnalize_demo/config.yaml --output /tmp/diurnalize_run --preset quick
diurnalize predict --run /tmp/diurnalize_run --grid /tmp/diurnalize_demo/baseline_grid.csv --output /tmp/diurnalize_run/predictions
diurnalize validate --run /tmp/diurnalize_run --output /tmp/diurnalize_run/validation
diurnalize report --run /tmp/diurnalize_run --output /tmp/diurnalize_run/report.html
```

The base package can be installed with `pip install diurnalize` for data loading,
configuration, synthetic demo generation, and CLI discovery. Install the
`model` extra for Bayesian fitting, prediction exports, validation plots, and
HTML reports.

## CSV Schemas

Observation CSVs require canonical headers matched case-insensitively only:

```text
sensor_id,lat,lon,timestamp_utc,value
```

Baseline grids require:

```text
lat,lon,baseline
```

Optional baseline columns include `cell_id`, `region_id`, and `area_weight`.

## Citation

If you find this package or the associated methods useful, please consider citing the associated paper. Paper reproduction workflows are intentionally kept outside this package.

## Development

```bash
pip install -e ".[dev]"
pytest
python -m build
python -m twine check dist/*
```
