lamindb

¿Qué hace lamindb?

Descripción general

LaminDB es un lago de datos (lakehouse) de código abierto con trazabilidad de linaje nativa para biología. Hace que los conjuntos de datos y modelos sean consultables, trazables, validados, reproducibles y FAIR (Encontrables, Accesibles, Interoperables, Reutilizables) mientras almacena datos en formatos abiertos en sistemas de archivos locales, S3, GCS, Hugging Face, SQLite y Postgres.

Propuesta de valor principal:

• Consultabilidad: Buscar y filtrar artefactos, registros, ejecuciones, características, esquemas y colecciones
• Trazabilidad: Rastrear entradas, salidas, parámetros, código fuente y entornos para notebooks, scripts, funciones y pipelines
• Validación: Curar DataFrames, AnnData, SpatialData, TileDB-SOMA, Parquet, Zarr y otros formatos biológicos con esquemas
• Cumplimiento FAIR: Estandarizar anotaciones con ontologías respaldadas por Bionty y registros personalizados
• Gestión de cambios: Organizar el trabajo con proyectos, ramas, espacios, colecciones y notas o planes guardados

Cuándo usar esta habilidad

Usa esta habilidad cuando:

• Gestiones conjuntos de datos biológicos: scRNA-seq, RNA-seq masivo, transcriptómica espacial, citometría de flujo, datos multimodales, datos de EHR
• Realices seguimiento de flujos de trabajo computacionales: Notebooks, scripts, funciones, scripts de shell y ejecución de pipelines (Nextflow, Snakemake, Redun)
• Cures y valides datos: Validación de esquemas, estandarización, anotación basada en ontologías
• Trabajes con ontologías biológicas: Genes, proteínas, tipos celulares, tejidos, enfermedades, vías (a través de Bionty)
• Construyas lagos de datos: Interfaz de consulta unificada entre múltiples conjuntos de datos
• Asegures la reproducibilidad: Versionado automático, seguimiento de linaje, captura del entorno
• Integres pipelines de ML: Conexión con Weights & Biases, MLflow, Hugging Face, Lightning, scVI-tools
• Despliegues infraestructura de datos: Configuración de sistemas de gestión de datos locales o en la nube
• Colabores en conjuntos de datos: Compartir datos curados y anotados con metadatos estandarizados

Capacidades principales

LaminDB proporciona seis áreas de capacidad interconectadas, cada una documentada en detalle en la carpeta de referencias.

1. Conceptos básicos y linaje de datos

Entidades principales:

• Artefactos: Conjuntos de datos versionados (DataFrame, AnnData, Parquet, Zarr, etc.)
• Registros y ULabels: Entidades experimentales, registros tipados y etiquetas simples
• Colecciones: Conjuntos versionados e inmutables de artefactos
• Ejecuciones y Transformaciones: Seguimiento de linaje computacional (qué código produjo qué datos)
• Características: Campos de metadatos tipados para anotación y consulta
• Proyectos, Ramas y Espacios: Agrupación de proyectos, gestión de cambios y límites de acceso

Flujos de trabajo clave:

• Crear y versionar artefactos desde archivos u objetos de Python
• Rastrear la ejecución de notebooks/scripts con ln.track() y ln.finish()
• Rastrear flujos de trabajo de funciones con @ln.flow() y @ln.step()
• Anotar artefactos con registros, ulabels, proyectos y características tipadas
• Visualizar gráficos de linaje de datos con artifact.view_lineage()
• Consultar por procedencia (encontrar todas las salidas de código/entradas específicas)

Referencia: references/core-concepts.md - Lee esto para obtener información detallada sobre artefactos, registros, ejecuciones, transformaciones, características, versionado y seguimiento de linaje.

2. Gestión y consulta de datos

Capacidades de consulta:

• Exploración y búsqueda en registros con autocompletado
• Recuperación de un solo registro con get(), one(), one_or_none()
• Filtrado con operadores de comparación (__gt, __lte, __contains, __startswith)
• Consultas basadas en características, incluyendo consultas de estilo de expresión con objetos Feature
• Recorrido entre registros con sintaxis de doble guión bajo
• Búsqueda de texto completo en todos los registros
• Consultas lógicas avanzadas con objetos ln.Q (AND, OR, NOT)
• Transmisión de grandes conjuntos de datos sin cargarlos en memoria

