lamindb

Que fait lamindb ?

Vue d'ensemble

LaminDB est un lakehouse open-source natif de lignée pour la biologie. Il rend les jeux de données et les modèles interrogeables, traçables, validés, reproductibles et conformes FAIR (Facile à trouver, Accessible, Interopérable, Réutilisable) tout en stockant les données dans des formats ouverts sur des systèmes de fichiers locaux, S3, GCS, Hugging Face, SQLite et Postgres.

Proposition de valeur principale :

• Interrogeabilité : Rechercher et filtrer les artefacts, enregistrements, exécutions, caractéristiques, schémas et collections
• Traçabilité : Suivre les entrées, sorties, paramètres, code source et environnements pour les notebooks, scripts, fonctions et pipelines
• Validation : Curater les DataFrame, AnnData, SpatialData, TileDB-SOMA, Parquet, Zarr et autres formats biologiques avec des schémas
• Conformité FAIR : Standardiser les annotations avec des ontologies Bionty et des registres personnalisés
• Gestion du changement : Organiser le travail avec des projets, branches, espaces, collections et notes/plans sauvegardés

Quand utiliser cette compétence

Utilisez cette compétence lorsque :

• Vous gérez des jeux de données biologiques : scRNA-seq, bulk RNA-seq, transcriptomique spatiale, cytométrie en flux, données multimodales, données EHR
• Vous suivez des workflows computationnels : Notebooks, scripts, fonctions, scripts shell et exécution de pipelines (Nextflow, Snakemake, Redun)
• Vous curez et validez des données : Validation de schéma, standardisation, annotation basée sur les ontologies
• Vous travaillez avec des ontologies biologiques : Gènes, protéines, types cellulaires, tissus, maladies, voies (via Bionty)
• Vous construisez des data lakehouses : Interface d'interrogation unifiée sur plusieurs jeux de données
• Vous assurez la reproductibilité : Versionnage automatique, suivi de lignée, capture d'environnement
• Vous intégrez des pipelines ML : Connexion avec Weights & Biases, MLflow, Hugging Face, Lightning, scVI-tools
• Vous déployez une infrastructure de données : Configuration de systèmes de gestion de données locaux ou cloud
• Vous collaborez sur des jeux de données : Partage de données curées et annotées avec des métadonnées standardisées

Capacités principales

LaminDB offre six domaines de capacités interconnectés, chacun documenté en détail dans le dossier references.

1. Concepts de base et lignée des données

Entités principales :

• Artefacts : Jeux de données versionnés (DataFrame, AnnData, Parquet, Zarr, etc.)
• Enregistrements et ULabels : Entités expérimentales, enregistrements typés et étiquettes simples
• Collections : Ensembles d'artefacts versionnés et immuables
• Exécutions et Transformations : Suivi de la lignée computationnelle (quel code a produit quelles données)
• Caractéristiques : Champs de métadonnées typés pour l'annotation et l'interrogation
• Projets, Branches et Espaces : Regroupement de projets, gestion du changement et limites d'accès

Workflows clés :

