Get started

Install metasalmonpy and create a review-ready Salmon Data Package.

Install

Install the released package from its tagged source archive:

python -m pip install \
  "metasalmonpy @ https://github.com/salmon-data-mobilization/metasalmonpy/archive/refs/tags/v0.5.0.tar.gz"

The package version is a claim of behavioural parity with metasalmon; see the parity guide. A checkout of main can contain unreleased changes even while reporting the released version. The tagged archive pins the package source and does not require a wheel release asset or local Git. Lock dependencies separately when reproducing a complete environment.

For development, clone the repository and install the test dependencies:

git clone https://github.com/salmon-data-mobilization/metasalmonpy.git
cd metasalmonpy
python -m venv .venv
. .venv/bin/activate
python -m pip install -e ".[test]"

The optional context extra adds Excel and PDF readers for LLM context:

python -m pip install -e ".[context,test]"

Optional schema settings, retrieval switches and credential inputs are listed in Configuration.

Create a package

Use create_sdp() for the standard one-call workflow. A single DataFrame uses table_id; a mapping of DataFrames uses each mapping key as its table id.

import pandas as pd
from metasalmonpy import create_sdp

catch = pd.DataFrame(
    {
        "survey_year": [2024, 2025],
        "species": ["Coho", "Coho"],
        "catch_count": [42, 57],
    }
)

path = create_sdp(
    catch,
    path="coho-catch-sdp",
    dataset_id="coho-catch",
    table_id="catch",
    seed_semantics=False,
)

Setting seed_semantics=False makes this example fully local. Semantic retrieval can contact configured ontology services; LLM review remains off unless llm_assess=True.

Review the output

The canonical layout is:

coho-catch-sdp/
|-- .sdp-package
|-- README-review.txt
|-- datapackage.json
|-- data/
|   `-- catch.csv
`-- metadata/
    |-- dataset.csv
    |-- tables.csv
    |-- column_dictionary.csv
    `-- codes.csv

Review the metadata in this order:

  1. Complete metadata/dataset.csv and metadata/tables.csv.
  2. Confirm roles, types, definitions, and semantic IRIs in metadata/column_dictionary.csv.
  3. Confirm controlled values and IRIs in metadata/codes.csv.
  4. Replace every MISSING placeholder and REVIEW: IRI.
  5. Run strict validation.
from metasalmonpy import validate_salmon_datapackage

result = validate_salmon_datapackage(path, require_iris=True)
print(result)

Strict validation fails while unresolved review markers remain. This protects the boundary between machine suggestions and curator-approved metadata.

Read the package

from metasalmonpy import read_salmon_datapackage

package = read_salmon_datapackage(path)
dictionary = package["dictionary"]
resources = package["resources"]

Continue with the package lifecycle for multi-table packages and manual assembly, or the semantic review guide for ontology suggestions.

Back to top