feat(toolkit): ship macro_lactone_toolkit package
Unify macrolactone detection, numbering, fragmentation, and splicing under the installable macro_lactone_toolkit package. - replace legacy src.* modules with the new package layout - add analyze/number/fragment CLI entrypoints and pixi tasks - migrate tests, README, and scripts to the new package API
This commit is contained in:
315
README.md
315
README.md
@@ -1,292 +1,67 @@
|
||||
# Macrolactone Fragmenter
|
||||
# macro_lactone_toolkit
|
||||
|
||||
[](https://www.python.org/downloads/)
|
||||
[](https://opensource.org/licenses/MIT)
|
||||
[](https://pixi.sh)
|
||||
`macro_lactone_toolkit` 是一个正式可安装的 Python 包，用于 12-20 元有效大环内酯的识别、环编号、侧链裂解和简单拼接回组装。
|
||||
|
||||
一个专业的大环内酯（Macrolactone, 12-20 元环）侧链断裂和分析工具，提供从分子编号、侧链断裂到可视化和数据导出的完整工作流。
|
||||
## 核心能力
|
||||
|
||||
## ✨ 主要特性
|
||||
- 默认自动识别 12-20 元有效大环内酯，也允许显式指定 `ring_size`
|
||||
- 环编号规则固定为：
|
||||
- 位置 1 = 内酯羰基碳
|
||||
- 位置 2 = 环上的酯键氧
|
||||
- 位置 3-N = 沿统一方向连续编号
|
||||
- 侧链裂解同时输出两套 SMILES：
|
||||
- `fragment_smiles_labeled`，例如 `[5*]`
|
||||
- `fragment_smiles_plain`，例如 `*`
|
||||
- dummy 原子与连接原子的原始键型保持一致
|
||||
- 提供正式 CLI：
|
||||
- `macro-lactone-toolkit analyze`
|
||||
- `macro-lactone-toolkit number`
|
||||
- `macro-lactone-toolkit fragment`
|
||||
|
||||
- 🔢 **智能环原子编号** - 支持 12-20 元环，基于内酯结构的固定编号系统
|
||||
- ✂️ **自动侧链断裂** - 智能识别并断裂所有侧链，支持单个或批量处理
|
||||
- 📊 **强大的可视化** - SVG 显示 + PNG 保存，支持自定义 DPI 和尺寸
|
||||
- 💾 **多种导出格式** - JSON、CSV、DataFrame，预留 SQLModel 数据库接口
|
||||
- 🚀 **批量处理** - 直接处理 CSV 文件，支持 2000+ 分子的大规模分析
|
||||
- 📦 **易于安装** - 使用 pixi 或 pip 安装，支持开发模式
|
||||
## 环境
|
||||
|
||||
## 🚀 快速开始
|
||||
|
||||
### 安装
|
||||
|
||||
**使用 Pixi（推荐）**
|
||||
推荐使用 `pixi`，项目已固定到 Python 3.12，并支持 `osx-arm64` 与 `linux-64`。
|
||||
|
||||
```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/
|
||||
pixi run python -c "import macro_lactone_toolkit"
|
||||
```
|
||||
|
||||
## 📝 许可证
|
||||
## Python API
|
||||
|
||||
本项目基于 [MIT License](LICENSE) 开源。
|
||||
```python
|
||||
from macro_lactone_toolkit import MacroLactoneAnalyzer, MacrolactoneFragmenter
|
||||
|
||||
## 🔗 相关链接
|
||||
analyzer = MacroLactoneAnalyzer()
|
||||
valid_ring_sizes = analyzer.get_valid_ring_sizes("O=C1CCCCCCCCCCCCCCO1")
|
||||
|
||||
- **文档**: [在线文档](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)
|
||||
fragmenter = MacrolactoneFragmenter()
|
||||
numbering = fragmenter.number_molecule("O=C1CCCCCCCCCCCCCCO1")
|
||||
result = fragmenter.fragment_molecule("O=C1CCCC(C)CCCCCCCCCCO1", parent_id="mol_001")
|
||||
```
|
||||
|
||||
## 📧 联系方式
|
||||
## CLI
|
||||
|
||||
如有问题或建议，请：
|
||||
单分子分析：
|
||||
|
||||
- 提交 [Issue](https://github.com/yourusername/macro_split/issues)
|
||||
- 参与 [Discussions](https://github.com/yourusername/macro_split/discussions)
|
||||
- 查看[文档](https://yourusername.github.io/macro_split/)
|
||||
```bash
|
||||
pixi run macro-lactone-toolkit analyze --smiles "O=C1CCCCCCCCCCCCCCO1"
|
||||
pixi run macro-lactone-toolkit number --smiles "O=C1CCCCCCCCCCCCCCO1"
|
||||
pixi run macro-lactone-toolkit fragment --smiles "O=C1CCCC(C)CCCCCCCCCCO1" --parent-id mol_001
|
||||
```
|
||||
|
||||
## 🌟 致谢
|
||||
CSV 批处理：
|
||||
|
||||
- [RDKit](https://www.rdkit.org/) - 化学信息学核心库
|
||||
- [Pixi](https://pixi.sh/) - 现代化的包管理工具
|
||||
- [MkDocs Material](https://squidfunk.github.io/mkdocs-material/) - 漂亮的文档主题
|
||||
```bash
|
||||
pixi run macro-lactone-toolkit fragment \
|
||||
--input molecules.csv \
|
||||
--output fragments.csv \
|
||||
--errors-output fragment_errors.csv
|
||||
```
|
||||
|
||||
---
|
||||
默认读取 `smiles` 列；若存在 `id` 列则将其作为 `parent_id`，否则自动生成 `row_<index>`。
|
||||
|
||||
<div align="center">
|
||||
## Legacy Scripts
|
||||
|
||||
**⭐ 如果这个项目对您有帮助，请给它一个 Star！⭐**
|
||||
|
||||
Made with ❤️ by Macro Split Team
|
||||
|
||||
</div>
|
||||
`scripts/` 目录保留为薄封装或迁移提示，不再承载核心实现。正式接口以 `macro_lactone_toolkit.*` 与 `macro-lactone-toolkit` CLI 为准。
|
||||
|
||||
Reference in New Issue
Block a user