• Créer et versionner des artefacts à partir de fichiers ou d'objets Python
• Suivre l'exécution de notebooks/scripts avec ln.track() et ln.finish()
• Suivre les workflows de fonctions avec @ln.flow() et @ln.step()
• Annoter des artefacts avec des enregistrements, ulabels, projets et caractéristiques typées
• Visualiser les graphes de lignée des données avec artifact.view_lineage()
• Interroger par provenance (trouver toutes les sorties d'un code/entrées spécifiques)

Référence : references/core-concepts.md - Lisez ceci pour des informations détaillées sur les artefacts, enregistrements, exécutions, transformations, caractéristiques, versionnage et suivi de lignée.

2. Gestion des données et interrogation

Capacités d'interrogation :

• Exploration et recherche de registres avec auto-complétion
• Récupération d'un seul enregistrement avec get(), one(), one_or_none()
• Filtrage avec des opérateurs de comparaison (__gt, __lte, __contains, __startswith)
• Requêtes basées sur les caractéristiques, y compris les requêtes de type expression avec des objets Feature
• Navigation inter-registres avec la syntaxe double-underscore
• Recherche plein texte sur les registres
• Requêtes logiques avancées avec des objets ln.Q (ET, OU, NON)
• Streaming de grands jeux de données sans les charger en mémoire

Workflows clés :

• Parcourir les artefacts avec des filtres et des tris
• Interroger par caractéristiques, date de création, créateur, taille, etc.
• Diffuser des fichiers volumineux par morceaux ou avec découpage de tableau
• Organiser les données avec des clés hiérarchiques
• Grouper les artefacts en collections

Référence : references/data-management.md - Lisez ceci pour des modèles d'interrogation complets, des exemples de filtrage, des stratégies de streaming et les meilleures pratiques d'organisation des données.

3. Annotation et validation

Processus de curation :

1. Validation : Confirmer que les jeux de données correspondent aux schémas souhaités
2. Standardisation : Corriger les fautes de frappe, mapper les synonymes aux termes canoniques
3. Annotation : Lier les jeux de données aux entités de métadonnées pour l'interrogeabilité

Types de schémas :

• Schémas flexibles : Valider uniquement les colonnes connues, autoriser des métadonnées supplémentaires
• Schémas minimaux requis : Spécifier les colonnes essentielles, autoriser des extras
• Schémas stricts : Contrôle complet sur la structure et les valeurs

Types de données pris en charge :

• DataFrames (Parquet, CSV)
• AnnData (génomique unicellulaire)
• MuData (multimodal)
• SpatialData (transcriptomique spatiale)
• TileDB-SOMA (tableaux évolutifs)

Workflows clés :

• Définir des caractéristiques et des schémas pour la validation des données
• Utiliser DataFrameCurator, AnnDataCurator, SpatialDataCurator ou TiledbsomaExperimentCurator pour la validation
• Standardiser les valeurs avec .cat.standardize()
• Mapper aux ontologies avec .cat.add_ontology()
• Sauvegarder des artefacts curés avec liaison de schéma
• Interroger les jeux de données validés par caractéristiques

Référence : references/annotation-validation.md - Lisez ceci pour des workflows de curation détaillés, des modèles de conception de schémas, la gestion des erreurs de validation et les meilleures pratiques.

4. Ontologies biologiques

Ontologies disponibles (via Bionty) :

• Gènes (Ensembl), Protéines (UniProt)
• Types cellulaires (CL), Lignées cellulaires (CLO)
• Tissus (Uberon), Maladies (Mondo, DOID)
• Phénotypes (HPO), Voies (GO)
• Facteurs expérimentaux (EFO), Stades de développement
• Organismes (NCBItaxon), Médicaments (DrugBank)

Workflows clés :

• Importer des ontologies publiques avec bt.CellType.import_source()
• Rechercher dans les ontologies avec correspondance par mot-clé ou exacte
• Standardiser les termes en utilisant le mappage de synonymes
• Explorer les relations hiérarchiques (parents, enfants, ancêtres)
• Valider les données par rapport aux termes d'ontologie
• Annoter des jeux de données avec des enregistrements d'ontologie
• Créer des termes personnalisés et des hiérarchies
• Gérer des contextes multi-organismes (humain, souris, etc.)

Référence : references/ontologies.md - Lisez ceci pour des opérations d'ontologie complètes, des stratégies de standardisation, la navigation hiérarchique et les workflows d'annotation.

5. Intégrations

Gestionnaires de workflows :

• Nextflow : Suivre les processus et sorties du pipeline
• Snakemake : Intégrer dans les règles Snakemake
• Redun : Combiner avec le suivi des tâches Redun
• Lightning : Persister les points de contrôle et les métadonnées d'entraînement

Plateformes MLOps :

• Weights & Biases : Lier les expériences avec les artefacts de données
• MLflow : Suivre les modèles et les expériences
• Hugging Face : Suivre le fine-tuning des modèles
• scVI-tools : Workflows d'analyse unicellulaire

Systèmes de stockage :

• Système de fichiers local, AWS S3, Google Cloud Storage
• Compatible S3 (MinIO, Cloudflare R2)
• Points de terminaison HTTP/HTTPS (lecture seule)
• Jeux de données HuggingFace

Magasins de tableaux :

• TileDB-SOMA (avec support cellxgene)
• DuckDB pour les requêtes SQL sur les fichiers Parquet

Visualisation :

• Vitessce pour la visualisation interactive spatiale/unicellulaire

Contrôle de version :

• Intégration Git pour le suivi du code source

Référence : references/integrations.md - Lisez ceci pour les modèles d'intégration, les exemples de code et le dépannage pour les systèmes tiers.

6. Configuration et déploiement

Installation :

• Baseline stable actuelle : lamindb==2.5.1 (publiée le 2026-06-01 ; Python >=3.10, <=3.14)
• Base : uv pip install 'lamindb==2.5.1'
• Avec extras : uv pip install 'lamindb[gcp,zarr-v2,fcs]==2.5.1'
• Espace de noms minimal uniquement : uv pip install 'lamindb-core==2.5.1'
• Module Bionty : inclus dans la documentation LaminDB et disponible avec uv pip install 'bionty==2.4.0'
• Modules optionnels : épingler les versions de révision pour les modules de schéma wetlab ou clinique plutôt que d'installer les dernières versions flottantes

Types d'instances :

• SQLite local (développement)
• Stockage cloud + SQLite (petites équipes)
• Stockage cloud + PostgreSQL (production)

Options de stockage :

• Système de fichiers local
• AWS S3 avec régions et permissions configurables
• Google Cloud Storage
• Points de terminaison compatibles S3 (MinIO, Cloudflare R2)

Configuration :

• Gestion du cache pour les fichiers cloud
• Configurations système multi-utilisateurs
• Synchronisation du dépôt Git
• Variables d'environnement nommées pour les identifiants et les URL de connexion

Modèles de déploiement :

• Migration dev local → production cloud
• Déploiements multi-régions
• Stockage partagé avec instances personnelles

Référence : references/setup-deployment.md - Lisez ceci pour une installation détaillée, la configuration, la configuration du stockage, la gestion de la base de données, les meilleures pratiques de sécurité et le dépannage.

Sécurité et valeurs par défaut

Lorsque vous aidez avec la configuration ou les intégrations de LaminDB :

• N'affichez, ne journalisez ou ne transmettez jamais les clés API réelles, les identifiants cloud, les mots de passe de base de données ou les chaînes de connexion complètes contenant des secrets.
• Préférez les rôles IAM, les identités de workload, les gestionnaires de secrets ou les variables d'environnement nommées telles que LAMIN_DB_URL, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY et GOOGLE_APPLICATION_CREDENTIALS ; vérifiez uniquement si une variable nommée est présente, pas sa valeur.
• Avant de sauvegarder le contenu des API REST, des bases de données externes ou des fichiers fournis par l'utilisateur, validez et nettoyez-le avec un schéma ou un curator explicite.
• Pour les installations reproductibles, épinglez les versions de paquets ou utilisez un fichier de verrouillage. Les installations flottantes sont acceptables uniquement lorsque l'utilisateur souhaite explicitement la dernière version en amont.

Workflows de cas d'utilisation courants

Cas d'utilisation 1 : Analyse scRNA-seq avec validation d'ontologie

import lamindb as ln
import bionty as bt
import anndata as ad

# Commencer le suivi d'une exécution de notebook/script
ln.track(params={"analysis": "scRNA-seq QC et annotation"})

# Importer l'ontologie des types cellulaires
bt.CellType.import_source()

# Charger les données
adata = ad.read_h5ad("raw_counts.h5ad")

# Valider et standardiser les types cellulaires
adata.obs["cell_type"] = bt.CellType.standardize(adata.obs["cell_type"])

# Curater avec un schéma
curator = ln.curators.AnnDataCurator(adata, schema)
curator.validate()
artifact = curator.save_artifact(key="scrna/validated.h5ad")

# Lier les annotations basées sur l'ontologie pour l'interrogeabilité
cell_types = bt.CellType.from_values(adata.obs["cell_type"])
artifact.cell_types.add(*cell_types)

ln.finish()

Cas d'utilisation 2 : Construction d'un data lakehouse interrogeable

import lamindb as ln

# Enregistrer plusieurs expériences
for i, file in enumerate(data_files):
    artifact = ln.Artifact.from_anndata(
        ad.read_h5ad(file),
        key=f"scrna/batch_{i}.h5ad",
        description=f"scRNA-seq lot {i}"
    ).save()

    # Annoter avec des caractéristiques
    artifact.features.set_values({
        "batch": i,
        "tissue": tissues[i],
        "condition": conditions[i]
    })

# Interroger toutes les expériences par caractéristiques annotées
immune_datasets = ln.Artifact.filter(
    key__startswith="scrna/",
    tissue="PBMC",
    condition="traité"
).to_dataframe()

# Charger des jeux de données spécifiques
for artifact in immune_datasets:
    adata = artifact.load()
    # Analyser

Cas d'utilisation 3 : Pipeline ML avec intégration W&B

import lamindb as ln
import wandb

# Initialiser les deux systèmes
wandb.init(project="réponse-médicament", name="exp-42")
ln.track(params={"model": "random_forest", "n_estimators": 100})

# Charger les données d'entraînement depuis LaminDB
train_artifact = ln.Artifact.get(key="datasets/train.parquet")
train_data = train_artifact.load()

# Entraîner le modèle
model = train_model(train_data)

# Journaliser dans W&B
wandb.log({"accuracy": 0.95})

# Sauvegarder le modèle dans LaminDB avec lien W&B
import joblib
joblib.dump(model, "model.pkl")
model_artifact = ln.Artifact("model.pkl", key="models/exp-42.pkl").save()
model_artifact.features.set_values({"wandb_run_id": wandb.run.id})

ln.finish()
wandb.finish()

Cas d'utilisation 4 : Intégration du pipeline Nextflow

# Dans le script de processus Nextflow
import lamindb as ln

ln.track()

# Charger l'artefact d'entrée
input_artifact = ln.Artifact.get(key="raw/batch_${batch_id}.fastq.gz")
input_path = input_artifact.cache()

# Traiter (alignement, quantification, etc.)
# ... Logique du processus Nextflow ...

# Sauvegarder la sortie
output_artifact = ln.Artifact(
    "counts.csv",
    key="processed/batch_${batch_id}_counts.csv"
).save()

ln.finish()

Pour les projets Nextflow natifs, privilégiez le plugin nf-lamin et les modèles nextflow.config actuels lorsqu'ils sont disponibles ; utilisez le suivi Python en ligne pour les étapes de pipeline petites ou personnalisées.

Liste de vérification pour commencer

Pour commencer à utiliser LaminDB efficacement :

1. Installation et configuration (references/setup-deployment.md)

   • Installer LaminDB épinglé et les extras requis
   • S'authentifier avec lamin login
   • Initialiser l'instance avec lamin init --storage ...

2. Apprendre les concepts de base (references/core-concepts.md)

   • Comprendre les artefacts, enregistrements, exécutions, transformations
   • Pratiquer la création et la récupération d'artefacts
   • Implémenter ln.track()/ln.finish() ou @ln.flow()/@ln.step() dans les workflows

3. Maîtriser l'interrogation (references/data-management.md)

   • Pratiquer le filtrage et la recherche dans les registres
   • Apprendre les requêtes basées sur les caractéristiques et les filtres de type expression
   • Expérimenter avec le streaming de fichiers volumineux

4. Configurer la validation (references/annotation-validation.md)

   • Définir les caractéristiques pertinentes pour le domaine de recherche
   • Créer des schémas pour les types de données
   • Pratiquer les workflows de curation

5. Intégrer les ontologies (references/ontologies.md)

   • Importer les ontologies biologiques pertinentes (gènes, types cellulaires, etc.)
   • Valider les annotations existantes
   • Standardiser les métadonnées avec les termes d'ontologie

6. Connecter les outils (references/integrations.md)

   • Intégrer avec les gestionnaires de workflows existants
   • Lier les plateformes ML pour le suivi des expériences
   • Configurer le stockage cloud et le calcul

Principes clés

Suivez ces principes lorsque vous travaillez avec LaminDB :

1. Tout suivre : Utilisez ln.track() au début de chaque analyse pour une capture automatique de la lignée

2. Valider tôt : Définissez des schémas et validez les données avant une analyse approfondie

3. Utiliser les ontologies : Exploitez les ontologies biologiques publiques pour des annotations standardisées

4. Versionner : Chaque artefact est immuable et versionné ; utilisez les collections pour gérer des ensembles d'artefacts

5. Intégrer : Connectez LaminDB à vos outils existants pour un flux de travail transparent