Lamindb

LaminDB

Visão Geral

LaminDB é um framework de dados de código aberto para biologia projetado para tornar dados consultáveis, rastreáveis, reproduzíveis e FAIR (Encontráveis, Acessíveis, Interoperáveis, Reutilizáveis). Fornece uma plataforma unificada que combina arquitetura lakehouse, rastreamento de linhagem, feature stores, ontologias biológicas, capacidades LIMS (Laboratory Information Management System) e ELN (Electronic Lab Notebook) através de uma única API Python.

Proposta de Valor Principal:

• Consultabilidade: Pesquisar e filtrar datasets por metadados, features e termos de ontologia
• Rastreabilidade: Rastreamento automático de linhagem de dados brutos até análise e resultados
• Reprodutibilidade: Controle de versão para dados, código e ambiente
• Conformidade FAIR: Anotações padronizadas usando ontologias biológicas

Quando Usar Esta Habilidade

Use esta habilidade quando:

• Gerenciar datasets biológicos: scRNA-seq, bulk RNA-seq, transcriptômica espacial, citometria de fluxo, dados multimodais, dados de prontuário eletrônico
• Rastrear workflows computacionais: Notebooks, scripts, execução de pipeline (Nextflow, Snakemake, Redun)
• Curar e validar dados: Validação de esquema, padronização, anotação baseada em ontologia
• Trabalhar com ontologias biológicas: Genes, proteínas, tipos de célula, tecidos, doenças, pathways (via Bionty)
• Construir data lakehouses: Interface de consulta unificada em múltiplos datasets
• Garantir reprodutibilidade: Versionamento automático, rastreamento de linhagem, captura de ambiente
• Integrar pipelines ML: Conectar com Weights & Biases, MLflow, HuggingFace, scVI-tools
• Fazer deploy de infraestrutura de dados: Configurar sistemas de gerenciamento de dados locais ou baseados em nuvem
• Colaborar em datasets: Compartilhar dados curados e anotados com metadados padronizados

Capacidades Principais

LaminDB oferece seis áreas de capacidade interconectadas, cada uma documentada em detalhes na pasta references.

1. Conceitos Centrais e Linhagem de Dados

Entidades principais:

• Artifacts: Datasets versionados (DataFrame, AnnData, Parquet, Zarr, etc.)
• Records: Entidades experimentais (amostras, perturbações, instrumentos)
• Runs & Transforms: Rastreamento de linhagem computacional (qual código produziu quais dados)
• Features: Campos de metadados tipados para anotação e consulta

Workflows principais:

• Criar e versionar artifacts de arquivos ou objetos Python
• Rastrear execução de notebook/script com ln.track() e ln.finish()
• Anotar artifacts com features tipadas
• Visualizar gráficos de linhagem de dados com artifact.view_lineage()
• Consultar por proveniência (encontrar todos os outputs de código/inputs específicos)

Referência: references/core-concepts.md - Leia para informações detalhadas sobre artifacts, records, runs, transforms, features, versionamento e rastreamento de linhagem.

2. Gerenciamento de Dados e Consultas

Capacidades de consulta:

• Exploração e lookup de registry com auto-complete
• Recuperação de registro único com get(), one(), one_or_none()
• Filtragem com operadores de comparação (__gt, __lte, __contains, __startswith)
• Consultas baseadas em features (consultar por metadados anotados)
• Traversal entre registries com sintaxe de duplo underscore
• Busca de texto completo em registries
• Consultas lógicas avançadas com objetos Q (AND, OR, NOT)
• Streaming de datasets grandes sem carregar em memória

Workflows principais:

• Navegar artifacts com filtros e ordenação
• Consultar por features, data de criação, criador, tamanho, etc.
• Fazer streaming de arquivos grandes em chunks ou com slicing de array
• Organizar dados com chaves hierárquicas
• Agrupar artifacts em collections

Referência: references/data-management.md - Leia para padrões de consulta abrangentes, exemplos de filtragem, estratégias de streaming e melhores práticas de organização de dados.

3. Anotação e Validação

Processo de curação:

1. Validação: Confirmar que datasets correspondem aos esquemas desejados
2. Padronização: Corrigir typos, mapear sinônimos para termos canônicos
3. Anotação: Vincular datasets a entidades de metadados para consultabilidade

Tipos de esquema:

• Esquemas flexíveis: Validar apenas colunas conhecidas, permitir metadados adicionais
• Esquemas minimamente necessários: Especificar colunas essenciais, permitir extras
• Esquemas rígidos: Controle completo sobre estrutura e valores

Tipos de dados suportados:

