Results Folder Layout ===================== BATTER writes portable analysis outputs under:: /results/ This tree is separate from ``executions//``. The execution directory holds the live working files for a run, while ``results/`` stores the analysis products that are meant to be queried later with ``batter fe`` or copied elsewhere. Top-Level Layout ---------------- A typical results tree looks like:: results/ ├── index.csv └── / ├── / │ ├── record.json │ ├── Results/ │ ├── Equil/ │ └── ... └── / The exact per-ligand contents depend on whether the record succeeded, failed, or came from an RBFE transformation. ``index.csv`` ------------- ``results/index.csv`` is the repository-wide summary table used by ``batter fe list``. Each row corresponds to one saved FE record and includes fields such as: * ``run_id`` and ``ligand`` * ``mol_name`` and ``system_name`` * ``temperature`` * ``total_dG`` and ``total_se`` * ``canonical_smiles``, ``original_name``, and ``original_path`` when available * ``protocol`` * ``analysis_start_step`` and ``n_bootstraps`` * ``status`` and ``failure_reason`` * ``created_at`` When BATTER saves the same ``(run_id, ligand, analysis_start_step, n_bootstraps)`` combination again, the row is replaced rather than duplicated. Successful Record Directory --------------------------- For a successful result, BATTER writes:: results/// ├── record.json ├── Results/ └── Equil/ # ABFE / ASFE / single-ligand runs ``record.json`` Portable structured summary of the FE result. This is what ``batter fe show`` loads. ``Results/`` Copy of the raw analysis folder from ``executions//.../fe/Results``. Common files include: * ``Results.dat`` with total and per-component FE values * ``fe_timeseries.json`` and ``fe_timeseries.png`` * ``_results.json`` * ``_convergence.png`` * ``_df_list_attrs.json`` * ``_df_list.pickle`` ``Results.dat`` Plain-text summary table with one line per analyzed component plus a final ``Total`` row. Each line stores ``LABEL FE SE``. ``fe_timeseries.json`` and ``fe_timeseries.png`` Overall progress diagnostic for the assembled FE estimate. The JSON file stores the cumulative FE value and uncertainty arrays across increasing fractions of the trajectory. The PNG plots those values against simulation progress, adds error bars, and overlays the final FE estimate as a dashed reference line with a shaded ``±1 kcal/mol`` band. ``_results.json`` Per-component scalar summary written by the MBAR analysis stage. It stores the final FE value, its uncertainty, and the component-level FE timeseries used to build the overall summary. ``_convergence.png`` Three-panel convergence diagnostic for one FE component. BATTER plots: * **Time Convergence**: forward/backward FE estimates as increasing fractions of the trajectory are included * **Overlap Matrix**: MBAR state overlap between neighboring windows * **Block Convergence**: FE estimates from block-averaged chunks of the data These plots are intended for checking whether a component is equilibrated, whether adjacent windows overlap adequately, and whether the estimate is stable to block partitioning. ``_df_list.pickle`` Python pickle cache containing the list of alchemlyb-style reduced-potential DataFrames, one per lambda window, that MBAR consumes. BATTER writes this file so repeated analysis or notebook-based debugging can reload the parsed data without re-reading all AMBER outputs. ``_df_list_attrs.json`` Sidecar metadata for the pickle cache. It records the component name, temperature, analysis start step, whether automatic equilibration detection was enabled, the sampling interval, and the number of frames retained per window. ``Equil/`` Selected equilibration artifacts copied for reference. Common files include: * ``README.txt`` describing the copied artifacts * ``equilibration_analysis_results.npz`` * ``simulation_analysis.png`` * ``dihed_hist.png`` * ``representative.pdb`` * ``representative_complex.pdb`` * ``representative_pose.pdb`` * ``initial_pose.pdb`` * ``initial_complex.pdb`` * ``.sdf``, ``.prmtop``, and ``.pdb`` when present Failure or Unbound Record Directory ----------------------------------- If BATTER cannot extract totals from the analysis outputs, or if a ligand is marked failed/unbound, it still creates a per-ligand directory:: results/// ├── failure.json ├── Results/ # only when raw analysis outputs exist to copy └── Equil/ # or Equil_ref / Equil_alt for RBFE ``failure.json`` stores the status and reason string. The matching ``index.csv`` row has ``status = failed`` or ``status = unbound`` and leaves FE totals empty. If a later rerun succeeds, BATTER removes the stale ``failure.json`` before writing the new ``record.json``. RBFE-Specific Additions ----------------------- RBFE records use the same top-level pattern, but the payload is slightly different:: results/// ├── record.json ├── Results/ │ ├── Results.dat │ ├── rbfe_network.png │ ├── mapping.json │ ├── mapping.pkl │ └── mapping.png ├── Equil_ref/ └── Equil_alt/ ``Results/rbfe_network.png`` Copy of the resolved RBFE network plot from ``executions//artifacts/config/rbfe_network.png``. ``Results/mapping.*`` Atom-mapping artifacts copied from the transformation setup directory. ``Equil_ref/`` and ``Equil_alt/`` Equilibration reference material for the two ligands that define the transformation pair. How to Read the Repository -------------------------- The main CLI entry points for this tree are: .. code-block:: bash batter fe list batter fe show --ligand ``fe list`` reads ``results/index.csv`` and prints one row per stored record. ``fe show`` opens ``record.json`` for a single record. Derived Cinnabar Exports ------------------------ The portable FE repository above is BATTER's canonical stored-results layer. For one work directory, the optional command:: batter fe cinnabar writes an additional derived export tree under:: /results/cinnabar/ This tree is not used by BATTER's core FE record loader. It is a convenience export layer for downstream Cinnabar notebooks, figures, and benchmarking workflows. For production benchmarking across different BATTER work directories, pass each run as an atomic ``--run WORK_DIR RUN_ID`` input and choose an output directory:: batter fe cinnabar \ --run work/adrb2 rep1 \ --run work/adrb2_retry rep2 \ --out-dir combined_cinnabar If explicit ``--run`` inputs come from multiple work directories and ``--out-dir`` is omitted, BATTER writes to ``./cinnabar``. A combined export typically looks like:: results/ ├── index.csv ├── / │ └── ... └── cinnabar/ ├── manifest.json ├── raw_signed.csv ├── edge_summary.csv ├── cinnabar_relative.csv ├── cinnabar_absolute.csv # when the network is connected ├── cinnabar_absolute_sorted.png ├── cinnabar_network.png ├── cinnabar_dg.png # when experiment is provided └── cinnabar_ddg.png # when experiment is provided When ``--split-runs`` is used with the same-work-dir command form, BATTER writes one subdirectory per run instead:: results/cinnabar// ``raw_signed.csv`` Measurement-level table after BATTER filters to RBFE rows, resolves the edge label, and assigns a sign convention based on sorted ligand names. ``edge_summary.csv`` Edge-level DDG estimates after repeat combination. This is the main table to inspect when you want one summarized value per perturbation. ``cinnabar_relative.csv`` Relative measurements exported from the constructed ``FEMap``. ``cinnabar_absolute.csv`` MLE-derived absolute values from Cinnabar. BATTER writes this only when the RBFE network is connected strongly enough for Cinnabar to solve absolute values. ``cinnabar_absolute_sorted.png`` BATTER-rendered ranking plot of the computed absolute free energies, sorted by energy and drawn with horizontal uncertainty bars. When ``--absolute-offset`` is used, BATTER applies that constant shift to the plotted computational energies and records the offset in ``manifest.json``. ``manifest.json`` Lightweight summary of what BATTER wrote, including whether experimental data was merged, whether absolute values were successfully generated, and the absolute offset used for the ranked absolute-energy plot. Where This Differs From ``executions/`` --------------------------------------- ``executions//`` is the working directory for an active or completed run. It contains staged inputs, Slurm scripts, logs, raw trajectories, and in-progress markers. ``results/`` is the compact, portable summary layer derived from those executions. If you only need final FE values plus the most important analysis artifacts, this is usually the tree to archive or inspect first. Visualizing Trajectories ------------------------ The portable ``results/`` repository does not duplicate the production trajectories. For molecular visualization, go back to the matching directory under ``executions//`` and open the staged coordinate and trajectory files there. For equilibration trajectories, a common workflow is: .. code-block:: bash vmd full.pdb md-*.nc Then load ``full.prmtop`` inside VMD to recover bonded information. For FE production trajectories, inspect one window at a time from the corresponding component directory. BATTER stores these trajectories without water, so a common workflow is: .. code-block:: bash vmd vac.pdb md-*.nc Then load ``vac.prmtop`` inside VMD to recover bonded information. ``vac.pdb`` also uses 1-based residue numbering, which is often convenient when comparing against the analysis outputs and restraint setup. It is often useful to visualize the first and last lambda windows explicitly. This can help identify cases where an additional symmetry correction may be needed for the transformation or restraint interpretation.