Metadata-Version: 2.4
Name: neptoon
Version: 1.11.3
Summary: Neptoon makes data processing for CRNS and its research simple.
Project-URL: Homepage, https://www.neptoon.org
Project-URL: Repository, https://codebase.helmholtz.cloud/cosmos/neptoon
Project-URL: Documentation, https://www.neptoon.org
Author-email: Daniel Power <dpower-rse@pm.me>, Martin Schroen <martin.schroen@ufz.de>, Louis Ferdinand Trinkle <louis-ferdinand.trinkle@ufz.de>, Markus Koehli <markus.koehli@ufz.de>
License-Expression: MIT AND LicenseRef-JAEA-EXPACS
License-File: LICENSE
License-File: THIRD-PARTY-LICENSES.md
Keywords: CRNS,CRP,Cosmic-Ray Neutron Sensors,Cosmic-Ray Probe,Data Processing,Hydrology,soil,soil moisture
Requires-Python: >=3.11
Requires-Dist: certifi>=2026.10.19
Requires-Dist: figurex>=0.2.15
Requires-Dist: magazine>=0.4.0
Requires-Dist: matplotlib<4,>=3.8
Requires-Dist: numpy>=2.0
Requires-Dist: pandas>=3.0.2
Requires-Dist: pandera>=0.31
Requires-Dist: platformdirs>=4.2.0
Requires-Dist: pyarrow<25,>=18.0.0
Requires-Dist: pydantic>=2.6.1
Requires-Dist: python-dateutil>=2.8.2
Requires-Dist: pyyaml>=6.0.1
Requires-Dist: requests>=2.31.0
Requires-Dist: rich>=13.9.4
Requires-Dist: saqc>=2.9
Requires-Dist: scipy<2,>=1.13
Requires-Dist: threadpoolctl<4,>=3.6
Requires-Dist: typer<1,>=0.26
Requires-Dist: urllib3>=2.2.0
Provides-Extra: all
Requires-Dist: branca>=0.8; extra == 'all'
Requires-Dist: earthengine-api>=1.5.0; extra == 'all'
Requires-Dist: folium>=0.20; extra == 'all'
Requires-Dist: fsspec<2027,>=2024.6; extra == 'all'
Requires-Dist: geopandas>=1.0; extra == 'all'
Requires-Dist: ipython>=8.0; extra == 'all'
Requires-Dist: matplotlib>=3.8; extra == 'all'
Requires-Dist: netcdf4>=1.6.5; extra == 'all'
Requires-Dist: osmnx>=2.0; extra == 'all'
Requires-Dist: paho-mqtt<3,>=2.1; extra == 'all'
Requires-Dist: paramiko>=3.4.0; extra == 'all'
Requires-Dist: plotly>=6.0.0; extra == 'all'
Requires-Dist: psycopg[binary]<4,>=3.1; extra == 'all'
Requires-Dist: pykrige>=1.7; extra == 'all'
Requires-Dist: pymongo<5,>=4.6; extra == 'all'
Requires-Dist: pymysql<2,>=1.1; extra == 'all'
Requires-Dist: pyproj>=3.6; extra == 'all'
Requires-Dist: pystac-client>=0.8; extra == 'all'
Requires-Dist: rasterio>=1.4; extra == 'all'
Requires-Dist: rosetta-soil>=0.3.2; extra == 'all'
Requires-Dist: s3fs<2027,>=2024.6; extra == 'all'
Requires-Dist: shapely>=2.0; extra == 'all'
Requires-Dist: sqlalchemy<3,>=2; extra == 'all'
Requires-Dist: streamlit>=1.52.0; extra == 'all'
Requires-Dist: tifffile>=2024.1.30; extra == 'all'
Requires-Dist: xarray>=2024.1.0; extra == 'all'
Requires-Dist: zarr<3,>=2.18.7; extra == 'all'
Provides-Extra: calibration-interpolation
Requires-Dist: geopandas>=1.0; extra == 'calibration-interpolation'
Requires-Dist: pyproj>=3.6; extra == 'calibration-interpolation'
Requires-Dist: rasterio>=1.4; extra == 'calibration-interpolation'
Requires-Dist: shapely>=2.0; extra == 'calibration-interpolation'
Provides-Extra: database-mongodb
Requires-Dist: pymongo<5,>=4.6; extra == 'database-mongodb'
Provides-Extra: database-mysql
Requires-Dist: pymysql<2,>=1.1; extra == 'database-mysql'
Requires-Dist: sqlalchemy<3,>=2; extra == 'database-mysql'
Provides-Extra: database-postgresql
Requires-Dist: psycopg[binary]<4,>=3.1; extra == 'database-postgresql'
Requires-Dist: sqlalchemy<3,>=2; extra == 'database-postgresql'
Provides-Extra: databases
Requires-Dist: psycopg[binary]<4,>=3.1; extra == 'databases'
Requires-Dist: pymongo<5,>=4.6; extra == 'databases'
Requires-Dist: pymysql<2,>=1.1; extra == 'databases'
Requires-Dist: sqlalchemy<3,>=2; extra == 'databases'
Provides-Extra: dev
Requires-Dist: pre-commit>=4.0; extra == 'dev'
Requires-Dist: pytest-cov>=6.2.1; extra == 'dev'
Requires-Dist: pytest>=9.1.0; extra == 'dev'
Requires-Dist: ruff>=0.15.13; extra == 'dev'
Requires-Dist: yamllint>=1.35.0; extra == 'dev'
Provides-Extra: gee
Requires-Dist: earthengine-api>=1.5.0; extra == 'gee'
Provides-Extra: geo
Requires-Dist: fsspec<2027,>=2024.6; extra == 'geo'
Requires-Dist: netcdf4>=1.6.5; extra == 'geo'
Requires-Dist: pyproj>=3.6; extra == 'geo'
Requires-Dist: pystac-client>=0.8; extra == 'geo'
Requires-Dist: rasterio>=1.4; extra == 'geo'
Requires-Dist: s3fs<2027,>=2024.6; extra == 'geo'
Requires-Dist: xarray>=2024.1.0; extra == 'geo'
Requires-Dist: zarr<3,>=2.18.7; extra == 'geo'
Provides-Extra: gui
Requires-Dist: plotly>=6.0.0; extra == 'gui'
Requires-Dist: streamlit>=1.52.0; extra == 'gui'
Provides-Extra: mqtt
Requires-Dist: paho-mqtt<3,>=2.1; extra == 'mqtt'
Provides-Extra: netcdf
Requires-Dist: netcdf4>=1.6.5; extra == 'netcdf'
Requires-Dist: xarray>=2024.1.0; extra == 'netcdf'
Provides-Extra: roving
Requires-Dist: branca>=0.8; extra == 'roving'
Requires-Dist: folium>=0.20; extra == 'roving'
Requires-Dist: geopandas>=1.0; extra == 'roving'
Requires-Dist: ipython>=8.0; extra == 'roving'
Requires-Dist: netcdf4>=1.6.5; extra == 'roving'
Requires-Dist: osmnx>=2.0; extra == 'roving'
Requires-Dist: plotly>=6.0; extra == 'roving'
Requires-Dist: pykrige>=1.7; extra == 'roving'
Requires-Dist: pyproj>=3.6; extra == 'roving'
Requires-Dist: rasterio>=1.4; extra == 'roving'
Requires-Dist: shapely>=2.0; extra == 'roving'
Requires-Dist: tifffile>=2024.1.30; extra == 'roving'
Requires-Dist: xarray>=2024.1.0; extra == 'roving'
Provides-Extra: roving-geo
Requires-Dist: geopandas>=1.0; extra == 'roving-geo'
Requires-Dist: osmnx>=2.0; extra == 'roving-geo'
Requires-Dist: pyproj>=3.6; extra == 'roving-geo'
Requires-Dist: rasterio>=1.4; extra == 'roving-geo'
Requires-Dist: shapely>=2.0; extra == 'roving-geo'
Requires-Dist: tifffile>=2024.1.30; extra == 'roving-geo'
Provides-Extra: roving-interpolation
Requires-Dist: pykrige>=1.7; extra == 'roving-interpolation'
Provides-Extra: roving-maps
Requires-Dist: branca>=0.8; extra == 'roving-maps'
Requires-Dist: folium>=0.20; extra == 'roving-maps'
Requires-Dist: ipython>=8.0; extra == 'roving-maps'
Requires-Dist: matplotlib>=3.8; extra == 'roving-maps'
Provides-Extra: roving-terrain
Requires-Dist: plotly>=6.0; extra == 'roving-terrain'
Provides-Extra: roving-webgl
Requires-Dist: pyproj>=3.6; extra == 'roving-webgl'
Provides-Extra: sftp
Requires-Dist: paramiko>=3.4.0; extra == 'sftp'
Provides-Extra: soil-hydraulics
Requires-Dist: rosetta-soil>=0.3.2; extra == 'soil-hydraulics'
Description-Content-Type: text/markdown

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/branding/neptoon-banner-dark.jpg">
  <source media="(prefers-color-scheme: light)" srcset="docs/assets/branding/neptoon-banner-light.jpg">
  <img src="docs/assets/branding/neptoon-banner-light.jpg" alt="Neptoon banner" width="100%">
