GMXvg 0.4.6

A tool to plot GROMACS .xvg files.

> Get older binaries for Ubuntu and Windows here -> [GMXvg v0.3](https://github.com/TheBiomics/GMXvg/releases/tag/v0.3) .

GMXvg: Utility to Convert/Plot GROMACS XVG files (#xmgrace)

• Commandline based GROMACS XVG File plotting utility.
• Discovers all the XVG files in the current or subdirectories and converts them in specified file formats (default JPG).
• Logs the summary of plots in a file (CSV file) to quickly access the plot values along with their standard deviation values.
• This tool may be an alternative to xmgrace.

Supported Platforms

The utility was developed and tested for following OS. However, we expect it to work on all windows and linux environment.

Easy to install and use

Install using pypi or other directly from source using python's pip module:

• Install using: pip install gmxvg
• Check Version: gmxvg --version
• Usage:
  • Switch to the directory where XVG files are located cd <xvg-file-directory
  • Run xvg
  • See further instructions to modify title, legends, or other outputs

Command Structure

• gmxvg --<key>=<value>: Double dash separated by equal sign
• gmxvg -<key> <val1> <val2> <val3> Single dash (single dash is not recommended) and multiple values

Supported overriding variables

Use gmxvg -h to see all options.

• path_base: Base path if running from different directory
• csv_filename: File name for CSV output else default will be used
• csv_filepath: Path where CSV output file will be stored
• path_move: Path where generated images will be moved (will be deleted from the dir where XVG are stored)
• path_copy: Path where generated images will be copied (source graphics will be there)
• pattern_xvg: Pattern to specify XVG images for conversion e.g., --new.xvg, old--temp-300.xvg
• merge_patterns: Pattern to select XVGs to group their output e.g., Protein-*-RMSD.xvg
• export_ext: Type of outputs, e.g., JPEG, PNG, JPG, PDF (Anything supported by Matplotlib)
• dpi: Resolution of the output, e.g., 72 for quick visualisation and 600 for many publications
• flag_plot_mean: yes|no; Use yes to enable plotting average line
• flag_plot_std: yes|no; Use yes to enable plotting standard deviation lines
• flag_export_csv: yes|no; If results should be exported in the form of CSV (includes directory name, file name, average of lines plotted and their standard deviation)
• flag_export_plot: yes|no; To specify if graphics should be exported or not

Exe Files (download and go solution!)

• Download GMXvg executable file (Windows 10/11) (or check latest or compatible executable for improved features) and copy/paste the exe file in the directory where XVG is contained. It will discover all xvg extension files in current or child folders and process them automatically.
• After execution all xvgs will be converted to jpg. For example, "rmsd-protein.xvg" will be converted to "rmsd-protein.dpi300.jpeg".
• After execution a CSV file containing mean and standard deviation of of the plotted lines in each xvg. For example, for gyration plot "gyration.xvg", the CSV file will show following columns
  • dir: where xvg was stored
  • file: name of the processed xvg file
  • plot: label of the plotted line
  • mean: Mean of the plotted line
  • std: Standard deviation for the plotted line
• Example result output

• To obtain customised output or results see commandline operations and customisation section.

Example Commands (using source code or executable file)

The utility finds *.xvg files in a directory or sub-directory. It need not to specify a file. This utility is made for bulk conversion of XVG files and extract the results in a separate directory.

Simple (directly opening gxmvg executable file)

This will discover XVG files in the subdirectory where gmxvg executable is present and plot XVG in JPEG Format

• gmxvg

Custom options using commandline

• gmxvg -b <path-to-dir-containing-xvg-files>

Generate multiple qualities of graphics

• gmxvg --dpi 96 300 600 --path_copy <path-to-aggregate-results-outside>

Export in multiple format(s)

• gmxvg --export_ext JPEG pdf

Other customisations and advance functions

• To merge multiple xvg files having ending (e.g., /complex1/lig.xvg, /complex2/lig.xvg, /complex3/lig.xvg) passed to -merge_patterns RMSD.xvg so that it will combine all to plot one file. --uid_part -1 parameter can be useful to define the Legend of the merged graphs.

gmxvg --dpi 96 -merge_patterns RMSD-of-Ligand.xvg RMSD-of-Protein-C-Alpha.xvg Gyration-of-Protein.xvg NPT-Temperature.xvg Inter-Ligand-Protein-H-Bonds.xvg --replacements "Receptor1--Lig2":p53-miR5 "Recptor2--Lig3":p53-miR3 --path_move <path-to-output-dir>/graphs

• Example to merge Protein-RMSD.xvg and Ligand-RMSD.xvg files in the same directory. gmxvg -merge_patterns RMSD.xvg -uid_part -1

• Use -replacements options to replace any text in the plot will change the labels and legends of the plot

Development

• To make any changes, fork this repository
• To contribute, create a pull request after you fork or comment

Development and Testing to Create Executable Files

• python -m venv <path-to>-env for Windows and sudo apt-get install python3.8-venv for Ubuntu
• Install missing packages
• <path-to>-env/Scripts/activate for Windows and source <path-to>-env/bin/activate for Ubuntu
• pip install pyinstaller
• pyinstaller gmxvg --onefile

Future Plans

• GUI or web interface through local server for interactive visualisation
• Edit labels or text for invidiual graphs through GUI
• Small executable size
• Fast Executable
• Webserver to convert and combine graphs

Accessory Details

• We recommend you going through the code to access the precision and quality of the generated results before you use.
• The code is free to be used by students, scholars, and professors.
• Version 0.4 details
  • DOI: doi:10.5281/zenodo.7395525
  • Authors: Vishal Kumar Sahu and Dr. Soumya Basu
  • Title: GMXvg: GROMACS XVG Graph Plotting Tool Version 0.4
  • Month & Year: December, 2022
  • Published on: Zenodo

Troubleshooting installation

• Use pip cache purge in case of installation issue