lamindb

O que lamindb faz?

Visão Geral

LaminDB é um lakehouse de código aberto e nativo de linhagem para biologia. Ele torna conjuntos de dados e modelos consultáveis, rastreáveis, validados, reproduzíveis e FAIR (Encontrável, Acessível, Interoperável, Reutilizável), enquanto armazena dados em formatos abertos em sistemas de arquivos locais, S3, GCS, Hugging Face, SQLite e Postgres.

Proposta de Valor Central:

• Consultabilidade: Pesquisar e filtrar artefatos, registros, execuções, recursos, esquemas e coleções
• Rastreabilidade: Rastrear entradas, saídas, parâmetros, código-fonte e ambientes para notebooks, scripts, funções e pipelines
• Validação: Curar DataFrames, AnnData, SpatialData, TileDB-SOMA, Parquet, Zarr e outros formatos biológicos com esquemas
• Conformidade FAIR: Padronizar anotações com ontologias baseadas em Bionty e registros personalizados
• Gerenciamento de mudanças: Organizar trabalho com projetos, branches, espaços, coleções e notas ou planos salvos

Quando Usar Esta Habilidade

Use esta habilidade quando:

• Gerenciando conjuntos de dados biológicos: scRNA-seq, bulk RNA-seq, transcriptômica espacial, citometria de fluxo, dados multimodais, dados de prontuários eletrônicos
• Rastreando fluxos de trabalho computacionais: Notebooks, scripts, funções, scripts de shell e execução de pipelines (Nextflow, Snakemake, Redun)
• Curando e validando dados: Validação de esquemas, padronização, anotação baseada em ontologia
• Trabalhando com ontologias biológicas: Genes, proteínas, tipos celulares, tecidos, doenças, vias (via Bionty)
• Construindo data lakehouses: Interface de consulta unificada em múltiplos conjuntos de dados
• Garantindo reprodutibilidade: Versionamento automático, rastreamento de linhagem, captura de ambiente
• Integrando pipelines de ML: Conectando com Weights & Biases, MLflow, Hugging Face, Lightning, scVI-tools
• Implantando infraestrutura de dados: Configurando sistemas de gerenciamento de dados locais ou na nuvem
• Colaborando em conjuntos de dados: Compartilhando dados curados e anotados com metadados padronizados

Capacidades Principais

LaminDB fornece seis áreas de capacidade interconectadas, cada uma documentada em detalhes na pasta de referências.

1. Conceitos Principais e Linhagem de Dados

Entidades principais:

• Artefatos: Conjuntos de dados versionados (DataFrame, AnnData, Parquet, Zarr, etc.)
• Registros e ULabels: Entidades experimentais, registros tipados e etiquetas simples
• Coleções: Conjuntos versionados e imutáveis de artefatos
• Execuções e Transformações: Rastreamento de linhagem computacional (qual código produziu quais dados)
• Recursos: Campos de metadados tipados para anotação e consulta
• Projetos, Branches e Espaços: Agrupamento de projetos, gerenciamento de mudanças e limites de acesso

Fluxos de trabalho principais:

• Criar e versionar artefatos a partir de arquivos ou objetos Python
• Rastrear execução de notebook/script com ln.track() e ln.finish()
• Rastrear fluxos de trabalho de funções com @ln.flow() e @ln.step()
• Anotar artefatos com registros, ulabels, projetos e recursos tipados
• Visualizar grafos de linhagem de dados com artifact.view_lineage()
• Consultar por proveniência (encontrar todas as saídas de código/entradas específicas)

Referência: references/core-concepts.md - Leia isto para informações detalhadas sobre artefatos, registros, execuções, transformações, recursos, versionamento e rastreamento de linhagem.

2. Gerenciamento e Consulta de Dados

Capacidades de consulta:

• Exploração e busca de registros com auto-completar
• Recuperação de registro único com get(), one(), one_or_none()
• Filtragem com operadores de comparação (__gt, __lte, __contains, __startswith)
• Consultas baseadas em recursos, incluindo consultas do tipo expressão com objetos Feature
• Travessia entre registros com sintaxe de duplo sublinhado
• Pesquisa de texto completo em registros
• Consultas lógicas avançadas com objetos ln.Q (AND, OR, NOT)
• Streaming de grandes conjuntos de dados sem carregar na memória