• DataFrames (Parquet, CSV)
• AnnData (genômica de célula única)
• MuData (multimodal)
• SpatialData (transcriptômica espacial)
• TileDB-SOMA (arrays escaláveis)

Workflows principais:

• Definir features e esquemas para validação de dados
• Usar DataFrameCurator ou AnnDataCurator para validação
• Padronizar valores com .cat.standardize()
• Mapear para ontologias com .cat.add_ontology()
• Salvar artifacts curados com vinculação de esquema
• Consultar datasets validados por features

Referência: references/annotation-validation.md - Leia para workflows de curação detalhados, padrões de design de esquema, tratamento de erros de validação e melhores práticas.

4. Ontologias Biológicas

Ontologias disponíveis (via Bionty):

• Genes (Ensembl), Proteínas (UniProt)
• Tipos de célula (CL), Linhagens celulares (CLO)
• Tecidos (Uberon), Doenças (Mondo, DOID)
• Fenótipos (HPO), Pathways (GO)
• Fatores experimentais (EFO), Estágios de desenvolvimento
• Organismos (NCBItaxon), Drogas (DrugBank)

Workflows principais:

• Importar ontologias públicas com bt.CellType.import_source()
• Pesquisar ontologias com correspondência de palavra-chave ou exata
• Padronizar termos usando mapeamento de sinônimos
• Explorar relacionamentos hierárquicos (pais, filhos, ancestrais)
• Validar dados contra termos de ontologia
• Anotar datasets com registros de ontologia
• Criar termos e hierarquias customizadas
• Tratar contextos multiorganismo (humano, camundongo, etc.)

Referência: references/ontologies.md - Leia para operações abrangentes de ontologia, estratégias de padronização, navegação de hierarquia e workflows de anotação.

5. Integrações

Orquestradores de workflow:

• Nextflow: Rastrear processos e outputs de pipeline
• Snakemake: Integrar em regras de Snakemake
• Redun: Combinar com rastreamento de tarefas de Redun

Plataformas MLOps:

• Weights & Biases: Vincular experimentos com artifacts de dados
• MLflow: Rastrear modelos e experimentos
• HuggingFace: Rastrear fine-tuning de modelos
• scVI-tools: Workflows de análise de célula única

Sistemas de armazenamento:

• Sistema de arquivos local, AWS S3, Google Cloud Storage
• Compatível com S3 (MinIO, Cloudflare R2)
• Endpoints HTTP/HTTPS (somente leitura)
• Datasets HuggingFace

Array stores:

• TileDB-SOMA (com suporte cellxgene)
• DuckDB para consultas SQL em arquivos Parquet

Visualização:

• Vitessce para visualização interativa espacial/célula única

Controle de versão:

• Integração Git para rastreamento de código-fonte

Referência: references/integrations.md - Leia para padrões de integração, exemplos de código e troubleshooting para sistemas de terceiros.

6. Configuração e Deployment

Instalação:

• Básico: uv pip install lamindb
• Com extras: uv pip install 'lamindb[gcp,zarr,fcs]'
• Módulos: bionty, wetlab, clinical

Tipos de instância:

• SQLite local (desenvolvimento)
• Cloud storage + SQLite (pequenas equipes)
• Cloud storage + PostgreSQL (produção)

Opções de armazenamento:

• Sistema de arquivos local
• AWS S3 com regiões e permissões configuráveis
• Google Cloud Storage
• Endpoints compatíveis com S3 (MinIO, Cloudflare R2)

Configuração:

• Gerenciamento de cache para arquivos em nuvem
• Configurações de sistema multiusuário
• Sincronização de repositório Git
• Variáveis de ambiente

Padrões de deployment:

• Migração dev local → produção em nuvem
• Deployments multi-região
• Armazenamento compartilhado com instâncias pessoais

Referência: references/setup-deployment.md - Leia para instalação detalhada, configuração, setup de armazenamento, gerenciamento de banco de dados, melhores práticas de segurança e troubleshooting.

Workflows de Casos de Uso Comuns

Caso de Uso 1: Análise de RNA-seq de Célula Única com Validação de Ontologia

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

# Iniciar rastreamento
ln.track(params={"analysis": "scRNA-seq QC and annotation"})

# Importar ontologia de tipo de célula
bt.CellType.import_source()

# Carregar dados
adata = ad.read_h5ad("raw_counts.h5ad")

# Validar e padronizar tipos de célula
adata.obs["cell_type"] = bt.CellType.standardize(adata.obs["cell_type"])

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

# Vincular anotações de ontologia
cell_types = bt.CellType.from_values(adata.obs.cell_type)
artifact.feature_sets.add_ontology(cell_types)

ln.finish()

Caso de Uso 2: Construindo um Data Lakehouse Consultável

