DuIvyTools (DIT)

⚠️ CRITICAL: Always check command help before using

DuIvyTools is actively developed. ALWAYS run dit <command> -h to get the most accurate and up-to-date information for any command before using it. This ensures you have the correct parameters and options for your version.

DuIvyTools is a command-line tool for analyzing and visualizing GROMACS molecular dynamics simulation results. It provides ~30 commands for processing XVG, XPM, NDX, and other common GROMACS output files.

Quick Start

Installation

bash

pip install DuIvyTools

Or use Tsinghua mirror (faster in China):

bash

pip install DuIvyTools -i https://pypi.tuna.tsinghua.edu.cn/simple

Verify installation:

bash

dit

Basic Usage

IMPORTANT: Always check command help before using

DuIvyTools is actively developed and parameters may vary between versions. ALWAYS use dit <command> -h to get the most accurate and up-to-date information for any command before using it.

bash

# Get all available commands
dit

# Get global parameters
dit -h

# Get help for specific command (ALWAYS do this first!)
dit <command> -h

For example:

bash

dit xvg_show -h
dit xpm_show -h
dit ndx_add -h

Common Commands

XVG Files (Data Plots)

Command	Description
`xvg_show`	Display XVG data with customizable visualization
`xvg_compare`	Compare multiple XVG files with flexible column selection
`xvg_ave`	Calculate average, std dev, std err for each column
`xvg_show_distribution`	Show data distribution as histogram/PDF/CDF
`xvg_show_stack`	Display stacked area plots for multiple data series
`xvg_show_scatter`	Create scatter plots (2D or 3D with color mapping)
`xvg_box_compare`	Compare distributions using violin and scatter plots
`xvg_combine`	Combine data from multiple XVG files into one
`xvg_ave_bar`	Calculate and display averages across parallel experiments
`xvg_rama`	Draw Ramachandran plots from phi/psi angle data
`xvg_energy_compute`	Calculate protein-ligand interaction energies

XPM Files (Matrix/Heatmaps)

Command	Description
`xpm_show`	Visualize XPM matrices with 4 plotting engines
`xpm2csv`	Convert XPM to CSV format (x, y, value)
`xpm2dat`	Convert XPM to M×N matrix format
`xpm_diff`	Calculate difference between two XPM files
`xpm_merge`	Merge two XPM files diagonally

NDX Files (Index Groups)

Command	Description
`ndx_add`	Add new index groups to NDX file
`ndx_split`	Split one index group into multiple groups
`ndx_show`	Display all index group names

Other Utilities

Command	Description
`mdp_gen`	Generate GROMACS MDP file templates
`show_style`	Display/generate plotting style configuration files
`find_center`	Find geometric center of atom groups
`dccm_ascii`	Convert ASCII covariance matrix to DCCM XPM
`dssp`	Convert GROMACS 2023 DSSP format to XPM/XVG

Key Concepts

Units and Data Conversion

⚠️ CRITICAL: Always verify data units before visualization

•GROMACS default units: Time = picoseconds (ps), Distance = nanometers (nm), Energy = kJ/mol
•XVG/XPM files may use different units: Always check the file header comments to verify the actual units
•DO NOT convert units by default: Preserve the original units unless the user explicitly requests conversion
•Unit conversion parameters: -xs, -ys, -zs (multiply) and -xp, -yp, -zp (add offset)
•Conversion safety: When converting units, ALWAYS update the corresponding axis labels to match
•
Common mistakes to avoid:
- •Using -xs 0.001 to convert ps→ns but keeping xlabel as "Time (ps)"
- •Applying time conversion to non-time data (e.g., residue numbers, PC values)
- •Converting energy values without proper understanding of the conversion factor

Recommended workflow:

•Read the XVG/XPM file header to identify units
•Visualize data with original units first
•Only apply unit conversion when explicitly requested by user
•When converting, ensure both data AND labels are updated consistently

Column and Row Indexing

•Columns: 0-based indexing (0 = first column)
•Rows: 0-based indexing (0 = first row)
•Atom indices (NDX): 1-based (GROMACS convention)
•Ranges: Left-closed, right-open (e.g., 1-7 means columns 1,2,3,4,5,6)

Common Parameters

Input/Output:

•-f INPUT [INPUT ...] - Input files (space-separated groups, comma-separated within groups)
•-o OUTPUT - Output file name
•-ns - Don't display figure (useful for batch processing)

