gather command

Currently, openfe gather is only able to gather results from Relative Binding Free Energy (RBFE) calculations.

To gather results from ABFE or SepTop protocols, you may use the experimental openfe gather-abfe and openfe gather-septop CLI commands, but please note that these commands are still under development and liable to change in future releases, and meant to be used only for exploratory work.

openfe gather

Gather simulation result JSON files from RBFE simulations and generate a report.

RESULTS is the path(s) to JSON files or directories of JSON files containing RBFE protocol results as generated by openfe quickrun.

All directories will be walked recursively and any valid JSON results files will be gathered. Files must end in .json to be collected, and invalid files will be ignored.

The results reported depends on --report flag:

* --report=dg (default) reports the ligand, its absolute free energy, and

the associated uncertainty as the maximum likelihood estimate obtained

from DDG replica averages and standard deviations. These MLE estimates

are centred around 0.0, and when plotted can be shifted to match

experimental values.

* --report=ddg reports pairs of ligand_i and ligand_j, the calculated

relative free energy DDG(i->j) = DG(j) - DG(i) and its uncertainty.

* --report=raw reports the raw results, which each repeat simulation given

separately (i.e. no combining of redundant simulations is performed)

The output is a table of tab separated values. By default, this outputs to stdout, use the -o option to specify an output filepath.

Usage

openfe gather [OPTIONS] RESULTS...

Options

--report <report>

What data to report. ‘dg’ gives maximum-likelihood estimate of absolute deltaG, ‘ddg’ gives delta-delta-G, and ‘raw’ gives the raw result of the deltaG for a leg.

Default:

'dg'

Options:

dg | ddg | raw

-o <output>

Filepath at which to write the tsv report.

--tsv

Results that are output to stdout will be formatted as tab-separated, identical to the formatting used when writing to file.By default, the output table will be formatted for human-readability.

--allow-partial

Do not raise errors if results are missing parts for some edges. (Skip those edges and issue warning instead.)

Arguments

RESULTS

Required argument(s)

openfe gather-abfe

Warning

Gathering of ABFE results with openfe gather-abfe is an experimental feature and is subject to change in a future release of openfe!

Gather simulation result JSON files from ABFE simulations and generate a report.

RESULTS is the path(s) to JSON files or directories of JSON files containing ABFE protocol results as generated by openfe quickrun.

All directories will be walked recursively and any valid JSON results files will be gathered. Files must end in .json to be collected, and invalid files will be ignored.

Each JSON contains the results of a separate leg from an Absolute Binding Free Energy calculation. See https://docs.openfree.energy/en/latest/tutorials/abfe_tutorial.html for details on running ABFE calculations.

The results reported depends on the --report flag:

* --report=dg (default) reports the ligand, its absolute free energy, and

the associated uncertainty obtained from DG replica averages and

standard deviations.

* --report=raw reports the raw results, which each repeat simulation given

separately (i.e. no combining of redundant simulations is performed)

The output is a table of tab separated values. By default, this outputs to stdout, use the -o option to specify an output filepath.

Usage

openfe gather-abfe [OPTIONS] RESULTS...

Options

--report <report>

What data to report. ‘dg’ computes the overall binding free energy of each ligand in the dataset (dG), and’raw’ outputs the raw dG values for each individual leg in the ABFE transformation cycles.

Default:

'dg'

Options:

dg | raw

-o <output>

Filepath at which to write the tsv report.

--tsv

Results that are output to stdout will be formatted as tab-separated, identical to the formatting used when writing to file.By default, the output table will be formatted for human-readability.

--allow-partial

Do not raise errors if results are missing parts for some edges. (Skip those edges and issue warning instead.)

Arguments

RESULTS

Required argument(s)

openfe gather-septop

Warning

Gathering of SepTop results with openfe gather-septop is an experimental feature and is subject to change in a future release of openfe!

Gather simulation result JSON files from SepTop simulations and generate a report.

RESULTS is the path(s) to JSON files or directories of JSON files containing SepTop protocol results as generated by openfe quickrun.

All directories will be walked recursively and any valid JSON results files will be gathered. Files must end in .json to be collected, and invalid files will be ignored.

Each JSON contains the results of a separate leg from a Separated Topologies calculation. See https://docs.openfree.energy/en/latest/tutorials/septop_tutorial.html for details on running SepTop calculations.

The results reported depends on --report flag:

* --report=dg (default) reports the ligand, its absolute free energy, and

the associated uncertainty as the maximum likelihood estimate obtained

from DDG replica averages and standard deviations. These MLE estimates

are centred around 0.0, and when plotted can be shifted to match

experimental values.

* --report=ddg reports pairs of ligand_i and ligand_j, the calculated

relative free energy DDG(i->j) = DG(j) - DG(i) and its uncertainty.

* --report=raw reports the raw results, which each repeat simulation given

separately (i.e. no combining of redundant simulations is performed)

The output is a table of tab separated values. By default, this outputs to stdout, use the -o option to specify an output filepath.

Usage

openfe gather-septop [OPTIONS] RESULTS...

Options

--report <report>

What data to report. ‘dg’ gives the maximum-likelihood estimate derived absolute deltaG value, ‘ddg’ gives delta-delta-G, and ‘raw’ gives the raw result of the deltaG for a leg.

Default:

'dg'

Options:

dg | ddg | raw

-o <output>

Filepath at which to write the tsv report.

--tsv

Results that are output to stdout will be formatted as tab-separated, identical to the formatting used when writing to file.By default, the output table will be formatted for human-readability.

--allow-partial

Do not raise errors if results are missing parts for some edges. (Skip those edges and issue warning instead.)

Arguments

RESULTS

Required argument(s)