macrolactone-toolkit/docs/SUMMARY.md

Macro Split 项目文档总结

本文档汇总了仓库中所有 Markdown 文件的内容摘要。

---

1. README.md (项目主文档)

位置: /README.md

项目简介

Macrolactone Fragmenter 是一个专业的大环内酯（12-20元环）侧链断裂和分析工具。

主要特性

• 智能环原子编号 - 支持 12-20 元环，基于内酯结构的固定编号系统
• 自动侧链断裂 - 智能识别并断裂所有侧链
• 强大的可视化 - SVG + PNG 输出
• 多种导出格式 - JSON、CSV、DataFrame
• 批量处理 - 支持 2000+ 分子的大规模分析

安装方式

# 使用 Pixi（推荐）
pixi install && pixi shell

# 使用 Pip
conda install -c conda-forge rdkit
pip install -e .

基本用法

from src.macrolactone_fragmenter import MacrolactoneFragmenter
fragmenter = MacrolactoneFragmenter(ring_size=16)
result = fragmenter.process_molecule(smiles, parent_id="mol_001")

---

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）

常用命令

# 本地预览
pixi run mkdocs serve

# 构建静态网站
pixi run mkdocs build

# 部署到 GitHub Pages
pixi run mkdocs gh-deploy

添加新文档步骤

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

文档命令

pixi run mkdocs serve      # 启动文档服务器
pixi run mkdocs build      # 构建静态文档
pixi run mkdocs gh-deploy  # 部署到 GitHub Pages

安装命令

pixi install && pixi shell  # Pixi 方式
pip install -e .            # 开发模式

开发工具

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 元环的所有分子
• 自动按环大小分类
• 检测并剔除含多个内酯键的分子

输出文件格式

{
  "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. 安装环境

   pixi install && pixi shell
   

2. 测试导入

   from src.macrolactone_fragmenter import MacrolactoneFragmenter
   fragmenter = MacrolactoneFragmenter(ring_size=16)
   

3. 查看文档

   pixi run mkdocs serve
   # 访问 http://localhost:8000
   

---

文档生成日期: 2025-01-23