Fluxos de trabalho principais:

• Navegar por artefatos com filtros e ordenação
• Consultar por recursos, data de criação, criador, tamanho, etc.
• Transmitir arquivos grandes em partes ou com fatiamento de array
• Organizar dados com chaves hierárquicas
• Agrupar artefatos em coleções

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

3. Anotação e Validação

Processo de curadoria:

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

Tipos de esquema:

• Esquemas flexíveis: Validar apenas colunas conhecidas, permitir metadados adicionais
• Esquemas mínimos obrigatórios: Especificar colunas essenciais, permitir extras
• Esquemas estritos: 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)

Fluxos de trabalho principais:

• Definir recursos e esquemas para validação de dados
• Usar DataFrameCurator, AnnDataCurator, SpatialDataCurator ou TiledbsomaExperimentCurator para validação
• Padronizar valores com .cat.standardize()
• Mapear para ontologias com .cat.add_ontology()
• Salvar artefatos curados com vinculação de esquema
• Consultar conjuntos de dados validados por recursos

Referência: references/annotation-validation.md - Leia isto para fluxos de trabalho detalhados de curadoria, padrões de design de esquemas, 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 celulares (CL), Linhagens celulares (CLO)
• Tecidos (Uberon), Doenças (Mondo, DOID)
• Fenótipos (HPO), Vias (GO)
• Fatores experimentais (EFO), Estágios de desenvolvimento
• Organismos (NCBItaxon), Fármacos (DrugBank)

Fluxos de trabalho 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 relações hierárquicas (pais, filhos, ancestrais)
• Validar dados em relação a termos de ontologia
• Anotar conjuntos de dados com registros de ontologia
• Criar termos e hierarquias personalizados
• Lidar com contextos de múltiplos organismos (humano, camundongo, etc.)

Referência: references/ontologies.md - Leia isto para operações abrangentes de ontologia, estratégias de padronização, navegação hierárquica e fluxos de trabalho de anotação.

5. Integrações

Gerenciadores de fluxo de trabalho:

• Nextflow: Rastrear processos e saídas de pipeline
• Snakemake: Integrar em regras Snakemake
• Redun: Combinar com rastreamento de tarefas Redun
• Lightning: Persistir checkpoints e metadados de treinamento

Plataformas MLOps:

• Weights & Biases: Vincular experimentos com artefatos de dados
• MLflow: Rastrear modelos e experimentos
• Hugging Face: Rastrear ajuste fino de modelos
• scVI-tools: Fluxos de trabalho 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)
• Conjuntos de dados HuggingFace

Armazenamentos de array:

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

Visualização:

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

Controle de versão:

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

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

6. Configuração e Implantação

Instalação:

• Versão estável atual: lamindb==2.5.1 (lançado em 01/06/2026; Python >=3.10, <=3.14)
• Básico: uv pip install 'lamindb==2.5.1'
• Com extras: uv pip install 'lamindb[gcp,zarr-v2,fcs]==2.5.1'
• Apenas namespace mínimo: uv pip install 'lamindb-core==2.5.1'
• Módulo Bionty: incluído na documentação LaminDB e disponível como uv pip install 'bionty==2.4.0'
• Módulos opcionais: fixar versões revisadas para módulos de esquema wetlab ou clínico, em vez de instalar as versões mais recentes flutuantes

Tipos de instância:

• SQLite local (desenvolvimento)
• Armazenamento na nuvem + SQLite (equipes pequenas)
• Armazenamento na nuvem + 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 na nuvem
• Configurações de sistema multiusuário
• Sincronização de repositório Git
• Variáveis de ambiente nomeadas para credenciais e URLs de conexão

Padrões de implantação:

• Migração de desenvolvimento local para produção na nuvem
• Implantações multirregião
• Armazenamento compartilhado com instâncias pessoais

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

Padrões de Segurança e Proteção

Ao ajudar com a configuração ou integrações do LaminDB:

