a3fe.analyse.detect_equil

Functions for detecting equilibration based on an ensemble of simulations.

Functions

`check_equil_block_gradient`(lam_win, run_nos)	Check if the ensemble of simulations at the lambda window is equilibrated based on the ensemble gradient between averaged blocks.
`check_equil_chodera`(lam_win[, run_nos])	Check if the ensemble of simulations at the lambda window is equilibrated based Chodera's method of maximising the number of uncorrelated samples.
`check_equil_multiwindow`(lambda_windows, ...)	Check if a set of lambda windows are equilibrated based on the ensemble gradient of the free energy change.
`check_equil_multiwindow_gelman_rubin`(...[, ...])	Run the Gelman-Rubin test individually on each lambda window to check for convergence and plot the results.
`check_equil_multiwindow_kpss`(lambda_windows, ...)	Check if a set of lambda windows are equilibrated based on the KPSS test for stationarity.
`check_equil_multiwindow_modified_geweke`(...)	Check if a set of lambda windows are equilibrated based on a modified version of the Geweke test (https://ideas.repec.org/p/fip/fedmsr/148.html).
`check_equil_multiwindow_paired_t`(...[, ...])	Check if a set of lambda windows are equilibrated based on a paired t-test between the average of each run over the first 10 % and last 50 % of the data.
`dummy_check_equil_multiwindow`(lam_win[, run_nos])	Becuse "check_equil_multiwindow" checks multiple windows at once and sets the _equilibrated and _equil_time attributes of the lambda windows, but a3fe was written based on per-window checks, we need a dummy function which just reads the attributes of the lambda window and assumes that they have already been set by "check_equil_multiwindow".
`get_gelman_rubin_rhat`(lambda_window[, ...])	Run the Gelman-Rubin test, as implemented in Arviz, to check for convergence (https://python.arviz.org/en/stable/api/generated/arviz.rhat.html).

a3fe.analyse.detect_equil.check_equil_block_gradient(lam_win: LamWindow, run_nos: List[int] | None) → Tuple[bool, float | None][source]

Check if the ensemble of simulations at the lambda window is equilibrated based on the ensemble gradient between averaged blocks.

Parameters:

lam_win (LamWindow) – Lambda window to check for equilibration.
run_nos (List[int], Optional, default: None) – The run numbers to use for MBAR. If None, all runs will be used.

Returns:

equilibrated (bool) – True if the simulation is equilibrated, False otherwise.
equil_time (float) – Time taken to equilibrate per simulation, in ns.

a3fe.analyse.detect_equil.check_equil_multiwindow_modified_geweke(lambda_windows: List[LamWindow], output_dir: str, run_nos: List[int] | None = None, first_frac: float = 0.1, last_frac: float = 0.5, intervals: int = 4, p_cutoff: float = 0.2) → Tuple[bool, float | None][source]

Check if a set of lambda windows are equilibrated based on a modified version of the Geweke test (https://ideas.repec.org/p/fip/fedmsr/148.html). Instead of using the original Geweke test on the cumulative timeseries of the free energy change where the variances are derived from spectral variance estimates from the single trace, we apply the Geweke test to the cumulative timeseries of the free energy change where the variances are derived from the inter-run uncertainties, assuming Gaussian distributions.

the Geweke test in Arviz (https://github.com/arviz-devs/arviz)

Parameters:

lambda_windows (List[LamWindow]) – List of lambda windows to check for equilibration.
output_dir (str) – Directory to write output files to.
run_nos (List[int], Optional, default: None) – The run numbers to use. If None, all runs will be used.
first_frac (float, default: 0.1) – The fraction of the simulation to use for the first part of the Geweke test. Defaults to original recommendation of using the first 10% of the data.
last_frac (float, default: 0.5) – The fraction of the simulation to use for the last part of the Geweke test. Defaults to original recommendation of using the last 50% of the data. This is taken as backwards from the end of the simulation, e.g. if last_frac = 0.3, the last 30% of the simulation will be used. This is also gives the maximum fraction of the simulation to discard when repeatedly discarding data from the start of the simulation and checking for convergence.
intervals (int, default: 4) – The number of equidistant starting fractions between 0 and 1 - last_frac for which to perform the Geweke test, discarding the starting fraction of the data.
p_cutoff (float, default: 0.2) – The p value cutoff for the Geweke test. If the p value is greater than this, the null hypothesis that the data is stationary is accepted and the data is considered equilibrated. A conservative value of 0.4 is used to increase the power of the test, at the expense of a higher false positive rate.

returns:

equilibrated (bool) – True if the set of lambda windows is equilibrated, False otherwise.
fractional_equil_time (float) – Time taken to equilibrate, as a fraction of the total simulation time.

a3fe.analyse.detect_equil.check_equil_multiwindow_paired_t(lambda_windows: List[LamWindow], output_dir: str, run_nos: List[int] | None = None, first_frac: float = 0.1, last_frac: float = 0.5, intervals: int = 4, p_cutoff: float = 0.05) → Tuple[bool, float | None][source]

Check if a set of lambda windows are equilibrated based on a paired t-test between the average of each run over the first 10 % and last 50 % of the data.

Parameters:

lambda_windows (List[LamWindow]) – List of lambda windows to check for equilibration.
output_dir (str) – Directory to write output files to.
run_nos (List[int], Optional, default: None) – The run numbers to use. If None, all runs will be used.
first_frac (float, default: 0.1) – The fraction of the simulation to use for the first part of the t-test. Defaults to original recommendation of using the first 10% of the data.
last_frac (float, default: 0.5) – The fraction of the simulation to use for the last part of the t-test. Defaults to original recommendation of using the last 50% of the data. This is taken as backwards from the end of the simulation, e.g. if last_frac = 0.3, the last 30% of the simulation will be used. This is also gives the maximum fraction of the simulation to discard when repeatedly discarding data from the start of the simulation and checking for convergence.
intervals (int, default: 4) – The number of equidistant starting fractions between 0 and 1 - last_frac for which to perform the paired t-test, discarding the starting fraction of the data.
p_cutoff (float, default: 0.05) – The p value cutoff for the test. If the p value is greater than this, the null hypothesis that the data is stationary is accepted and the data is considered equilibrated. A conservative value of 0.4 is used to increase the power of the test, at the expense of a higher false positive rate.

Returns:

equilibrated (bool) – True if the set of lambda windows is equilibrated, False otherwise.
fractional_equil_time (float) – Time taken to equilibrate, as a fraction of the total simulation time.

a3fe.analyse.detect_equil.dummy_check_equil_multiwindow(lam_win: LamWindow, run_nos: List[int] | None = None) → Tuple[bool, float | None][source]

Becuse “check_equil_multiwindow” checks multiple windows at once and sets the _equilibrated and _equil_time attributes of the lambda windows, but a3fe was written based on per-window checks, we need a dummy function which just reads the attributes of the lambda window and assumes that they have already been set by “check_equil_multiwindow”.

Parameters:

lam_win (LamWindow) – Lambda window to check for equilibration (ignored in practice)
run_nos (List[int], Optional, default: None) – Ignored in practice, but included for consistency.

Returns:

equilibrated (bool) – True if the simulation is equilibrated, False otherwise.
equil_time (float) – Time taken to equilibrate per simulation, in ns.

a3fe.analyse.detect_equil.get_gelman_rubin_rhat(lambda_window: LamWindow, discard_frac: float = 0.1, run_nos: List[int] | None = None) → float[source]

Run the Gelman-Rubin test, as implemented in Arviz, to check for convergence (https://python.arviz.org/en/stable/api/generated/arviz.rhat.html). Note that this test should not be used on block-averaged results, as Rhat is related to the effective sample size, which is affected by block averaging. See references given in Arviz documentation for more details (link above).

Parameters:

lambda_window (LamWindow) – Lambda window to check for equilibration.
discard_frac (float, default: 0.1) – Fraction of the simulation to discard as burn-in.
run_nos (List[int], Optional, default: None) – The run numbers to use. If None, all runs will be used.

Returns:

rhat – Gelman-Rubin statistic.

Return type:

float