# MARISCO
<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->
The [IAEA **M**arine **R**adioactivity **I**nformation **S**ystem
(MARIS)](https://maris.iaea.org) provides open access to radioactivity
measurements in marine environments. Developed by the [IAEA Marine
Environmental
Laboratories](https://www.iaea.org/about/organizational-structure/department-of-nuclear-sciences-and-applications/division-of-iaea-environment-laboratories)
in Monaco, MARIS offers data on seawater, biota, sediment, and suspended
matter.
This Python package includes command-line tools to convert MARIS
datasets into [`NetCDF`](https://www.unidata.ucar.edu/software/netcdf/)
or `.csv` formats, enhancing compatibility with various scientific and
data analysis software.
## Core Concept: Handlers
`marisco` is built around the concept of `handlers` - specialized
modules designed to convert MARIS datasets into NetCDF format. Each
handler is tailored to a specific data provider and implemented as a
dedicated Jupyter notebook.
### Literate Programming Approach
We’ve adopted a Literate Programming approach, which means:
1. **Documentation**: Each handler serves as comprehensive
documentation.
2. **Code Reference**: The notebooks contain the actual implementation
code.
3. **Communication Tool**: They facilitate discussions with data
providers about discrepancies or inconsistencies.
### Powered by nbdev
To achieve this, we leverage [nbdev](https://nbdev.fast.ai), a powerful
tool that allows us to:
1. Write code within Jupyter notebooks
2. Automatically export relevant parts as dedicated Python modules
This approach bridges the gap between documentation and implementation,
ensuring they remain in sync.
### See It in Action
For a concrete example of this approach, check out our [HELCOM dataset
handler
implementation](https://fr.anckalbi.net/marisco/handlers/helcom.html).
Please note that this project is **still under development**.
We have implemented the [MARIS Legacy
handler](https://fr.anckalbi.net/marisco/handlers/maris_legacy.html) to
convert all existing datasets from the MARIS master database into NetCDF
format. For datasets that are frequently updated, such as
[HELCOM](https://fr.anckalbi.net/marisco/handlers/helcom.html),
[OSPAR](https://www.ospar.org/), and TEPCO/Fukushima-related datasets,
individual handlers are currently being developed and will be available
soon.
## Install
Now, to install `marisco` simply run
``` console
pip install marisco
```
Once successfully installed, run the following command:
``` console
maris_init
```
This command:
1. creates a `.marisco/` directory containing various
configuration/configurable files ((below)) in your `/home`
directory;
2. creates a `configs.toml` file containing default but configurable
settings (default paths, …);
3. downloads several MARIS DB nomenclature/lookup table into
`.marisco/lut/` directory;
4. downloads `maris-template.nc`, the MARIS NetCDF4 template.
> [!TIP]
>
> For inexperienced Python users, please refers to [How to setup
> `Marisco` with
> Anaconda](https://github.com/franckalbinet/marisco/tree/main/install_configure_guide/windows_anaconda)
> or [How to setup `Marisco` with Windows Subsystem for Linux (WSL) and
> Visual Studio Code
> editor](https://github.com/franckalbinet/marisco/tree/main/install_configure_guide//windows_ubuntu_sub_system).
### Zotero API key
Upon conversion, `marisco` will automatically retrieve the bibliographic
metadata of each MARIS dataset from [Zotero](https://www.zotero.org/).
To do so, you need to define the following environment variable
`ZOTERO_API_KEY` containing the MARIS Zotero API key. Please contact the
MARIS team to get your API key.
## Getting started
### Command line utilities
All commands accept a `-h` argument to get access to its documentation.
#### `maris_init`
Donwload configuration file, NetCDF MAris template and required lookup
tables (nomenclatures).
#### `maris_netcdfy`
Encode MARIS dataset as NetCDF
Positional arguments:
- `handler_name`: Handler’s name (e.g helcom, …)
- `str`: Path to dataset to encode
- `dest`: Path to converted NetCDF4
Example:
``` console
maris_netcdfy helcom _data/accdb/mors/csv _data/output/helcom.nc
```
## Development
The MARIS NetCDF template is generated from `nbs/files/cdl/maris.cdl`
Common Data Language (CDL) file as defined by
[Unidata](https://docs.unidata.ucar.edu/). To generate the MARIS NetCDF
template `nbs/files/nc/maris-template.nc`, install the
[NetCDF-C](https://pjbartlein.github.io/REarthSysSci/install_netCDF.html)
utilities, once in `Marisco` home directory, run:
``` console
ncgen -4 -o nc/maris-template.nc cdl/maris.cdl
```
Raw data
{
"_id": null,
"home_page": "https://github.com/franckalbinet/marisco",
"name": "marisco",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "nbdev jupyter notebook python",
"author": "Franck Albinet",
"author_email": "franckalbinet@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/83/a8/df2e14f4890b01f73b82d10ee95bca0a4ba3faaf7eb989f3089abd4dfa78/marisco-0.8.0.tar.gz",
"platform": null,
"description": "# MARISCO\n\n\n<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->\n\nThe [IAEA **M**arine **R**adioactivity **I**nformation **S**ystem\n(MARIS)](https://maris.iaea.org) provides open access to radioactivity\nmeasurements in marine environments. Developed by the [IAEA Marine\nEnvironmental\nLaboratories](https://www.iaea.org/about/organizational-structure/department-of-nuclear-sciences-and-applications/division-of-iaea-environment-laboratories)\nin Monaco, MARIS offers data on seawater, biota, sediment, and suspended\nmatter.\n\nThis Python package includes command-line tools to convert MARIS\ndatasets into [`NetCDF`](https://www.unidata.ucar.edu/software/netcdf/)\nor `.csv` formats, enhancing compatibility with various scientific and\ndata analysis software.\n\n## Core Concept: Handlers\n\n`marisco` is built around the concept of `handlers` - specialized\nmodules designed to convert MARIS datasets into NetCDF format. Each\nhandler is tailored to a specific data provider and implemented as a\ndedicated Jupyter notebook.\n\n### Literate Programming Approach\n\nWe\u2019ve adopted a Literate Programming approach, which means:\n\n1. **Documentation**: Each handler serves as comprehensive\n documentation.\n2. **Code Reference**: The notebooks contain the actual implementation\n code.\n3. **Communication Tool**: They facilitate discussions with data\n providers about discrepancies or inconsistencies.\n\n### Powered by nbdev\n\nTo achieve this, we leverage [nbdev](https://nbdev.fast.ai), a powerful\ntool that allows us to:\n\n1. Write code within Jupyter notebooks\n2. Automatically export relevant parts as dedicated Python modules\n\nThis approach bridges the gap between documentation and implementation,\nensuring they remain in sync.\n\n### See It in Action\n\nFor a concrete example of this approach, check out our [HELCOM dataset\nhandler\nimplementation](https://fr.anckalbi.net/marisco/handlers/helcom.html).\n\nPlease note that this project is **still under development**.\n\nWe have implemented the [MARIS Legacy\nhandler](https://fr.anckalbi.net/marisco/handlers/maris_legacy.html) to\nconvert all existing datasets from the MARIS master database into NetCDF\nformat. For datasets that are frequently updated, such as\n[HELCOM](https://fr.anckalbi.net/marisco/handlers/helcom.html),\n[OSPAR](https://www.ospar.org/), and TEPCO/Fukushima-related datasets,\nindividual handlers are currently being developed and will be available\nsoon.\n\n## Install\n\nNow, to install `marisco` simply run\n\n``` console\npip install marisco\n```\n\nOnce successfully installed, run the following command:\n\n``` console\nmaris_init\n```\n\nThis command:\n\n1. creates a `.marisco/` directory containing various\n configuration/configurable files ((below)) in your `/home`\n directory;\n2. creates a `configs.toml` file containing default but configurable\n settings (default paths, \u2026);\n3. downloads several MARIS DB nomenclature/lookup table into\n `.marisco/lut/` directory;\n4. downloads `maris-template.nc`, the MARIS NetCDF4 template.\n\n> [!TIP]\n>\n> For inexperienced Python users, please refers to [How to setup\n> `Marisco` with\n> Anaconda](https://github.com/franckalbinet/marisco/tree/main/install_configure_guide/windows_anaconda)\n> or [How to setup `Marisco` with Windows Subsystem for Linux (WSL) and\n> Visual Studio Code\n> editor](https://github.com/franckalbinet/marisco/tree/main/install_configure_guide//windows_ubuntu_sub_system).\n\n### Zotero API key\n\nUpon conversion, `marisco` will automatically retrieve the bibliographic\nmetadata of each MARIS dataset from [Zotero](https://www.zotero.org/).\nTo do so, you need to define the following environment variable\n`ZOTERO_API_KEY` containing the MARIS Zotero API key. Please contact the\nMARIS team to get your API key.\n\n## Getting started\n\n### Command line utilities\n\nAll commands accept a `-h` argument to get access to its documentation.\n\n#### `maris_init`\n\nDonwload configuration file, NetCDF MAris template and required lookup\ntables (nomenclatures).\n\n#### `maris_netcdfy`\n\nEncode MARIS dataset as NetCDF\n\nPositional arguments:\n\n- `handler_name`: Handler\u2019s name (e.g helcom, \u2026)\n- `str`: Path to dataset to encode\n- `dest`: Path to converted NetCDF4\n\nExample:\n\n``` console\nmaris_netcdfy helcom _data/accdb/mors/csv _data/output/helcom.nc\n```\n\n## Development\n\nThe MARIS NetCDF template is generated from `nbs/files/cdl/maris.cdl`\nCommon Data Language (CDL) file as defined by\n[Unidata](https://docs.unidata.ucar.edu/). To generate the MARIS NetCDF\ntemplate `nbs/files/nc/maris-template.nc`, install the\n[NetCDF-C](https://pjbartlein.github.io/REarthSysSci/install_netCDF.html)\nutilities, once in `Marisco` home directory, run:\n\n``` console\nncgen -4 -o nc/maris-template.nc cdl/maris.cdl\n```\n",
"bugtrack_url": null,
"license": "Apache Software License 2.0",
"summary": "MARIS companion package and tutorials",
"version": "0.8.0",
"project_urls": {
"Homepage": "https://github.com/franckalbinet/marisco"
},
"split_keywords": [
"nbdev",
"jupyter",
"notebook",
"python"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6ada68120f36dd131101e7c2d5d85476e958d62102228566def5b6c8d0cef3d0",
"md5": "16f9ba6aee5768c55c3e00863f0b44dd",
"sha256": "7b1ed15d7e2dff77b287000c64fa1155a63b078d41202343933bb0ed9159702e"
},
"downloads": -1,
"filename": "marisco-0.8.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "16f9ba6aee5768c55c3e00863f0b44dd",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 54512,
"upload_time": "2024-12-08T20:33:55",
"upload_time_iso_8601": "2024-12-08T20:33:55.924460Z",
"url": "https://files.pythonhosted.org/packages/6a/da/68120f36dd131101e7c2d5d85476e958d62102228566def5b6c8d0cef3d0/marisco-0.8.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "83a8df2e14f4890b01f73b82d10ee95bca0a4ba3faaf7eb989f3089abd4dfa78",
"md5": "6e53258ed00b381a6079dae2a7d0a7f9",
"sha256": "3d5312afe5777eb799b79dbdf55c6e6b20919ed8ddadd13e8cd3e9b739e68873"
},
"downloads": -1,
"filename": "marisco-0.8.0.tar.gz",
"has_sig": false,
"md5_digest": "6e53258ed00b381a6079dae2a7d0a7f9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 50959,
"upload_time": "2024-12-08T20:33:57",
"upload_time_iso_8601": "2024-12-08T20:33:57.806066Z",
"url": "https://files.pythonhosted.org/packages/83/a8/df2e14f4890b01f73b82d10ee95bca0a4ba3faaf7eb989f3089abd4dfa78/marisco-0.8.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-08 20:33:57",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "franckalbinet",
"github_project": "marisco",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "marisco"
}
JSON
