marisco 1.4.0

MARIS companion package and tutorials

MARISCO

The IAEA Marine Radioactivity Information System (MARIS) provides open access to radioactivity measurements in marine environments (seawater, biota, sediment, and suspended matter) collected by national laboratories, monitoring programmes, and research institutions worldwide. Developed by the IAEA Marine Environmental Laboratories in Monaco, MARIS is the authoritative international reference for marine radioactivity data.

marisco is being developed as the data processing foundation of MARIS: a Python package that converts provider datasets into standardised NetCDF4 and CSV formats for ingestion into the MARIS database.

Transparency by design

Each dataset is processed by a dedicated handler, a Jupyter notebook that documents every curation decision alongside the code that implements it. Unit conversions, nuclide nomenclature mapping, coordinate standardisation, outlier flags: every choice is visible, traceable, and auditable.

Handlers are shared with data providers as a working document. If a conversion looks wrong, a mapping is missing, or terminology differs from your internal standards, the notebook is where we discuss and resolve it; not buried in email threads or internal comments.

For a concrete example, see the GEOTRACES handler.

Available handlers

Handler	Description	Data source	Status
HELCOM	Baltic Sea marine environment monitoring	HELCOM	✅ Active
GEOTRACES	BODC GEOTRACES oceanographic radionuclide data	GEOTRACES IDP2021	✅ Active
MARIS Legacy	Historical MARIS datasets from the master database	—	⚠️ Migrating
OSPAR	NE Atlantic marine environment datasets	ODIMS OSPAR	⚠️ Migrating
TEPCO	TEPCO Fukushima Daiichi monitoring data	TEPCO Monitoring	⚠️ Migrating

Migrating: handler is functional but being updated to the current matching API.

Install

pip install marisco

Two environment variables may be required depending on the dataset:

• ZOTERO_API_KEY: used to fetch bibliographic metadata from the MARIS Zotero library. Contact MARIS Administrators to obtain your key:

  export ZOTERO_API_KEY=your_api_key_here
  

• INIS: bibliographic metadata is being progressively migrated from Zotero to the IAEA INIS database. The INISClient fetches records via curl, which must be installed separately. In the near term both systems coexist; INIS will supersede Zotero as the migration completes.

Quick start

Command line utilities

All commands accept -h for full documentation.

Convert a provider dataset to MARIS NetCDF4:

maris_to_nc ospar 191-OSPAR-2024.nc

Convert the MARIS legacy database dump to NetCDF4:

maris_db_to_nc "~/data/maris/dump.txt" ~/output
# or a subset:
maris_db_to_nc "~/data/maris/dump.txt" ~/output --ref_ids="16,30"

Convert a NetCDF4 file to MARIS-format CSV (for database import):

maris_nc_to_csv ~/output/191-OSPAR-2024.nc ~/output/191-OSPAR-2024

The CSV utility appends the sample type automatically (e.g. 191-OSPAR-2024_BIOTA.csv), and may generate multiple files — one per sample type present in the source dataset.

Documentation

Documentation is organised into two groups:

How-to guides

Practical walkthroughs for common tasks:

• Writing a new handler: step-by-step guide to adding a new data provider to the marisco pipeline
• Nomenclature reconciliation: repeatable procedure for mapping provider names (nuclides, species, units, …) to MARIS standard identifiers

Reference

Detailed specifications and reference material:

• MARIS Data Guide: overview of sample types, measurement fields, nomenclature, curation pipeline, and available datasets; aimed at data providers and data users
• Field Definitions: complete field-by-field reference with MARISCO column names, NetCDF variable names, CSV variable names, types, and lookup tables
• Data Curation Rules: rules applied during data curation across all handlers
• Enum Rules: enumeration value handling rules
• Sample ID Coverage: coverage analysis of sample identifiers
• Sample Uniqueness: sample uniqueness constraints and validation

Development

The MARIS NetCDF template is generated from nbs/files/cdl/maris.cdl. To regenerate it locally, install NetCDF-C and run:

ncgen -4 -o nbs/files/nc/maris-template.nc nbs/files/cdl/maris.cdl

Contributor guidance — architecture, coding conventions, handler documentation style — is in the CRAFTs/ notebooks at the repository root.

Acknowledgements

Development of this package was supported by the Solveit platform, an interactive development environment for dialog-driven software engineering.