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
文档内容
🎯 核心功能
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