alterlab-datamol

Datamol ケモインフォマティクススキル

概要

Datamol は、分子ケモインフォマティクス向けに、RDKit 上に軽量で Python らしい抽象化レイヤーを提供する Python ライブラリです。適切なデフォルト設定、効率的な並列処理、最新の I/O 機能により、複雑な分子操作を簡素化します。すべての分子オブジェクトはネイティブの rdkit.Chem.Mol インスタンスであり、RDKit エコシステムとの完全な互換性が確保されています。

主な機能：

• 分子形式の変換（SMILES、SELFIES、InChI）
• 構造の標準化とサニタイズ
• 分子記述子とフィンガープリント
• 3D コンフォマーの生成と解析
• クラスタリングと多様性に基づく選択
• 骨格とフラグメントの解析
• 化学反応の適用
• 可視化とアラインメント
• 並列処理によるバッチ処理
• fsspec によるクラウドストレージのサポート

このスキルを使用する場面

ユーザーが次のことをしたい場合に、このスキルを使用します。

• ほとんど定型コードを書かずに、分子テーブル（CSV/SDF/Excel/Parquet、ローカルまたはクラウド）を読み込み、標準化し、重複を除去する
• 化合物セットの datamol の記述子セット、フィンガープリント、Tanimoto 距離行列を計算する
• ライブラリをクラスタリングする、多様性の高いサブセットを選択する、Murcko 骨格を抽出する、またはフラグメント化する（BRICS/RECAP）
• 3D コンフォマーを生成してクラスタリングする、または SAR レビュー用にアラインメント済みの分子グリッドを描画する

該当しない場合

シナリオ	代わりに使用
低レベルの制御：カスタムのサニタイズフラグ、原子マッピングされた反応の詳細、特殊なフィンガープリント／記述子アルゴリズム	alterlab-rdkit
ML 用の特徴量行列、事前学習済み埋め込み、または特徴量化器のベンチマーク	alterlab-molfeat
薬物らしさのルールセット、PAINS／構造アラート、複雑性によるフィルタリング	alterlab-medchem
骨格分割またはコールド分割に対応した、キュレーション済み ADMET/DTI ベンチマークデータセットのダウンロード	alterlab-pytdc

インストールとセットアップ

datamol のインストール方法を案内します。

uv pip install datamol

ここでの例は datamol 0.13.0（2026-09 時点の最新バージョン。Python ≥ 3.11 が必要で、RDKit もインストールされます）で検証済みです。0.13 では、誤記されていた複素環記述子が修正されています。compute_many_descriptors のキーは現在、n_aromatic_heterocycles / n_aliphatic_heterocycles / n_saturated_heterocycles です（以前は ..._heterocyles でした。旧関数名は非推奨エイリアスとしてのみ残っています）。これらのキーに依存する場合は、'datamol>=0.13' を指定してください。

インポート規約：

import datamol as dm

主なワークフロー

各小節では、基本的な呼び出しパターンを示します。API の完全なシグネチャ、パラメーター、追加の例については、各小節で参照しているモジュール別リファレンスファイルを参照してください。複数ステップからなるパイプラインの全例は、references/workflow_recipes.md にあります。

1. 分子の基本操作

import datamol as dm

# Parse SMILES (returns None on failure)
mol = dm.to_mol("CCO")                        # Ethanol
mols = [dm.to_mol(smi) for smi in ["CCO", "c1ccccc1", "CC(=O)O"]]
if dm.to_mol("invalid_smiles") is None:
    print("Failed to parse SMILES")

# Export to common formats (canonical + isomeric by default)
smiles   = dm.to_smiles(mol)                  # keeps stereochemistry
flat     = dm.to_smiles(mol, isomeric=False)  # drops stereochemistry
inchi    = dm.to_inchi(mol)
inchikey = dm.to_inchikey(mol)
selfies  = dm.to_selfies(mol)

# Standardize user-provided molecules (recommended for datasets)
mol = dm.sanitize_mol(mol)
mol = dm.standardize_mol(mol, disconnect_metals=True, normalize=True, reionize=True)
clean_smiles = dm.standardize_smiles(smiles)

変換、サニタイズ、標準化の API の全容については、references/core_api.md を参照してください。

2. 分子ファイルの読み込みと書き出し

