# Macrolactone Fragmenter

[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Pixi](https://img.shields.io/badge/pixi-managed-blue)](https://pixi.sh)

一个专业的大环内酯（Macrolactone, 12-20 元环）侧链断裂和分析工具，提供从分子编号、侧链断裂到可视化和数据导出的完整工作流。

## ✨ 主要特性

- 🔢 **智能环原子编号** - 支持 12-20 元环，基于内酯结构的固定编号系统
- ✂️ **自动侧链断裂** - 智能识别并断裂所有侧链，支持单个或批量处理
- 📊 **强大的可视化** - SVG 显示 + PNG 保存，支持自定义 DPI 和尺寸
- 💾 **多种导出格式** - JSON、CSV、DataFrame，预留 SQLModel 数据库接口
- 🚀 **批量处理** - 直接处理 CSV 文件，支持 2000+ 分子的大规模分析
- 📦 **易于安装** - 使用 pixi 或 pip 安装，支持开发模式

## 🚀 快速开始

### 安装

**使用 Pixi（推荐）**

```bash
# 安装 pixi
curl -fsSL https://pixi.sh/install.sh | bash

# 克隆项目并安装依赖
git clone https://github.com/yourusername/macro_split.git
cd macro_split
pixi install

# 激活环境
pixi shell
```

**使用 Pip**

```bash
# 首先安装 RDKit（必须通过 conda）
conda install -c conda-forge rdkit

# 安装项目
pip install -e .  # 开发模式
```

### 基本使用

```python
from src.macrolactone_fragmenter import MacrolactoneFragmenter

# 创建 16 元环处理器
fragmenter = MacrolactoneFragmenter(ring_size=16)

# 处理单个分子
smiles = "CCC1OC(=O)C[C@H](O)C(C)[C@@H](O)..."
result = fragmenter.process_molecule(smiles, parent_id="mol_001")

# 查看结果
print(f"总碎片数: {len(result.fragments)}")
for frag in result.fragments[:5]:
    print(f"位置 {frag.cleavage_position}: {frag.fragment_smiles}")

# 可视化
svg = fragmenter.visualize_molecule(result.parent_smiles)

# 导出数据
fragmenter.save_to_json(result, "output/fragments.json")
df = fragmenter.to_dataframe(result)
```

### 批量处理

```python
# 批量处理 CSV 文件
results = fragmenter.process_csv(
    "data/molecules.csv",
    smiles_column="smiles",
    id_column="unique_id",
    max_rows=100
)

# 转换为 DataFrame 并保存
df_all = fragmenter.batch_to_dataframe(results)
df_all.to_csv("output/all_fragments.csv", index=False)
```

## 📖 文档

完整的文档请访问：[在线文档](https://yourusername.github.io/macro_split/)

或本地查看：

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

### 文档内容

- 📘 **[快速开始](docs/getting-started.md)** - 5 分钟上手指南
- 📗 **[安装指南](docs/installation.md)** - 详细的安装说明
- 📙 **[用户指南](docs/user-guide/index.md)** - 完整的使用说明
- 📕 **[API 参考](docs/api/index.md)** - 自动生成的 API 文档
- 📔 **[教程与示例](docs/tutorials/index.md)** - 实际使用案例

## 🎯 核心功能

### MacrolactoneFragmenter 类

高级封装类，提供一站式解决方案：

```python
fragmenter = MacrolactoneFragmenter(ring_size=16)

# 一站式处理
result = fragmenter.process_molecule(smiles)

# 单位置断裂
fragments = fragmenter.cleave_at_position(mol, position=5)

# 可视化（SVG + PNG）
fragmenter.visualize_molecule(smiles, save_path="mol.png", dpi=600)

# 批量处理
results = fragmenter.process_csv("molecules.csv")
```

### 环编号系统

基于内酯结构的固定编号：

- **位置 1**: 羰基碳（C=O 中的 C）
- **位置 2**: 酯键氧（环上的 O）
- **位置 3-N**: 按顺序编号环上剩余原子

### 数据结构

使用 dataclass 存储碎片信息，支持 JSON 导入导出：

```python
@dataclass
class Fragment:
    fragment_smiles: str         # 碎片 SMILES（含 dummy 原子 *）
    parent_smiles: str           # 母分子 SMILES
    cleavage_position: int       # 断裂位置（1-N）
    fragment_id: str             # 碎片 ID
    parent_id: str               # 母分子 ID
    atom_count: int              # 原子数
    molecular_weight: float      # 分子量
```

## 📂 项目结构

```
macro_split/
├── src/                         # 核心源代码
│   ├── macrolactone_fragmenter.py  # ⭐ 高级封装类
│   ├── ring_numbering.py        # 环编号系统
│   ├── ring_visualization.py    # 可视化工具
│   ├── fragment_dataclass.py    # 碎片数据类
│   ├── fragment_cleaver.py      # 侧链断裂
│   └── visualizer.py            # 统计可视化
├── notebooks/                   # Jupyter Notebook 示例
│   └── filter_molecules.ipynb   # ⭐ 完整使用案例
├── docs/                        # MkDocs 文档
├── scripts/                     # 执行脚本
├── tests/                       # 单元测试
├── pyproject.toml               # 项目配置
├── setup.py                     # 打包脚本
├── pixi.toml                    # Pixi 环境配置
└── mkdocs.yml                   # 文档配置
```

## 🔧 环境管理

本项目使用 [Pixi](https://pixi.sh/) 进行环境管理。Pixi 是一个现代化的包管理工具，具有以下优势：

- ✅ 自动安装 RDKit（无需手动配置 conda）
- ✅ 环境隔离，不污染系统
- ✅ 跨平台支持（Linux、macOS、Windows）
- ✅ 快速且可重现的依赖管理

### Pixi 常用命令

```bash
# 安装依赖
pixi install

# 激活环境
pixi shell

# 添加新包
pixi add package-name

# 运行命令
pixi run python script.py
pixi run jupyter notebook

# 查看已安装包
pixi list
```

## 🧪 运行示例

### 方式 1: Jupyter Notebook

```bash
pixi run jupyter notebook notebooks/filter_molecules.ipynb
```

查看第 15 章节的 MacrolactoneFragmenter 完整演示。

### 方式 2: Python 脚本

```bash
pixi run python examples/basic_usage.py
```

### 方式 3: 交互式 Python

```bash
pixi shell
python
>>> from src.macrolactone_fragmenter import MacrolactoneFragmenter
>>> fragmenter = MacrolactoneFragmenter(ring_size=16)
>>> # 开始使用...
```

## 📊 性能

- **处理速度**: ~100 分子/分钟
- **已测试**: 2000+ 个 16 元环大环内酯
- **支持环大小**: 12-20 元环
- **输出格式**: JSON, CSV, DataFrame, PNG, SVG

## 🤝 贡献

欢迎贡献！请查看 [贡献指南](docs/development/contributing.md)。

### 开发环境设置

```bash
# Fork 并克隆项目
git clone https://github.com/YOUR_USERNAME/macro_split.git
cd macro_split

# 安装开发依赖
pixi install

# 运行测试
pixi run pytest

# 检查代码风格
pixi run black src/
pixi run flake8 src/
```

## 📝 许可证

本项目基于 [MIT License](LICENSE) 开源。

## 🔗 相关链接

- **文档**: [在线文档](https://yourusername.github.io/macro_split/)
- **GitHub**: [macro_split](https://github.com/yourusername/macro_split)
- **PyPI**: [macrolactone-fragmenter](https://pypi.org/project/macrolactone-fragmenter/)（即将发布）
- **问题反馈**: [Issues](https://github.com/yourusername/macro_split/issues)

## 📧 联系方式

如有问题或建议，请：

- 提交 [Issue](https://github.com/yourusername/macro_split/issues)
- 参与 [Discussions](https://github.com/yourusername/macro_split/discussions)
- 查看[文档](https://yourusername.github.io/macro_split/)

## 🌟 致谢

- [RDKit](https://www.rdkit.org/) - 化学信息学核心库
- [Pixi](https://pixi.sh/) - 现代化的包管理工具
- [MkDocs Material](https://squidfunk.github.io/mkdocs-material/) - 漂亮的文档主题

---

<div align="center">

**⭐ 如果这个项目对您有帮助，请给它一个 Star！⭐**

Made with ❤️ by Macro Split Team

</div>