a3fe.analyse.plot

Plotting functions

Functions

general_plot(x_vals, y_vals, x_label, ...[, ...])

Plot several sets of y_vals against one set of x vals, and show confidence intervals based on inter-y-set deviations (assuming normality).

p_plot(times, p_vals, outfile[, p_cutoff])

Plot the p value against time discarded from the start of the simulation.

plot_against_exp(all_results, output_dir[, ...])

Plot all results from a set of calculations against the experimental values.

plot_av_waters(lam_windows, output_dir, ...)

Calculate average number of waters within given distance of an atom (or two atoms) with given index over the specified percentage of the end of the trajectory, for all simulations for all runs for all lambda windows supplied.

plot_comparitive_convergence(sim_runners[, ...])

Plot the convergence of multiple simulation runners against each other.

plot_comparitive_convergence_on_ax(...[, ...])

Plot the convergence of multiple simulation runners against each other, on the axis supplied.

plot_comparitive_convergence_sem(sim_runners)

Plot the convergence of the SEM of the free energy changes for simulation runners against each other.

plot_comparitive_convergence_sem_on_ax(...)

Plot the convergence of the SEM of the free energy changes for simulation runners against each other, on the supplied axis.

plot_convergence(fracts, dgs, tot_simtime, ...)

Plot convergence of free energy estimate as a function of the total simulation time.

plot_equilibration_time(lam_windows, output_dir)

Plot the equilibration time for each lambda window.

plot_gelman_rubin_rhat(rhat_dict, output_dir)

Plot the Gelman-Rubin Rhat statistic for each lambda window.

plot_gradient_hists(gradients_data, output_dir)

Plot histograms of the gradients for a list of lambda windows.

plot_gradient_stats(gradients_data, ...)

Plot the variance of the gradients for a list of lambda windows.

plot_gradient_timeseries(gradients_data, ...)

Plot timeseries of the gradients for a list of lambda windows.

plot_mbar_gradient_convergence(fracts, ...)

Plot the convergence of the gradients obtained from MBAR as a function of simulation time.

plot_mbar_pmf(outfiles, output_dir)

Plot the PMF from MBAR for each run.

plot_normality(data, output_dir)

Plot the histogram and QQ plot for a given set of data.

plot_overlap_mat(ax, name[, mbar_file, ...])

Plot the overlap matrix for a given MBAR file on the supplied axis.

plot_overlap_mats(output_dir, nlam[, ...])

Plot the overlap matrices for all mbar outfiles supplied.

plot_rmsds(lam_windows, output_dir, selection)

Plot the RMSDs for each lambda window.

plot_sq_sem_convergence(fracts, dgs, ...)

Plot convergence of the squared standard error of the mean of the free energy estimate as a function of the total simulation time.
a3fe.analyse.plot.general_plot(x_vals: ndarray, y_vals: ndarray, x_label: str, y_label: str, outfile: str, vline_val: float | None = None, hline_val: float | None = None, run_nos: List[int] | None = None) → None[source]

Plot several sets of y_vals against one set of x vals, and show confidence intervals based on inter-y-set deviations (assuming normality).

Parameters:

  • x_vals (np.ndarray) – 1D array of x values.

  • y_vals (np.ndarray) – 1 or 2D array of y values, with shape (n_sets, n_vals). Assumes that the sets of data are passed in the same order as the runs.

  • x_label (str) – Label for the x axis.

  • y_label (str) – Label for the y axis.

  • outfile (str) – Name of the output file.

  • vline_val (float, Optional) – x value to draw a vertical line at, for example the time taken for equilibration.

  • hline_val (float, Optional) – y value to draw a horizontal line at.

  • run_nos (List[int], Optional) – List of of the numbers of the runs supplied. If None, the runs are numbered in the order supplied from 1.

a3fe.analyse.plot.p_plot(times: ndarray, p_vals: ndarray, outfile: str, p_cutoff: float = 0.4) → None[source]

Plot the p value against time discarded from the start of the simulation.

Parameters:

  • times (np.ndarray) – 1D array of times discarded from the start of the simulation. This is per run.

  • p_vals (np.ndarray) – 1D array of p values.

  • outfile (str) – Name of the output file.

  • p_cutoff (float, optional) – p value cutoff for significance. Default is 0.4. A horizontal line is drawn at this value.

Return type:

None

a3fe.analyse.plot.plot_against_exp(all_results: DataFrame, output_dir: str, offset: bool = False, stats: Dict | None = None) → None[source]

Plot all results from a set of calculations against the experimental values.

Parameters:

  • all_results (_pd.DataFrame) – A DataFrame containing the experimental and calculated free energy changes and errors.

  • output_dir (str) – Directory to save the plot to.

  • offset (bool, Optional, Default = False) – Whether the calculated absolute binding free energies have been offset so that the mean experimental and calculated values are the same.

  • stats (Dict, Optional, Default = None) – A dictionary of statistics, obtained using analyse.analyse_set.compute_stats

