neptoon 0.14.0

The neptoon package makes CRNS processing and research simple.

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
• 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, reproduceable workflows, and comprehensive documentation

Installation

pip install neptoon

Isolated Environment with uv (recommended):

uv init --python 3.10
uv add neptoon

Isolated Environment with conda:

conda create -n neptoon python=3.10 ipykernel
conda activate neptoon
pip install neptoon

For more detailed instructions, see the installation documentation.

Quick Start

from neptoon.io.read import DataHubFromConfig
from neptoon.workflow.process_with_yaml import ProcessWithConfig
from neptoon.config import ConfigurationManager

# 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 examples with sample data are available in the neptoon_examples repository.

Documentation

Comprehensive documentation is available at:

• www.neptoon.org - Main documentation
• User Guide - Detailed workflow description
• 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 [e-mail]
• Issues: Report bugs or request features through GitLab issues
• Contributing: See the contribution guidelines for details on how to contribute

Authors and Acknowledgments

Lead Developers:

• Daniel Power ([e-mail])
• Martin Schrön ([e-mail])
• Louis Trinkle ([e-mail])
• Markus Köhli

Additional Contributors:

• Fredo Erxleben
• Steffen Zacharias
• Rafael Rosolem
• Daniel Rasche

License

Neptoon is licensed under the MIT License. See the LICENSE file for details.

Citation

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

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},
}

More Detailed Documentation

The agent/ directory contains in-depth guides covering project conventions and AI-assisted development workflows.

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 - Logger setup and log level conventions.
• Testing - Test organization, fixtures, markers, and CI pipeline.
• ColumnInfo - Column naming system and enum usage.
• Configuration - Pydantic config models and YAML loading.
• Hub Pattern - CRNSDataHub, DataFrames, and quality flags.
• Corrections - Factory/Builder pattern for the correction pipeline.
• Git Workflow - Branching, CI pipeline, and release process.

AI-Assisted Development

This repository includes an agent/ directory with configuration for AI coding agents (currently optimised for Claude Code). It contains coding conventions, reusable skills, and architecture documentation that help AI agents work effectively with the neptoon codebase.

If you use an AI coding agent, see agent/README.md for setup instructions. The convention files in agent/conventions/ are also useful reading for any developer — they document the patterns and practices used throughout the codebase.

If you use a different AI coding tool and want to contribute agent configuration for it, get in touch with the core developers.

Skills

Step-by-step guides that AI agents follow when performing common development tasks:

• CLAUDE.md - Root configuration for AI assistants working on this codebase.
• Convention Keeper - Systematic audit of the codebase against all project conventions.
• Meta Session - Structured planning workflow for substantial development tasks.