Flujos de trabajo clave:

• Navegar por artefactos con filtros y ordenación
• Consultar por características, fecha de creación, creador, tamaño, etc.
• Transmitir archivos grandes en fragmentos o con división de arreglos
• Organizar datos con claves jerárquicas
• Agrupar artefactos en colecciones

Referencia: references/data-management.md - Lee esto para patrones de consulta exhaustivos, ejemplos de filtrado, estrategias de transmisión y mejores prácticas de organización de datos.

3. Anotación y validación

Proceso de curación:

1. Validación: Confirmar que los conjuntos de datos coinciden con los esquemas deseados
2. Estandarización: Corregir errores tipográficos, mapear sinónimos a términos canónicos
3. Anotación: Vincular conjuntos de datos a entidades de metadatos para su consultabilidad

Tipos de esquema:

• Esquemas flexibles: Validar solo columnas conocidas, permitir metadatos adicionales
• Esquemas mínimos requeridos: Especificar columnas esenciales, permitir extras
• Esquemas estrictos: Control completo sobre la estructura y los valores

Tipos de datos compatibles:

• DataFrames (Parquet, CSV)
• AnnData (genómica unicelular)
• MuData (multimodal)
• SpatialData (transcriptómica espacial)
• TileDB-SOMA (arreglos escalables)

Flujos de trabajo clave:

• Definir características y esquemas para la validación de datos
• Usar DataFrameCurator, AnnDataCurator, SpatialDataCurator o TiledbsomaExperimentCurator para validación
• Estandarizar valores con .cat.standardize()
• Mapear a ontologías con .cat.add_ontology()
• Guardar artefactos curados con enlace al esquema
• Consultar conjuntos de datos validados por características

Referencia: references/annotation-validation.md - Lee esto para flujos de trabajo de curación detallados, patrones de diseño de esquemas, manejo de errores de validación y mejores prácticas.

4. Ontologías biológicas

Ontologías disponibles (a través de Bionty):

• Genes (Ensembl), Proteínas (UniProt)
• Tipos celulares (CL), Líneas celulares (CLO)
• Tejidos (Uberon), Enfermedades (Mondo, DOID)
• Fenotipos (HPO), Vías (GO)
• Factores experimentales (EFO), Etapas de desarrollo
• Organismos (NCBItaxon), Fármacos (DrugBank)

Flujos de trabajo clave:

• Importar ontologías públicas con bt.CellType.import_source()
• Buscar en ontologías con coincidencia exacta o por palabra clave
• Estandarizar términos usando mapeo de sinónimos
• Explorar relaciones jerárquicas (padres, hijos, antepasados)
• Validar datos contra términos de ontología
• Anotar conjuntos de datos con registros de ontología
• Crear términos y jerarquías personalizadas
• Manejar contextos multi-organismo (humano, ratón, etc.)

Referencia: references/ontologies.md - Lee esto para operaciones exhaustivas de ontologías, estrategias de estandarización, navegación jerárquica y flujos de trabajo de anotación.

5. Integraciones

Gestores de flujo de trabajo:

• Nextflow: Rastrear procesos y salidas del pipeline
• Snakemake: Integrar en reglas de Snakemake
• Redun: Combinar con el seguimiento de tareas de Redun
• Lightning: Persistir puntos de control y metadatos de entrenamiento

Plataformas MLOps:

• Weights & Biases: Vincular experimentos con artefactos de datos
• MLflow: Rastrear modelos y experimentos
• Hugging Face: Rastrear ajuste fino de modelos
• scVI-tools: Flujos de trabajo de análisis unicelulares

Sistemas de almacenamiento:

• Sistema de archivos local, AWS S3, Google Cloud Storage
• Compatible con S3 (MinIO, Cloudflare R2)
• Puntos finales HTTP/HTTPS (solo lectura)
• Conjuntos de datos de HuggingFace

