Metadata-Version: 2.1
Name: marisco
Version: 0.1.5
Summary: MARIS companion package and tutorials
Home-page: https://github.com/franckalbinet/marisco
Author: Franck Albinet
Author-email: franckalbinet@gmail.com
License: Apache Software License 2.0
Keywords: nbdev jupyter notebook python
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: License :: OSI Approved :: Apache Software License
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas (==2.2)
Requires-Dist: openpyxl (==3.1.0)
Requires-Dist: fastcore
Requires-Dist: tqdm
Requires-Dist: netcdf4
Requires-Dist: tomli
Requires-Dist: tomli-w
Requires-Dist: shapely
Requires-Dist: pyzotero
Requires-Dist: jellyfish
Requires-Dist: xarray
Provides-Extra: dev
Requires-Dist: unitest ; extra == 'dev'

# Marisco


<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

The IAEA [Marine Radioactivity Information System
(**MARIS**)](https://maris.iaea.org) allows free access to users to
search and download the results of measurements of radioactivity in
seawater, biota, sediment and suspended matter. MARIS is maintained and
developed by the [IAEA Environmental
Laboratories](https://www.iaea.org/about/organizational-structure/department-of-nuclear-sciences-and-applications/division-of-iaea-environment-laboratories)
in Monaco.

The current Python package offers command-line utilities for encoding
MARIS harvested datasets into
[`NetCDF`](https://www.unidata.ucar.edu/software/netcdf/) or `.csv`
formats. This allows to convert **MARIS data into a format that is
compatible with a wide range of scientific and data analysis tools**.

## 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.  creates a configurable `cdl.toml` file used to generate a MARIS
    [NetCDF4 CDL (Common Data
    Language)](https://www.unidata.ucar.edu/software/netcdf/workshops/most-recent/nc3model/Cdl.html)
    template;
4.  downloads several MARIS DB nomenclature/lookup table into
    `.marisco/lut/` directory
5.  generate `maris-template.nc`, the MARIS NetCDF4 template generated
    from `cdl.toml` and use to encode MARIS datasets

> [!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).

## Getting started

### Command line utilities

All commands accept a `-h` argument to get access to its documentation.

#### `maris_init`

Create configuration files, MARIS NetCDF CDL (Common Data Language) and
donwload required lookup tables (nomenclatures).

#### `maris_create_nc_template`

Generate MARIS NetCDF template to be used when encoding datasets

#### `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

### FAQ

#### How is `cdl.toml` created & what it is used for?

A Python dictionary named `CONFIGS_CDL` specifying MARIS NetCDF
attributes, variables, dimensions, … is defined in
`nbs/api/configs.ipynb` in the first instance. Running the command
`maris_init` will generate a [`toml`](https://www.wikiwand.com/fr/TOML)
version of it named `.marisco/cdl.toml` further used to create a MARIS
NetCDF template named in `.marisco/maris-template.nc`.

Once `marisco` installed, further customization of the MARIS NetCDF
template can be done directly through `.marisco/cdl.toml` file then
running the command `maris_create_nc_template`.
