Analysis Toolkit#

BATTER ships with an analysis package that focuses on post-processing ABFE/ASFE outputs with MBAR and alchemlyb, validating replica-exchange logs. This page summarises the most common entry points so you can reuse them in notebooks or bespoke pipelines.

Component Free-Energy Analysis#

batter.analysis.analysis.MBARAnalysis encapsulates the workflow of collecting AMBER window energies, trimming equilibration, and running an alchemlyb MBAR estimator.

Key capabilities:

  • Deterministic caching – reduced potentials are written to <lig_folder>/Results/<component>_df_list.pickle and re-used when load=True.

  • Equilibration detection – each window can be truncated using pymbar.timeseries.detect_equilibration() by setting detect_equil=True.

  • Convergence summaries – MBAR diagnostics (forward/backward convergence, block averages, window overlap) are stored alongside the analysis object and can be plotted via helper methods such as MBARAnalysis.plot_convergence().

Minimal example:

from batter.analysis.analysis import MBARAnalysis

analysis = MBARAnalysis(
    lig_folder="work/adrb2/simulations/LIG1",
    component="e",
    windows=list(range(21)),
    temperature=310.0,
    energy_unit="kcal/mol",
    detect_equil=True,
)
analysis.run_analysis()
print(analysis.fe, "+/-", analysis.fe_error)
analysis.plot_convergence(save_path="lig1_e_convergence.png")

Handling Restrained Components#

RESTMBARAnalysis extends MBARAnalysis for the restraint components (a, l, t, c, r, m, n). It reads the window-specific disang.rest files, extracts cpptraj restraint traces, and converts them into reduced potentials before running MBAR. Use it exactly like MBARAnalysis; the class automatically detects the additional files it needs.

Replica-Exchange Diagnostics#

batter.analysis.remd.RemdLog provides a lightweight parser for AMBER remlog files. Instantiate it with the logfile path and call RemdLog.analyze() to obtain round-trip statistics and neighbour acceptance ratios. You can also poke at RemdLog.replica_trajectory to produce custom plots.

For quick visual checks, call batter.analysis.remd.plot_trajectory(), which renders either a single combined plot or a grid of per-replica subplots.