MARISCO

Marine radioactivity data standardisation & conversion

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:

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.