# Read (open_df auto-detects .sdf/.csv/.xlsx/.parquet/.json)
mols = dm.read_sdf("compounds.sdf")                              # default: list of Mols
df = dm.read_sdf("compounds.sdf", as_df=True, mol_column="mol")  # DataFrame instead
df = dm.read_csv("data.csv", smiles_column="SMILES", mol_column="mol")
df = dm.open_df("file.sdf")

# Write
dm.to_sdf(mols, "output.sdf")               # or dm.to_sdf(df, "output.sdf", mol_column="mol")
dm.to_smi(mols, "output.smi")
dm.to_xlsx(df, "output.xlsx", mol_column="mol")   # renders molecule images in cells

# Remote paths work everywhere via fsspec (S3, GCS, HTTP)
mols = dm.read_sdf("s3://bucket/compounds.sdf")
dm.to_sdf(mols, "s3://bucket/output.sdf")

リーダー／ライターの完全なシグネチャ（read_smi、read_excel、read_mol2file、read_pdbfile、save_df、共通パラメーター）については、references/io_module.md を参照してください。

3. 分子記述子と特性

# Single molecule -> ~22 keys. Note datamol's naming (NOT rdkit's):
desc = dm.descriptors.compute_many_descriptors(mol)
#   {'mw': 46.04, 'clogp': -0.0, 'n_lipinski_hbd': 1, 'n_lipinski_hba': 1,
#    'tpsa': 20.23, 'n_rotatable_bonds': 0, 'qed': ..., 'fsp3': ..., 'sas': ..., ...}
# Gotcha: logP is 'clogp'; donors/acceptors are 'n_lipinski_hbd'/'n_lipinski_hba'.
# There is no 'logp', 'hbd', 'hba', or 'n_aromatic_atoms' key in this dict.

# Batch (parallel) -> DataFrame with the same keys. Pass an explicit batch_size
# when n_jobs != 1: the default batch_size=None is rejected by joblib >= 1.6
# ("batch_size must be 'auto' or a positive integer").
desc_df = dm.descriptors.batch_compute_many_descriptors(mols, n_jobs=-1, batch_size=256,
                                                        progress=True)

# Standalone descriptors not in the dict above
dm.descriptors.n_aromatic_atoms(mol)
dm.descriptors.n_stereo_centers(mol)
dm.descriptors.n_rigid_bonds(mol)

# Drug-likeness filter (Lipinski's Rule of Five) with datamol's exact key names
def is_druglike(mol):
    d = dm.descriptors.compute_many_descriptors(mol)
    return (d['mw'] <= 500 and d['clogp'] <= 5 and
            d['n_lipinski_hbd'] <= 5 and d['n_lipinski_hba'] <= 10)

druglike_mols = [m for m in mols if is_druglike(m)]

記述子の全カタログ、RDKit 記述子へのアクセス、ADME の例については、references/descriptors_viz.md を参照してください。

4. 分子フィンガープリントと類似度

# Fingerprints (ECFP/Morgan is the default; datamol's ecfp default is radius=3, i.e. ECFP6)
# Extra kwargs go straight to RDKit's rdFingerprintGenerator: use fpSize, not n_bits/nBits.
fp       = dm.to_fp(mol, fp_type='ecfp', radius=2, fpSize=2048)
fp_maccs = dm.to_fp(mol, fp_type='maccs')
# Also available: 'topological', 'atompair', 'fcfp', 'rdkit', '*-count' variants
# (full list: dm.list_supported_fingerprints())

# Similarity as Tanimoto distance (distance = 1 - similarity; lower = more similar)
dist_matrix = dm.pdist(mols, n_jobs=-1)          # square N x N matrix (squareform=True default)
condensed   = dm.pdist(mols, squareform=False)   # condensed vector, SciPy-style
distances   = dm.cdist(query_mols, library_mols, n_jobs=-1)  # between two sets

フィンガープリントの種類と pdist / cdist の詳細については、references/core_api.md を参照してください。

5. クラスタリングと多様性に基づく選択

# Butina clustering (cutoff = Tanimoto distance). Returns a TUPLE:
# (cluster_indices, cluster_mols) — one tuple of indices / list of Mols per cluster.
cluster_idx, cluster_mols = dm.cluster_mols(mols, cutoff=0.2, n_jobs=-1)
for i, members in enumerate(cluster_idx):
    print(i, len(members))

