ECFP Fingerprint Generator CLI (ecfp-gen)

SMILESを含むCSV/TSVファイルから ECFP (Extended-Connectivity Fingerprints) / Morgan fingerprint を高速かつ堅牢に一括生成する公開グレードのコマンドラインツール（CLI）です。

Note: 本ツールは 2D Morgan / ECFP フィンガープリント計算専用であり、3D座標生成や力場最適化は行いません。

---

動作要件 (Requirements)

• Python 3.10 以上推奨 (Python 3.10+ recommended)
• (※ Python 3.10 および 3.11 にて動作確認済み)

---

インストール (Installation)

git clone https://github.com/377H-Miru/ecfp_cli.git
cd ecfp_cli
pip install -e .

ヘルプメッセージの表示:

ecfp-gen --help

---

Quick Start & 実行例

1. 最小入力CSV例 (examples/sample.csv)

smiles,compound_id
CCO,MOL001
c1ccccc1,MOL002
CO.[Na+].[Cl-],MOL003
INVALID_SMILES,MOL004

2. コマンドライン実行例 (CLI Mode)

ecfp-gen \
  --input examples/sample.csv \
  --output result.tsv \
  --smiles-col smiles \
  --name-col compound_id \
  --overwrite

---

主要なオプション仕様

脱塩処理 (--desalt / --no-desalt)

• デフォルト: 有効 (--desalt)
• 塩や溶媒を含む複合分子（例: CO.[Na+].[Cl-]）に対し、最も構成原子数の多い最大フラグメントのみを保持してフィンガープリントを計算します。無効化する場合は --no-desalt を指定します。

分子標準化 (--standardize)

• デフォルト: 無効 (Off)
• RDKit の MolStandardizeCleanup 処理を適用します。構造補正が必要な特定のデータセットでのみ明示的に指定して使用してください。

ビット命名規則 (--bit-prefix, --zero-indexed-bits)

• デフォルトでは Bit_1 から Bit_2048 の 1-indexed カラム名が生成されます。
• --zero-indexed-bits を指定すると Bit_0 から Bit_2047 の 0-indexed に変更可能です。

---

出力仕様およびエラーログ

正常出力 (output.tsv / output.csv)

• 入力で指定した化合物ID (ID) と脱塩・標準化処理後の正規化SMILES (canonical_smiles)、および各ビット列が出力されます。

エラーログ (output.tsv.errors.tsv / output.csv.errors.csv)

パース不能な SMILES や処理失敗分子は正常出力から自動除外され、以下の多段階構造化フォーマットで記録されます。

• row_index: 入力データの行番号
• ID: 化合物ID/名称
• input_smiles: 元の入力SMILES
• canonical_smiles: 処理途中の正規化SMILES
• stage: 失敗段階（parse, preprocess, standardize, fingerprint）
• error_type: エラー種別
• error_message: 詳細エラーメッセージ

---

Python API としての使用例

generate_ecfp_batch をインポートして Python コード内でも利用可能です。

from ecfp_generator import generate_ecfp_batch

smiles_list = ["CCO", "c1ccccc1", "INVALID"]
results, errors = generate_ecfp_batch(smiles_list, radius=2, n_bits=2048, desalt=True, workers=1)

---

サードパーティ依存関係 (Third-party dependencies)

本ツールは、SMILESのパースおよび Morgan / ECFP フィンガープリント生成に RDKit を利用しています。 RDKit は BSD 系のオープンソースライセンスで配布されています。RDKit 本体のライセンス条件については RDKit プロジェクトを参照してください。

---

ライセンス (License)

本プロジェクトは MIT License のもとで公開されています。