Metadata-Version: 2.4
Name: neptoon
Version: 0.73.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
License-File: LICENSE
Keywords: CRNS,CRP,Cosmic-Ray Neutron Sensors,Cosmic-Ray Probe,Data Processing,Hydrology,soil,soil moisture
Requires-Python: >=3.11
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: typer<1,>=0.26
Requires-Dist: urllib3>=2.2.0
Provides-Extra: all
Requires-Dist: netcdf4>=1.6.5; 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: rosetta-soil>=0.3.2; extra == 'all'
Requires-Dist: streamlit>=1.31.0; extra == 'all'
Requires-Dist: xarray>=2024.1.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: black>=25.1.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: gui
Requires-Dist: plotly>=6.0.0; extra == 'gui'
Requires-Dist: streamlit>=1.31.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: 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 to produce field-scale soil moisture estimates. 

## 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**: Tools for N0 calibration using soil sampling data
- **External Data Integration**: Automatic integration with NMDB.eu for incoming neutron corrections
- **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 init --python 3.11
uv add neptoon
```

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

Comprehensive documentation is available at:
- [www.neptoon.org](https://www.neptoon.org) - Main documentation
- [User Guide](https://www.neptoon.org/en/latest/user-guide/workflow-description/) - Detailed workflow description
- [Examples](https://www.neptoon.org/en/latest/user-guide/neptoon-examples/) - Practical examples and tutorials

## Project Status

Neptoon is currently in active development. Version 1.0, focusing on stability and robustness, is expected soon. Future plans include:

- Roving CRNS processing capabilities
- Server/Docker versions for automated processing

## 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 — [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 is licensed under the MIT License. See the [LICENSE](https://codebase.helmholtz.cloud/cosmos/neptoon/-/blob/main/LICENSE) file for details.

## Citation

> Power, D., Schrön, M., Erxleben, F., Rosolem, R., & Zacharias, S. (2025). "Neptoon". Zenodo. doi:[10.5281/zenodo.19916004](https://doi.org/10.5281/zenodo.19916004)

<details>
<summary>BibTex</summary>

```bibtex
@software{Neptoon,
  author       = {Power, Daniel and Schrön, Martin and Erxleben, Fredo and Rosolem, Rafael and Zacharias, Steffen},
  title        = {Neptoon},
  month        = sep,
  year         = 2025,
  publisher    = {Zenodo},
  doi          = {10.5281/zenodo.19916004},
  url          = {https://doi.org/10.5281/zenodo.19916004},
}
```
</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

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.
