feat(toolkit): add classification and migration

Implement the standard/non-standard/not-macrolactone classification layer and integrate it into analyzer, fragmenter, and CLI outputs. Port the remaining legacy package capabilities into new visualization and workflow modules, restore batch/statistics/SDF scripts on top of the flat CSV workflow, and update active docs to the new package API.
2026-03-18 23:56:41 +08:00
parent 9ccbcfcd04
commit c0ead42384
24 changed files with 1497 additions and 313 deletions
--- a/docs/SUMMARY.md
+++ b/docs/SUMMARY.md
@@ -1,243 +1,49 @@
-# Macro Split 项目文档总结
+# Macro Split 文档摘要

-本文档汇总了仓库中所有 Markdown 文件的内容摘要。
+当前仓库的正式接口全部集中在 `src/macro_lactone_toolkit/`，核心能力包括：

---
+- `MacroLactoneAnalyzer`
+  - 分子级分类：`standard_macrolactone` / `non_standard_macrocycle` / `not_macrolactone`
+  - 12-20 元大环内酯识别
+  - 批量统计、DataFrame 分类、动态 SMARTS、基本理化性质
+- `MacrolactoneFragmenter`
+  - 标准大环内酯编号
+  - 侧链裂解
+  - flat JSON/CSV 输出
+- `macro_lactone_toolkit.visualization`
+  - 编号分子 SVG/PNG
+  - 碎片 SVG/PNG
+- `macro_lactone_toolkit.workflows`
+  - CSV 批量裂解
+  - `FragmentationResult` 转 DataFrame
+  - JSON 导出
+  - 编号图片 + 标注 CSV 导出
+- `macro_lactone_toolkit.splicing`
+  - 通用大环内酯 scaffold 预处理
+  - 片段活化和拼接

-## 1. README.md (项目主文档)
+推荐起步方式：

-**位置**: `/README.md`
-
-### 项目简介
-Macrolactone Fragmenter 是一个专业的大环内酯（12-20元环）侧链断裂和分析工具。
-
-### 主要特性
- **智能环原子编号** - 支持 12-20 元环，基于内酯结构的固定编号系统
- **自动侧链断裂** - 智能识别并断裂所有侧链
- **强大的可视化** - SVG + PNG 输出
- **多种导出格式** - JSON、CSV、DataFrame
- **批量处理** - 支持 2000+ 分子的大规模分析
-
-### 安装方式
-```bash
-# 使用 Pixi（推荐）
-pixi install && pixi shell
-
-# 使用 Pip
-conda install -c conda-forge rdkit
-pip install -e .
-```
-
-### 基本用法
 ```python
-from src.macrolactone_fragmenter import MacrolactoneFragmenter
-fragmenter = MacrolactoneFragmenter(ring_size=16)
-result = fragmenter.process_molecule(smiles, parent_id="mol_001")
+from macro_lactone_toolkit import MacroLactoneAnalyzer, MacrolactoneFragmenter
+from macro_lactone_toolkit.workflows import fragment_csv, results_to_dataframe
+
+analyzer = MacroLactoneAnalyzer()
+classification = analyzer.classify_macrocycle(smiles)
+
+fragmenter = MacrolactoneFragmenter()
+result = fragmenter.fragment_molecule(smiles, parent_id="mol_001")
+
+results = fragment_csv("molecules.csv")
+fragments_df = results_to_dataframe(results)
 ```

---
+推荐脚本工作流：

-## 2. CLEANUP_SUMMARY.md (清理总结)
-
-**位置**: `/CLEANUP_SUMMARY.md`
-
-### 内容概要
-记录了项目根目录的清理工作：
- **保留的文件**: README.md, DOCUMENTATION_GUIDE.md, QUICK_COMMANDS.md
- **归档的文件**: 14 个历史文档已移至 `archive/` 目录
- **清理前**: 17 个 MD 文件，约 120KB
- **清理后**: 3 个核心 MD 文件 + 30+ 个文档系统文件
-
---
-
-## 3. DOCUMENTATION_GUIDE.md (文档系统指南)
-
-**位置**: `/DOCUMENTATION_GUIDE.md`
-
-### 文档系统特性
- 使用 **MkDocs + Material 主题 + mkdocstrings** 构建
- 支持中文、深色/浅色模式
- 自动从代码生成 API 文档
- 支持数学公式（MathJax）
-
-### 常用命令
 ```bash
-# 本地预览
-pixi run mkdocs serve
-
-# 构建静态网站
-pixi run mkdocs build
-
-# 部署到 GitHub Pages
-pixi run mkdocs gh-deploy
+python scripts/batch_process.py --input molecules.csv --output fragments.csv --errors-output errors.csv
+python scripts/analyze_fragments.py --input fragments.csv --output-dir analysis
+python scripts/generate_sdf_and_statistics.py --input fragments.csv --output-dir sdf_output
 ```

