Plot the Forward and Backward Convergence

The function plot_convergence() allows the user to visualise the convergence by plotting the free energy change computed using the equilibrated snapshots between the proper target time frames. The data could be provided as a Dataframe from alchemlyb.convergence.forward_backward_convergence() or provided explicitly in both forward (data points are stored in forward and forward_error) and reverse (data points are stored in backward and backward_error) directions.

The unit in the y axis could be labelled to other units by setting units, which by default is \(kT\). The user can pass matplotlib.axes.Axes into the function to have the convergence drawn on a specific axes.

Please check How to plot convergence for usage.

API Reference

alchemlyb.visualisation.plot_convergence(dataframe, units=None, final_error=None, ax=None)

Plot the forward and backward convergence.

The input could be the result from forward_backward_convergence() or fwdrev_cumavg_Rc(). The input should be a pandas.DataFrame which has column Forward, Backward and pandas.DataFrame.attrs should compile with A note on units. The errorbar will be plotted if column Forward_Error and Backward_Error is present.

Forward: A column of free energy estimate from the first X% of data, where optional Forward_Error column is the corresponding error.

Backward: A column of free energy estimate from the last X% of data., where optional Backward_Error column is the corresponding error.

final_error is the error of the final value and is shown as the error band around the final value. It can be provided in case an estimate is available that is more appropriate than the default, which is the error of the last value in Backward.

dataframeDataframe

Output Dataframe has column Forward, Backward or optionally Forward_Error, Backward_Error see plot_convergence.

unitsstr

The unit of the estimate. The default is None, which is to use the unit in the input. Setting this will change the output unit.

final_errorfloat

The error of the final value in units. If not given, takes the last error in backward_error.

axmatplotlib.axes.Axes

Matplotlib axes object where the plot will be drawn on. If ax=None, a new axes will be generated.

matplotlib.axes.Axes

An axes with the forward and backward convergence drawn.

The code is taken and modified from Alchemical Analysis.

Changed in version 1.0.0: Keyword arg final_error for plotting a horizontal error bar. The array input has been deprecated. The units default to None which uses the units in the input.

Changed in version 0.6.0: data now takes in dataframe

Added in version 0.4.0.