Welcome to 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.
How it works
MARIS does not impose a data schema on providers. It accepts data in whatever form it arrives, and it makes the cost of that acceptance visible.
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. Some formats need less work than others, and the handler makes that difference plain. If you are a data provider, see contributing data for what this means for your dataset.
This is deliberate. The friction a dataset creates is a signal, and surfacing it is the point. It tells the MARIS team how much work a provider’s format really requires, it gives the provider a concrete, itemised record of what to improve, and it makes the next release of the dataset cheaper to ingest. Over time, the easiest path for everyone is for providers to align with the MARIS way of organising data, not because it is imposed, but because the cost of not doing so is visible.
The payoff is a harmonised world reference: measurements of marine radioactivity from providers worldwide, stored in the MARIS database in one comparable form. That comparability is the real value, for data providers, for the scientific community, and beyond. It rests on visible curation: the process that made the data comparable is documented and auditable, so the harmonisation can be checked, questioned, and trusted.
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.
The harmonised data reaches users through three channels: the explore portal for interactive visualisation, the datasets page for downloading individual NetCDF files (joined soon by INIS), and the MARIS API for programmatic access.
Available handlers
| Handler | Description | Status |
|---|---|---|
| FRAM STRAIT | Fram Strait 2020-2025 I-129, U-236, U-238 seawater radionuclide data | Active |
| GEOTRACES | BODC GEOTRACES oceanographic radionuclide data | Active |
| HELCOM | Baltic Sea marine environment monitoring data | Active |
| JOIS | BGOS-JOIS Beaufort Sea seawater radionuclide data | Active |
| OSPAR | OSPAR radioactive substances monitoring data (seawater and biota) | Under review |
| TEPCO | TEPCO data | Under refactoring |
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_hereVS Code reads environment variables only when it starts. To set the key without restarting VS Code, put
ZOTERO_API_KEY=your_api_key_herein a.envfile at the root of your VS Code workspace, then restart the notebook kernel. -
INIS: bibliographic metadata is being progressively migrated from Zotero to the IAEA INIS database. In the near term both systems coexist; INIS will supersede Zotero as the migration completes.
Command-line utilities
All commands accept -h for help.
Ingest a provider dataset
$ marisco-ingest helcom output/100-HELCOM-MORS-2024.nc
The handler name selects the provider. Each handler decides whether to download the source data or read it from a local file.
Ingest a MARIS legacy database dump
$ marisco-ingest maris_legacy ~/output --src ~/data/maris/dump.txt
To process only selected references:
$ marisco-ingest maris_legacy ~/output \
--src ~/data/maris/dump.txt \
--ref_ids "16,30"
If a handler produces several files, the command writes them to the destination folder. It creates the folder if it does not exist.
Export NetCDF4 to MARIS CSV
$ marisco-export ~/output/191-OSPAR-2024.nc
The command appends the sample type to the output name. For example,
191-OSPAR-2024_BIOTA.csv. It creates one CSV file for each sample type in the
NetCDF4 file.
Use --dest to choose a different output stem.
Check Zenodo for new datasets and versions
$ marisco-poll
The command lists each Zenodo record that a handler reads and whose dataset has a newer version, with the id of the newer record. It also lists the datasets in the TITANICA Zenodo community that no handler reads. Use --community to check another community.
Documentation
Documentation is organised into three groups.
Onboarding
A staged path for MARIS team members who will create handlers with the help of an AI agent. It starts with setting up your machine.
How-to guides
Practical walkthroughs for common tasks:
- Contributing data to MARIS: how a data provider delivers a dataset to the repository
- 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
- Explore a MARIS NetCDF file: step-by-step guide to reading a MARIS NetCDF file: global metadata, group structure, lookup tables and nomenclatures, and each sample-type dataset as a pandas DataFrame
Reference
Detailed specifications and reference material:
- Reporting template: the MARIS data reporting template as documentation, with the general instructions, per-sample-type column tables, and lookup lists
- Field Definitions: complete field-by-field reference with MARISCO column names, NetCDF variable names, CSV variable names, types, and lookup tables
- MARIS database schema: the master database
sampleandmeasuretables, their mandatory columns, and their constraints
Development
marisco follows the nbdev workflow: all code lives in notebooks under nbs/, and the marisco/ package is generated from them.
- Edit the notebooks in
nbs/, then runnbdev-exportto regenerate the modules andnbdev-readmeto regenerate this README. - After changing
pyproject.toml(entry points, dependencies), reinstall the package withpip install -e .. - 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 on architecture, coding conventions, and handler documentation style lives in the
CRAFTs/notebooks at the repository root. - Writing a new handler walks through adding a new data provider to the pipeline.
Acknowledgements
Development of this package was supported by the Solveit platform, an interactive development environment for dialog-driven software engineering.
1 maintainer
Metadata
1 maintainer
Release files for marisco 1.12.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| marisco-1.12.0.tar.gz | 3.5 MB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| marisco-1.12.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 7.0 MB
Release files / marisco-1.12.0.tar.gz
| Download URL | marisco-1.12.0.tar.gz |
|---|---|
| Size | 3.5 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9d75812f12783bcd017628b36740ff1b9830ff79f74a0e44892891746114016e
|
|
BLAKE2b-256 checksum How to use checksums |
ec904f197172efb92adb9b0ea523584f831b196c07268f2b4603c08a2b3a7117
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.13
|
Release files / marisco-1.12.0-py3-none-any.whl
| Download URL | marisco-1.12.0-py3-none-any.whl |
|---|---|
| Size | 3.5 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e5989dc7d2c32a5bb7cedcaef4fd67bf67581d87019f30b5407be1707efb5b14
|
|
BLAKE2b-256 checksum How to use checksums |
a41c256da552350e088d3c78d7859a9b36ec635dcf389a4146371910c87eb0bf
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.13
|
Security for marisco 1.12.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
