datamol

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

概要

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

主な機能:

• 分子フォーマット変換（SMILES、SELFIES、InChI）
• 構造の標準化とサニタイズ
• 分子記述子とフィンガープリント
• 3D コンフォーマー生成と解析
• クラスタリングと多様性選択
• スキャフォールドとフラグメント解析
• ケミカルリアクションの適用
• 可視化とアライメント
• 並列化によるバッチ処理
• fsspec によるクラウドストレージ対応

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

ユーザーに datamol のインストールを案内します:

uv pip install datamol

インポートの慣例:

import datamol as dm

主要ワークフロー

1. 基本的な分子の扱い

SMILES からの分子の作成:

import datamol as dm

# Single molecule
mol = dm.to_mol("CCO")  # Ethanol

# From list of SMILES
smiles_list = ["CCO", "c1ccccc1", "CC(=O)O"]
mols = [dm.to_mol(smi) for smi in smiles_list]

# Error handling
mol = dm.to_mol("invalid_smiles")  # Returns None
if mol is None:
    print("Failed to parse SMILES")

分子の SMILES への変換:

# Canonical SMILES
smiles = dm.to_smiles(mol)

# Isomeric SMILES (includes stereochemistry)
smiles = dm.to_smiles(mol, isomeric=True)

# Other formats
inchi = dm.to_inchi(mol)
inchikey = dm.to_inchikey(mol)
selfies = dm.to_selfies(mol)

標準化とサニタイズ（ユーザーが提供した分子には必ず推奨）:

# Sanitize molecule
mol = dm.sanitize_mol(mol)

# Full standardization (recommended for datasets)
mol = dm.standardize_mol(
    mol,
    disconnect_metals=True,
    normalize=True,
    reionize=True
)

# For SMILES strings directly
clean_smiles = dm.standardize_smiles(smiles)

2. 分子ファイルの読み書き

I/O の詳細なドキュメントは references/io_module.md を参照してください。

ファイルの読み込み:

# SDF files (most common in chemistry)
df = dm.read_sdf("compounds.sdf", mol_column='mol')

# SMILES files
df = dm.read_smi("molecules.smi", smiles_column='smiles', mol_column='mol')

# CSV with SMILES column
df = dm.read_csv("data.csv", smiles_column="SMILES", mol_column="mol")

# Excel files
df = dm.read_excel("compounds.xlsx", sheet_name=0, mol_column="mol")

# Universal reader (auto-detects format)
df = dm.open_df("file.sdf")  # Works with .sdf, .csv, .xlsx, .parquet, .json

ファイルの書き出し:

# Save as SDF
dm.to_sdf(mols, "output.sdf")
# Or from DataFrame
dm.to_sdf(df, "output.sdf", mol_column="mol")

# Save as SMILES file
dm.to_smi(mols, "output.smi")

# Excel with rendered molecule images
dm.to_xlsx(df, "output.xlsx", mol_columns=["mol"])

リモートファイルのサポート（S3、GCS、HTTP）:

# Read from cloud storage
df = dm.read_sdf("s3://bucket/compounds.sdf")
df = dm.read_csv("https://example.com/data.csv")

# Write to cloud storage
dm.to_sdf(mols, "s3://bucket/output.sdf")

3. 分子記述子とプロパティ

詳細な記述子のドキュメントは references/descriptors_viz.md を参照してください。

単一分子の記述子の計算:

# Get standard descriptor set
descriptors = dm.descriptors.compute_many_descriptors(mol)
# Returns: {'mw': 46.07, 'logp': -0.03, 'hbd': 1, 'hba': 1,
#           'tpsa': 20.23, 'n_aromatic_atoms': 0, ...}

バッチでの記述子計算（データセットに推奨）:

# Compute for all molecules in parallel
desc_df = dm.descriptors.batch_compute_many_descriptors(
    mols,
    n_jobs=-1,      # Use all CPU cores
    progress=True   # Show progress bar
)

特定の記述子:

# Aromaticity
n_aromatic = dm.descriptors.n_aromatic_atoms(mol)
aromatic_ratio = dm.descriptors.n_aromatic_atoms_proportion(mol)

# Stereochemistry
n_stereo = dm.descriptors.n_stereo_centers(mol)
n_unspec = dm.descriptors.n_stereo_centers_unspecified(mol)

# Flexibility
n_rigid = dm.descriptors.n_rigid_bonds(mol)

薬物らしさによるフィルタリング（Lipinski の 5 則）:

