Deepchem

DeepChem

Visão Geral

DeepChem é uma biblioteca Python abrangente para aplicar machine learning à química, ciência de materiais e biologia. Habilite predição de propriedades moleculares, descoberta de fármacos, design de materiais e análise de biomoléculas através de redes neurais especializadas, métodos de featurização molecular e modelos pré-treinados.

Quando Usar Esta Skill

Esta skill deve ser usada quando:

• Carregando e processando dados moleculares (strings SMILES, arquivos SDF, sequências de proteínas)
• Prevendo propriedades moleculares (solubilidade, toxicidade, afinidade de ligação, propriedades ADMET)
• Treinando modelos em conjuntos de dados químicos/biológicos
• Usando conjuntos de dados benchmark MoleculeNet (Tox21, BBBP, Delaney, etc.)
• Convertendo moléculas em features prontas para ML (fingerprints, representações em grafo, descritores)
• Implementando redes neurais convolucionais de grafos para moléculas (GCN, GAT, MPNN, AttentiveFP)
• Aplicando transfer learning com modelos pré-treinados (ChemBERTa, GROVER, MolFormer)
• Prevendo propriedades de cristais/materiais (bandgap, energia de formação)
• Analisando sequências de proteínas ou DNA

Capacidades Principais

1. Carregamento e Processamento de Dados Moleculares

DeepChem fornece loaders especializados para vários formatos de dados químicos:

import deepchem as dc

# Carregar CSV com SMILES
featurizer = dc.feat.CircularFingerprint(radius=2, size=2048)
loader = dc.data.CSVLoader(
    tasks=['solubility', 'toxicity'],
    feature_field='smiles',
    featurizer=featurizer
)
dataset = loader.create_dataset('molecules.csv')

# Carregar arquivos SDF
loader = dc.data.SDFLoader(tasks=['activity'], featurizer=featurizer)
dataset = loader.create_dataset('compounds.sdf')

# Carregar sequências de proteínas
loader = dc.data.FASTALoader()
dataset = loader.create_dataset('proteins.fasta')

Loaders Principais:

• CSVLoader: Dados tabulares com identificadores moleculares
• SDFLoader: Arquivos de estrutura molecular
• FASTALoader: Sequências de proteínas/DNA
• ImageLoader: Imagens moleculares
• JsonLoader: Conjuntos de dados em formato JSON

2. Featurização Molecular

Converta moléculas em representações numéricas para modelos de ML.

Árvore de Decisão para Seleção de Featurizer

O modelo é uma rede neural de grafos?
├─ SIM → Use featurizers de grafos
│   ├─ GNN padrão → MolGraphConvFeaturizer
│   ├─ Message passing → DMPNNFeaturizer
│   └─ Pré-treinado → GroverFeaturizer
│
└─ NÃO → Que tipo de modelo?
    ├─ ML tradicional (RF, XGBoost, SVM)
    │   ├─ Baseline rápido → CircularFingerprint (ECFP)
    │   ├─ Interpretável → RDKitDescriptors
    │   └─ Cobertura máxima → MordredDescriptors
    │
    ├─ Deep learning (não-grafo)
    │   ├─ Redes densas → CircularFingerprint
    │   └─ CNN → SmilesToImage
    │
    ├─ Modelos de sequência (LSTM, Transformer)
    │   └─ SmilesToSeq
    │
    └─ Análise de estrutura 3D
        └─ CoulombMatrix

Exemplo de Featurização

# Fingerprints (para ML tradicional)
fp = dc.feat.CircularFingerprint(radius=2, size=2048)

# Descritores (para modelos interpretáveis)
desc = dc.feat.RDKitDescriptors()

# Features de grafos (para GNNs)
graph_feat = dc.feat.MolGraphConvFeaturizer()

# Aplicar featurização
features = fp.featurize(['CCO', 'c1ccccc1'])

Guia de Seleção:

• Conjuntos pequenos (<1K): CircularFingerprint ou RDKitDescriptors
• Conjuntos médios (1K-100K): CircularFingerprint ou featurizers de grafos
• Conjuntos grandes (>100K): Featurizers de grafos (MolGraphConvFeaturizer, DMPNNFeaturizer)
• Transfer learning: Featurizers de modelos pré-treinados (GroverFeaturizer)

Veja references/api_reference.md para documentação completa de featurizers.

3. Divisão de Dados

Crítico: Para tarefas de descoberta de fármacos, use ScaffoldSplitter para evitar data leakage de estruturas moleculares semelhantes aparecendo em conjuntos de treino e teste.

# Divisão por scaffold (recomendado para moléculas)
splitter = dc.splits.ScaffoldSplitter()
train, valid, test = splitter.train_valid_test_split(
    dataset,
    frac_train=0.8,
    frac_valid=0.1,
    frac_test=0.1
)

