wepy.analysis.profiles module

Analysis routines for generating free energy profiles over wepy simulation data.

wepy.analysis.profiles._percentage_cumulative_partitions(ensemble_values, percentages=[0.25, 0.5, 0.75, 1.0])[source]
wepy.analysis.profiles._tranche_cumulative_partitions(ensemble_values, time_tranche=None, num_partitions=4)[source]
wepy.analysis.profiles.cumulative_partitions(ensemble_values, time_tranche=None, num_partitions=5, percentages=None)[source]

Calculate the cumulative free energies for an ensemble of trajectory weights.

Parameters

  • ensemble_values (arraylikes of float of shape (n_cycles, n_trajs)) – Array of scalar values for all of the frames of an ensemble simulation.

  • time_tranche (int) – Width of time-bins/windows/tranche to compute free energies for. This overrides the functionality of the ‘partitions’ argument. The last tranche will be truncated to the remainder after partitioning by tranches.

  • num_partitions (int) – Will evenly partition the time coordinate given the dataset. The first partition will carry the remainder. Overriden by time_tranche.

  • percentages (list of float, optional) –

Yields

cumulative_tranche (arraylike) – A slice along the cycles axis of the ensemble values starting at the beginning and including up to the end of the next tranche.

wepy.analysis.profiles.free_energy_profile(weights, observables, bins=30, max_energy=100, zero_point_energy=1e-12)[source]
Parameters

  • weights (arraylikes of float of shape (n_trajs, n_cycles)) – The weights for all of the frames of an ensemble simulation.

  • observables (arraylikes of shape (n_trajs, n_cycles)) – The scalar observables to compute the free energy over.

  • bins (int or sequence of scalars or str) – The number of bins to bin along the observable axis, or the actual bin edges, or the spec for the binning method.

Returns

  • hist_fe (arraylike) – The free energies of the histogram bins

  • bin_edges (arraylike) – The edges of the bins of the histogram.

wepy.analysis.profiles.contigtrees_bin_edges(contigtrees, bins, field_key, truncate_cycles=None)[source]

Get the bin edges that best describes the aggregate data for multiple contigtrees.

Parameters

  • contigtrees (list of ContigTree objects) – The contigtrees to draw the data from.

  • bins (int or str or sequence of scalars or function) – The number of bins to make or the method to use for autobinning or the actual specification of bins. See numpy.histogram_bin_edges for exact meaning and methods.

  • field_key (str) – The trajectory field key for the values to get bins for.

  • truncate_cycles (None or int) – If None include all cycles of a run. Otherwise only consider cycles for spans up to (exclusive) the cycle index given.

Returns

bin_edges – The edges to pass into numpy.histogram

Return type

array of dtype float

See also

numpy.histogram_bin_edges

For the bin edge function

class wepy.analysis.profiles.ContigTreeProfiler(contigtree, truncate_cycles=None)[source]

Bases: object

A wrapper class around a ContigTree that provides extra methods for generating free energy profiles for observables.

Create a wrapper around a contigtree for the profiler.

Parameters

  • contigtree (ContigTree object) – The contigtree you want to generate profiles for.

  • truncate_cycles (None or int) – If None include all cycles of a run. Otherwise only consider cycles for spans up to (exclusive) the cycle index given.

classmethod _get_ignore_trace(contigtree, truncate_cycles)[source]

Get a trace of the ignore frames if we are truncating on a particular cycle index. Is exclusive of the truncate_cycles value.

Parameters

  • contigtree (ContigTree) –

  • truncate_cycles (int) – The cycle index to truncate at (exclusive).

Returns

ignored_trace – The frames to ignore given the truncation.

Return type

set of (int, int)

property contigtree

The underlying contigtree this wraps.

fe_profile_trace(trace, field_key, bins=None, ignore_truncate=False)[source]

Calculate the free energy histogram over a trajectory field.

Parameters

  • trace (list of tuple of ints (run_idx, traj_idx, cycle_idx)) –

  • field_key (str) – The key for the trajectory field to calculate the profiles for. Must be a rank 0 (or equivalent (1,) rank) field.

  • bins (int or sequence of scalars or str or None) – The number of bins to bin along the observable axis, or the actual bin edges, or the spec for the binning method, or None. If None will generate them with the ‘auto’ setting for this span.

  • ignore_truncate (bool) – Ignore the truncate_cycles value.

Returns

fe_profile – An array of free energies for each bin.

Return type