# Filter compounds
def is_druglike(mol):
    desc = dm.descriptors.compute_many_descriptors(mol)
    return (
        desc['mw'] <= 500 and
        desc['logp'] <= 5 and
        desc['hbd'] <= 5 and
        desc['hba'] <= 10
    )

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

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

フィンガープリントの生成:

# ECFP (Extended Connectivity Fingerprint, default)
fp = dm.to_fp(mol, fp_type='ecfp', radius=2, n_bits=2048)

# Other fingerprint types
fp_maccs = dm.to_fp(mol, fp_type='maccs')
fp_topological = dm.to_fp(mol, fp_type='topological')
fp_atompair = dm.to_fp(mol, fp_type='atompair')

類似度の計算:

# Pairwise distances within a set
distance_matrix = dm.pdist(mols, n_jobs=-1)

# Distances between two sets
distances = dm.cdist(query_mols, library_mols, n_jobs=-1)

# Find most similar molecules
from scipy.spatial.distance import squareform
dist_matrix = squareform(dm.pdist(mols))
# Lower distance = higher similarity (Tanimoto distance = 1 - Tanimoto similarity)

5. クラスタリングと多様性選択

クラスタリングの詳細は references/core_api.md を参照してください。

Butina クラスタリング:

# Cluster molecules by structural similarity
clusters = dm.cluster_mols(
    mols,
    cutoff=0.2,    # Tanimoto distance threshold (0=identical, 1=completely different)
    n_jobs=-1      # Parallel processing
)

# Each cluster is a list of molecule indices
for i, cluster in enumerate(clusters):
    print(f"Cluster {i}: {len(cluster)} molecules")
    cluster_mols = [mols[idx] for idx in cluster]

重要: Butina クラスタリングは完全な距離行列を構築するため、約 1000 分子までに適しており、10,000 分子以上には向きません。

多様性選択:

# Pick diverse subset
diverse_mols = dm.pick_diverse(
    mols,
    npick=100  # Select 100 diverse molecules
)

# Pick cluster centroids
centroids = dm.pick_centroids(
    mols,
    npick=50   # Select 50 representative molecules
)

6. スキャフォールド解析

完全なスキャフォールドのドキュメントは references/fragments_scaffolds.md を参照してください。

Murcko スキャフォールドの抽出:

# Get Bemis-Murcko scaffold (core structure)
scaffold = dm.to_scaffold_murcko(mol)
scaffold_smiles = dm.to_smiles(scaffold)

スキャフォールドに基づく解析:

# Group compounds by scaffold
from collections import Counter

scaffolds = [dm.to_scaffold_murcko(mol) for mol in mols]
scaffold_smiles = [dm.to_smiles(s) for s in scaffolds]

# Count scaffold frequency
scaffold_counts = Counter(scaffold_smiles)
most_common = scaffold_counts.most_common(10)

# Create scaffold-to-molecules mapping
scaffold_groups = {}
for mol, scaf_smi in zip(mols, scaffold_smiles):
    if scaf_smi not in scaffold_groups:
        scaffold_groups[scaf_smi] = []
    scaffold_groups[scaf_smi].append(mol)

スキャフォールドに基づく学習/テスト分割（機械学習向け）:

# Ensure train and test sets have different scaffolds
scaffold_to_mols = {}
for mol, scaf in zip(mols, scaffold_smiles):
    if scaf not in scaffold_to_mols:
        scaffold_to_mols[scaf] = []
    scaffold_to_mols[scaf].append(mol)

# Split scaffolds into train/test
import random
scaffolds = list(scaffold_to_mols.keys())
random.shuffle(scaffolds)
split_idx = int(0.8 * len(scaffolds))
train_scaffolds = scaffolds[:split_idx]
test_scaffolds = scaffolds[split_idx:]

# Get molecules for each split
train_mols = [mol for scaf in train_scaffolds for mol in scaffold_to_mols[scaf]]
test_mols = [mol for scaf in test_scaffolds for mol in scaffold_to_mols[scaf]]

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

フラグメント化の詳細は references/fragments_scaffolds.md を参照してください。

BRICS フラグメント化（16 種類の結合タイプ）:

# Fragment molecule
fragments = dm.fragment.brics(mol)
# Returns: set of fragment SMILES with attachment points like '[1*]CCN'

RECAP フラグメント化（11 種類の結合タイプ）:

fragments = dm.fragment.recap(mol)

