Skill: charleshahn/duivytools-skills (version 1.0.0)

--- name: duivytools-skills description: "DuIvyTools (dit) 命令行工具使用指南。当 Agent 需要使用 DuIvyTools 但不清楚命令用法时调用。功能覆盖：(1) XVG 数据可视化 - RMSD、RMSF、能量、氢键、回转半径等；(2) XPM 矩阵可视化 - DCCM、FEL、DSSP 二级结构热图；(3) NDX 索引文件操作 - 查看、合并、提取原子组；(4) 统计分析 - 平均值、标准差、分布、相关性；(5) 拉马钱德兰图绘制；(6) 数据格式转换 - 导出为 CSV/DAT。支持 matplotlib、plotly、gnuplot、plotext 四种绘图引擎。" --- # DuIvyTools (DIT) > **重要：使用前务必查看命令帮助** > > DuIvyTools 持续开发中。**务必**先运行 `dit <command> -h` 获取该命令最准确、最新的参数信息。 DuIvyTools 是一个命令行工具，用于分析和可视化 GROMACS 分子动力学模拟结果。它提供约 30 个命令，用于处理 XVG、XPM、NDX 等常见的 GROMACS 输出文件。 ## 快速入门 ### 安装 ```bash pip install DuIvyTools ``` 或使用清华镜像（国内更快）： ```bash pip install DuIvyTools -i https://pypi.tuna.tsinghua.edu.cn/simple ``` ### 验证安装 ```bash dit ``` ### 获取帮助 ```bash dit # 所有可用命令 dit -h # 全局参数 dit xvg_show -h # 特定命令帮助（务必先执行此操作！） ``` ## 核心概念 ### 单位与数据转换 - **GROMACS 默认单位**：时间 = ps，距离 = nm，能量 = kJ/mol - **默认不转换单位**：除非用户明确要求，否则保留原始单位 - **转换时**：必须同时更新数据和坐标轴标签 ### 列与行索引 - **列索引**：从 0 开始（0 = 第一列） - **行索引**：从 0 开始（0 = 第一行） - **原子索引（NDX）**：从 1 开始（GROMACS 惯例） - **范围**：左闭右开（如 `1-7` 表示第 1 至第 6 列） ### XPM 数据类型 - **离散型（Discrete）**：如 DSSP，每个像素代表一个离散状态 - **连续型（Continuous）**：如 DCCM、FEL，每个像素代表一个连续值 - **xpm_diff**：仅适用于连续型，不适用于 DSSP 等离散型 ## 命令列表 ### XVG 命令（数据可视化） | 命令 | 功能说明 | |------|----------| | `xvg_show` | 显示 XVG 数据，自动解析图例和坐标轴 | | `xvg_compare` | 比较多个 XVG 文件，支持灵活的列选择 | | `xvg_ave` | 计算每列的平均值、标准差、标准误 | | `xvg_show_distribution` | 显示数据分布（直方图/PDF/CDF） | | `xvg_show_stack` | 绘制堆积面积图 | | `xvg_show_scatter` | 绘制 2D 或 3D 散点图 | | `xvg_box_compare` | 使用小提琴图和散点图比较分布 | | `xvg_combine` | 将多个 XVG 文件的数据合并为一个 | | `xvg_ave_bar` | 计算并显示平行实验的平均值 | | `xvg_rama` | 根据 phi/psi 二面角绘制拉式图（Ramachandran plot） | | `xvg_energy_compute` | 计算蛋白质-配体相互作用能 | ### XPM 命令（矩阵可视化） | 命令 | 功能说明 | |------|----------| | `xpm_show` | 使用 4 种绘图引擎可视化 XPM 矩阵 | | `xpm2csv` | 将 XPM 转换为 CSV 格式（x, y, value） | | `xpm2dat` | 将 XPM 转换为 M×N 矩阵格式 | | `xpm_diff` | 计算两个 XPM 文件的差值（仅连续型） | | `xpm_merge` | 将两个 XPM 文件沿对角线合并 | ### NDX 命令（索引文件） | 命令 | 功能说明 | |------|----------| | `ndx_add` | 向 NDX 文件添加新的索引组 | | `ndx_split` | 将一个索引组切分为多个 | | `ndx_show` | 显示所有索引组名称 | | `ndx_rm_dup` | 删除重复的索引组 | ### 工具命令 | 命令 | 功能说明 | |------|----------| | `mdp_gen` | 生成 GROMACS MDP 文件模板 | | `show_style` | 显示/生成绘图样式配置文件 | | `find_center` | 查找原子组的几何中心 | | `dccm_ascii` | 将 ASCII 协方差矩阵转换为 DCCM XPM | | `dssp` | 将 GROMACS 2023 DSSP 格式转换为 XPM/XVG | 完整参数说明请参阅 [commands-reference.md](references/commands-reference.md)。 ## 绘图引擎 | 引擎 | 适用场景 | |------|----------| | `matplotlib`（默认） | 功能最全面，支持所有模式 | | `plotly` | 交互式图表，适合网页展示 | | `gnuplot` | 高质量输出，需单独安装 | | `plotext` | 终端显示，快速预览 | 使用 `-eg` 参数指定引擎：`dit xvg_show -f data.xvg -eg plotly` ## 常用工作流 ### 可视化 XVG 数据 ```bash # 基本显示 dit xvg_show -f rmsd.xvg # 比较多个文件 dit xvg_compare -f rmsd.xvg gyrate.xvg -c 1 1,2 -l RMSD Gyrate # 计算平均值（从第 2000 行到末尾） dit xvg_ave -f rmsd.xvg -b 2000 # 显示分布 dit xvg_show_distribution -f gyrate.xvg -c 1 ``` ### 显示 XPM 矩阵 ```bash # 基本显示 dit xpm_show -f dccm.xpm -cmap coolwarm -zmin -1 -zmax 1 # 3D 模式 dit xpm_show -f fel.xpm -m 3d -x PC1 -y PC2 -z Energy # 等高线图 dit xpm_show -f dccm.xpm -m contour -cmap coolwarm # 交互式 plotly dit xpm_show -f fel.xpm -eg plotly -m 3d ``` 更多实际场景请参阅 [examples.md](references/examples.md)。 ## 参考文档 - **[commands-reference.md](references/commands-reference.md)** - 完整命令参数说明 - **[examples.md](references/examples.md)** - 实际使用场景示例 ## 相关资源 - GitHub: https://github.com/CharlesHahn/DuIvyTools - 文档: https://duivytools.readthedocs.io/ - 引用: https://doi.org/10.5281/zenodo.6339993

