Metadata-Version: 2.4
Name: marinerg-schema
Version: 0.6.0
Summary: MARINERG-i dataset metadata model (LinkML) and its generated controlled-vocabulary registry.
Author-email: Irish Centre for High End Computing <james.grogan@ichec.ie>
License: MIT
Project-URL: Repository, https://git.ichec.ie/marinerg-i/marinerg-schema
Project-URL: Homepage, https://git.ichec.ie/marinerg-i/marinerg-schema
Keywords: Marine Renewable Energy,Metadata,LinkML,DCAT,EOSC
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML
Dynamic: license-file

# marinerg-schema

The MARINERG-i dataset metadata model, as a Python package.

[`marinerg_dataset.linkml.yaml`](src/marinerg_schema/data/marinerg_dataset.linkml.yaml),
written in LinkML, defines the dataset fields and their controlled vocabularies. The CKAN
catalogue's form and validators, and the facility client's checks, all take their fields and
values from it. It's a package so that each of them uses the same version instead of a copy.

## Install

```sh
pip install marinerg-schema
```

## Use

```python
from marinerg_schema import (
    check,
    concept_uri,
    dataset_slots,
    permitted_values,
    slot,
    value_titles,
)
from marinerg_schema.ckan import field_names

# frozenset({'L0', 'L1', 'L2', 'L3', 'L4'})
permitted_values("processing_level")
# 'http://vocab.nerc.ac.uk/collection/EPL/current/L1/'
concept_uri("processing_level", "L1")
# {'L0': 'L0 — Raw', ...}, for a form's choices
value_titles("ProcessingLevelEnum")
# The slot's range, constraints and RDF predicate
slot("device_trl")
# ValueError: Must be at most 9: '12'
check("device_trl", "12")
# The model's fields, in model order
dataset_slots()
# The keys a CKAN dataset takes at the top level
field_names()
```

The measured-parameter vocabulary says what a data channel measures. A facility
template names each channel's parameter by its code:

```python
from marinerg_schema import parameter, parameters

parameter("wind_speed").unit  # 'm s-1', as UDUNITS
parameter("wind_speed").cf_standard_name  # 'wind_speed'
parameter("roll").cf_standard_name  # None: no verified CF name
```

A CF or NERC mapping is filled only where the term was checked to exist. Lab and
device quantities, such as mooring-line tension, often have none yet.

`registry_path()` returns the generated registry YAML for consumers that want a file rather
than the API. `vocab_path()` returns our own vocabulary as SKOS Turtle: every term under
`https://vocab.marinerg-i.eu/`, with its label, definition and close matches.

## Consumers

| Repo | What it takes |
|---|---|
| [`ckanext-marinerg`](https://git.ichec.ie/marinerg-i/ckanext-marinerg) | Vocabularies, titles and constraints for its form, validators and RDF export |
| [`marinerg-data`](https://git.ichec.ie/marinerg-i/marinerg-data) | Vocabularies to check a dataset before a DOI is minted, and the CKAN field list |

## Predecessor

This model follows on from MaRINET2's 2020 metadata schemas, at
[github.com/Marinet2/metadata-schema](https://github.com/Marinet2/metadata-schema) and
[FAIRsharing bsg-s001497](https://fairsharing.org/bsg-s001497/). This package replaces its dataset
schema. `marinerg-data`'s run manifest replaces its datastream schema. `"Marinet2 NetCDF 0.1"` is
still an allowed value in the `conventions` list.

The MaRINET2 repository still reads as current. Only its owners can add a notice there, or link
this model from its FAIRsharing record.

## Change the model

Edit the LinkML file, then regenerate the registry and the SKOS vocabulary. Never edit either
by hand. The tests fail if they differ from the model.

```sh
uv run python -m marinerg_schema
uv run python -m marinerg_schema --check
```

Give every value a `title`, which forms show, and a `meaning`, its concept URI. Write NERC
CURIEs with their trailing slash, such as `nerc_epl:L1/`, because NERC's concept URIs end in
one. A value of our own also needs a `description`, which becomes its SKOS definition.

The package reads the model without LinkML, so it installs anywhere CKAN does. The tests run
`linkml-lint` and check the package's reading against LinkML's own.

After a vocabulary change, cut a release, then move the pin in each consumer. The model's version
is the package's.

## Develop

```sh
uv sync --group dev
uv run tox
```

`uv run tox` runs the format check, lint, type check and tests, as CI does.

The package supports Python 3.10, because CKAN 2.11 runs on it. Ruff targets 3.10 for the same
reason.

## Release

Open the [newest pipeline for `main`](https://git.ichec.ie/marinerg-i/marinerg-schema/-/pipelines/main/latest)
and press the play button on release patch, minor or major. The release pipeline publishes to
PyPI, then tags the commit and creates the GitLab release.

## Licence

Copyright ICHEC. MIT. See [`LICENSE`](LICENSE).
