MBAR

The MBAR estimator is a light wrapper around the reference implementation of MBAR [Shirts2008] from pymbar (pymbar.mbar.MBAR). As a generalization of BAR, it uses information from all sampled states to generate an estimate for the free energy difference between each state.

API Reference

class alchemlyb.estimators.MBAR(maximum_iterations: int = 10000, relative_tolerance: float = 1e-07, initial_f_k: ndarray | Literal['BAR'] | None = 'BAR', method: str = 'robust', n_bootstraps: int = 0, verbose: bool = False)[source]

Multi-state Bennett acceptance ratio (MBAR).

Parameters:

  • maximum_iterations (int, optional) – Set to limit the maximum number of iterations performed.

  • relative_tolerance (float, optional) – Set to determine the relative tolerance convergence criteria.

  • initial_f_k (np.ndarray, float, shape=(K), optional or String BAR) –

    When isinstance(initial_f_k, np.ndarray), initial_f_k will be used as initial guess for MBAR estimator. initial_f_k should be dimensionless free energies. When initial_f_k is None, initial_f_k will be set to 0. When initial_f_k is set to “BAR”, a BAR calculation will be done and the result is used as the initial guess (default).

    Changed in version 2.3.0: The new default is now “BAR” as it provides a substantial speedup over the previous default None.

  • method (str, optional, default="robust") – The optimization routine to use. This can be any of the methods available via scipy.optimize.minimize() or scipy.optimize.root().

  • n_bootstraps (int, optional) – Whether to use bootstrap to estimate uncertainty. 0 means use analytic error estimation. 50~200 is a reasonable range to do bootstrap.

  • verbose (bool, optional) – Set to True if verbose debug output from pymbar is desired.

delta_f_

The estimated dimensionless free energy difference between each state.

Type:

DataFrame

d_delta_f_

The estimated statistical uncertainty (one standard deviation) in dimensionless free energy differences.

Type:

DataFrame

delta_h_

The estimated dimensionless enthalpy difference between each state.

Type:

DataFrame

d_delta_h_

The estimated statistical uncertainty (one standard deviation) in dimensionless enthalpy differences.

Type:

DataFrame

delta_sT_

The estimated dimensionless entropy difference between each state.

Type:

DataFrame, optional

d_delta_sT_

The estimated statistical uncertainty (one standard deviation) in dimensionless entropy differences.

Type:

DataFrame

theta_

The theta matrix.

Type:

DataFrame

states_

Lambda states for which free energy differences were obtained.

Type:

list

Notes

See [Shirts2008] for details of the derivation and cite the paper when using MBAR in published work.

See also

pymbar.mbar.MBAR

Changed in version 1.0.0: delta_f_, d_delta_f_, states_ are view of the original object.

Changed in version 2.0.0: default value for method was changed from “hybr” to “robust”

Changed in version 2.1.0: n_bootstraps option added.

Changed in version 2.4.0: Handle initial estimate, initial_f_k, from bar in the instance that not all lambda states represented as column headers are represented in the indices of u_nk.

Changed in version 2.5.0: Added computation of enthalpy and entropy

__init__(maximum_iterations: int = 10000, relative_tolerance: float = 1e-07, initial_f_k: ndarray | Literal['BAR'] | None = 'BAR', method: str = 'robust', n_bootstraps: int = 0, verbose: bool = False) → None[source]
fit(u_nk: DataFrame, compute_entropy_enthalpy: bool = False) → MBAR[source]

Compute overlap matrix of reduced potentials using multi-state Bennett acceptance ratio.

Parameters:

  • u_nk (DataFrame) – u_nk[n, k] is the reduced potential energy of uncorrelated configuration n evaluated at state k.

  • compute_entropy_enthalpy (bool, optional, default=False) – Compute entropy and enthalpy.

property overlap_matrix: ndarray[tuple[Any, ...], dtype[_ScalarT]]

MBAR overlap matrix.

The estimated state overlap matrix \(O_{ij}\) is an estimate of the probability of observing a sample from state \(i\) in state \(j\).

The overlap_matrix is computed on-the-fly. Assign it to a variable if you plan to re-use it.

See also

pymbar.MBAR.compute_overlap

classmethod __init_subclass__(**kwargs)

Set the set_{method}_request methods.

This uses PEP-487 [1] to set the set_{method}_request methods. It looks for the information available in the set default values which are set using __metadata_request__* class attributes, or inferred from method signatures.

The __metadata_request__* class attributes are used when a method does not explicitly accept a metadata through its arguments or if the developer would like to specify a request value for those metadata which are different from the default None.

References

property d_delta_f_: DataFrame | None
property d_delta_h_: DataFrame | None
property d_delta_sT_: DataFrame | None
property delta_f_: DataFrame | None
property delta_h_: DataFrame | None
property delta_sT_: DataFrame | None
get_metadata_routing()

Get metadata routing of this object.

Please check User Guide on how the routing mechanism works.

Returns:

routing – A MetadataRequest encapsulating routing information.

Return type:

MetadataRequest

get_params(deep=True)

Get parameters for this estimator.

Parameters:

deep (bool, default=True) – If True, will return the parameters for this estimator and contained subobjects that are estimators.

Returns:

params – Parameter names mapped to their values.

Return type:

dict

set_fit_request(*, compute_entropy_enthalpy: bool | None | str = '$UNCHANGED$', u_nk: bool | None | str = '$UNCHANGED$') → MBAR

Configure whether metadata should be requested to be passed to the fit method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the User Guide on how the routing mechanism works.

The options for each parameter are:

  • True: metadata is requested, and passed to fit if provided. The request is ignored if metadata is not provided.

  • False: metadata is not requested and the meta-estimator will not pass it to fit.

  • None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.

  • str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

Added in version 1.3.

Parameters:

  • compute_entropy_enthalpy (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for compute_entropy_enthalpy parameter in fit.

  • u_nk (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for u_nk parameter in fit.

Returns:

self – The updated object.

Return type:

object

set_params(**params)

Set the parameters of this estimator.

The method works on simple estimators as well as on nested objects (such as Pipeline). The latter have parameters of the form <component>__<parameter> so that it’s possible to update each component of a nested object.

Parameters:

**params (dict) – Estimator parameters.

Returns:

self – Estimator instance.

Return type:

estimator instance

property states_: list[Any] | None