path: references/commands-reference.md
content: # DuIvyTools 命令参考文档

本文件包含所有命令的详细参数说明。关于核心概念和快速入门，请参考主 SKILL.md 文件。

> **重要说明**：不同命令支持的参数不同。以下列出的是所有可能的参数，具体某个命令支持哪些参数，请使用 `dit <command> -h` 查看。

## 目录

- [DuIvyTools 命令参考文档](#duivytools-命令参考文档)
  - [目录](#目录)
  - [通用参数说明](#通用参数说明)
    - [输入输出参数](#输入输出参数)
    - [数据选择参数](#数据选择参数)
    - [绘图标签参数](#绘图标签参数)
    - [数据范围参数](#数据范围参数)
    - [数据变换参数](#数据变换参数)
    - [绘图控制参数](#绘图控制参数)
    - [统计分析参数](#统计分析参数)
    - [插值参数](#插值参数)
    - [模式参数](#模式参数)
  - [XVG 命令](#xvg-命令)
    - [xvg\_show](#xvg_show)
    - [xvg\_compare](#xvg_compare)
    - [xvg\_ave](#xvg_ave)
    - [xvg\_show\_distribution](#xvg_show_distribution)
    - [xvg\_show\_stack](#xvg_show_stack)
    - [xvg\_show\_scatter](#xvg_show_scatter)
    - [xvg\_box\_compare](#xvg_box_compare)
    - [xvg\_combine](#xvg_combine)
    - [xvg\_ave\_bar](#xvg_ave_bar)
    - [xvg\_rama](#xvg_rama)
    - [xvg\_energy\_compute](#xvg_energy_compute)
  - [XPM 命令](#xpm-命令)
    - [xpm\_show](#xpm_show)
    - [xpm2csv](#xpm2csv)
    - [xpm2dat](#xpm2dat)
    - [xpm\_diff](#xpm_diff)
    - [xpm\_merge](#xpm_merge)
  - [NDX 命令](#ndx-命令)
    - [ndx\_add](#ndx_add)
    - [ndx\_split](#ndx_split)
    - [ndx\_show](#ndx_show)
    - [ndx\_rm\_dup](#ndx_rm_dup)
  - [其他命令](#其他命令)
    - [mdp\_gen](#mdp_gen)
    - [show\_style](#show_style)
    - [find\_center](#find_center)
    - [dccm\_ascii](#dccm_ascii)
    - [dssp](#dssp)
  - [常用 Colormap 参考](#常用-colormap-参考)

---

## 通用参数说明

以下是 DuIvyTools 各命令可能支持的参数。**不同命令支持的参数不同**，具体请查看 `dit <command> -h`。

### 输入输出参数

| 参数 | 说明 |
|------|------|
| `-f INPUT [INPUT ...]` | 输入文件（一个或多个） |
| `-o OUTPUT` | 输出文件名 |

### 数据选择参数

| 参数 | 说明 |
|------|------|
| `-c COLUMNS [COLUMNS ...]` | 选择数据列索引（0-based）。格式：`1-7,10` 表示第1到6列和第10列。多组文件：`1-7,10 0,1,4` |
| `-b BEGIN` | 起始行索引（包含） |
| `-e END` | 结束行索引（不包含） |
| `-dt DT` | 步长，默认为1 |

### 绘图标签参数

| 参数 | 说明 |
|------|------|
| `-l LEGENDS [LEGENDS ...]` | 图例标签。不显示：`-l "" "" ""`。支持 LaTeX：`-l "$\Delta G_{energy}$"` |
| `-x XLABEL` | X 轴标签 |
| `-y YLABEL` | Y 轴标签 |
| `-z ZLABEL` | Z 轴标签（用于颜色、3D图等） |
| `-t TITLE` | 图片标题。不显示：`-t ""` |

### 数据范围参数

| 参数 | 说明 |
|------|------|
| `-xmin XMIN` / `-xmax XMAX` | X 轴范围 |
| `-ymin YMIN` / `-ymax YMAX` | Y 轴范围 |
| `-zmin ZMIN` / `-zmax ZMAX` | Z 轴范围（某些情况下可能是颜色值） |

### 数据变换参数

| 参数 | 说明 |
|------|------|
| `-xs XSHRINK` / `-ys YSHRINK` / `-zs ZSHRINK` | 数据缩放因子，默认1.0 |
| `-xp XPLUS` / `-yp YPLUS` / `-zp ZPLUS` | 数据偏移量，默认0.0 |

**警告**：变换后必须更新对应的轴标签，不可以随意修改数据，除非用户明确要求！

### 绘图控制参数

| 参数 | 说明 |
|------|------|
| `-ns` | 不显示图形（用于批量处理） |
| `--alpha ALPHA` | 图形元素透明度 |
| `-csv CSV` | 将数据导出到 CSV 文件 |
| `-eg {matplotlib,plotly,gnuplot,plotext}` | 绘图引擎，默认 matplotlib |
| `-cmap COLORMAP` | 颜色映射（matplotlib 和 plotly） |
| `--colorbar_location {None,left,top,bottom,right}` | 颜色条位置 |
| `--legend_location {inside,outside}` | 图例位置 |
| `--legend_ncol LEGEND_NCOL` | 图例列数，默认1 |

### 统计分析参数

| 参数 | 说明 |
|------|------|
| `-smv [{,CI,origin}]` | 显示滑动平均值。`CI` 显示置信区间, `origin`显示原始数据作为背景 |
| `-ws WINDOWSIZE` | 滑动平均窗口大小，默认50 |
| `-cf CONFIDENCE` | 置信区间可信度，默认0.95 |

### 插值参数

| 参数 | 说明 |
|------|------|
| `-ip INTERPOLATION` | 插值方法（bilinear, bicubic, nearest, linear, cubic, quintic），需要根据程序输出进行调整，当使用imshow的时候，插值方法是matplotlib的插值方法，当使用其它mode的时候，使用的是scipy支持的插值方法 |
| `-ipf INTERPOLATION_FOLD` | 插值倍数，默认10 |

### 模式参数

| 参数 | 说明 |
|------|------|
| `-m MODE` | 模式选择：`pcolormesh`, `3d`, `contour`, `pdf`, `cdf` 等 |

---

## XVG 命令

### xvg_show

**功能**：快速显示一个或多个 XVG 文件中的所有数据。

**说明**：
- 默认第0列为 X 值，第1列及之后为 Y 值
- 自动解析图例、X/Y 轴标签

**参数**：标准参数（见全局参数）

**示例**：
```bash
# 显示单个文件
dit xvg_show -f rmsd.xvg

# 显示多个文件
dit xvg_show -f rmsd.xvg gyrate.xvg

# 选择特定列并设置标签
dit xvg_show -f rmsd.xvg -c 1 -x "Time (ns)" -y "RMSD (nm)" -t "RMSD Analysis"
```

---

### xvg_compare

**功能**：比较多个 XVG 文件中的数据，支持灵活的列选择和滑动平均。

**说明**：
- 比 xvg_show 更灵活，推荐使用
- 每个输入文件可以选择不同的列
- 支持滑动平均和置信区间显示

**示例**：
```bash
# 比较两个文件的不同列
dit xvg_compare -f rmsd.xvg gyrate.xvg -c 1 1,2

# 设置图例和轴标签
dit xvg_compare -f rmsd.xvg gyrate.xvg -c 1 1,2 -l RMSD gyrate gyrate_X -x "Time(ps)" -y "(nm)"

# 显示滑动平均值
dit xvg_compare -f energy.xvg -c 1,3 -l "LJ(SR)" "Coulomb(SR)" -smv

# 使用 plotly 引擎
dit xvg_compare -f energy.xvg -c 1,3 -l "LJ(SR)" "Coulomb(SR)" -smv -eg plotly

# 导出数据到 CSV
dit xvg_compare -f energy.xvg -c 1,3 -ns -csv data.csv
```

---

### xvg_ave

**功能**：计算 XVG 文件中每一列数据的平均值、标准偏差和标准误差。

**参数**：
- `-f`：输入 XVG 文件
- `-b`：起始行索引（包含）
- `-e`：结束行索引（不包含）

**示例**：
```bash
# 计算平均值
dit xvg_ave -f rmsd.xvg -b 1000 -e 2001

# 输出示例：
# >>>>>>>>>                    rmsd.xvg                    <<<<<<<<<<<<<<
# ----------------------------------------------------------------------------
# |                  |     Average      |     Std.Dev      |     Std.Err      |
# ----------------------------------------------------------------------------
# |    Time (ps)     |   15000.000000   |   2891.081113    |    91.378334     |
# ----------------------------------------------------------------------------
# |    RMSD (nm)     |     0.388980     |     0.038187     |     0.001207     |
# ----------------------------------------------------------------------------
```

---

### xvg_show_distribution

**功能**：显示数据的分布情况，支持直方图、PDF 和 CDF。

**参数**：
- `-m`：显示模式
  - 默认：直方图
  - `pdf`：概率密度函数
  - `cdf`：累积密度函数

**示例**：
```bash
# 显示分布
dit xvg_show_distribution -f gyrate.xvg -c 1,2

# 显示 PDF
dit xvg_show_distribution -f gyrate.xvg -c 1,2 -m pdf -eg plotly

# 显示 CDF
dit xvg_show_distribution -f gyrate.xvg -c 1,2 -m cdf
```

---

### xvg_show_stack

**功能**：绘制堆积折线图，适用于二级结构含量变化等场景。

**示例**：
```bash
# 绘制二级结构含量堆积图
dit xvg_show_stack -f dssp_sc.xvg -c 2-7 -x "Time (ns)"
```

---

### xvg_show_scatter

**功能**：绘制散点图，支持两列或三列数据。

**说明**：
- 两列：X-Y 散点图
- 三列：X-Y 散点图，第三列用于颜色映射

**示例**：
```bash
# 两列散点图
dit xvg_show_scatter -f gyrate.xvg -c 1,2

# 三列散点图（用第三列着色）
dit xvg_show_scatter -f gyrate.xvg -c 1,2,0 -z "Time(ps)" -eg plotly
```

---

### xvg_box_compare

**功能**：以小提琴图和散点图的形式比较数据列。

**参数**：
- `-m withoutScatter`：不显示散点图

**示例**：
```bash
# 显示小提琴图和散点图
dit xvg_box_compare -f gyrate.xvg -c 1,2,3,4 -l Gyrate Gx Gy Gz -z "Time(ps)"

# 仅显示小提琴图
dit xvg_box_compare -f gyrate.xvg -c 1,2,3,4 -l Gyrate Gx Gy Gz -m withoutScatter

# 使用 plotly 引擎
dit xvg_box_compare -f gyrate.xvg -c 1,2,3,4 -l Gyrate Gx Gy Gz -eg plotly
```

---

### xvg_combine

**功能**：从多个 XVG 文件中读取数据并组合成一个新的 XVG 文件。

**示例**：
```bash
# 组合两个文件的数据
dit xvg_combine -f RMSD.xvg Gyrate.xvg -c 0,1 1 -l RMSD Gyrate -x "Time(ps)"

# 组合并输出到新文件
dit xvg_combine -f f1.xvg f2.xvg -c 1,2 2,3 -o res.xvg
```

---

### xvg_ave_bar

**功能**：计算多组数据的平均值和误差，并绘制柱状图。

**说明**：适用于比较多个平行模拟的结果。

**参数**：
- `-al`：X 轴标签
- `-csv`：导出数据到 CSV

**示例**：
```bash
# 比较三个配体体系的氢键数量（逗号分隔表示平行实验）
dit xvg_ave_bar -f bar_0_0.xvg,bar_0_1.xvg bar_1_0.xvg,bar_1_1.xvg \
  -c 1,2 -l MD_0 MD_1 -al Hbond Pair -csv hhh.csv -y Number
```

---

### xvg_rama

**功能**：将 Ramachandran 数据（phi 和 psi 二面角）绘制成拉式图。

**示例**：
```bash
# 绘制拉式图
dit xvg_rama -f rama.xvg

# 保存为图片
dit xvg_rama -f rama.xvg -ns -o rama.png
```

---

### xvg_energy_compute

**功能**：计算蛋白质和配体之间的能量。

---

## XPM 命令

### xpm_show

**功能**：可视化 XPM 矩阵文件。

**支持的绘图模式**（`-m` 参数）：
| 模式 | 说明 | 支持引擎 |
|------|------|----------|
| `imshow` | 快速图像显示（默认） | matplotlib |
| `pcolormesh` | 网格可视化 | matplotlib, plotly, gnuplot |
| `3d` | 3D 表面图 | matplotlib, plotly, gnuplot |
| `contour` | 等高线图 | matplotlib, plotly, gnuplot |

**特有参数**：
| 参数 | 说明 |
|------|------|
| `-xmin/-xmax/-ymin/-ymax` | 图像切割（像素索引） |
| `--x_numticks/--y_numticks/--z_numticks` | 刻度数量 |

**示例**：
```bash
# 基本显示
dit xpm_show -f DSSP.xpm

# 不显示图形，保存到文件
dit xpm_show -f DSSP.xpm -ns -o dssp.png

# 3D 模式
dit xpm_show -f FEL.xpm -m 3d -x PC1 -y PC2 -z Energy -t FEL --alpha 0.5

# 等高线模式
dit xpm_show -f FEL.xpm -m contour -cmap jet -zmin 0 -zmax 20

# 图像切割（显示部分区域）
dit xpm_show -f DSSP.xpm -xmin 1000 -xmax 2001 -ymin 50 -ymax 101

# 使用 plotly 引擎
dit xpm_show -f FEL.xpm -eg plotly -m 3d -cmap spectral

# 使用 gnuplot 引擎
dit xpm_show -f FEL.xpm -eg gnuplot -m 3d -ip cubic
```

---

### xpm2csv

**功能**：将 XPM 文件转换为 CSV 格式（x, y, v 三列）。

**示例**：
```bash
dit xpm2csv -f test.xpm -o test.csv
```

---

### xpm2dat

**功能**：将 XPM 文件转换为 M×N 的 DAT 格式。

**输出格式**：
- 第一行：X 轴标题、Y 轴标题、矩阵标题
- 第二行：X 轴数据
- 第三行：Y 轴数据（从下到上）
- 后续：M×N 数据矩阵

**示例**：
```bash
dit xpm2dat -f test.xpm -o test.dat
```

---

### xpm_diff

**功能**：计算两个相同尺寸 XPM 文件的差值。

**说明**：
- 仅适用于 Continuous 类型（如 DCCM、FEL）
- 不适用于 Discrete 类型（如 DSSP）

**示例**：
```bash
dit xpm_diff -f DCCM0.xpm DCCM1.xpm -o DCCM0-1.xpm
```

---

### xpm_merge

**功能**：将两个相同尺寸的 XPM 文件沿对角线一半一半拼接。

**示例**：
```bash
dit xpm_merge -f DCCM0.xpm DCCM1.xpm -o DCCM0-1.xpm
```

---

## NDX 命令

### ndx_add

**功能**：向 NDX 索引文件添加新的索引组。

**参数**：
- `-al`：组名（可多个）
- `-c`：原子索引（从1开始，GROMACS 约定）

**示例**：
```bash
# 添加单个组
dit ndx_add -f index.ndx -o test.ndx -al lig -c 1-10

# 添加多个组
dit ndx_add -al lig mol -c 1-10-3,11-21 21-42
```

---

### ndx_split

**功能**：将一个索引组均匀切分成多个组。

**参数**：
- `-al`：组名或组索引 + 切分数量

**示例**：
```bash
# 按组索引切分
dit ndx_split -f index.ndx -al 1 2

# 按组名切分
dit ndx_split -f index.ndx -al Protein 2

# 切分并输出到新文件
dit ndx_split -f index.ndx -al Protein 2 -o test.ndx
```

---

### ndx_show

**功能**：显示 NDX 文件中所有索引组的名称。

**示例**：
```bash
dit ndx_show -f test.ndx
```

---

### ndx_rm_dup

**功能**：删除 NDX 文件中所有重复的索引组（名称和索引都相同）。

**示例**：
```bash
dit ndx_rm_dup -f test.ndx -o res.ndx
```

---

## 其他命令

### mdp_gen

**功能**：生成 GROMACS MDP 文件模板。

**说明**：生成的模板不一定适合您的体系，请根据实际情况调整参数。

**示例**：
```bash
# 生成默认模板
dit mdp_gen

# 生成指定文件名的模板
dit mdp_gen -o nvt.mdp
```

---

### show_style

**功能**：显示或生成不同绘图引擎的格式控制文件。

**说明**：生成的样式文件放在工作目录会自动被 DIT 加载。

**示例**：
```bash
# 显示默认 matplotlib 样式
dit show_style

# 显示 plotly 样式
dit show_style -eg plotly

# 显示 gnuplot 样式
dit show_style -eg gnuplot

# 生成样式文件
dit show_style -eg plotly -o DIT_plotly.json
```

---

### find_center

**功能**：寻找 GRO 文件中原子组的几何中心。

**参数**：
- `-m AllAtoms`：在所有原子中寻找指定原子组的几何中心

**示例**：
```bash
# 计算所有原子的几何中心
dit find_center -f test.gro

# 使用索引文件
dit find_center -f test.gro index.ndx

# 在所有原子中寻找指定组的几何中心
dit find_center -f test.gro index.ndx -m AllAtoms
```

---

### dccm_ascii

**功能**：将 GROMACS `covar` 命令的 ASCII 格式协方差矩阵转换为动态互相关矩阵（DCCM）XPM 文件。

**示例**：
```bash
dit dccm_ascii -f covar.dat -o dccm.xpm
```

---

### dssp

**功能**：处理 GROMACS 2023 的 `dssp` 命令生成的 DAT 文件，转换为 DSSP XPM 和 sc.xvg 文件。

**说明**：将 GROMACS 2023 格式转换为旧版本格式。

**参数**：
- `-c`：残基索引（用于时间序列生成）
- `-b/-e/-dt`：时间序列参数

**示例**：
```bash
# 基本转换
dit dssp -f dssp.dat -o dssp.xpm

# 生成时间序列
dit dssp -f dssp.dat -c 1-42,1-42,1-42 -b 1000 -e 2001 -dt 10 -x "Time (ps)"
```

---

## 常用 Colormap 参考

| 名称 | 适用场景 |
|------|----------|
| `coolwarm` | 对称数据（DCCM） |
| `jet` / `jet_r` `Blues_r` | 自由能景观 |
| `viridis` / `plasma` | 连续数据 |
| `Blues` / `Reds` / `Greys` | 单色调 |
| `tab10` | 离散数据 |

输入错误的 colormap 名称会显示所有可用选项。


path: references/examples.md
content: # DuIvyTools 使用示例

本文件包含真实使用场景的完整示例。关于核心概念和命令参数，请参考主 SKILL.md 文件和 commands-reference.md。

## 目录

- [分子动力学结果分析](#分子动力学结果分析)
- [能量分析](#能量分析)
- [氢键分析](#氢键分析)
- [二级结构分析](#二级结构分析)
- [RMSD/RMSF 分析](#rmsdrmsf-分析)
- [动态互相关矩阵 (DCCM)](#动态互相关矩阵-dccm)
- [自由能景观 (FEL)](#自由能景观-fel)
- [Ramachandran 图](#ramachandran-图)
- [蛋白质几何性质](#蛋白质几何性质)
- [批量处理和脚本生成](#批量处理和脚本生成)
- [高级技巧](#高级技巧)
- [常见问题](#常见问题)

---

## 分子动力学结果分析

### 场景1：比较不同模拟的 RMSD

**问题**：你有三个不同的模拟体系，每个体系进行了3次平行实验，需要比较它们的 RMSD 变化。

```bash
# 显示所有 RMSD 文件
dit xvg_compare -f md1_rep1_rmsd.xvg md1_rep2_rmsd.xvg md1_rep3_rmsd.xvg \
  md2_rep1_rmsd.xvg md2_rep2_rmsd.xvg md2_rep3_rmsd.xvg \
  md3_rep1_rmsd.xvg md3_rep2_rmsd.xvg md3_rep3_rmsd.xvg \
  -c 1 1 1 1 1 1 1 1 1 \
  -l "MD1-1" "MD1-2" "MD1-3" "MD2-1" "MD2-2" "MD2-3" "MD3-1" "MD3-2" "MD3-3" \
  -x "Time (ps)" -y "RMSD (nm)" -t "RMSD Comparison" -smv

# 保存为图片
dit xvg_compare -f md1_rep1_rmsd.xvg md2_rep1_rmsd.xvg md3_rep1_rmsd.xvg \
  -c 1 1 1 \
  -l "MD1" "MD2" "MD3" \
  -x "Time (ps)" -y "RMSD (nm)" \
  -ns -o rmsd_comparison.png
```

---

### 场景2：分析蛋白质回转半径（Gyrate）

**问题**：分析蛋白质在不同方向上的回转半径变化（Rg, RgX, RgY, RgZ）。

```bash
# 显示所有回转半径分量
dit xvg_compare -f gyrate.xvg -c 1,2,3,4 \
  -l Rg RgX RgY RgZ \
  -x "Time (ps)" -y "Rg (nm)" -t "Radius of Gyration"

# 使用小提琴图比较分布
dit xvg_box_compare -f gyrate.xvg -c 1,2,3,4 \
  -l Rg RgX RgY RgZ \
  -z "Time(ps)" \
  -t "Gyrate Distribution"

# 仅显示小提琴图
dit xvg_box_compare -f gyrate.xvg -c 1,2,3,4 \
  -l Rg RgX RgY RgZ \
  -z "Time(ps)" \
  -m withoutScatter
```

---

### 场景3：计算平衡时期的平均值

**问题**：模拟运行了 100 ns，前 20 ns 是平衡时期，需要计算后 80 ns 的平均值和标准误差。

```bash
# 假设 xvg 文件有 10000 行，前 2000 行是平衡时期
# 从第 2000 行开始计算到末尾
dit xvg_ave -f rmsd.xvg -b 2000

# 计算指定范围的平均值（2000-4000 行）
dit xvg_ave -f rmsd.xvg -b 2000 -e 4001
```

---

## 能量分析

### 场景4：分析蛋白质-配体相互作用能

**问题**：分析蛋白质和配体之间的 Lennard-Jones 和库仑相互作用能。

```bash
# 显示能量变化（带滑动平均）
dit xvg_compare -f energy.xvg -c 1,3 \
  -l "LJ(SR)" "Coulomb(SR)" \
  -x "Time (ps)" -y "Energy (kJ/mol)" \
  -t "Protein-Ligand Interaction Energy" \
  -smv -ws 100

# 使用 plotly 交互式图表
dit xvg_compare -f energy.xvg -c 1,3 \
  -l "LJ(SR)" "Coulomb(SR)" \
  -x "Time (ps)" -y "Energy (kJ/mol)" \
  -eg plotly -smv

# 导出数据到 CSV
dit xvg_compare -f energy.xvg -c 1,3 \
  -l "LJ(SR)" "Coulomb(SR)" \
  -ns -csv energy_data.csv
```

---

### 场景5：比较不同配体的结合能

**问题**：你有三个不同的配体，每个配体进行了3次平行实验，需要比较它们的平均结合能。

```bash
# 计算平均值并绘制柱状图
dit xvg_ave_bar \
  -f lig1_rep1_energy.xvg,lig1_rep2_energy.xvg,lig1_rep3_energy.xvg \
     lig2_rep1_energy.xvg,lig2_rep2_energy.xvg,lig2_rep3_energy.xvg \
     lig3_rep1_energy.xvg,lig3_rep2_energy.xvg,lig3_rep3_energy.xvg \
  -c 1 1 1 \
  -l Ligand1 Ligand2 Ligand3 \
  -al "Ligand" "Binding Energy" \
  -y "Energy (kJ/mol)" \
  -t "Binding Energy Comparison" \
  -csv binding_energy.csv
```

---

## 氢键分析

### 场景6：分析蛋白质-配体氢键数量

**问题**：分析蛋白质和配体之间的氢键数量变化，计算稳定时期的平均值。

```bash
# 显示氢键数量变化
dit xvg_show -f hbonds.xvg \
  -x "Time (ps)" -y "Number of H-bonds" \
  -t "Protein-Ligand Hydrogen Bonds"

# 计算稳定时期的平均值
dit xvg_ave -f hbonds.xvg -b 3000

# 显示分布
dit xvg_show_distribution -f hbonds.xvg -c 1 \
  -x "Number of H-bonds" -t "H-bond Distribution"
```

---

### 场景7：比较不同条件下的氢键

**问题**：比较野生型和突变体与配体的氢键数量。

```bash
# 比较氢键数量
dit xvg_compare -f wt_hbonds.xvg mutant_hbonds.xvg \
  -c 1 1 \
  -l "Wild-Type" "Mutant" \
  -x "Time (ps)" -y "Number of H-bonds" \
  -t "Hydrogen Bond Comparison"

# 使用小提琴图比较分布
dit xvg_box_compare -f wt_hbonds.xvg mutant_hbonds.xvg \
  -c 1 1 \
  -l "Wild-Type" "Mutant" \
  -z "Time(ps)" \
  -t "H-bond Distribution"
```

---

## 二级结构分析

### 场景8：可视化蛋白质二级结构随时间的变化

**问题**：使用 DSSP 分析蛋白质二级结构随时间的变化。

```bash
# 如果使用 GROMACS 2023+，需要先转换 DSSP 输出
dit dssp -f dssp.dat -o dssp.xpm

# 显示二级结构矩阵
dit xpm_show -f dssp.xpm \
  -x "Residue Index" -y "Time (ps)" \
  -t "Secondary Structure"

# 切割显示特定区域（残基 50-150，时间 1000-2000 ps）
dit xpm_show -f dssp.xpm \
  -xmin 50 -xmax 151 -ymin 1000 -ymax 2001 \
  -x "Residue Index" -y "Time (ps)" \
  -t "Secondary Structure (Residues 50-150)"

# 使用 plotly 交互式查看
dit xpm_show -f dssp.xpm -eg plotly \
  -x "Residue Index" -y "Time (ps)"
```

---

### 场景9：分析二级结构含量变化

**问题**：分析不同二级结构（α-helix, β-sheet, coil 等）的含量随时间的变化。

```bash
# 显示二级结构含量堆积图
dit xvg_show_stack -f dssp_sc.xvg -c 2-7 \
  -x "Time (ps)" -y "Amino Acids Count" \
  -t "Secondary Structure Content"
```

---

### 场景10：比较不同状态的动态互相关矩阵（DCCM）

**问题**：比较蛋白质在结合配体前后原子运动相关性的变化。

**注意**：DCCM 是 Continuous 类型，可以计算差值。DSSP 是 Discrete 类型，不能计算差值。

**方法1：计算差值矩阵**
```bash
# 计算 DCCM 差值（Holo - Apo）
dit xpm_diff -f apo_dccm.xpm holo_dccm.xpm -o dccm_diff.xpm

# 显示差值矩阵
dit xpm_show -f dccm_diff.xpm \
  -x "Residue Index" -y "Residue Index" \
  -t "DCCM Difference (Holo - Apo)" \
  -cmap coolwarm -zmin -2 -zmax 2

# 保存差值矩阵图片
dit xpm_show -f dccm_diff.xpm -ns -o dccm_diff.png
```

**方法2：合并显示两个矩阵**
```bash
# 合并显示（左上 Apo，右下 Holo）
dit xpm_merge -f apo_dccm.xpm holo_dccm.xpm -o dccm_merged.xpm
dit xpm_show -f dccm_merged.xpm \
  -x "Residue Index" -y "Residue Index" \
  -t "DCCM (Top-Left: Apo, Bottom-Right: Holo)"
```

**结果解读**（针对差值矩阵）：
- 正值（红色）：配体结合增强了这两个残基之间的正相关运动
- 负值（蓝色）：配体结合改变了运动方向，使原本正相关变为负相关
- 接近0：配体结合对这对残基的相关性影响较小

---

## RMSD/RMSF 分析

### 场景11：分析蛋白质骨架和重原子的 RMSD

**问题**：同时分析蛋白质骨架（backbone）和重原子（heavy atoms）的 RMSD。

```bash
# 同时显示两个 RMSD
dit xvg_compare -f rmsd_backbone.xvg rmsd_heavy.xvg \
  -c 1 1 \
  -l "Backbone" "Heavy Atoms" \
  -x "Time (ps)" -y "RMSD (nm)" \
  -t "RMSD Comparison"

# 使用滑动平均和置信区间
dit xvg_compare -f rmsd_backbone.xvg rmsd_heavy.xvg \
  -c 1 1 \
  -l "Backbone" "Heavy Atoms" \
  -x "Time (ps)" -y "RMSD (nm)" \
  -smv CI -ws 100 -cf 0.95
```

---

### 场景12：分析残基的 RMSF

**问题**：分析每个残基的均方根涨落（RMSF），识别柔性区域。

```bash
# 显示 RMSF
dit xvg_show -f rmsf.xvg \
  -x "Residue Index" -y "RMSF (nm)" \
  -t "Root Mean Square Fluctuation"

# 比较不同状态的 RMSF
dit xvg_compare -f apo_rmsf.xvg holo_rmsf.xvg \
  -c 1 1 \
  -l "Apo" "Holo" \
  -x "Residue Index" -y "RMSF (nm)" \
  -t "RMSF Comparison"
```

---

## 动态互相关矩阵 (DCCM)

### 场景13：生成和分析 DCCM

**问题**：分析蛋白质残基之间的动态相关性。

```bash
# 从协方差矩阵生成 DCCM
dit dccm_ascii -f covar.dat -o dccm.xpm

# 显示 DCCM
dit xpm_show -f dccm.xpm \
  -x "Residue Index" -y "Residue Index" \
  -z "Correlation" \
  -t "Dynamic Cross-Correlation Matrix" \
  -cmap coolwarm -zmin -1 -zmax 1

# 使用等高线显示
dit xpm_show -f dccm.xpm \
  -m contour -cmap coolwarm \
  -zmin -1 -zmax 1 \
  -x "Residue Index" -y "Residue Index"

# 保存为图片
dit xpm_show -f dccm.xpm -ns -o dccm.png
```

---

## 自由能景观 (FEL)

### 场景14：2D 自由能景观

**问题**：可视化二维自由能景观。

```bash
# 显示自由能景观
dit xpm_show -f fel.xpm \
  -x "PC1" -y "PC2" -z "Energy (kJ/mol)" \
  -t "Free Energy Landscape" \
  -cmap jet_r

# 使用 3D 模式
dit xpm_show -f fel.xpm \
  -m 3d \
  -x "PC1" -y "PC2" -z "Energy (kJ/mol)" \
  -t "Free Energy Landscape" \
  -cmap jet_r --alpha 0.8

# 使用等高线
dit xpm_show -f fel.xpm \
  -m contour -cmap jet_r \
  -x "PC1" -y "PC2" -z "Energy (kJ/mol)" \
  --colorbar_location bottom

# 插值平滑
dit xpm_show -f fel.xpm \
  -m pcolormesh -ip cubic -ipf 3 \
  -cmap jet_r
```

---

### 场景15：3D 自由能景观

**问题**：使用三个反应坐标构建三维自由能景观。

```bash
# 使用 3D 模式显示
dit xpm_show -f fel_3d.xpm \
  -m 3d \
  -x "PC1" -y "PC2" -z "Energy (kJ/mol)" \
  -t "3D Free Energy Landscape" \
  -cmap plasma --alpha 0.7

# 设置刻度数量
dit xpm_show -f fel.xpm \
  -m 3d \
  --x_numticks 5 --y_numticks 5 --z_numticks 5 \
  -x "PC1" -y "PC2" -z "Energy (kJ/mol)"
```

---

## Ramachandran 图

### 场景16：分析蛋白质主链二面角

**问题**：分析蛋白质的 phi 和 psi 二面角分布，识别二级结构区域。

```bash
# 绘制 Ramachandran 图
dit xvg_rama -f rama.xvg

# 保存为图片
dit xvg_rama -f rama.xvg -ns -o rama.png

# 比较不同残基类型
dit xvg_rama -f rama_gly.xvg
dit xvg_rama -f rama_ala.xvg
```

---

## 蛋白质几何性质

### 场景17：计算几何中心

**问题**：计算配体或残基的几何中心。

```bash
# 计算配体的几何中心
dit find_center -f complex.gro ligand.ndx

# 在所有原子中寻找配体的几何中心
dit find_center -f complex.gro ligand.ndx -m AllAtoms

# 计算蛋白质的几何中心
dit find_center -f protein.gro
```

---

### 场景18：分析残基间距离

**问题**：分析两个残基之间的距离随时间的变化。

```bash
# 显示距离变化
dit xvg_show -f distance.xvg \
  -x "Time (ps)" -y "Distance (nm)" \
  -t "Residue Distance"

# 计算平均距离
dit xvg_ave -f distance.xvg -b 2000

# 显示距离分布
dit xvg_show_distribution -f distance.xvg -c 1 \
  -x "Distance (nm)" -t "Distance Distribution"
```

---

## 批量处理和脚本生成

### 场景19：批量生成所有分析的图片

**Windows PowerShell 脚本**：
```powershell
# 定义文件列表
$files = @("md1_rmsd.xvg", "md2_rmsd.xvg", "md3_rmsd.xvg")

# 批量生成 RMSD 图片
foreach ($file in $files) {
    $output = $file -replace ".xvg", ".png"
    dit xvg_show -f $file -x "Time (ps)" -y "RMSD (nm)" -ns -o $output
}

# 批量生成能量图片
$energy_files = @("md1_energy.xvg", "md2_energy.xvg", "md3_energy.xvg")
foreach ($file in $energy_files) {
    $output = $file -replace ".xvg", ".png"
    dit xvg_compare -f $file -c 1,3 -l "LJ" "Coulomb" -ns -o $output
}
```

**Bash 脚本**：
```bash
#!/bin/bash

# 批量生成 RMSD 图片
for file in md*_rmsd.xvg; do
    output="${file%.xvg}.png"
    dit xvg_show -f "$file" -x "Time (ps)" -y "RMSD (nm)" -ns -o "$output"
done

# 批量生成能量图片
for file in md*_energy.xvg; do
    output="${file%.xvg}.png"
    dit xvg_compare -f "$file" -c 1,3 -l "LJ" "Coulomb" -ns -o "$output"
done
```

---

### 场景20：使用 gnuplot 生成高质量图片

**问题**：使用 gnuplot 引擎生成高质量、可定制的图片。

```bash
# 生成 gnuplot 脚本（不显示图片）
dit xvg_show -f rmsd.xvg -eg gnuplot -ns -o rmsd.png

# 这会生成一个 gnuplot 脚本文件
# 可以手动编辑脚本进行进一步定制

# 使用 gnuplot 生成 3D 图
dit xpm_show -f fel.xpm -m 3d -eg gnuplot -ns -o fel_3d.png
```

---

### 场景21：自定义绘图样式

**问题**：自定义 matplotlib 绘图样式以满足特定要求。

**创建样式文件 `dit_mplstyle.mplstyle`**：
```python
## 自定义 matplotlib 样式
axes.labelsize:     14
axes.linewidth:     1.5
xtick.labelsize:    12
ytick.labelsize:    12
lines.linewidth:    2.5
legend.fontsize:    12
font.family:        Arial
font.size:          12
image.cmap:         viridis
figure.dpi:         100
savefig.dpi:        600
```

**使用自定义样式**：
```bash
# 将样式文件放在工作目录，DIT 会自动加载
dit xvg_show -f rmsd.xvg
```

---

## 高级技巧

### 技巧1：组合多种分析

```bash
# 组合 RMSD、Rg 和能量
dit xvg_compare -f rmsd.xvg gyrate.xvg energy.xvg \
  -c 1 1 1 \
  -l RMSD Rg Energy \
  -x "Time (ps)" \
  -t "Multiple Properties"

# 使用散点图显示相关性
dit xvg_show_scatter -f rmsd.xvg -c 0,1 \
  -x "Time (ps)" -y "RMSD (nm)" -t "RMSD vs Time"
```

---

### 技巧2：导出数据用于其他软件

```bash
# 导出 XVG 数据
dit xvg_compare -f rmsd.xvg -c 1 -ns -csv rmsd_data.csv

# 导出 XPM 数据
dit xpm2csv -f fel.xpm -o fel_data.csv

# 导出 XPM 为矩阵格式
dit xpm2dat -f fel.xpm -o fel_data.dat
```

---

### 技巧3：处理大型数据集

```bash
# 只读取部分行（1000-2000 行）
dit xvg_show -f large_rmsd.xvg -b 1000 -e 2001

# 只显示 XPM 的部分区域
dit xpm_show -f large_dssp.xpm -xmin 0 -xmax 100 -ymin 0 -ymax 1000

# 使用步长减少数据点
dit xvg_show -f large_rmsd.xvg -dt 10
```

---

### 技巧4：使用不同的 colormap 突出显示特征

```bash
# 显示对称数据（如 DCCM）
dit xpm_show -f dccm.xpm -cmap coolwarm -zmin -1 -zmax 1

# 显示自由能（高能量红色，低能量蓝色）
dit xpm_show -f fel.xpm -cmap jet_r

# 显示离散数据（如 DSSP）
dit xpm_show -f dssp.xpm -cmap tab10

# 使用渐变 colormap
dit xpm_show -f fel.xpm -cmap viridis
```

---

### 技巧5：生成出版级图片

```bash
# 使用 matplotlib 引擎，调整分辨率
# 编辑 dit_mplstyle.mplstyle，设置 savefig.dpi: 600
# 然后
dit xvg_show -f rmsd.xvg -ns -o rmsd_publication.png

# 使用 gnuplot 生成矢量图
dit xvg_show -f rmsd.xvg -eg gnuplot -ns -o rmsd.eps

# 使用 plotly 生成交互式网页
dit xvg_show -f rmsd.xvg -eg plotly -ns -o rmsd.html
```

---

## 常见问题

### Q1: 如何处理中文路径或文件名？

DuIvyTools 支持中文路径和文件名，但建议使用英文路径以避免编码问题。

```bash
dit xvg_show -f "路径/中文文件名.xvg"
```

---

### Q2: 如何调整图例位置？

使用 `--legend_location` 参数：

```bash
# 图例在图外
dit xvg_show -f rmsd.xvg --legend_location outside

# 图例在图内（默认）
dit xvg_show -f rmsd.xvg --legend_location inside
```

---

### Q3: 如何处理时间单位？

**默认保持原始单位（通常是 ps）**，仅在用户明确要求时转换：

```bash
# 保持原始单位（推荐）
dit xvg_show -f rmsd.xvg -x "Time (ps)"

# 用户明确要求转换为 ns 时
dit xvg_show -f rmsd.xvg -xs 0.001 -x "Time (ns)"
```

**警告**：单位转换时必须同时更新轴标签。

---

### Q4: 如何处理能量单位？

**默认保持原始单位（通常是 kJ/mol）**，仅在用户明确要求时转换：

```bash
# 保持原始单位（推荐）
dit xvg_show -f energy.xvg -c 1 -y "Energy (kJ/mol)"

# 用户明确要求转换为 kcal/mol 时（乘以 0.239）
dit xvg_show -f energy.xvg -c 1 -ys 0.239 -y "Energy (kcal/mol)"
```

---

### Q5: xpm_diff 可以用于 DSSP 吗？

**不可以**。DSSP 是 Discrete 类型（离散），每个像素代表一个状态，不能计算差值。xpm_diff 仅适用于 Continuous 类型（如 DCCM、FEL）。

对于 DSSP 比较，建议使用：
- `xpm_merge` 合并显示两个矩阵
- 分析二级结构含量变化（xvg_show_stack）

Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)