Arboreto

Quando usar

Use Arboreto para classificar associações candidatas entre reguladores e alvos a partir de medições de expressão. GRNBoost2 ajusta regressões de gradient boosting estocástico; GENIE3 ajusta random forests. Cada alvo é previsto a partir de reguladores candidatos, excluindo a si mesmo. Estas são associações preditivas observacionais, não prova de ligação direta, ativação/repressão ou regulação causal.

A versão mais recente do PyPI verificada é a 0.1.6 (09/02/2021). O Read the Docs ainda rotula sua documentação como 0.1.5; o código fonte atual do GitHub contém correções que não estão no wheel do PyPI. Não assuma que uma instalação sem pin bem-sucedida pode executar inferência. Veja detalhes de compatibilidade e distribuição.

Instalação e compatibilidade

A seguinte pilha exata passou nos testes de fumaça para GRNBoost2 denso e CSC-esparso, GENIE3 denso, GBM/RF customizado e wrappers no macOS arm64 com Python 3.11.11:

uv venv --python 3.11 .venv-arboreto
uv pip install --python .venv-arboreto/bin/python \
  'arboreto==0.1.6' 'dask[complete]==2024.7.1' 'distributed==2024.7.1' \
  'numpy==1.26.4' 'pandas==2.2.3' 'scikit-learn==1.5.2' 'scipy==1.13.1'

Esta é uma receita de compatibilidade limitada, não uma afirmação de que as versões atuais de todas as dependências funcionam. O Arboreto do PyPI constrói um grafo de metadados vazio que a implementação mais nova do dataframe Dask rejeita. Para esta versão fixada do Dask, selecione seu backend de dataframe legado antes de importar Arboreto ou dask.dataframe:

import dask
dask.config.set({"dataframe.query-planning": False})
from arboreto.algo import grnboost2, genie3

O wrapper empacotado faz isso para o Dask 2024.7.1. Reinicie um kernel de notebook existente se ele já importou o backend de dataframe mais novo. Alvos esparsos também usam .A dentro do Arboreto 0.1.6; este atributo foi removido no SciPy 1.14. Mantenha o pin SciPy testado para inferência esparsa. Nenhum monkeypatch no site-packages é exigido por esta receita.

Fluxo de trabalho

1. Selecione células/amostras biologicamente comparáveis; documente normalização, filtragem, tratamento de batch, organismo, namespace de identificador e camada de expressão.
2. Prepare linhas = observações, colunas = genes. Exclua IDs de amostra dos valores de expressão. Exija nomes de genes únicos, valores numéricos finitos e uma lista de TFs com sobreposição não vazia. Genes totalmente zero/constantes não fornecem alvos úteis.
3. Escolha GRNBoost2 para uma análise inicial eficiente, GENIE3 para comparação de métodos, ou diy para configurações explícitas de regressores. Veja algoritmos.
4. Execute um pequeno subconjunto primeiro no ambiente fixado, depois escale as contagens de workers para a memória disponível. Mantenha a proteção if __name__ == "__main__": em scripts baseados em processos.
5. Inspecione avisos de workers e cobertura de alvos, salve a rede classificada completa e avalie a estabilidade entre seeds e observações reamostradas antes de priorizar arestas.

Execute o wrapper empacotado

A partir deste diretório de skill, com um TSV contendo cabeçalhos de genes e linhas numéricas:

.venv-arboreto/bin/python scripts/basic_grn_inference.py expression_data.tsv network.tsv \
  --tf-file tfs.txt --seed 777 --workers 2 --limit 5000

Adicione --index-col 0 apenas se a primeira coluna contiver identificadores de célula/amostra. O wrapper rejeita cabeçalhos duplicados antes que o pandas possa renomeá-los, valores não numéricos ou não finitos, sobreposição de TF vazia, limites inválidos e resultados completamente vazios. Ele relata a sobreposição de TF e usa um novo cliente Dask limitado que fecha em caso de erro. O padrão é um worker; aumente-o após um piloto bem-sucedido. Sem um arquivo de TF, todos os genes são reguladores candidatos, mesmo que a coluna de saída seja nomeada TF.

A saída é um TSV sem cabeçalho na ordem TF, target, importance. Para consumidores a jusante que exigem cabeçalhos de coluna (incluindo carregamento de adjacência pySCENIC), escreva uma cópia separada com header=True em vez de assumir que toda ferramenta aceita o formato de exemplo de entrada sem cabeçalho.

Exemplo mínimo de Python

Este exemplo sintético verifica a execução e a estrutura de saída; não é um benchmark biológico. As mesmas chamadas foram testadas com um fixture de 32 observações e quatro genes.

import dask
dask.config.set({"dataframe.query-planning": False})
import numpy as np
import pandas as pd
from arboreto.algo import grnboost2
from distributed import Client, LocalCluster

if __name__ == "__main__":
    rng = np.random.default_rng(123)
    values = rng.normal(size=(32, 4))
    values[:, 2] = 3 * values[:, 0] + rng.normal(scale=0.1, size=32)

…