# Diversity / representative selection — both return (indices, mols)
diverse_idx, diverse = dm.pick_diverse(mols, npick=100)
centroid_idx, centroids = dm.pick_centroids(mols, npick=50)

スケールに関する注意：Butina は距離行列全体を作成するため、約 1,000 分子なら問題ありませんが、10,000 分子以上には適しません。クラスタリングのパラメーターについては、references/core_api.md を参照してください。

6. 骨格解析

# Bemis-Murcko scaffold (core ring systems + linkers)
scaffold = dm.to_scaffold_murcko(mol)
scaffold_smiles = dm.to_smiles(scaffold)

骨格の頻度集計、骨格ごとの分子グループ化、ML 用の骨格ベースの訓練／テスト分割については、references/workflow_recipes.md を参照してください。fuzzy_scaffolding などについては、references/fragments_scaffolds.md を参照してください。

7. 分子のフラグメント化

# BRICS (16 bond types) and RECAP (11 bond types) return lists of RDKit Mol
# fragments, parent molecule first unless remove_parent=True. The default
# fix=True caps the dummy atoms; pass fix=False to keep attachment points
# such as '[1*]C(C)=O' in the SMILES.
frags_brics = dm.fragment.brics(mol, remove_parent=True, fix=False)
frag_smiles = {dm.to_smiles(f) for f in frags_brics}
frags_recap = dm.fragment.recap(mol, remove_parent=True)

ライブラリ間でのフラグメント頻度解析と、フラグメント重複スコアリングのレシピについては、references/workflow_recipes.md を参照してください。MMPA フラグメント化と手法の比較表については、references/fragments_scaffolds.md を参照してください。

8. 3D 配座生成

# Generate 3D conformers (ETKDGv3 is the default method; minimize_energy defaults
# to False — pass True for UFF minimization)
mol_3d = dm.conformers.generate(mol, n_confs=50, rms_cutoff=0.5,
                                minimize_energy=True, method='ETKDGv3')
mol_3d.GetNumConformers()
conf = mol_3d.GetConformer(0)
positions = conf.GetPositions()          # Nx3 array of atom coordinates

# Cluster conformers by RMSD (Butina on symmetry-aware pairwise RMS)
centroid_mol = dm.conformers.cluster(mol_3d, rms_cutoff=1.0)       # one Mol holding the centroid conformers
per_cluster  = dm.conformers.cluster(mol_3d, rms_cutoff=1.0, centroids=False)  # list of Mols, one per cluster

# Solvent accessible surface area
sasa_values = dm.conformers.sasa(mol_3d, n_jobs=-1)
sasa = mol_3d.GetConformer(0).GetDoubleProp('rdkit_free_sasa')

埋め込み手法、RMSD 行列、低レベルの座標操作については、references/conformers_module.md を参照してください。

9. 可視化

# Grid image (SVG by default: use_svg=True). For a PNG file pass use_svg=False —
# otherwise SVG markup is written into the .png file.
dm.viz.to_image(mols[:20], legends=[dm.to_smiles(m) for m in mols[:20]],
                n_cols=5, mol_size=(300, 300))
dm.viz.to_image(mols, outfile="molecules.png", use_svg=False)
dm.viz.to_image(mols, outfile="molecules.svg")

# Align by MCS for SAR series; highlight atoms/bonds; render conformers
dm.viz.to_image(similar_mols, align=True, legends=activity_labels, n_cols=4)
dm.viz.to_image(mol, highlight_atom=[0, 1, 2, 3], highlight_bond=[0, 1, 2])
dm.viz.conformers(mol_3d, n_confs=10, align_conf=True, n_cols=3)

to_image／conformers／circle_grid の全パラメーターとベストプラクティスについては、references/descriptors_viz.md を参照してください。

10. 化学反応

from rdkit.Chem import rdChemReactions

# Build a reaction from SMARTS, then apply it to a reactant tuple. By default
# apply_reaction returns every product set (list of lists); ask for one Mol:
rxn = rdChemReactions.ReactionFromSmarts('[C:1](=[O:2])[OH:3]>>[C:1](=[O:2])[Cl:3]')
product = dm.reactions.apply_reaction(rxn, (dm.to_mol("CC(=O)O"),),
                                      single_product_group=True, product_index=0,
                                      sanitize=True)