Column Selection:

•
-c COLUMNS [COLUMNS ...] - Select columns (0-based)
- •Example: -c 1-7,10 0,1,4 = first file: cols 1-6 + col 10; second file: cols 0,1,4

Data Range:

•-b BEGIN - Start row (inclusive)
•-e END - End row (exclusive)
•-dt DT - Step size (default 1)

Labels:

•-l LEGENDS [LEGENDS ...] - Legend labels (match number of selected columns)
•-x XLABEL, -y YLABEL, -z ZLABEL - Axis labels
•-t TITLE - Figure title
•Supports LaTeX: "$\Delta G_{energy}$"

Data Transformation:

•-xs, -ys, -zs - Multiply data by factor (default 1.0)
•-xp, -yp, -zp - Add offset (default 0.0)

⚠️ WARNING: Use transformation parameters carefully. Always verify that:

•The transformation is appropriate for the data type (e.g., time, energy, distance)
•The axis labels are updated to reflect the transformation
•The transformation factor is correct for the unit conversion
•The transformation does not distort scientific interpretation

Plotting:

•-eg {matplotlib,plotly,gnuplot,plotext} - Plotting engine (default: matplotlib)
•-cmap COLORMAP - Color map (matplotlib/plotly)
•-smv [{,CI,origin}] - Show moving average (with CI or origin background)
•-ws WINDOWSIZE - Moving average window size (default 50)
•--alpha ALPHA - Transparency
•-csv CSV - Export data to CSV

Plotting Engines

•matplotlib (default): Most comprehensive, supports all modes and parameters. Default choice when no specific engine is requested by users.
•plotly: Interactive plots suitable for web server integration and interactive dashboards.
•gnuplot: Requires gnuplot installation, generates scripts for external rendering.
•plotext: Terminal-based, for simple quick plots

XPM Visualization Modes

•imshow (matplotlib default): Fast image display
•pcolormesh: Grid-based visualization
•3d: 3D surface plots
•contour: Contour plots

Usage Patterns

Analyze Single XVG File

bash

# Simple display
dit xvg_show -f rmsd.xvg

# With labels (preserving original units)
dit xvg_show -f rmsd.xvg -x "Time (ps)" -y "RMSD (nm)" -t "RMSD Analysis"

# Convert ps to ns (ONLY when explicitly requested)
dit xvg_show -f rmsd.xvg -xs 0.001 -x "Time (ns)"

Compare Multiple Files

bash

# Compare two files, different columns
dit xvg_compare -f rmsd.xvg gyrate.xvg -c 1 1,2 \
  -l RMSD Gyrate Gyrate_X -x "Time (ps)"

# With moving average
dit xvg_compare -f energy.xvg -c 1,3 -l "LJ(SR)" "Coulomb(SR)" -smv

# Export to CSV
dit xvg_compare -f rmsd.xvg -c 1 -ns -csv rmsd_data.csv

Visualize XPM Matrix

bash

# Basic display
dit xpm_show -f dssp.xpm

# 3D mode
dit xpm_show -f fel.xpm -m 3d -x PC1 -y PC2 -z Energy -t FEL

# Contour plot
dit xpm_show -f dccm.xpm -m contour -cmap coolwarm -zmin -1 -zmax 1

# Crop region (pixels)
dit xpm_show -f dssp.xpm -xmin 100 -xmax 200 -ymin 500 -ymax 1000

# Interactive plotly
dit xpm_show -f fel.xpm -eg plotly -m 3d

Statistical Analysis

bash

# Calculate averages (rows 2000 to end)
dit xvg_ave -f rmsd.xvg -b 2000

# Show distribution
dit xvg_show_distribution -f gyrate.xvg -c 1,2

# PDF/CDF
dit xvg_show_distribution -f gyrate.xvg -c 1,2 -m pdf

Manipulate NDX Files

bash

# Show all groups
dit ndx_show -f index.ndx

# Add new group (residues 1-10)
dit ndx_add -f index.ndx -o test.ndx -al lig -c 1-10

# Split group into 2
dit ndx_split -f index.ndx -al Protein 2

Generate MDP Template

bash

dit mdp_gen -o nvt.mdp

Advanced Topics

Custom Plotting Styles

