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")

Config-driven trimming#

analysis_start_step in SimulationConfig (set via fe_sim.analysis_start_step) controls how much of each FE window is ignored before MBAR runs. The orchestrator passes that value into record writers so downstream consumers (CLI, notebooks) can respect the same cutoff. analysis_range is deprecated and rejected at load time; use analysis_start_step instead. To mirror the config in standalone scripts, set start_step when instantiating MBARAnalysis:

analysis = MBARAnalysis(..., start_step=sim_cfg.analysis_start_step)
analysis.run_analysis()

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.

RBFE SFC Correction#

batter.analysis.cycle_closure applies state-function based free-energy correction (SFC/WSFC) to RBFE networks. It accepts BATTER/Cinnabar-style edge tables with labelA, labelB, calc_DDG, and calc_dDDG columns, or whitespace-delimited SFC-style input files.

Minimal example:

from batter.analysis.cycle_closure import cycle_closure_from_dataframe

result = cycle_closure_from_dataframe(
    edge_summary,
    reference="LIG_A",
    reference_free_energy=-8.3,
)
print(result.node_results)
print(result.edge_results)