product_smiles = dm.to_smiles(product)   # 'CC(=O)Cl' (or pass as_smiles=True)

バッチでの反応適用、一般的な反応テンプレート（アミド、鈴木カップリング、エステル化）、およびおもちゃの datamol.data データセットについては、references/reactions_data.md を参照してください。

並列化

Datamol には、多くの操作向けの組み込み並列化機能があります。n_jobs パラメーターを使用してください。

• n_jobs=1：逐次実行（並列化なし）
• n_jobs=-1：利用可能なすべての CPU コアを使用
• n_jobs=4：4 コアを使用

並列化に対応する関数：

• dm.read_sdf(..., n_jobs=-1)
• dm.descriptors.batch_compute_many_descriptors(..., n_jobs=-1, batch_size=256)（joblib ≥ 1.6 では batch_size の明示的な指定が必要です）
• dm.cluster_mols(..., n_jobs=-1)
• dm.pdist(..., n_jobs=-1)
• dm.conformers.sasa(..., n_jobs=-1)

プログレスバー：多くのバッチ操作は progress=True パラメーターに対応しています。

一般的なワークフローとパターン

データ読み込み → フィルタリング → 分析、構造活性相関（SAR）分析、バーチャルスクリーニングを含む、コピーしてすぐ使える完全なパイプラインに加え、機械学習用の特徴生成と堅牢なエラー処理ラッパーは、ファイルを簡潔に保つため、このファイルから移動しました。references/workflow_recipes.md を参照してください。

リファレンスドキュメント

API の詳細については、次のリファレンスファイルを参照してください。

• references/core_api.md：コア名前空間関数（変換、標準化、フィンガープリント、クラスタリング）
• references/io_module.md：ファイル I/O 操作（SDF、CSV、Excel、リモートファイルの読み書き）
• references/conformers_module.md：3D 配座生成、クラスタリング、SASA 計算
• references/descriptors_viz.md：分子記述子と可視化関数
• references/fragments_scaffolds.md：足場の抽出、BRICS／RECAP フラグメンテーション
• references/reactions_data.md：化学反応とおもちゃのデータセット
• references/workflow_recipes.md：エンドツーエンドのパイプライン、SAR／スクリーニングのレシピ、ML 統合、エラー処理

ベストプラクティス

1. 外部ソースの分子は必ず標準化してください。

   mol = dm.standardize_mol(mol, disconnect_metals=True, normalize=True, reionize=True)
   

2. 分子のパース後に None 値を確認してください。

   mol = dm.to_mol(smiles)
   if mol is None:
       ...  # log and skip the invalid SMILES
   

3. 大規模なデータセットでは並列処理を使用してください。

   result = dm.operation(..., n_jobs=-1, progress=True)
   

4. クラウドストレージには fsspec を活用してください。

   df = dm.read_sdf("s3://bucket/compounds.sdf")
   

5. 類似性の評価には適切なフィンガープリントを使用してください。

   • ECFP（Morgan）：汎用、構造類似性
   • MACCS：高速、特徴空間が小さい
   • 原子ペア：原子ペアと距離を考慮

6. スケールの制限を考慮してください。

   • Butina クラスタリング：約1,000分子（距離行列全体を使用）
   • より大きなデータセットの場合：多様性選択または階層的手法を使用

7. ML では足場による分割を行ってください：足場ごとに適切な訓練データ／テストデータの分離を確保します。

8. SAR 系列を可視化する際は、分子をアラインメントしてください。

トラブルシューティング

問題：分子のパースに失敗する

• 解決策：まず dm.standardize_smiles() を使用するか、dm.fix_mol() を試してください。

問題：クラスタリングでメモリーエラーが発生する

• 解決策：大規模なセットでは、完全なクラスタリングの代わりに dm.pick_diverse() を使用してください。

問題：配座生成が遅い

• 解決策：n_confs を減らすか、rms_cutoff を大きくして、生成する配座の数を減らしてください。

問題：リモートファイルにアクセスできない

• 解決策：fsspec と適切なクラウドプロバイダーのライブラリ（s3fs、gcsfs など）がインストールされていることを確認してください。

追加リソース

• Datamol ドキュメント：https://docs.datamol.io/
• RDKit ドキュメント：https://www.rdkit.org/docs/
• GitHub リポジトリ：https://github.com/datamol-io/datamol

AlterLab Academic Skills スイートの一部です。