Macrolactone Fragmenter

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

✨ 主要特性

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

🚀 快速开始

安装

使用 Pixi（推荐）

# 安装 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

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

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

基本使用

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)

批量处理

# 批量处理 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)

📖 文档

完整的文档请访问：在线文档

或本地查看：

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

文档内容

• 📘 快速开始 - 5 分钟上手指南
• 📗 安装指南 - 详细的安装说明
• 📙 用户指南 - 完整的使用说明
• 📕 API 参考 - 自动生成的 API 文档
• 📔 教程与示例 - 实际使用案例

🎯 核心功能

MacrolactoneFragmenter 类

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

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 导入导出：

@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 进行环境管理。Pixi 是一个现代化的包管理工具，具有以下优势：

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

Pixi 常用命令

# 安装依赖
pixi install

# 激活环境
pixi shell

# 添加新包
pixi add package-name

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

# 查看已安装包
pixi list

🧪 运行示例

方式 1: Jupyter Notebook

pixi run jupyter notebook notebooks/filter_molecules.ipynb

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

方式 2: Python 脚本

pixi run python examples/basic_usage.py

方式 3: 交互式 Python

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

📊 性能

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

🤝 贡献

欢迎贡献！请查看 贡献指南。

开发环境设置

# 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 开源。

🔗 相关链接

• 文档: 在线文档
• GitHub: macro_split
• PyPI: macrolactone-fragmenter（即将发布）
• 问题反馈: Issues

📧 联系方式

如有问题或建议，请：

• 提交 Issue
• 参与 Discussions
• 查看文档

🌟 致谢

• RDKit - 化学信息学核心库
• Pixi - 现代化的包管理工具
• MkDocs Material - 漂亮的文档主题

---

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

Made with ❤️ by Macro Split Team