• Nunca exiba, registre ou transmita chaves de API reais, credenciais de nuvem, senhas de banco de dados ou strings de conexão completas que incluam segredos.
• Prefira funções IAM, identidade de carga de trabalho, gerenciadores de segredos ou variáveis de ambiente nomeadas como LAMIN_DB_URL, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY e GOOGLE_APPLICATION_CREDENTIALS; apenas verifique se uma variável nomeada está presente, não seu valor.
• Antes de salvar conteúdo de APIs REST, bancos de dados externos ou arquivos fornecidos pelo usuário, valide e sanitize-o com um esquema ou curador explícito.
• Para instalações reproduzíveis, fixe versões de pacotes ou use um arquivo de bloqueio. Instalações flutuantes são aceitáveis apenas quando o usuário explicitamente deseja a versão upstream mais recente.

Fluxos de Trabalho 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 de execução de notebook/script
ln.track(params={"analysis": "scRNA-seq QC e anotação"})

# Importar ontologia de tipo celular
bt.CellType.import_source()

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

# Validar e padronizar tipos celulares
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 baseadas em ontologia para consultabilidade
cell_types = bt.CellType.from_values(adata.obs["cell_type"])
artifact.cell_types.add(*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 lote {i}"
    ).save()

    # Anotar com recursos
    artifact.features.set_values({
        "batch": i,
        "tissue": tissues[i],
        "condition": conditions[i]
    })

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

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

Caso de Uso 3: Pipeline de 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)

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

# Salvar modelo no LaminDB com vinculação 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: Integração de Pipeline Nextflow

# No script de processo Nextflow
import lamindb as ln

ln.track()

# Carregar artefato 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 do processo Nextflow ...

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

ln.finish()

Para projetos nativos Nextflow, prefira o plugin nf-lamin e os padrões atuais de nextflow.config quando disponíveis; use rastreamento Python embutido para etapas pequenas ou personalizadas do pipeline.

Lista de Verificação para Início

Para começar a usar LaminDB efetivamente:

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

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

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

   • Entender Artefatos, Registros, Execuções, Transformações
   • Praticar criação e recuperação de artefatos
   • Implementar ln.track()/ln.finish() ou @ln.flow()/@ln.step() em fluxos de trabalho

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

   • Praticar filtragem e pesquisa em registros
   • Aprender consultas baseadas em recursos e filtros do tipo expressão
   • Experimentar streaming de arquivos grandes

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

   • Definir recursos relevantes para o domínio de pesquisa
   • Criar esquemas para tipos de dados
   • Praticar fluxos de trabalho de curadoria

5. Integrar Ontologias (references/ontologies.md)

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

6. Conectar Ferramentas (references/integrations.md)

   • Integrar com gerenciadores de fluxo de trabalho existentes
   • Vincular plataformas de ML para rastreamento de experimentos
   • Configurar armazenamento e computação em nuvem

Princípios Chave

Siga estes princípios ao trabalhar com LaminDB:

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

2. Valide cedo: Defina esquemas e valide dados antes de análises extensas

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

4. Versionamento consistente: Crie artefatos versionados e use coleções para conjuntos imutáveis

5. Preferir resultados determinísticos: Sempre fixe versões de pacotes para reprodutibilidade

6. Compartilhe dados de forma anotada: Sempre que possível, incorpore metadados e anotações diretamente nos artefatos

Referências em Detalhe

Cada uma das áreas de capacidade acima é expandida em documentos de referência dedicados dentro da pasta references/. Use estes atalhos para navegação rápida:

• references/core-concepts.md — Leia primeiro para obter uma base sobre artefatos, registros, linhagem e versionamento.
• references/data-management.md — Leia depois para dominar consultas, filtragem e organização de dados.
• references/annotation-validation.md — Consulte ao configurar validação de dados e fluxos de trabalho de curadoria.
• references/ontologies.md — Consulte ao trabalhar com ontologias biológicas e padronização.
• references/integrations.md — Consulte para padrões de conexão com sistemas externos (MLflow, W&B, Hugging Face, Nextflow, etc.).
• references/setup-deployment.md — Consulte para guias detalhados de instalação, configuração de armazenamento e procedimentos de implantação.

Considerações Finais

LaminDB é uma ferramenta poderosa para cientistas de dados e bioinformatas que precisam gerenciar conjuntos de dados biológicos complexos. Ao seguir as práticas recomendadas descritas nesta habilidade, os usuários podem garantir que seus dados sejam reprodutíveis, rastreáveis e facilmente descobertos.