Local free energy of lnPi (lnpienergy)

Functions:

find_boundaries(masks[, mode, connectivity])	Find boundary region for masks
find_boundaries_overlap(masks, *[, ...])	Find regions where boundaries overlap
find_masked_extrema(data, masks[, ...])	Find position and value of extrema of masked data.
merge_regions(w_tran, w_min, masks[, ...])	Merge labels where free energy energy barrier < efac.

Classes:

wFreeEnergy(data, masks[, convention, ...])	Analysis of local free energy \(w = \beta f = - \ln \Pi\).
wFreeEnergyCollection(parent)	Calculate the transition free energies for a lnpy.lnpiseries.lnPiCollection.
wFreeEnergyPhases(parent)	Stripped down version of wFreeEnergyCollection for single phase grouping.

lnpy.lnpienergy.find_boundaries(masks, mode='thick', connectivity=None, **kws)

Find boundary region for masks

Parameters:

• masks (sequence of None or ndarray of bool) – Masks using “image” convention. Where masks[i] is True, values are included for sample i.

• mode (str, default "thick") – mode to use in skimage.segmentation.find_boundaries()

• connectivity (int, optional) – Defaults to masks[0].ndim

Returns:

boundaries (list of ndarray of bool) – Boundaries of each mask.

See also

skimage.segmentation.find_boundaries

lnpy.lnpienergy.find_boundaries_overlap(masks, *, boundaries=None, flag_none=True, mode='thick', connectivity=None, method='exact')

Find regions where boundaries overlap

Parameters:

• masks (sequence of None or ndarray of bool) – Masks using “image” convention. Where masks[i] is True, values are included for sample i.

• boundaries (list of ndarray of bool, optional) – If supplied, use these areas as boundaries. Otherwise, calculate boundaries using find_boundaries

• flag_none (bool, default True) – if True, replace overlap with None if no overlap between regions

• connectivity (int, optional) – Defaults to masks[0].ndim

• method (str, {'approx', 'exact'}) –

  • approx : consider regions where boundaries overlap and in one of the two region

  • exact : consider regions where boundaries overlap

Returns:

overlap (dict of ndarray of bool) – overlap[i, j] = region of overlap between boundaries and masks in regions i and j

See also

find_boundaries

lnpy.lnpienergy.find_masked_extrema(data, masks, convention='image', extrema='max', fill_val=nan, fill_arg=None, unravel=True)

Find position and value of extrema of masked data.

Parameters:

• data (ndarray) – input data to consider

• masks (sequence of None or ndarray of bool) – Masking arrays.

• convention (string or bool) – Convention for mask. Allowable values are:

  • ‘image’ or TrueTrue values included, False values excluded.

    This is the normal convention in scipy.ndimage.

  • ‘masked’ or False: False values are included, True values are excluded.

    This is the convention in numpy.ma

