LaminDB

When to use

Use for registering biological datasets, curating DataFrame/AnnData metadata, querying annotated artifacts, and tracking scientific scripts or workflows. LaminDB stores metadata in SQLite/PostgreSQL and files in configured storage; registration alone does not establish scientific validity or FAIR compliance.

This skill targets LaminDB 2.10.0 and Bionty 2.5.0. The local examples were executed on Python 3.12, pandas 3.0.6, and AnnData 0.13.2. The LaminDB release caps AnnData at 0.13.2; preserve its dependency constraints. Install IPython for registry synonym helpers (add_synonym() imports it in this release).

Workflow

1. Confirm the intended instance, storage, and write scope with lamin info. Use a new local development directory for experiments. See setup and deployment.
2. Define typed Feature records and a Schema for the biological data. Use registry-backed categorical dtypes for controlled vocabularies; dtype=str only checks strings. See annotation and validation.
3. Review the ontology source/version and organism. Standardize only reviewed synonyms and preserve unresolved annotations. See Bionty ontologies.
4. In a script or notebook, start ln.track(), load registered inputs, validate, and save outputs. curator.validate() returns None on success and raises ln.errors.ValidationError on failure. Repair, then validate again.
5. Save through the curator or a schema-aware artifact constructor. Check the stored schema and round-trip content; finish a successful run with ln.finish().
6. Query metadata before loading content. Record artifact UIDs and schema/source provenance for reproducibility; a key can resolve to a newer version later. See queries and streaming.

Local worked example

Run in a dedicated environment and an empty project directory:

uv venv --python 3.12
uv pip install 'lamindb==2.10.0' 'bionty==2.5.0' 'ipython==9.17.1'
source .venv/bin/activate
lamin init --storage ./storage --name biology-demo --modules bionty

Save the following as curate_qc.py, then run python curate_qc.py:

import pandas as pd
import lamindb as ln

ln.track(params={"analysis": "QC metadata curation"})
count = ln.Feature(name="gene_count", dtype=int).save()
condition = ln.Feature(name="condition", dtype=str).save()
schema = ln.Schema(
    name="qc_metadata",
    features=[count, condition],
    maximal_set=True,  # reject extra columns
).save()
df = pd.DataFrame({
    "gene_count": [120, 130],
    "condition": ["control", "treated"],
})
curator = ln.curators.DataFrameCurator(df, schema)
curator.validate()  # raises on invalid data; do not use as an if condition
artifact = curator.save_artifact(key="experiments/qc.parquet")
assert artifact.schema == schema
pd.testing.assert_frame_equal(artifact.load(), df)
ln.finish()

This validates table structure/types, not whether the counts satisfy assay QC. Add assay-specific checks (units, allowed ranges, missingness, duplicate sample IDs, batch balance) before publication or downstream analysis.

Core objects and contracts

Use @ln.flow() for a workflow entry point and @ln.step() within it. Lineage captures tracked accesses, not arbitrary reads outside LaminDB. Review core concepts for tracking, labels, and revisions.

Failure patterns to avoid

…