Molecular simulation tools such as GROMACS routinely produce time-series of energies and other observables. To turn this data into publication quality figures a user can either use a (commercial) software package with a graphical user interface, often offering fine control and high-quality output, or write their own code to make plots using a scripting language. In the age of big data and machine learning it is often necessary to generate many graphs, be able to rapidly inspect them, and to make plots for manuscripts. This repository provides plotxvg, a simple Python tool built on the well-known matplotlib plotting library that will generate publication-quality graphics from, for instance, an energy calculation. This will allow users to rapidly and reproducibly generate series of graphics files without programming. Obviously, the tool is applicable to any kind of line graph data, not just that from molecular simulations.
Pip install plotXVG to your current python environment by running
python -m pip install plotxvg
in the command line. Or, if preferred, you can clone this repository by running
git clone https://github.com/AlexandriaChemistry/plotXVG
cd into it and then run
python -m pip install .
Simple as that! In the plotXVG directory you can find a number of showcase illustrations along with descriptive text files found
under tests/plotxvg_tests-output/ and can also easily be generated by running python test.py in the tests folder.
Example xvg-files have been generated by GROMACS and
Alexandria Chemistry Toolkit (ACT), which cen be found in their respective folders.
To use plotXVG, simply type plotxvg -f <filename>.xvg in the command line and it will generate a plot.
Default setting is a scatterplot, if you want to generate a lineplot, add the linestyle flag along with a line argument, such as -ls solid.
In order to use plotXVG in an API, the general call in a python environment looks like this:
import plotxvg
plotxvg.plot(["file1.xvg", "file2.xvg"],
ls=["solid", "dashed"],
panels=True)
Note that boolean flags not in lists such as panels do not need to be strings.
You can also create 2D density plots using either the ´-contour´ or ´-heatmap´ flag! Additionally, you can utilize SciPy's kde for probability density calculations of datasets with few datapoints. Note that you do not require the SciPy package for using the rest of plotXVG's functions.
PlotXVG supports a number of flags, shown below.
For more information on installation, usage and a collection of plotXVG examples, you find the manual in the plotXVG_manual directory.
options:
-h, --help show this help message and exit
-f [FILENAME ...], --filename [FILENAME ...]
Filename(s) to read and plot
-follow, --follow Continuously update the plot by re-reading the input file(s). Use for CLI operations.
-debug, --debug Turn on printing of debugging messages
-font FONTNAME, --fontname FONTNAME
Font for all text.
-allfs ALLFONTSIZES, --allfontsizes ALLFONTSIZES
Scale all font sizes equally, default 0
-axfs AXISLABELFONTSIZE, --axislabelfontsize AXISLABELFONTSIZE
Axis label font size, default 26
-tfs TITLEFONTSIZE, --titlefontsize TITLEFONTSIZE
Title font size, set to zero for no title, default 30
-lfs LEGENDFONTSIZE, --legendfontsize LEGENDFONTSIZE
Legend font size, set to zero for no legend, default 26
-tickfs TICKFONTSIZE, --tickfontsize TICKFONTSIZE
Tick font size, default 24
-ls LINESTYLE [LINESTYLE ...], --linestyle LINESTYLE [LINESTYLE ...]
What kind of line style: solid, dashed, dashdot, dotted
-mk MARKER [MARKER ...], --marker MARKER [MARKER ...]
Use markers for data sets: o, +, x, <, >...
-mksize MARKERSIZE, --markersize MARKERSIZE
Size of filled markers for data sets, default 10
-mkwidth MARKEREDGEWIDTH, --markeredgewidth MARKEREDGEWIDTH
Size of character markers (e.g. +) for data sets, default 2
-colors [COLORS ...], --colors [COLORS ...]
Colors for the plots. Colors defined by the user will be applied to the datasets in order. If there are more datasets than color inputs, default colors will be used.
-save SAVE, --save SAVE
Save plot. Please specify saving location and preferred filetype (.pdf, .png...)
-sqfig, --squarefig Make the figure square
-eqax, --equalaxes Make the plot square with equally large axes
-bar, --bar Make a bar graph
-noshow, --noshow Do not show the figure
-res, --residual Subtract x from y for all data sets - useful for correlation plots
-fl, --filelabel Add the filename to the labels in the plot (may yield long labels)
-logy, --logy Use a log scale on the Y-axis
-xmin XMIN, --xmin XMIN
Minimum value of X-axis. Default = defined by data.
-xmax XMAX, --xmax XMAX
Maximum value of X-axis. Default = defined by data.
-ymin YMIN, --ymin YMIN
Minimum value of Y-axis. Default = defined by data.
-ymax YMAX, --ymax YMAX
Maximum value of Y-axis. Default = defined by data.
-xframe XFRAME, --xframe XFRAME
Width of the plot 100 pixels, default 16
-yframe YFRAME, --yframe YFRAME
Height of the plot 100 pixels, default 9
-panels [{top,side}], --panels [{top,side}]
Generate different panels to plot in, one file per panel. Add 'side' for side-by side panels.
-sfx SUBFIGUREX, --subfigureX SUBFIGUREX
X position of subfigure label when using panels. Default -0.15
-sfy SUBFIGUREY, --subfigureY SUBFIGUREY
Y position of subfigure label when using panels. Default 1.0
-ign [IGNORE ...], --ignore [IGNORE ...]
legends of the series to ignore. Please specify the whole legend label.
-title TITLE [TITLE ...], --title TITLE [TITLE ...]
User-defined title(s). This flag overwrites pre-defined titles. If the user wants to use user-defined titles and pre-defined titles on different panels, use None
as placeholders for predefnied title panels. If the user wants to remove a specific panel title, put an empty string ''.
-notitles, --notitles
Remove all titles (Both user-defined and title pre-defined by data.)
-dslegends [DATASETLEGENDS ...], --datasetlegends [DATASETLEGENDS ...]
Set user-defined legends. If legends are already defined in the input file they are combined for each dataset i.e. '<user-defined legend> <pre-defined legend>'.
-sharelabel, --sharelabel
Show only the x-labels on the last row of plots and the y-labels on the first column of plots (useful if all subplots share the same x- and y-labels)
-legend_x LEGEND_X, --legend_x LEGEND_X
Put the legend box horizontally on this position, default 0.02
-legend_y LEGEND_Y, --legend_y LEGEND_Y
Put the legend box vertically on this position, default 0.98
-stats, --stats Print RMSD and R2 values of datasets (x-axis is reference data and y-axis holds the predicted values)
-colx COLX, --colx COLX
Choose what x column you would like from for example a csv file. Choose only one column. Default is column 1
-coly COLY [COLY ...], --coly COLY [COLY ...]
Choose what y column(s) you would like from for example a csv file. Default is column 3
-v, --version show program's version number and exit
-heatmap, --heatmap 2D heatmap plot
-contour, --contour Contour 2D plot
-cmap COLORMAP, --colormap COLORMAP
Matplotlib colormap
-levels LEVELS, --levels LEVELS
Number of contour levels
-bins BINS, --bins BINS
Number of bins for 2D histogram
-gibbs, --gibbs Calculates Gibbs free energy from probabilty density
-temp TEMPERATURE, --temperature TEMPERATURE
At what temperature to calcuate Gibbs free energy according to G = kBT - log(P).
-kde, --kde Calculate probability density using kernel density estimation (kde). Preferably combined with contour rather than heatmap. OBS! You need the scipy package for this function.
-showdots, --showdots
Choose to show the scattered dots together with kde.