フラグメント解析:

# Find common fragments across compound library
from collections import Counter

all_fragments = []
for mol in mols:
    frags = dm.fragment.brics(mol)
    all_fragments.extend(frags)

fragment_counts = Counter(all_fragments)
common_frags = fragment_counts.most_common(20)

# Fragment-based scoring
def fragment_score(mol, reference_fragments):
    mol_frags = dm.fragment.brics(mol)
    overlap = mol_frags.intersection(reference_fragments)
    return len(overlap) / len(mol_frags) if mol_frags else 0

8. 3D コンフォーマー生成

詳細なコンフォーマーのドキュメントは references/conformers_module.md を参照してください。

コンフォーマーの生成:

# Generate 3D conformers
mol_3d = dm.conformers.generate(
    mol,
    n_confs=50,           # Number to generate (auto if None)
    rms_cutoff=0.5,       # Filter similar conformers (Ångströms)
    minimize_energy=True,  # Minimize with UFF force field
    method='ETKDGv3'      # Embedding method (recommended)
)

# Access conformers
n_conformers = mol_3d.GetNumConformers()
conf = mol_3d.GetConformer(0)  # Get first conformer
positions = conf.GetPositions()  # Nx3 array of atom coordinates

コンフォーマーのクラスタリング:

# Cluster conformers by RMSD
clusters = dm.conformers.cluster(
    mol_3d,
    rms_cutoff=1.0,
    centroids=False
)

# Get representative conformers
centroids = dm.conformers.return_centroids(mol_3d, clusters)

SASA の計算:

# Calculate solvent accessible surface area
sasa_values = dm.conformers.sasa(mol_3d, n_jobs=-1)

# Access SASA from conformer properties
conf = mol_3d.GetConformer(0)
sasa = conf.GetDoubleProp('rdkit_free_sasa')

9. 可視化

可視化のドキュメントは references/descriptors_viz.md を参照してください。

基本的な分子グリッド:

# Visualize molecules
dm.viz.to_image(
    mols[:20],
    legends=[dm.to_smiles(m) for m in mols[:20]],
    n_cols=5,
    mol_size=(300, 300)
)

# Save to file
dm.viz.to_image(mols, outfile="molecules.png")

# SVG for publications
dm.viz.to_image(mols, outfile="molecules.svg", use_svg=True)

アライメントされた可視化（SAR 解析向け）:

# Align molecules by common substructure
dm.viz.to_image(
    similar_mols,
    align=True,  # Enable MCS alignment
    legends=activity_labels,
    n_cols=4
)

部分構造のハイライト:

# Highlight specific atoms and bonds
dm.viz.to_image(
    mol,
    highlight_atom=[0, 1, 2, 3],  # Atom indices
    highlight_bond=[0, 1, 2]      # Bond indices
)

コンフォーマーの可視化:

# Display multiple conformers
dm.viz.conformers(
    mol_3d,
    n_confs=10,
    align_conf=True,
    n_cols=3
)

10. ケミカルリアクション

リアクションのドキュメントは references/reactions_data.md を参照してください。

リアクションの適用:

from rdkit.Chem import rdChemReactions

# Define reaction from SMARTS
rxn_smarts = '[C:1](=[O:2])[OH:3]>>[C:1](=[O:2])[Cl:3]'
rxn = rdChemReactions.ReactionFromSmarts(rxn_smarts)

# Apply to molecule
reactant = dm.to_mol("CC(=O)O")  # Acetic acid
product = dm.reactions.apply_reaction(
    rxn,
    (reactant,),
    sanitize=True
)

# Convert to SMILES
product_smiles = dm.to_smiles(product)

バッチでのリアクション適用:

# Apply reaction to library
products = []
for mol in reactant_mols:
    try:
        prod = dm.reactions.apply_reaction(rxn, (mol,))
        if prod is not None:
            products.append(prod)
    except Exception as e:
        print(f"Reaction failed: {e}")

並列化

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)
• dm.cluster_mols(..., n_jobs=-1)
• dm.pdist(..., n_jobs=-1)
• dm.conformers.sasa(..., n_jobs=-1)

進捗バー: 多くのバッチ操作は progress=True パラメーターに対応しています。

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

完全なパイプライン: データの読み込み → フィルタリング → 解析

import datamol as dm
import pandas as pd

# 1. Load molecules
df = dm.read_sdf("compounds.sdf")