# Divisão aleatória (para dados não-moleculares)
splitter = dc.splits.RandomSplitter()
train, test = splitter.train_test_split(dataset)

# Divisão estratificada (para classificação desbalanceada)
splitter = dc.splits.RandomStratifiedSplitter()
train, test = splitter.train_test_split(dataset)

Splitters Disponíveis:

• ScaffoldSplitter: Dividir por scaffolds moleculares (previne leakage)
• ButinaSplitter: Divisão molecular baseada em clustering
• MaxMinSplitter: Maximizar diversidade entre conjuntos
• RandomSplitter: Divisão aleatória
• RandomStratifiedSplitter: Preserva distribuições de classe

4. Seleção de Modelo e Treinamento

Guia Rápido de Seleção de Modelo

Exemplo: ML Tradicional

from sklearn.ensemble import RandomForestRegressor

# Encapsular modelo scikit-learn
sklearn_model = RandomForestRegressor(n_estimators=100)
model = dc.models.SklearnModel(model=sklearn_model)
model.fit(train)

Exemplo: Deep Learning

# Regressor multitarefa (para fingerprints)
model = dc.models.MultitaskRegressor(
    n_tasks=2,
    n_features=2048,
    layer_sizes=[1000, 500],
    dropouts=0.25,
    learning_rate=0.001
)
model.fit(train, nb_epoch=50)

Exemplo: Redes Neurais de Grafos

# Graph Convolutional Network
model = dc.models.GCNModel(
    n_tasks=1,
    mode='regression',
    batch_size=128,
    learning_rate=0.001
)
model.fit(train, nb_epoch=50)

# Graph Attention Network
model = dc.models.GATModel(n_tasks=1, mode='classification')
model.fit(train, nb_epoch=50)

# Attentive Fingerprint
model = dc.models.AttentiveFPModel(n_tasks=1, mode='regression')
model.fit(train, nb_epoch=50)

5. Benchmarks MoleculeNet

Acesso rápido a 30+ conjuntos de dados benchmark curados com divisões treino/validação/teste padronizadas:

# Carregar conjunto de dados benchmark
tasks, datasets, transformers = dc.molnet.load_tox21(
    featurizer='GraphConv',  # ou 'ECFP', 'Weave', 'Raw'
    splitter='scaffold',     # ou 'random', 'stratified'
    reload=False
)
train, valid, test = datasets

# Treinar e avaliar
model = dc.models.GCNModel(n_tasks=len(tasks), mode='classification')
model.fit(train, nb_epoch=50)

metric = dc.metrics.Metric(dc.metrics.roc_auc_score)
test_score = model.evaluate(test, [metric])

Conjuntos de Dados Comuns:

• Classificação: load_tox21(), load_bbbp(), load_hiv(), load_clintox()
• Regressão: load_delaney(), load_freesolv(), load_lipo()
• Propriedades quânticas: load_qm7(), load_qm8(), load_qm9()
• Materiais: load_perovskite(), load_bandgap(), load_mp_formation_energy()

Veja references/api_reference.md para lista completa de conjuntos de dados.

6. Transfer Learning

Aproveite modelos pré-treinados para melhor desempenho, especialmente em conjuntos pequenos:

# ChemBERTa (BERT pré-treinado em 77M moléculas)
model = dc.models.HuggingFaceModel(
    model='seyonec/ChemBERTa-zinc-base-v1',
    task='classification',
    n_tasks=1,
    learning_rate=2e-5  # LR mais baixa para fine-tuning
)
model.fit(train, nb_epoch=10)

# GROVER (transformador de grafos pré-treinado em 10M moléculas)
model = dc.models.GroverModel(
    task='regression',
    n_tasks=1
)
model.fit(train, nb_epoch=20)

Quando usar transfer learning:

• Conjuntos pequenos (< 1000 samples)
• Scaffolds moleculares novos
• Recursos computacionais limitados
• Necessidade de prototipagem rápida

Use o script scripts/transfer_learning.py para workflows de transfer learning guiados.

7. Avaliação de Modelo

# Definir métricas
classification_metrics = [
    dc.metrics.Metric(dc.metrics.roc_auc_score, name='ROC-AUC'),
    dc.metrics.Metric(dc.metrics.accuracy_score, name='Accuracy'),
    dc.metrics.Metric(dc.metrics.f1_score, name='F1')
]

regression_metrics = [
    dc.metrics.Metric(dc.metrics.r2_score, name='R²'),
    dc.metrics.Metric(dc.metrics.mean_absolute_error, name='MAE'),
    dc.metrics.Metric(dc.metrics.root_mean_squared_error, name='RMSE')
]

# Avaliar
train_scores = model.evaluate(train, classification_metrics)
test_scores = model.evaluate(test, classification_metrics)

8. Fazendo Previsões

# Prever no conjunto de teste
predictions = model.predict(test)