a3fe.analyse.plot.plot_av_waters(lam_windows: List[LamWindow], output_dir: str, percent_traj: float, index: int, length: float, index2: int | None = None, length2: float | None = None, run_nos: List[int] | None = None) → None[source]

Calculate average number of waters within given distance of an atom (or two atoms) with given index over the specified percentage of the end of the trajectory, for all simulations for all runs for all lambda windows supplied.

Parameters:

  • lam_windows (List[LamWindow]) – List of LamWindow objects for which to calculate average number of waters

  • output_dir (str) – Directory to save the plot to.

  • percent_traj (float) – percentage of trajectory (beginning from end) over which to average

  • index (int) – Atom from which distance is calculated

  • length (float) – Distance in Angstrom

  • index2 (int, optional, default=None) – Optional. Index of second atom from which water must be within a specified distance

  • length2 (float, optional, default=None) – Optional. Distance (Angstrom) from second atom which water must be within

  • run_nos (Optional[List[int]], default=None) – Optional. List of run numbers to include in the analysis. If None, all runs will be included.

Returns:

avg_close_waters – Average number of waters within the specified distance(s) of the specified atom(s) for each lambda window for each run. Shape is (n_runs, n_lam_windows).

Return type:

_np.ndarray

a3fe.analyse.plot.plot_comparitive_convergence(sim_runners: SimulationRunnerIterator, output_dir: str = '.', equilibrated: bool = False, mode: str = 'cumulative', name: str | None = None) → None[source]

Plot the convergence of multiple simulation runners against each other.

Parameters:

  • sim_runners (List[sim_runner]) – The simulation runners to compare.

  • output_dir (str, optional) – The directory to save the plot to. Defaults to the current directory.

  • equilibrated (bool, optional, default=False) – Whether to use the equilibrated simulation time or the total simulation time. If False, all simulation data will be used, otherwise only the equilibrated data will be used.

  • mode (str, optional, default=”cumulative”) – “cumulative” or “block”. The type of averaging to use. In both cases, 20 MBAR evaluations are performed per simulation runner.

  • name (str, optional) – The name of the plot. Defaults to “comparitive_convergence”.

Return type:

None

a3fe.analyse.plot.plot_comparitive_convergence_on_ax(sim_runners: SimulationRunnerIterator, ax: Axes, equilibrated: bool = False, mode: str = 'cumulative') → None[source]

Plot the convergence of multiple simulation runners against each other, on the axis supplied.

Parameters:

  • sim_runners (List[sim_runner]) – The simulation runners to compare.

  • ax (matplotlib axis) – Axis on which to plot.

  • equilibrated (bool, optional, default=False) – Whether to use the equilibrated simulation time or the total simulation time. If False, all simulation data will be used, otherwise only the equilibrated data will be used.

  • mode (str, optional, default=”cumulative”) – “cumulative” or “block”. The type of averaging to use. In both cases, 20 MBAR evaluations are performed per simulation runner.

Return type:

None

a3fe.analyse.plot.plot_comparitive_convergence_sem(sim_runners: SimulationRunnerIterator, output_dir: str = '.', equilibrated: bool = False, mode: str = 'cumulative', name: str | None = None, color_indices: List[int] | None = None) → None[source]

Plot the convergence of the SEM of the free energy changes for simulation runners against each other.

Parameters:

  • sim_runners (List[sim_runner]) – The simulation runners to compare.

  • output_dir (str, optional) – The directory to save the plot to. Defaults to the current directory.

  • equilibrated (bool, optional, default=False) – Whether to use the equilibrated simulation time or the total simulation time. If False, all simulation data will be used, otherwise only the equilibrated data will be used.

  • mode (str, optional, default=”cumulative”) – “cumulative” or “block”. The type of averaging to use. In both cases, 20 MBAR evaluations are performed per simulation runner.

  • name (str, optional) – The name of the plot. Defaults to “comparitive_convergence”.

  • color_indices (List[int], optional) – The color group to use for the simulation runners. If None, a different color will be used for each simulation runner.

Return type:

None

a3fe.analyse.plot.plot_comparitive_convergence_sem_on_ax(sim_runners: SimulationRunnerIterator, ax: Axes, equilibrated: bool = False, mode: str = 'cumulative', color_indices: List[int] | None = None) → None[source]

Plot the convergence of the SEM of the free energy changes for simulation runners against each other, on the supplied axis.

Parameters:

  • sim_runners (List[sim_runner]) – The simulation runners to compare.

  • ax (matplotlib axis) – Axis on which to plot.

  • equilibrated (bool, optional, default=False) – Whether to use the equilibrated simulation time or the total simulation time. If False, all simulation data will be used, otherwise only the equilibrated data will be used.

  • mode (str, optional, default=”cumulative”) – “cumulative” or “block”. The type of averaging to use. In both cases, 20 MBAR evaluations are performed per simulation runner.

  • color_indices (List[int], optional) – The color group to use for the simulation runners. If None, a different color will be used for each simulation runner.