# 2. Standardize
df['mol'] = df['mol'].apply(lambda m: dm.standardize_mol(m) if m else None)
df = df[df['mol'].notna()]  # Remove failed molecules

# 3. Compute descriptors
desc_df = dm.descriptors.batch_compute_many_descriptors(
    df['mol'].tolist(),
    n_jobs=-1,
    progress=True
)

# 4. Filter by drug-likeness
druglike = (
    (desc_df['mw'] <= 500) &
    (desc_df['logp'] <= 5) &
    (desc_df['hbd'] <= 5) &
    (desc_df['hba'] <= 10)
)
filtered_df = df[druglike]

# 5. Cluster and select diverse subset
diverse_mols = dm.pick_diverse(
    filtered_df['mol'].tolist(),
    npick=100
)

# 6. Visualize results
dm.viz.to_image(
    diverse_mols,
    legends=[dm.to_smiles(m) for m in diverse_mols],
    outfile="diverse_compounds.png",
    n_cols=10
)

構造活性相関（SAR）分析

# Group by scaffold
scaffolds = [dm.to_scaffold_murcko(mol) for mol in mols]
scaffold_smiles = [dm.to_smiles(s) for s in scaffolds]

# Create DataFrame with activities
sar_df = pd.DataFrame({
    'mol': mols,
    'scaffold': scaffold_smiles,
    'activity': activities  # User-provided activity data
})

# Analyze each scaffold series
for scaffold, group in sar_df.groupby('scaffold'):
    if len(group) >= 3:  # Need multiple examples
        print(f"\nScaffold: {scaffold}")
        print(f"Count: {len(group)}")
        print(f"Activity range: {group['activity'].min():.2f} - {group['activity'].max():.2f}")

        # Visualize with activities as legends
        dm.viz.to_image(
            group['mol'].tolist(),
            legends=[f"Activity: {act:.2f}" for act in group['activity']],
            align=True  # Align by common substructure
        )

バーチャルスクリーニングパイプライン

# 1. Generate fingerprints for query and library
query_fps = [dm.to_fp(mol) for mol in query_actives]
library_fps = [dm.to_fp(mol) for mol in library_mols]

# 2. Calculate similarities
from scipy.spatial.distance import cdist
import numpy as np

distances = dm.cdist(query_actives, library_mols, n_jobs=-1)

# 3. Find closest matches (min distance to any query)
min_distances = distances.min(axis=0)
similarities = 1 - min_distances  # Convert distance to similarity

# 4. Rank and select top hits
top_indices = np.argsort(similarities)[::-1][:100]  # Top 100
top_hits = [library_mols[i] for i in top_indices]
top_scores = [similarities[i] for i in top_indices]

# 5. Visualize hits
dm.viz.to_image(
    top_hits[:20],
    legends=[f"Sim: {score:.3f}" for score in top_scores[:20]],
    outfile="screening_hits.png"
)

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

詳細な 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: 化学反応とトイデータセット

ベストプラクティス

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

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

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

   mol = dm.to_mol(smiles)
   if mol is None:
       # Handle 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: 高速で、特徴空間が小さくなります
   • Atom pairs: 原子対とその距離を考慮します

6. 規模の制約を考慮してください:

   • Butina クラスタリング: 約 1,000 分子まで（全距離行列を使用するため）
   • より大規模なデータセットの場合: 多様性選択や階層的手法を使用してください

7. 機械学習のためのスカフォールド分割: スカフォールドによって訓練データとテストデータが適切に分離されるようにしてください

8. SAR 系列を可視化する際は分子を整列させてください

エラー処理

# Safe molecule creation
def safe_to_mol(smiles):
    try:
        mol = dm.to_mol(smiles)
        if mol is not None:
            mol = dm.standardize_mol(mol)
        return mol
    except Exception as e:
        print(f"Failed to process {smiles}: {e}")
        return None

# Safe batch processing
valid_mols = []
for smiles in smiles_list:
    mol = safe_to_mol(smiles)
    if mol is not None:
        valid_mols.append(mol)

機械学習との統合

# Feature generation
X = np.array([dm.to_fp(mol) for mol in mols])

# Or descriptors
desc_df = dm.descriptors.batch_compute_many_descriptors(mols, n_jobs=-1)
X = desc_df.values

# Train model
from sklearn.ensemble import RandomForestRegressor
model = RandomForestRegressor()
model.fit(X, y_target)

# Predict
predictions = model.predict(X_test)

トラブルシューティング

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

• 解決策: まず 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