# Prever em novas moléculas
new_smiles = ['CCO', 'c1ccccc1', 'CC(C)O']
new_features = featurizer.featurize(new_smiles)
new_dataset = dc.data.NumpyDataset(X=new_features)

# Aplicar mesmas transformações do treinamento
for transformer in transformers:
    new_dataset = transformer.transform(new_dataset)

predictions = model.predict(new_dataset)

Workflows Típicos

Workflow A: Avaliação Rápida em Benchmark

Para avaliar um modelo em benchmarks padrão:

import deepchem as dc

# 1. Carregar benchmark
tasks, datasets, _ = dc.molnet.load_bbbp(
    featurizer='GraphConv',
    splitter='scaffold'
)
train, valid, test = datasets

# 2. Treinar modelo
model = dc.models.GCNModel(n_tasks=len(tasks), mode='classification')
model.fit(train, nb_epoch=50)

# 3. Avaliar
metric = dc.metrics.Metric(dc.metrics.roc_auc_score)
test_score = model.evaluate(test, [metric])
print(f"Test ROC-AUC: {test_score}")

Workflow B: Previsão com Dados Personalizados

Para treinar em conjuntos de dados moleculares personalizados:

import deepchem as dc

# 1. Carregar e featurizar dados
featurizer = dc.feat.CircularFingerprint(radius=2, size=2048)
loader = dc.data.CSVLoader(
    tasks=['activity'],
    feature_field='smiles',
    featurizer=featurizer
)
dataset = loader.create_dataset('my_molecules.csv')

# 2. Dividir dados (use ScaffoldSplitter para moléculas!)
splitter = dc.splits.ScaffoldSplitter()
train, valid, test = splitter.train_valid_test_split(dataset)

# 3. Normalizar (opcional mas recomendado)
transformers = [dc.trans.NormalizationTransformer(
    transform_y=True, dataset=train
)]
for transformer in transformers:
    train = transformer.transform(train)
    valid = transformer.transform(valid)
    test = transformer.transform(test)

# 4. Treinar modelo
model = dc.models.MultitaskRegressor(
    n_tasks=1,
    n_features=2048,
    layer_sizes=[1000, 500],
    dropouts=0.25
)
model.fit(train, nb_epoch=50)

# 5. Avaliar
metric = dc.metrics.Metric(dc.metrics.r2_score)
test_score = model.evaluate(test, [metric])

Workflow C: Transfer Learning em Pequeno Dataset

Para aproveitar modelos pré-treinados:

import deepchem as dc

# 1. Carregar dados (modelos pré-treinados frequentemente precisam de SMILES bruto)
loader = dc.data.CSVLoader(
    tasks=['activity'],
    feature_field='smiles',
    featurizer=dc.feat.DummyFeaturizer()  # Modelo trata featurização
)
dataset = loader.create_dataset('small_dataset.csv')

# 2. Dividir dados
splitter = dc.splits.ScaffoldSplitter()
train, test = splitter.train_test_split(dataset)

# 3. Carregar modelo pré-treinado
model = dc.models.HuggingFaceModel(
    model='seyonec/ChemBERTa-zinc-base-v1',
    task='classification',
    n_tasks=1,
    learning_rate=2e-5
)

# 4. Fine-tune
model.fit(train, nb_epoch=10)

# 5. Avaliar
predictions = model.predict(test)

Veja references/workflows.md para 8 exemplos de workflows detalhados cobrindo geração molecular, ciência de materiais, análise de proteínas e mais.

Scripts de Exemplo

Esta skill inclui três scripts prontos para produção no diretório scripts/:

1. predict_solubility.py

Treinar e avaliar modelos de predição de solubilidade. Funciona com benchmark Delaney ou dados CSV personalizados.

# Usar benchmark Delaney
python scripts/predict_solubility.py

# Usar dados personalizados
python scripts/predict_solubility.py \
    --data my_data.csv \
    --smiles-col smiles \
    --target-col solubility \
    --predict "CCO" "c1ccccc1"

2. graph_neural_network.py

Treinar várias arquiteturas de redes neurais de grafos em dados moleculares.

# Treinar GCN em Tox21
python scripts/graph_neural_network.py --model gcn --dataset tox21

# Treinar AttentiveFP em dados personalizados
python scripts/graph_neural_network.py \
    --model attentivefp \
    --data molecules.csv \
    --task-type regression \
    --targets activity \
    --epochs 100

3. transfer_learning.py

Fine-tune modelos pré-treinados (ChemBERTa, GROVER) em tarefas de predição de propriedades moleculares.

# Fine-tune ChemBERTa em BBBP
python scripts/transfer_learning.py --model chemberta --dataset bbbp

# Fine-tune GROVER em dados personalizados
python scripts/transfer_learning.py \
    --model grover \
    --data small_dataset.csv \
    --target activity \
    --task-type classification \
    --epochs 20

