293 lines
7.7 KiB
Markdown
293 lines
7.7 KiB
Markdown
# Macrolactone Fragmenter
|
||
|
||
[](https://www.python.org/downloads/)
|
||
[](https://opensource.org/licenses/MIT)
|
||
[](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>
|