</picture>

# neptoon

[![PyPI version](https://img.shields.io/pypi/v/neptoon.svg)](https://pypi.org/project/neptoon/)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.19916004.svg)](https://doi.org/10.5281/zenodo.19916004)
[![Documentation](https://img.shields.io/badge/docs-latest-blue.svg)](https://www.neptoon.org)
[![License](https://img.shields.io/pypi/l/neptoon.svg)](https://codebase.helmholtz.cloud/cosmos/neptoon/-/blob/main/LICENSE)
[![PyPI Downloads](https://static.pepy.tech/badge/neptoon)](https://pepy.tech/projects/neptoon)


neptoon is a Python package for processing Cosmic-Ray Neutron Sensor (CRNS)
data and estimating field-scale soil moisture. It supports stationary and
roving workflows, quality assessment, sensor calibration and field-sampling
planning.

## Key Features

- **Modular Correction Pipeline**: Apply multiple correction methods for pressure, incoming intensity, humidity, and biomass
- **Quality Assessment**: Built-in data quality checks integrated with [SaQC](https://rdm-software.pages.ufz.de/saqc/index.html)
- **Sensor Calibration**: Method-aware N0/I_D calibration using soil sampling data
- **External Data Integration**: Automatic integration with NMDB.eu for incoming neutron corrections
- **Roving CRNS**: Process mobile surveys with track-aware QA/corrections, shared geospatial adapters, gridding, footprints, interpolation, maps, and terrain products
- **Multiple Interfaces**: Use via Python API, configuration files, or GUI
- **Published Science**: Implementations based on peer-reviewed methodologies
- **Reproducibility**: Built-in reporting, reproducible workflows, and comprehensive documentation


## Installation

```bash
pip install neptoon
```

Isolated Environment with **uv** (recommended):
```bash
uv venv --python 3.11
uv pip install neptoon
```

These commands install Neptoon into a local `.venv` without creating a new
project or modifying an existing `pyproject.toml`.

Isolated Environment with **conda**:
```bash
conda create -n neptoon python=3.11 ipykernel
conda activate neptoon
pip install neptoon
```

For more detailed instructions, see the [installation documentation](https://www.neptoon.org/en/latest/user-guide/installation/).

## Quick Start

```python
from neptoon.config import ConfigurationManager
from neptoon.workflow import ProcessWithConfig

# Load configurations
config = ConfigurationManager()
config.load_configuration(file_path="path/to/sensor_config.yaml")
config.load_configuration(file_path="path/to/processing_config.yaml")

# Process data
yaml_processor = ProcessWithConfig(configuration_object=config)
yaml_processor.run_full_process()
```

Ready-to-use configurations, sample data, scripts, and notebooks are indexed in [examples/README.md](examples/README.md).

## Documentation

The documentation is published at [www.neptoon.org](https://www.neptoon.org).
The same source pages can also be opened directly in the GitLab repository:

- [Documentation home](docs/index.md) — All documentation entry points.
- [Beginner's guide](docs/user-guide/beginners-guide.md) — First steps with Neptoon.
- [CRNS history](docs/user-guide/crns-history.md) — Background and development of CRNS.
- [Scientific literature](docs/scientific-literature.md) — Primary references for the implemented methods.
- [Site planning and sampling](docs/user-guide/site-planer.md) — Sampling schemes and the interactive Site planer.
- [Workflow guide](docs/user-guide/workflow-description.md) — Detailed processing workflow.
- [Examples](docs/user-guide/neptoon-examples.md) — Practical examples and tutorials.

These relative `.md` links work in the GitLab Markdown view; MkDocs resolves the
corresponding source-page links in `docs/index.md` into published website URLs.

## Project Status

Neptoon 1.0 is the first stable release. Since 1.0, breaking configuration changes should be limited to major versions. Development continues; see the [roadmap](https://www.neptoon.org/en/latest/home/roadmap/) for planned work.

## Support and Contribution

- **Contact**: Email us at [contact@neptoon.org](mailto:contact@neptoon.org)
- **Issues**: Report bugs or request features through [GitLab issues](https://codebase.helmholtz.cloud/cosmos/neptoon/-/issues)
- **Contributing**: See the [contribution guidelines](https://www.neptoon.org/en/latest/contribution/overview-contribution/) for details on how to contribute

## Authors and Acknowledgments

**Lead Developers:**

- Daniel Power — [ORCID](https://orcid.org/0000-0002-0829-8580) · [Email](mailto:daniel.power@ufz.de)
- Martin Schrön — [ORCID](https://orcid.org/0000-0002-0220-0677) · [Homepage](https://www.ufz.de/index.php?en=38055) · [Email](mailto:martin.schroen@ufz.de)
- Louis Trinkle — [ORCID](https://orcid.org/0009-0003-0434-939X) · [Email](mailto:louis-ferdinand.trinkle@ufz.de)
- Markus Köhli — [ORCID](https://orcid.org/0000-0001-6098-3094) · [Homepage](https://www.physi.uni-heidelberg.de/Forschung/ANP/Cascade/Team/Markus.php) · [Email](mailto:markus.koehli@ufz.de)

**Acknowledgments:**

- Fredo Erxleben — [ORCID](https://orcid.org/0000-0001-7233-3005)
- Steffen Zacharias — [ORCID](https://orcid.org/0000-0002-7825-0072)
- Rafael Rosolem — [ORCID](https://orcid.org/0000-0002-4914-692X) · [Homepage](https://research-information.bris.ac.uk/en/persons/rafael-rosolem/)
- Miguel Rico-Ramirez — [ORCID](https://orcid.org/0000-0002-8885-4582)
- Till Francke — [ORCID](https://orcid.org/0000-0001-8934-4421)
- Daniel Rasche — [ORCID](https://orcid.org/0000-0003-4611-0750)

## License

Neptoon's original code is licensed under [MIT](LICENSE). The bundled
PARMA/EXPACS model and data are **not covered by the MIT grant** and have
separate JAEA terms restricting commercial use. Supplemental detector-response
files also need a provenance and redistribution review. See
[THIRD-PARTY-LICENSES.md](THIRD-PARTY-LICENSES.md) before redistributing the
package, especially for commercial use.

## Citation

Cite the archived version you used. The exact-version citation below points to
the latest archived Zenodo release; the source-tree package `VERSION` may be
ahead while the next release is being prepared. The badge above uses the concept
DOI, which covers all versions.

<!-- release:version-doi:start -->
> Power, D., Köhli, M., Schrön, M., Trinkle, L., Erxleben, F., Rosolem, R., & Zacharias, S. (2026). Neptoon (Version 1.11.3) [Software]. Zenodo. [https://doi.org/10.5281/zenodo.23597347](https://doi.org/10.5281/zenodo.23597347)
<!-- release:version-doi:end -->

<details>
<summary>BibTex</summary>

<!-- release:version-doi:start -->
```bibtex
@software{Neptoon,
  author       = {Power, Daniel and Köhli, Markus and Schrön, Markus and Trinkle, Louis and Erxleben, Fredo and Rosolem, Rafael and Zacharias, Steffen},
  title        = {Neptoon},
  year         = 2026,
  publisher    = {Zenodo},
  version      = {v1.11.3},
  doi          = {10.5281/zenodo.23597347},
  url          = {https://doi.org/10.5281/zenodo.23597347},
}
```
<!-- release:version-doi:end -->
</details>

## More Detailed Documentation

### Scientific literature

The scientific methods implemented or discussed by Neptoon are linked to their primary and supporting references in the [scientific literature documentation](docs/scientific-literature.md).

### Conventions

These documents define the coding standards and architectural patterns used throughout the project. They serve as the single source of truth for both human contributors and AI assistants.

- [Logging](agent/conventions/logging.md) - Logger setup and log level conventions.
- [Testing](agent/conventions/testing.md) - Test organization, fixtures, markers, and CI pipeline.
- [ColumnInfo](agent/conventions/column_info.md) - Column naming system and enum usage.
- [Configuration](agent/conventions/configuration.md) - Pydantic config models and YAML loading.
- [Hub Pattern](agent/conventions/hub_pattern.md) - CRNSDataHub, DataFrames, and quality flags.
- [Corrections](agent/conventions/corrections.md) - Factory/Builder pattern for the correction pipeline.
- [Git Workflow](agent/conventions/git_workflow.md) - Branching, CI pipeline, and release process.

## AI-Assisted Development

The repository includes durable guidance for coding agents and contributors:

- [`AGENTS.md`](AGENTS.md) — universal entry point and toolchain rules
- [`agent/code-overview.md`](agent/code-overview.md) — detailed find/edit/test map
- [`agent/architecture.md`](agent/architecture.md) — stable architecture summary
- [`agent/conventions/`](agent/conventions/) — recurring implementation conventions
- [`agent/decisions/`](agent/decisions/) — architecture and policy records
- [`agent/playbooks/convention-audit.md`](agent/playbooks/convention-audit.md) — project-specific guidance audit
- [`agent/playbooks/add-meteo-provider.md`](agent/playbooks/add-meteo-provider.md) — provider integration checklist
- [`agent/playbooks/add-report-figure.md`](agent/playbooks/add-report-figure.md) — report figure/config/PDF integration
- [`agent/playbooks/debug-ci-regression.md`](agent/playbooks/debug-ci-regression.md) — reproduce and diagnose CI regressions

Temporary plans, session memory, current priorities, contributor profiles, and agent
personas are local concerns and are intentionally not tracked. See
[`agent/README.md`](agent/README.md) for the repository/local boundary.