Padrões Comuns e Melhores Práticas

Padrão 1: Sempre Use Scaffold Splitting para Moléculas

# BOM: Previne data leakage
splitter = dc.splits.ScaffoldSplitter()
train, test = splitter.train_test_split(dataset)

# RUIM: Moléculas semelhantes em treino e teste
splitter = dc.splits.RandomSplitter()
train, test = splitter.train_test_split(dataset)

Padrão 2: Normalize Features e Targets

transformers = [
    dc.trans.NormalizationTransformer(
        transform_y=True,  # Também normalizar valores de target
        dataset=train
    )
]
for transformer in transformers:
    train = transformer.transform(train)
    test = transformer.transform(test)

Padrão 3: Comece Simples, Depois Escale

1. Comece com Random Forest + CircularFingerprint (baseline rápido)
2. Tente XGBoost/LightGBM se RF funcionar bem
3. Mude para deep learning (MultitaskRegressor) se tiver >5K samples
4. Tente GNNs se tiver >10K samples
5. Use transfer learning para conjuntos pequenos ou scaffolds novos

Padrão 4: Lidar com Dados Desbalanceados

# Opção 1: Transformador de balanceamento
transformer = dc.trans.BalancingTransformer(dataset=train)
train = transformer.transform(train)

# Opção 2: Usar métricas balanceadas
metric = dc.metrics.Metric(dc.metrics.balanced_accuracy_score)

Padrão 5: Evitar Problemas de Memória

# Usar DiskDataset para conjuntos grandes
dataset = dc.data.DiskDataset.from_numpy(X, y, w, ids)

# Usar batch sizes menores
model = dc.models.GCNModel(batch_size=32)  # Em vez de 128

Armadilhas Comuns

Issue 1: Data Leakage em Descoberta de Fármacos

Problema: Usar divisão aleatória permite moléculas semelhantes em conjuntos treino/teste. Solução: Sempre use ScaffoldSplitter para conjuntos de dados moleculares.

Issue 2: GNN Underperforming vs Fingerprints

Problema: Redes neurais de grafos têm pior desempenho que fingerprints simples. Soluções:

• Certifique-se que o dataset é grande o suficiente (>10K samples geralmente)
• Aumente as épocas de treinamento (50-100)
• Tente diferentes arquiteturas (AttentiveFP, DMPNN em vez de GCN)
• Use modelos pré-treinados (GROVER)

Issue 3: Overfitting em Pequenos Conjuntos

Problema: Modelo memoriza dados de treino. Soluções:

• Use regularização mais forte (aumente dropout para 0.5)
• Use modelos mais simples (Random Forest em vez de deep learning)
• Aplique transfer learning (ChemBERTa, GROVER)
• Colete mais dados

Issue 4: Erros de Import

Problema: Erros de módulo não encontrado. Solução: Certifique-se que DeepChem está instalado com dependências necessárias:

uv pip install deepchem
# Para modelos PyTorch
uv pip install deepchem[torch]
# Para todos os recursos
uv pip install deepchem[all]

Documentação de Referência

Esta skill inclui documentação de referência abrangente:

references/api_reference.md

Documentação completa de API incluindo:

• Todos os data loaders e seus casos de uso
• Classes de datasets e quando usar cada uma
• Catálogo completo de featurizers com guia de seleção
• Catálogo de modelos organizado por categoria (50+ modelos)
• Descrições de conjuntos de dados MoleculeNet
• Funções de métricas e avaliação
• Padrões de código comuns

Quando consultar: Busque neste arquivo quando precisar de detalhes específicos de API, nomes de parâmetros, ou quiser explorar opções disponíveis.

references/workflows.md

Oito workflows detalhados end-to-end:

1. Predição de propriedades moleculares a partir de SMILES
2. Usando benchmarks MoleculeNet
3. Otimização de hiperparâmetros
4. Transfer learning com modelos pré-treinados
5. Geração molecular com GANs
6. Predição de propriedades de materiais
7. Análise de sequências de proteínas
8. Integração de modelo personalizado

Quando consultar: Use estes workflows como templates para implementar soluções completas.

Notas de Instalação

Instalação básica:

uv pip install deepchem

Para modelos PyTorch (GCN, GAT, etc.):

uv pip install deepchem[torch]

Para todos os recursos:

uv pip install deepchem[all]

Se erros de import ocorrerem, o usuário pode precisar de dependências específicas. Verifique a documentação DeepChem para instruções detalhadas de instalação.

Recursos Adicionais

• Documentação oficial: https://deepchem.readthedocs.io/
• Repositório GitHub: https://github.com/deepchem/deepchem
• Tutoriais: https://deepchem.readthedocs.io/en/latest/get_started/tutorials.html
• Paper: "MoleculeNet: A Benchmark for Molecular Machine Learning"