-### 添加新文档步骤
-1. 在 `docs/` 创建 `.md` 文件
-2. 编辑内容
-3. 在 `mkdocs.yml` 的 `nav` 部分添加链接
-4. 运行预览验证
-
---
-
-## 4. IMPLEMENTATION_SUMMARY.md (实现总结)
-
-**位置**: `/IMPLEMENTATION_SUMMARY.md`
-
-### MacroLactoneAnalyzer 封装
-新增 `src/macro_lactone_analyzer.py` 模块，提供：
-
-#### 静态方法
- `detect_ring_sizes(mol)` - 识别环大小
- `is_valid_macrolactone(mol, size)` - 验证大环内酯
- `analyze_smiles(smiles)` - 单分子分析
- `dynamic_smarts_match(smiles, ring_size)` - 动态 SMARTS 匹配
-
-#### 实例方法
- `get_single_ring_info(smiles)` - 单分子详细信息
- `analyze_list(smiles_list)` - 批量分析
- `classify_molecules(df)` - DataFrame 分类
-
-### 特性
- 高复用性、类型安全、详细错误处理
- 支持 12-20 元环分析
- 版本号更新至 2.0.0
-
---
-
-## 5. QUICK_COMMANDS.md (快速命令参考)
-
-**位置**: `/QUICK_COMMANDS.md`
-
-### 文档命令
-```bash
-pixi run mkdocs serve      # 启动文档服务器
-pixi run mkdocs build      # 构建静态文档
-pixi run mkdocs gh-deploy  # 部署到 GitHub Pages
-```
-
-### 安装命令
-```bash
-pixi install && pixi shell  # Pixi 方式
-pip install -e .            # 开发模式
-```
-
-### 开发工具
-```bash
-pixi run black src/         # 格式化代码
-pixi run flake8 src/        # 检查代码质量
-pixi run pytest             # 运行测试
-```
-
---
-
-## 6. notebooks/README_analyze_ring16.md (Notebook 说明)
-
-**位置**: `/notebooks/README_analyze_ring16.md`
-
-### 文件说明
- **Notebook**: `analyze_ring16_molecules.ipynb`
- **输入**: `../output/ring16_match_smarts.csv` (307个分子)
-
-### 分析内容
-1. **分子基本性质**: 分子量、LogP、QED、TPSA 等
-2. **侧链断裂分析**: 使用 MacrolactoneFragmenter 类
-3. **分布图绘制**: 4x4 子图布局，位置 3-16 的分布
-
-### 输出文件
- `ring16_molecular_properties_distribution.png`
- `atom_count_distribution_ring16.png`
- `molecular_weight_distribution_ring16.png`
- `ring16_fragments_analysis.csv`
-
-### 延伸分析建议
- LogP/QED/TPSA 分析
- SAR 分析（如有活性数据）
- 碎片多样性分析
- 聚类分析
-
---
-
-## 7. scripts/README.md (脚本使用说明)
-
-**位置**: `/scripts/README.md`
-
-### 脚本列表
-
-#### batch_process_ring16.py
- 处理 16 元环分子（1241个）
- 输入: `ring16/temp_filtered_complete.csv`
- 输出: `output/ring16_fragments/`
-
-#### batch_process_multi_rings.py
- 处理 12-20 元环的所有分子
- 自动按环大小分类
- 检测并剔除含多个内酯键的分子
-
-### 输出文件格式
-```json
-{
-  "parent_id": "ring16_mol_0",
-  "parent_smiles": "...",
-  "fragments": [
-    {
-      "fragment_smiles": "CC(C)C",
-      "cleavage_position": 5,
-      "atom_count": 4,
-      "molecular_weight": 58.12
-    }
-  ]
-}
-```
-
-### 日志文件
- `processing_log_*.txt` - 处理过程
- `error_log_*.txt` - 错误记录
- `multiple_lactone_log_*.txt` - 多内酯键分子
-
---
-
-## 项目结构概览
-
-```
-macro_split/
-├── src/                           # 核心源代码
-│   ├── macrolactone_fragmenter.py # 高级封装类
-│   ├── macro_lactone_analyzer.py  # 环数分析器
-│   ├── ring_numbering.py          # 环编号系统
-│   ├── ring_visualization.py      # 可视化工具
-│   └── fragment_dataclass.py      # 碎片数据类
-├── notebooks/                     # Jupyter Notebook 示例
-├── scripts/                       # 批量处理脚本
-├── docs/                          # 文档目录
-├── tests/                         # 单元测试
-├── pyproject.toml                 # 项目配置
-├── setup.py                       # 打包脚本
-├── pixi.toml                      # Pixi 环境配置
-└── mkdocs.yml                     # 文档配置
-```
-
---
-
-## 快速开始
-
-1. **安装环境**
-   ```bash
-   pixi install && pixi shell
-   ```
-
-2. **测试导入**
-   ```python
-   from src.macrolactone_fragmenter import MacrolactoneFragmenter
-   fragmenter = MacrolactoneFragmenter(ring_size=16)
-   ```
-
-3. **查看文档**
-   ```bash
-   pixi run mkdocs serve
-   # 访问 http://localhost:8000
-   ```
-
---
-
-*文档生成日期: 2025-01-23*
+活动文档和脚本都基于 `macro_lactone_toolkit.*`。历史 notebook `.ipynb` 快照保留作归档参考，但不再作为当前 API 文档。
--- a/docs/project-docs/QUICK_COMMANDS.md
+++ b/docs/project-docs/QUICK_COMMANDS.md
@@ -33,23 +33,20 @@ pip install .
 ## 🧪 测试安装

 ```python
-# 测试导入
-from src.macrolactone_fragmenter import MacrolactoneFragmenter
-print("✓ 安装成功！")
+from macro_lactone_toolkit import MacroLactoneAnalyzer, MacrolactoneFragmenter
+from macro_lactone_toolkit.workflows import fragment_csv, results_to_dataframe

-# 快速测试
-fragmenter = MacrolactoneFragmenter(ring_size=16)
-print(f"✓ 初始化成功！ring_size={fragmenter.ring_size}")
+analyzer = MacroLactoneAnalyzer()
+fragmenter = MacrolactoneFragmenter()
+print("✓ 安装成功！")
 ```

 ## 📓 运行示例

 ```bash
-# Jupyter Notebook
-pixi run jupyter notebook notebooks/filter_molecules.ipynb
-
-# 或启动 Jupyter Lab
-pixi run jupyter lab
+pixi run macro-lactone-toolkit analyze --smiles 'O=C1CCCCCCCCCCCCCCO1'
+python scripts/batch_process.py --input molecules.csv --output fragments.csv --errors-output errors.csv
+python scripts/analyze_fragments.py --input fragments.csv --output-dir analysis
 ```

 ## 🔍 项目结构
@@ -129,11 +126,10 @@ cat pyproject.toml | grep version
 | 文件 | 说明 |
 |------|------|
 | `README.md` | 项目主文档 |
-| `DOCUMENTATION_GUIDE.md` | 文档系统使用指南 |
-| `PROJECT_COMPLETION_SUMMARY.md` | 项目完成总结 |
-| `QUICK_COMMANDS.md` | 本文件 |
+| `docs/SUMMARY.md` | 当前 API 和工作流摘要 |
+| `scripts/README.md` | 脚本工作流说明 |
+| `src/macro_lactone_toolkit/` | 正式包实现 |
 | `pyproject.toml` | Python 项目配置 |
-| `setup.py` | 打包脚本 |
 | `mkdocs.yml` | 文档配置 |
 | `pixi.toml` | Pixi 环境配置 |

@@ -145,5 +141,4 @@ cat pyproject.toml | grep version

 ---

-**需要帮助？** 查看 `DOCUMENTATION_GUIDE.md` 或运行 `pixi run mkdocs serve`
-
+**需要帮助？** 查看 `docs/SUMMARY.md`、`scripts/README.md` 或运行 `pixi run mkdocs serve`