• extrema ({'max','min}) – Type of extrema to calculate

• fill_val (scalar, default nan) – Value to fill for out_arg for empty mask

• fill_arg (scalar, optional) – Value to fill for out_val for empty mask

• unravel (bool, default True) – If True, unravel flat index to multi dimensional index.

Returns:

• out_arg (list of int) – index of extrema, one for each mask

• out_val (ndarray) – value of extrema, one for each mask

lnpy.lnpienergy.merge_regions(w_tran, w_min, masks, nfeature_max=None, efac=1.0, force=True, convention='image', warn=True)

Merge labels where free energy energy barrier < efac.

The scaled free energy \(w = \beta f = - \ln \Pi ` is analyzed. Anywhere where :math:\)Delta w = text{w_tran} - text{w_min} < text{efac}` will be merged into a single phase. Here, w_trans is the transition energy between phases (i.e., the minimum value of lnPi` between regions`) and w_min is the minimum energy (the maximum lnPi) for a phase.

Parameters:

• w_tran (ndarray) – Shape of array is (n, n), where n is the number of unique regions/phases.

• This is the transitional free energy ()

• w_min (ndarray) – Shape of array is (n, 1).

• masks (sequence of None or ndarray of bool) – Masking arrays.

• nfeature_max (int) – maximum number of features/phases to allow

• efac (float, default 0.5) – Energy difference to merge on. When w_trans[i, j] - w_min[i] < efac, phases i and j will be merged together.

• force (bool, default True) – if True, then keep going until nfeature <= nfeature_max even if min_val > efac.

• convention (string or bool) – Convention for mask. Allowable values are:

  • ‘image’ or TrueTrue values included, False values excluded.

    This is the normal convention in scipy.ndimage.

  • ‘masked’ or False: False values are included, True values are excluded.

    This is the convention in numpy.ma

• warn (bool, default True) – if True, give warning messages

Returns:

• masks (list of ndarray of bool) – output masks using convention

• w_trans (ndarray) – transition energy for new masks

• w_min (ndarray) – free energy minima of new masks

class lnpy.lnpienergy.wFreeEnergy(data, masks, convention='image', connectivity=None, index=None)

Bases: object

Analysis of local free energy \(w = \beta f = - \ln \Pi\).

Parameters:

• data (ndarray) – lnPi data

• masks (sequence of None or ndarray of bool) – Masking arrays.

• convention (string or bool) – Convention for mask. Allowable values are:

  • ‘image’ or TrueTrue values included, False values excluded.

    This is the normal convention in scipy.ndimage.

  • ‘masked’ or False: False values are included, True values are excluded.

    This is the convention in numpy.ma

• connectivity (int, optional) – Defaults to masks[0].ndim

• index (sequence of int, optional) – Optional index to apply to phases. Not yet fully supported.

Notes

this class uses the ‘image’ convention for masks. That is where mask == True indicates locations in the phase/region, and mask == False indicates locations not in the phase/region. This is opposite the convention used in numpy.ma.

Attributes:

nfeature	Number of features/regions/phases
w_min	Minimum value of w (max lnPi) in each phase/region.
w_argmin	Locations of the minimum of w in each phase/region
w_tran	Minimum value of w (max lnPi) in the boundary between phases.
w_argtran	Location of w_tran
delta_w	Transition energy delta_w[i, j] = w_tran[i, j] - w_min[i].

Methods:

from_labels(data, labels[, connectivity, ...])	Create wFreeEnergy from labels
merge_regions([nfeature_max, efac, force, ...])	Merge labels where free energy energy barrier < efac.

property nfeature

Number of features/regions/phases

classmethod from_labels(data, labels, connectivity=None, features=None, include_boundary=False, **kwargs)

Create wFreeEnergy from labels

Parameters:

• data (ndarray) – lnPi data

• labels (ndarray of int) – Each unique value i in labels indicates a mask. That is labels == i is a mask for feature i.

• connectivity (int, optional) – Defaults to masks[0].ndim

• features (sequence of int) – If specified, extract only those locations where labels == feature for all values feature in features. That is, select a subset of unique label values.

• include_boundary (bool) – if True, include boundary regions in output mask

• **kwargs – Extra arguments to labels_to_masks()

Returns:

out (wFreeEnergy)

See also

lnpy.utils.labels_to_masks

property w_min

Minimum value of w (max lnPi) in each phase/region.

property w_argmin

Locations of the minimum of w in each phase/region

property w_tran

Minimum value of w (max lnPi) in the boundary between phases.

w_tran[i, j] is the transition energy between phases i and j.

property w_argtran

Location of w_tran

delta_w

Transition energy delta_w[i, j] = w_tran[i, j] - w_min[i].

merge_regions(nfeature_max=None, efac=1.0, force=True, convention='image', warn=True)

Merge labels where free energy energy barrier < efac.

Interface to merge_regions()

Parameters:

• nfeature_max (int) – maximum number of features/phases to allow

• efac (float, default 0.5) – Energy difference to merge on. When w_trans[i, j] - w_min[i] < efac, phases i and j will be merged together.

• force (bool, default True) – if True, then keep going until nfeature <= nfeature_max even if min_val > efac.

• {mask_convention}

• warn (bool, default True) – if True, give warning messages

Returns:

• masks (list of ndarray of bool) – output masks using convention

• w_trans (ndarray) – transition energy for new masks

• w_min (ndarray) – free energy minima of new masks

class lnpy.lnpienergy.wFreeEnergyCollection(parent)

Bases: object

Calculate the transition free energies for a lnpy.lnpiseries.lnPiCollection.

\(w(N) = \beta f(N) = - \ln \Pi(N)\)

Parameters:

parent (lnPiCollection)

Notes

An instance of wFreeEnergyCollection is normally created from the accessor lnpy.lnpiseries.lnPiCollection.wfe()

Attributes:

w_min	Minimum energy (maximum lnPi) for a given region/phase
w_tran	Minimum energy (maximum lnPi) at boundary between phases
w_argmin	Location of w_min
w_argtran	Location of w_tran
dw	Series representation of dw = w_tran - w_min
dwx	xarray representation of dw

Methods:

get_dwx(idx[, idx_nebr])	Helper function to get the change in energy from phase idx to idx_nebr.
get_dw(idx[, idx_nebr])	Series version of get_dwx()

property w_min

Minimum energy (maximum lnPi) for a given region/phase

property w_tran

Minimum energy (maximum lnPi) at boundary between phases

property w_argmin

Location of w_min

property w_argtran

Location of w_tran

property dw

Series representation of dw = w_tran - w_min

property dwx

xarray representation of dw

get_dwx(idx, idx_nebr=None)

Helper function to get the change in energy from phase idx to idx_nebr.

Parameters:

• idx (int) – phase index to consider transitions from

• idx_nebr (int or list, optional) – if supplied, consider transition from idx to idx_nebr or minimum of all element in idx_nebr. Default behavior is to return minimum transition from idx to all other neighboring regions

Returns:

dw (DataArray) – Transition energy from idx to idx_nebr - if only phase idx exists, dw = np.inf - if idx does not exists, dw = 0.0 (no barrier between idx and anything else) - else min of transition for idx to idx_nebr

get_dw(idx, idx_nebr=None)

Series version of get_dwx()

class lnpy.lnpienergy.wFreeEnergyPhases(parent)

Bases: wFreeEnergyCollection

Stripped down version of wFreeEnergyCollection for single phase grouping.

This should be used for a collection of lnPi that is at a single state point, with multiple phases.

Parameters:

parent (lnPiCollection)

Notes

This is accessed through lnpy.lnpiseries.lnPiCollection.wfe_phases

Attributes:

dwx	xarray representation of dw
w_argmin	Location of w_min
w_argtran	Location of w_tran
w_min	Minimum energy (maximum lnPi) for a given region/phase
w_tran	Minimum energy (maximum lnPi) at boundary between phases
dw	Series representation of delta_w

Methods:

get_dwx(idx[, idx_nebr])	Helper function to get the change in energy from phase idx to idx_nebr.
get_dw(idx[, idx_nebr])	Series version of get_dwx()

property dwx

xarray representation of dw

get_dwx(idx, idx_nebr=None)

Helper function to get the change in energy from phase idx to idx_nebr.

Parameters:

• idx (int) – phase index to consider transitions from

• idx_nebr (int or list, optional) – if supplied, consider transition from idx to idx_nebr or minimum of all element in idx_nebr. Default behavior is to return minimum transition from idx to all other neighboring regions

Returns:

dw (DataArray) – Transition energy from idx to idx_nebr - if only phase idx exists, dw = np.inf - if idx does not exists, dw = 0.0 (no barrier between idx and anything else) - else min of transition for idx to idx_nebr

property w_argmin

Location of w_min

property w_argtran

Location of w_tran

property w_min

Minimum energy (maximum lnPi) for a given region/phase

property w_tran

Minimum energy (maximum lnPi) at boundary between phases

property dw

Series representation of delta_w

get_dw(idx, idx_nebr=None)

Series version of get_dwx()