Molfeat — Featurização de pequenas moléculas

Quando usar

Use esta funcionalidade para transformar SMILES ou moléculas RDKit em fingerprints, descritores, farmacóforos ou embeddings pré-treinados para aprendizado de máquina molecular e busca por similaridade. Compare representações no mesmo split molecular e endpoint de ensaio.

Esta funcionalidade tem como alvo Molfeat 1.0.0. As orientações anteriores para o runtime 0.11 estão obsoletas: 1.x suporta Python moderno e remove DGL/DGLLife, Graphormer legado e adaptadores de proteína. Cartões históricos do model-store ainda podem nomear adaptadores removidos. O guia de migração 1.0 marcado e o código fonte têm precedência sobre páginas mais antigas ainda servidas no URL da documentação stable.

Instalação

Crie um ambiente isolado. Exemplos principais foram executados em Python 3.13.3/macOS Apple Silicon com Molfeat 1.0.0, datamol 0.13.0, RDKit 2026.03.6 e PyTorch 2.14.1.

uv venv --python 3.13 .venv-molfeat
uv pip install --python .venv-molfeat/bin/python "molfeat==1.0.0"

No Windows, use .venv-molfeat\Scripts\python.exe como caminho do interpretador. O upstream suporta Python 3.11–3.14; macOS Intel usa Python 3.11–3.12, PyTorch 2.2.x, NumPy<2 e Transformers<5. Outras plataformas exigem PyTorch>=2.5. Deixe os marcadores de plataforma do Molfeat resolverem essas restrições; não copie os pinos do Apple Silicon para o Intel.

Instale apenas os extras necessários com o mesmo interpretador: molfeat[transformer]==1.0.0 para modelos Hugging Face, [mordred] para mordredcommunity, [pyg] para tensores de grafo, [fcd] para embeddings ChemNet, [selfies] para conversão SELFIES, [cache] para HDF5/Parquet, [viz] para visualização e [cloud] para armazenamentos S3/GCS. Extras DGL e Graphormer não existem mais. A inferência pré-treinada pode baixar pesos substanciais; verifique o licenciamento do modelo, o espaço em disco e os requisitos do dispositivo primeiro.

Fluxo de trabalho

1. Preserve IDs de registro de origem, rótulos, estruturas originais e uma política declarada para sais, estereoquímica, tautômeros, carga e compostos duplicados. A padronização altera a identidade química; aplique a mesma política ao treinamento e à predição.
2. Comece com um baseline explícito de ECFP. Um calculador processa uma molécula; MoleculeTransformer a agrupa. datamol.Mol é o tipo de molécula do RDKit.
3. Registre posições rejeitadas e alinhe todos os arrays associados. Inspecione NaN/Inf de descritores separadamente: o parsing bem-sucedido não garante características finitas.
4. Ajuste qualquer seleção de características, imputação, escalonamento e modelo dentro da dobra de treinamento. Prefira splits de scaffold/grupo ou temporais apropriados à questão científica; splits aleatórios podem vazar análogos próximos ou medições repetidas.
5. Salve o estado do featurizador, nomes de características ordenados, versões de pacotes, política de pré-processamento molecular e IDs de entrada. Revalide o estado antigo após migrar para 1.x.

Baseline de fingerprint e registros inválidos

import numpy as np
from molfeat.calc import FPCalculator
from molfeat.trans import MoleculeTransformer

smiles = ["CCO", "invalid", "CC(=O)O", "c1ccccc1"]
record_ids = np.array(["ethanol", "rejected", "acetate", "benzene"])
y = np.array([0.1, 9.9, 0.2, 0.3])  # toy labels only
calc = FPCalculator("ecfp", radius=2, fpSize=2048, includeChirality=True)
transformer = MoleculeTransformer(calc, n_jobs=1, dtype=np.float32)
X, valid_ids = transformer(smiles, ignore_errors=True)
assert X.shape == (3, 2048)
X_ids, y_valid = record_ids[valid_ids], y[valid_ids]
assert valid_ids == [0, 2, 3]
assert np.isfinite(X).all()

ignore_errors pertence à chamada, não ao construtor. Com True, __call__ retorna características filtradas e posições de entrada originais; com False, ele gera um erro em moléculas falhas. transform(..., ignore_errors=True) preserva posições usando None para falhas. Nunca filtre cada bloco de características independentemente e depois concatene.

O raio ECFP é um raio de ligação: radius=2 significa ECFP4; raio 3 significa ECFP6. Em 1.0.0 FPCalculator("ecfp") tem o padrão de raio 2 e 2048 bits. FPVecTransformer tem um comprimento padrão diferente de 2000, portanto, especifique length=2048 ao usá-lo.

Configuração de ida e volta

transformer.to_state_yaml_file("featurizer.yml")
loaded = MoleculeTransformer.from_state_yaml_file("featurizer.yml")
np.testing.assert_array_equal(loaded(["CCO"]), transformer(["CCO"]))

Carregue apenas configurações/artefatos confiáveis. O estado pode identificar classes Python e

…