Almacenes de arreglos:

• TileDB-SOMA (con soporte cellxgene)
• DuckDB para consultas SQL en archivos Parquet

Visualización:

• Vitessce para visualización interactiva espacial/unicelular

Control de versiones:

• Integración con Git para el seguimiento del código fuente

Referencia: references/integrations.md - Lee esto para patrones de integración, ejemplos de código y resolución de problemas para sistemas de terceros.

6. Configuración e implementación

Instalación:

• Versión estable actual: lamindb==2.5.1 (publicada el 2026-06-01; Python >=3.10, <=3.14)
• Básica: uv pip install 'lamindb==2.5.1'
• Con extras: uv pip install 'lamindb[gcp,zarr-v2,fcs]==2.5.1'
• Solo espacio de nombres mínimo: uv pip install 'lamindb-core==2.5.1'
• Módulo Bionty: incluido en la documentación de LaminDB y disponible como uv pip install 'bionty==2.4.0'
• Módulos opcionales: fijar versiones revisadas para módulos de esquema de laboratorio húmedo o clínico en lugar de instalar las últimas versiones flotantes

Tipos de instancia:

• SQLite local (desarrollo)
• Almacenamiento en la nube + SQLite (equipos pequeños)
• Almacenamiento en la nube + PostgreSQL (producción)

Opciones de almacenamiento:

• Sistema de archivos local
• AWS S3 con regiones y permisos configurables
• Google Cloud Storage
• Puntos finales compatibles con S3 (MinIO, Cloudflare R2)

Configuración:

• Gestión de caché para archivos en la nube
• Configuraciones de sistema multiusuario
• Sincronización de repositorio Git
• Variables de entorno con nombre para credenciales y URL de conexión

Patrones de implementación:

• Migración de desarrollo local a producción en la nube
• Implementaciones multirregión
• Almacenamiento compartido con instancias personales

Referencia: references/setup-deployment.md - Lee esto para instalación detallada, configuración, configuración de almacenamiento, gestión de bases de datos, mejores prácticas de seguridad y resolución de problemas.

Valores predeterminados de seguridad y protección

Al ayudar con la configuración o integraciones de LaminDB:

• Nunca mostrar, registrar ni transmitir claves API reales, credenciales en la nube, contraseñas de bases de datos o cadenas de conexión completas que incluyan secretos.
• Preferir roles IAM, identidad de carga de trabajo, gestores de secretos o variables de entorno con nombre como LAMIN_DB_URL, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY y GOOGLE_APPLICATION_CREDENTIALS; solo verificar si una variable con nombre está presente, no su valor.
• Antes de guardar contenido de API REST, bases de datos externas o archivos proporcionados por el usuario, validar y sanitizar con un esquema o curador explícito.
• Para instalaciones reproducibles, fijar versiones de paquetes o usar un archivo de bloqueo. Las instalaciones flotantes son aceptables solo cuando el usuario desea explícitamente la última versión ascendente.

Flujos de trabajo de casos de uso comunes

Caso de uso 1: Análisis de ARN-seq unicelular con validación de ontología

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

# Iniciar el seguimiento de una ejecución de notebook/script
ln.track(params={"analysis": "scRNA-seq QC and annotation"})

# Importar ontología de tipos celulares
bt.CellType.import_source()

# Cargar datos
adata = ad.read_h5ad("raw_counts.h5ad")

# Validar y estandarizar tipos celulares
adata.obs["cell_type"] = bt.CellType.standardize(adata.obs["cell_type"])

# Curar con esquema
curator = ln.curators.AnnDataCurator(adata, schema)
curator.validate()
artifact = curator.save_artifact(key="scrna/validated.h5ad")

# Vincular anotaciones respaldadas por ontología para su consultabilidad
cell_types = bt.CellType.from_values(adata.obs["cell_type"])
artifact.cell_types.add(*cell_types)

ln.finish()

Caso de uso 2: Construcción de un lago de datos consultable

import lamindb as ln

