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(*data, units='kT', ax=None)

Plot the forward and backward convergence.

The input could be the result from forward_backward_convergence() or it could be given explicitly as forward, forward_error, backward, backward_error.

forward: A list of free energy estimate from the first X% of data, where forward_error is the corresponding error.

backward: A list of free energy estimate from the last X% of data., where backward_error is the corresponding error.

These four array_like objects should have the same shape and can be used as input for the matplotlib.pyplot.errorbar().

Parameters

  • data (Dataframe or 4 array_like objects) – Output Dataframe from forward_backward_convergence(). Or given explicitly as forward, forward_error, backward, backward_error see plot_convergence.

  • units (str) – The label for the unit of the estimate. Default: “kT”

  • ax (matplotlib.axes.Axes) – Matplotlib axes object where the plot will be drawn on. If ax=None, a new axes will be generated.

Returns

An axes with the forward and backward convergence drawn.

Return type

matplotlib.axes.Axes

Note

The code is taken and modified from Alchemical Analysis.

If data is not an :class:pandas.Dataframe` produced by forward_backward_convergence(), the unit will be adjusted according to the units variable. Otherwise, the units variable is for labelling only. Changing it doesn’t change the unit of the underlying variable.

Changed in version 0.6.0: data now takes in dataframe

New in version 0.4.0.