boltzkit.utils.histogram

Functions

get_histogram_1d(data[, n_bins, data_range])

Compute a 1D histogram of data.

get_histogram_2d(data[, n_bins, data_range, ...])

Compute and display a 2D Ramachandran histogram.

load_histogram(fpath)

plot_as_density(hist)

plot_as_free_energy(hist)

plot_as_log_density(hist)

save_histograms(hists, dirpath)

visualize_histogram_1d(hist, vis_mode, show, ...)

Plot a 1D histogram as counts or free energy.

visualize_histogram_2d(hist, vis_mode, show, ...)

Plot a 2D histogram as counts or free energy and return a PDF buffer.

visualize_histograms(hists, ...)

Classes

Histogram1D

Histogram2D

VisualizationMode

class boltzkit.utils.histogram.Histogram1D[source]

Bases: object

__init__(counts: ndarray, bin_edges: ndarray, n_producing_samples: int)[source]
save(fpath: str)[source]
property n_producing_samples: int
property bin_edges
get_bin_centers()[source]
get_normalized_counts() → ndarray[source]
get_approximate_absolute_counts() → ndarray[source]
get_extend() → tuple[float, float][source]
get_as_density() → ndarray[source]
get_bin_area()[source]
get_num_bins() → int[source]
class boltzkit.utils.histogram.Histogram2D[source]

Bases: object

__init__(counts: ndarray, bin_edges_x: ndarray, bin_edges_y: ndarray, n_producing_samples: int)[source]
get_bin_centers()[source]
save(fpath: str)[source]
property n_producing_samples: int
property bin_edges_x
property bin_edges_y
get_approximate_absolute_counts() → ndarray[source]
get_extend() → tuple[float, float, float, float][source]
get_bin_area()[source]
get_normalized_counts() → ndarray[source]
get_as_density() → ndarray[source]
get_num_bins() → tuple[int, int][source]
boltzkit.utils.histogram.get_histogram_1d(data: ndarray, n_bins: int = 100, data_range: tuple[float, float] | None = None)[source]

Compute a 1D histogram of data.

Parameters:

  • data (np.ndarray) – 1D array of shape (N,)

  • n_bins (int, optional) – Number of histogram bins (default is 100).

  • data_range (tuple[float, float] or None, optional) – Tuple specifying (min, max) range of the histogram. If None, the range is inferred from the data.

Returns:

A Histogram1D object containing the histogram and bin edges.

Return type:

Histogram1D

boltzkit.utils.histogram.get_histogram_2d(data: ndarray, n_bins: int = 100, data_range: tuple[tuple[float, float], tuple[float, float]] | None = None, density: bool = True)[source]

Compute and display a 2D Ramachandran histogram.

Parameters:

  • data (np.ndarray) – Array of shape (N, 2)

  • n_bins (int, optional) – Number of bins per dimension.

  • data_range (((float, float), (float, float)) or None) – 2D tuple specifying (min, max) range of the histogram. If None, the range is inferred from the data.

  • density (bool) – Whether to normalize counts or not, default is True.

Returns:

A Histogram2D object containing the histogram counts and bin edges.

Return type:

Histogram2D

boltzkit.utils.histogram.load_histogram(fpath: str) → Histogram1D | Histogram2D[source]
boltzkit.utils.histogram.save_histograms(hists: dict[str, Histogram1D | Histogram2D], dirpath: str)[source]
class boltzkit.utils.histogram.VisualizationMode[source]

Bases: Protocol

property id: str
__init__(*args, **kwargs)
boltzkit.utils.histogram.plot_as_free_energy(hist: Histogram1D | Histogram2D) → tuple[ndarray, str][source]
boltzkit.utils.histogram.plot_as_density(hist: Histogram1D | Histogram2D) → tuple[ndarray, str][source]
boltzkit.utils.histogram.plot_as_log_density(hist: Histogram1D | Histogram2D) → tuple[ndarray, str][source]
boltzkit.utils.histogram.visualize_histogram_1d(hist: Histogram1D, vis_mode: VisualizationMode = <function plot_as_log_density>, show: bool = False, ax: Axes | None = None, title: str | None = None, xlabel: str | None = None, ylabel: str | None = None, label: str | None = None, linestyle: str = '-', transpose: bool = False)[source]

Plot a 1D histogram as counts or free energy.

Parameters:

  • hist (np.ndarray) – Histogram counts or probabilities. If plotting as free energy, these will be normalized internally. Shape: (n_bins,)

  • bin_edges (np.ndarray) – Bin edges defining the histogram intervals. Length is one greater than the number of bins, i.e., shape: (n_bins + 1,). The i-th bin covers the interval [bin_edges[i], bin_edges[i+1]).

  • vis_mode (VisualizationMode) – Transforms the given histogram counts/density into an np.ndarray for visualization. The function further returns default label, which is used if ylabel is None.

  • show (bool) – Whether to immediately display the plot.

  • ax (plt.Axes, optional) – Axes to plot on; if None, a new figure/axes is created.

  • title (str, optional) – Plot title.

  • xlabel (str, optional) – Label for x-axis.

  • ylabel (str, optional) – Label for y-axis.

  • label (str, optional) – Legend label.

  • linestyle (str) – Line style for the plot.

Returns:

pdf_buffer – Buffer containing the generated PDF or None if ax is not None

Return type:

PdfBuffer | None

boltzkit.utils.histogram.visualize_histogram_2d(hist: Histogram2D, vis_mode: VisualizationMode = <function plot_as_log_density>, show: bool = False, ax: Axes | None = None, title: str | None = None, xlabel: str | None = None, ylabel: str | None = None, cmap: None | str = None, vmin: float | None = None, vmax: float | None = None, cbar: bool = True, cbar_label: str | None = None)[source]

Plot a 2D histogram as counts or free energy and return a PDF buffer.

Parameters:

  • hist (np.ndarray) – 2D histogram counts or probabilities. Shape: (nx, ny)

  • x_bin_edges (np.ndarray) – Bin edges for x-dimension. Shape: (nx + 1,)

  • y_bin_edges (np.ndarray) – Bin edges for y-dimension. Shape: (ny + 1,)

  • vis_mode (VisualizationMode) – Transforms the given histogram counts/density into an np.ndarray for visualization. The function further returns default label, which is used if cbar_label is None.

  • show (bool) – Whether to immediately display the plot.

  • ax (plt.Axes, optional) – Axes to plot on; if None, a new figure/axes is created.

Returns:

pdf_buffer – Buffer containing the generated PDF.

Return type:

PdfBuffer

boltzkit.utils.histogram.visualize_histograms(hists: list[~boltzkit.utils.histogram.Histogram2D] | list[~boltzkit.utils.histogram.Histogram1D | dict[str, ~boltzkit.utils.histogram.Histogram1D]], vis_mode: ~boltzkit.utils.histogram.VisualizationMode = <function plot_as_log_density>, grid_shape: tuple[int, int] | None = None, show: bool = False, progressbar_description: str = '', **kwargs)[source]