# Registrar múltiples experimentos
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 batch {i}"
    ).save()

    # Anotar con características
    artifact.features.set_values({
        "batch": i,
        "tissue": tissues[i],
        "condition": conditions[i]
    })

# Consultar en todos los experimentos por características anotadas
immune_datasets = ln.Artifact.filter(
    key__startswith="scrna/",
    tissue="PBMC",
    condition="treated"
).to_dataframe()

# Cargar conjuntos de datos específicos
for artifact in immune_datasets:
    adata = artifact.load()
    # Analizar

Caso de uso 3: Pipeline de ML con integración de W&B

import lamindb as ln
import wandb

# Inicializar ambos sistemas
wandb.init(project="drug-response", name="exp-42")
ln.track(params={"model": "random_forest", "n_estimators": 100})

# Cargar datos de entrenamiento desde LaminDB
train_artifact = ln.Artifact.get(key="datasets/train.parquet")
train_data = train_artifact.load()

# Entrenar modelo
model = train_model(train_data)

# Registrar en W&B
wandb.log({"accuracy": 0.95})

# Guardar modelo en LaminDB con enlace a 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()

Caso de uso 4: Integración con pipeline de Nextflow

# En script de proceso de Nextflow
import lamindb as ln

ln.track()

# Cargar artefacto de entrada
input_artifact = ln.Artifact.get(key="raw/batch_${batch_id}.fastq.gz")
input_path = input_artifact.cache()

# Procesar (alineación, cuantificación, etc.)
# ... lógica del proceso de Nextflow ...

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

ln.finish()

Para proyectos nativos de Nextflow, prefiere el plugin nf-lamin y los patrones actuales de nextflow.config cuando estén disponibles; usa seguimiento en línea de Python para pasos pequeños o de pipeline personalizados.

Lista de verificación para comenzar

Para comenzar a usar LaminDB de manera efectiva:

1. Instalación y configuración (references/setup-deployment.md)

   • Instalar LaminDB fijado y los extras requeridos
   • Autenticar con lamin login
   • Inicializar instancia con lamin init --storage ...

2. Aprender conceptos básicos (references/core-concepts.md)

   • Comprender artefactos, registros, ejecuciones, transformaciones
   • Practicar la creación y recuperación de artefactos
   • Implementar ln.track()/ln.finish() o @ln.flow()/@ln.step() en flujos de trabajo

3. Dominar las consultas (references/data-management.md)

   • Practicar el filtrado y la búsqueda en registros
   • Aprender consultas basadas en características y filtros de estilo de expresión
   • Experimentar con la transmisión de archivos grandes

4. Configurar validación (references/annotation-validation.md)

   • Definir características relevantes para el dominio de investigación
   • Crear esquemas para tipos de datos
   • Practicar flujos de trabajo de curación

5. Integrar ontologías (references/ontologies.md)

   • Importar ontologías biológicas relevantes (genes, tipos celulares, etc.)
   • Validar anotaciones existentes
   • Estandarizar metadatos con términos de ontología

6. Conectar herramientas (references/integrations.md)

   • Integrar con gestores de flujo de trabajo existentes
   • Vincular plataformas de ML para seguimiento de experimentos
   • Configurar almacenamiento y cómputo en la nube

Principios clave

Sigue estos principios al trabajar con LaminDB:

1. Rastrear todo: Usa ln.track() al inicio de cada análisis para la captura automática de linaje

2. Validar temprano: Define esquemas y valida datos antes de un análisis extenso

3. Usar ontologías: Aprovecha las ontologías biológicas públicas para anotaciones estandarizadas

4. Estructurar datos: Usa claves jerárquicas y colecciones para una organización de datos clara

5. Preferir la entrada única: Para artefactos compartidos y registros centrales, usa el principio de entrada única (canónico: un artefacto o registro por clave/identidad; práctico: consultar primero, crear después si no existe)

6. Exponer el linaje de forma nativa: En lugar de reconstruir manualmente el historial de datos, deja que el grafo de ejecución (ejecuciones → artefactos) capture las dependencias de forma automática y permita consultas posteriores por procedencia