DuIvyTools supports custom plotting styles for all four plotting engines. Use the show_style command to generate style configuration files:

bash

# Generate default matplotlib style file (dit_mplstyle.mplstyle)
dit show_style

# Generate plotly style file
dit show_style -eg plotly

# Generate gnuplot style file
dit show_style -eg gnuplot

# Save to custom filename
dit show_style -eg plotly -o DIT_plotly.json

How it works:

•Run dit show_style to generate the default style file in your working directory
•Modify the generated style file according to your preferences
•DIT automatically loads the style file from the working directory when executing commands

Matplotlib example (dit_mplstyle.mplstyle):

dit_mplstyle.mplstyle

## Matplotlib style for DuIvyTools
axes.labelsize: 12
axes.linewidth: 1
xtick.labelsize: 12
ytick.labelsize: 12
lines.linewidth: 2
legend.fontsize: 12
legend.loc: best
font.family: Arial
font.size: 12
image.cmap: coolwarm
figure.dpi: 100
savefig.dpi: 300

For detailed matplotlib customization, see: https://matplotlib.org/stable/tutorials/introductory/customizing.html

Other engines:

•plotly: JSON-based configuration (DIT_plotly.json)
•gnuplot: Script-based configuration (DIT_gnuplot.plt)
•plotext: Minimal terminal-based styling

Batch Processing

bash

# Generate multiple plots
for file in md*_rmsd.xvg; do
  dit xvg_show -f "$file" -ns -o "${file%.xvg}.png"
done

Interpolation

bash

# Linear interpolation, 10x
dit xpm_show -f fel.xpm -ip linear -ipf 10

# Bicubic (matplotlib imshow)
dit xpm_show -f fel.xpm -m imshow -ip bicubic

Important Notes

Installation Requirements

•Python 3.6+
•matplotlib (default)
•numpy, pandas

Optional Dependencies

•pip install plotly - For interactive plots
•Install gnuplot - For gnuplot engine
•pip install plotext - For terminal plots

Column Indexing

•Always 0-based for XVG/XPM columns and rows
•1-based for NDX atom indices (GROMACS convention)
•-e parameter is exclusive (not included in calculation)

Data Selection

bash

# Select columns 1-6 and column 10
dit xvg_show -f rmsd.xvg -c 1-7,10

# Rows 100-199 (every 2nd row)
dit xvg_show -f rmsd.xvg -b 100 -e 200 -dt 2

LaTeX Support

bash

dit xvg_show -f energy.xvg -l "$\Delta G_{binding}$" -x "Time ($ns$)"

When to Use This Skill

Use DuIvyTools when you need to:

•Visualize XVG data: RMSD, RMSF, energy, hydrogen bonds, gyrate, etc.
•Analyze XPM matrices: DCCM, FEL, DSSP secondary structure, contact maps
•Process NDX files: Add/split/show index groups
•Calculate statistics: Averages, distributions, correlations
•Generate plots: Line, scatter, violin, stacked, 3D, contour, heatmaps
•Batch process: Multiple simulation results with consistent styling
•Export data: Convert to CSV/DAT for other software

Reference Documentation

For detailed information, consult these references:

•Installation & Configuration - Installation methods, plotting engine setup, custom styles
•Commands Reference - Complete documentation for all commands, parameters, and options
•Usage Examples - Real-world scenarios and complete workflows

Get Help

bash

# All commands
dit

# Global parameters
dit -h

# Specific command
dit xvg_show -h
dit xpm_show -h
dit ndx_add -h

duivytools-skills

DuIvyTools (DIT)

Quick Start

Installation

Basic Usage

Common Commands

XVG Files (Data Plots)

XPM Files (Matrix/Heatmaps)

NDX Files (Index Groups)

Other Utilities

Key Concepts

Units and Data Conversion

Column and Row Indexing

Common Parameters

Plotting Engines

XPM Visualization Modes

Usage Patterns

Analyze Single XVG File

Compare Multiple Files

Visualize XPM Matrix

Statistical Analysis

Manipulate NDX Files

Generate MDP Template

Advanced Topics

Custom Plotting Styles

Batch Processing

Interpolation

Important Notes

Installation Requirements

Optional Dependencies

Column Indexing

Data Selection

LaTeX Support

When to Use This Skill

Reference Documentation

Get Help

Citation

Resources