arraylike of dtype float

fe_profile_all(field_key, bins=None, ignore_truncate=False)[source]

Calculate the free energy histogram over a trajectory field.

Parameters

  • field_key (str) – The key for the trajectory field to calculate the profiles for. Must be a rank 0 (or equivalent (1,) rank) field.

  • bins (int or sequence of scalars or str or None) – The number of bins to bin along the observable axis, or the actual bin edges, or the spec for the binning method, or None. If None will generate them with the ‘auto’ setting for this span.

  • ignore_truncate (bool) – Ignore the truncate_cycles value.

Returns

fe_profile – An array of free energies for each bin.

Return type

arraylike of dtype float

fe_profile(span, field_key, bins=None, ignore_truncate=False)[source]

Calculate the free energy histogram over a trajectory field.

Deprecation warning: This will likely be deprecated and renamed to fe_profile_span because it is misleading that a profile is span based.

Parameters

  • span (int) – The index of the span to calculate profiles for.

  • field_key (str) – The key for the trajectory field to calculate the profiles for. Must be a rank 0 (or equivalent (1,) rank) field.

  • bins (int or sequence of scalars or str or None) – The number of bins to bin along the observable axis, or the actual bin edges, or the spec for the binning method, or None. If None will generate them with the ‘auto’ setting for this span.

  • ignore_truncate (bool) – Ignore the truncate_cycles value.

Returns

fe_profile – An array of free energies for each bin.

Return type

arraylike of dtype float

fe_cumulative_profiles(span, field_key, bins=None, time_tranche=None, num_partitions=5, ignore_truncate=False)[source]

Calculate the cumulative free energy histograms for a trajectory field.

Parameters

  • span (int) – The index of the span to calculate profiles for.

  • field_key (str) – The key for the trajectory field to calculate the profiles for. Must be a rank 0 (or equivalent (1,) rank) field.

  • bins (int or sequence of scalars or str or None) – The number of bins to bin along the observable axis, or the actual bin edges, or the spec for the binning method, or None. If None will generate them with the ‘auto’ setting for this span.

  • time_tranche (int) – Width of time-bins/windows/tranche to compute free energies for. This overrides the functionality of the ‘num_partitions’ argument. The last tranche will be truncated to the remainder after partitioning by tranches. Overrides partitions.

  • num_partitions (int) – Will evenly partition the time coordinate given the dataset. The first partition will carry the remainder. Overriden by time_tranche.

  • ignore_truncate (bool) – Ignore the truncate_cycles value.

Returns

  • cumulative_fe_profiles (list of arraylike of dtype float) – A list of each cumulative free energy profile. Each profile is an array of free energies for each bin.

  • profile_num_cycles (list of int) – The number of cycles in each cumulative fe profile.

fe_all_cumulative_profiles(field_key, bins=None, time_tranche=None, num_partitions=5, percentages=None, ignore_truncate=False)[source]

Calculate the cumulative free energy histograms for a trajectory field for all spans in a contigtree.

Parameters

  • field_key (str) – The key for the trajectory field to calculate the profiles for. Must be a rank 0 (or equivalent (1,) rank) field.

  • bins (int or sequence of scalars or str or None) – The number of bins to bin along the observable axis, or the actual bin edges, or the spec for the binning method, or None. If None will generate them with the ‘auto’ setting for this span.

  • time_tranche (int) – Width of time-bins/windows/tranche to compute free energies for. This overrides the functionality of the ‘num_partitions’ argument. The last tranche will be truncated to the remainder after partitioning by tranches. Overrides partitions.

  • num_partitions (int) – Will evenly partition the time coordinate given the dataset. The first partition will carry the remainder. Overriden by time_tranche.

  • percentages (list of float) –

  • ignore_truncate (bool) – Ignore the truncate_cycles value.

Returns

  • cumulative_fe_profiles (list of arraylike of dtype float) – A list of each cumulative free energy profile. Each profile is an array of free energies for each bin.

  • profile_num_cycles (list of int) – The number of cycles in each cumulative fe profile.

bin_edges(bins, field_key)[source]

Compute the bin edges that best describes all of the contigtree data for the number of bins.

Parameters

  • bins (int or str) – The number of bins to make or the method to use for autobinning.

  • field_key (str) – The trajectory field key for the values to get bins for.

Returns

bin_edges – The edges to pass into numpy.histogram

Return type

array of dtype float

See also

numpy.histogram_bin_edges

For the bin edge function