Return type:

None

a3fe.analyse.plot.plot_equilibration_time(lam_windows: List[LamWindows], output_dir: str) → None[source]

Plot the equilibration time for each lambda window.

Parameters:

  • lam_windows (List[LamWindows]) – List of LamWindows objects.

  • output_dir (str) – Directory to save the plot to.

Return type:

None

a3fe.analyse.plot.plot_gelman_rubin_rhat(rhat_dict: Dict[str, float], output_dir: str, cutoff: float = 1.1) → None[source]

Plot the Gelman-Rubin Rhat statistic for each lambda window.

Parameters:

  • rhat_dict (Dict[str, float]) – A dictionary of the Rhat statistic for each lambda window.

  • output_dir (str) – Directory to save the plot to.

  • cutoff (float, Optional, Default = 1.1) – The cutoff for the Rhat statistic. The empirical 1.1 is default.

Return type:

None

a3fe.analyse.plot.plot_gradient_hists(gradients_data: GradientData, output_dir: str, run_nos: List[int] | None = None) → None[source]

Plot histograms of the gradients for a list of lambda windows. If equilibrated is True, only data after equilibration is used.

Parameters:

  • gradients_data (GradientData) – GradientData object containing the gradient data.

  • output_dir (str) – Directory to save the plot to.

  • run_nos (List[int], Optional, default: None) – The run numbers to use. If None, all runs will be used.

Return type:

None

a3fe.analyse.plot.plot_gradient_stats(gradients_data: GradientData, output_dir: str, plot_type: str) → None[source]

Plot the variance of the gradients for a list of lambda windows. If equilibrated is True, only data after equilibration is used.

Parameters:

  • gradients_data (GradientData) – GradientData object containing the gradient data.

  • output_dir (str) – Directory to save the plot to.

  • plot_type (str) – Type of plot to make. Can be “mean”, “variance”, “sem”, “stat_ineff”, “integrated_sem”, or “integrated_var”.

Return type:

None

a3fe.analyse.plot.plot_gradient_timeseries(gradients_data: GradientData, output_dir: str, run_nos: List[int] | None = None) → None[source]

Plot timeseries of the gradients for a list of lambda windows. If equilibrated is True, only data after equilibration is used.

Parameters:

  • gradients_data (GradientData) – GradientData object containing the gradient data.

  • output_dir (str) – Directory to save the plot to.

  • run_nos (List[int], Optional, default: None) – The run numbers to use. If None, all runs will be used.

Return type:

None

a3fe.analyse.plot.plot_mbar_pmf(outfiles: List[str], output_dir: str) → None[source]

Plot the PMF from MBAR for each run.

Parameters:

  • outfiles (List[str]) – List of MBAR output files. It is assumed that these are passed in the same order as the runs they correspond to.

  • output_dir (str) – Directory to save the plot to.

Return type:

None

a3fe.analyse.plot.plot_normality(data: ndarray, output_dir: str) → None[source]

Plot the histogram and QQ plot for a given set of data.

Parameters:

  • data (np.ndarray) – The data to plot.

  • output_dir (str) – The directory to save the plot to.

Return type:

None

a3fe.analyse.plot.plot_overlap_mat(ax: Axes, name: str, mbar_file: str | None = None, predicted: bool = False, gradient_data: GradientData | None = None, color_bar_cutoffs=[0, 0.03, 0.1, 0.3, 1]) → None[source]

Plot the overlap matrix for a given MBAR file on the supplied axis.

Parameters:

  • ax (matplotlib axis) – Axis on which to plot.

  • name (str) – Name of the plot.

  • mbar_file (str, optional, default=None) – Path to MBAR file.

  • predicted (bool, default=False) – If True, the overlap matrix is predicted from the variances of the gradient alone.

  • gradient_data (GradientData, optional) – GradientData object containing the gradient data. Only required if predicted is True.

Return type:

None

a3fe.analyse.plot.plot_overlap_mats(output_dir: str, nlam: int, run_nos: List[int] | None = None, mbar_outfiles: List[str] | None = None, predicted: bool = False, gradient_data: GradientData | None = None) → None[source]

Plot the overlap matrices for all mbar outfiles supplied.

Parameters:

  • output_dir (str) – The directory to save the plot to.

  • nlam (int) – Number of lambda windows.

  • run_nos (Optional[List[int]], default=None) – List of run numbers to use for MBAR. If None, all runs will be used.

  • mbar_outfiles (Optional[List[str]], default=None) – List of MBAR outfiles. It is assumed that these are passed in the same order as the runs they correspond to. This is required if predicted is False (the default).

  • predicted (bool, default=False) – If True, the overlap matrices are predicted from the variances of the gradient alone.

  • gradient_data (GradientData) – GradientData object containing the gradient data. Only required if predicted is True.

Return type:

None