import lamindb as ln

# Registrar múltiplos 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 com features
    artifact.features.add_values({
        "batch": i,
        "tissue": tissues[i],
        "condition": conditions[i]
    })

# Consultar em todos os experimentos
immune_datasets = ln.Artifact.filter(
    key__startswith="scrna/",
    tissue="PBMC",
    condition="treated"
).to_dataframe()

# Carregar datasets específicos
for artifact in immune_datasets:
    adata = artifact.load()
    # Analisar

Caso de Uso 3: Pipeline ML com Integração W&B

import lamindb as ln
import wandb

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

# Carregar dados de treinamento do LaminDB
train_artifact = ln.Artifact.get(key="datasets/train.parquet")
train_data = train_artifact.load()

# Treinar modelo
model = train_model(train_data)

# Fazer log em W&B
wandb.log({"accuracy": 0.95})

# Salvar modelo no LaminDB com vinculação 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.add_values({"wandb_run_id": wandb.run.id})

ln.finish()
wandb.finish()

Caso de Uso 4: Integração com Pipeline Nextflow

# Em script de processo Nextflow
import lamindb as ln

ln.track()

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

# Processar (alinhamento, quantificação, etc.)
# ... lógica de processo Nextflow ...

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

ln.finish()

Checklist de Começando

Para começar a usar LaminDB efetivamente:

1. Instalação & Configuração (references/setup-deployment.md)

   • Instalar LaminDB e extras necessários
   • Autenticar com lamin login
   • Inicializar instância com lamin init --storage ...

2. Aprender Conceitos Centrais (references/core-concepts.md)

   • Entender Artifacts, Records, Runs, Transforms
   • Praticar criação e recuperação de artifacts
   • Implementar ln.track() e ln.finish() em workflows

3. Dominar Consultas (references/data-management.md)

   • Praticar filtragem e pesquisa de registries
   • Aprender consultas baseadas em features
   • Experimentar streaming de arquivos grandes

4. Configurar Validação (references/annotation-validation.md)

   • Definir features relevantes ao domínio de pesquisa
   • Criar esquemas para tipos de dados
   • Praticar workflows de curação

5. Integrar Ontologias (references/ontologies.md)

   • Importar ontologias biológicas relevantes (genes, tipos de célula, etc.)
   • Validar anotações existentes
   • Padronizar metadados com termos de ontologia

6. Conectar Ferramentas (references/integrations.md)

   • Integrar com orquestradores de workflow existentes
   • Vincular plataformas ML para rastreamento de experimentos
   • Configurar armazenamento em nuvem e compute

Princípios Principais

Siga esses princípios ao trabalhar com LaminDB:

1. Rastreie tudo: Use ln.track() no início de toda análise para captura automática de linhagem

2. Valide cedo: Defina esquemas e valide dados antes de análise extensa

3. Use ontologias: Aproveite ontologias biológicas públicas para anotações padronizadas

4. Organize com chaves: Estruture chaves de artifact hierarquicamente (ex: project/experiment/batch/file.h5ad)

5. Consulte metadados primeiro: Filtre e pesquise antes de carregar arquivos grandes

6. Versione, não duplique: Use versionamento integrado em vez de criar novas chaves para modificações

7. Anote com features: Defina features tipadas para metadados consultáveis

8. Documente completamente: Adicione descrições a artifacts, esquemas e transforms

9. Aproveite a linhagem: Use view_lineage() para entender proveniência de dados

10. Comece localmente, escale para nuvem: Desenvolva localmente com SQLite, faça deploy em nuvem com PostgreSQL

Arquivos de Referência

Esta habilidade inclui documentação de referência abrangente organizada por capacidade:

• references/core-concepts.md - Artifacts, records, runs, transforms, features, versionamento, linhagem
• references/data-management.md - Consultas, filtragem, pesquisa, streaming, organização de dados
• references/annotation-validation.md - Design de esquema, workflows de curação, estratégias de validação
• references/ontologies.md - Gerenciamento de ontologia biológica, padronização, hierarquias
• references/integrations.md - Orquestradores de workflow, plataformas MLOps, sistemas de armazenamento, ferramentas
• references/setup-deployment.md - Instalação, configuração, deployment, troubleshooting

Leia o(s) arquivo(s) de referência relevante(s) baseado na capacidade específica de LaminDB necessária para a tarefa em mãos.

Recursos Adicionais

• Documentação Oficial: https://docs.lamin.ai
• Referência de API: https://docs.lamin.ai/api
• Repositório GitHub: https://github.com/laminlabs/lamindb
• Tutorial: https://docs.lamin.ai/tutorial
• FAQ: https://docs.lamin.ai/faq