# Macro Split 项目文档总结

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

---

## 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")
```

---

## 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
```

### 添加新文档步骤
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*