lnPi data classes and routines (lnpidata)

lnPi data classes and routines (`lnpidata`)#

Classes:

`lnPiArray`(lnz, data[, state_kws, extra_kws, ...])	Wrapper on lnPi lnPiArray
`lnPiMasked`(lnz, base[, mask, copy])	Masked array like wrapper for lnPi data.

class lnpy.lnpidata.lnPiArray(lnz, data, state_kws=None, extra_kws=None, fill_value=None, copy=False)[source]#

Bases: object

Wrapper on lnPi lnPiArray

Parameters:: lnz (float or sequence of float)

Methods:

`new_like`([lnz, data, copy])	Create new object with optional replacements.
`pad`([axes, ffill, bfill, limit])	Pad nan values in underlying data to values
`zeromax`([mask])	Shift values such that lnpi.max() == 0

new_like(lnz=None, data=None, copy=False)[source]#

Create new object with optional replacements.

All parameters are optional. If not passed, use values in self

Parameters:

{lnz}
{data}
{copy}

Returns:

out (lnPiArray) – New object with optionally updated parameters.

pad(axes=None, ffill=True, bfill=False, limit=None)[source]#

Pad nan values in underlying data to values

Parameters:

ffill (bool, default True) – Do forward filling
bfill (bool, default False) – Do back filling
limit (int, default None) – The maximum number of consecutive NaN values to forward fill. In other words, if there is a gap with more than this number of consecutive NaNs, it will only be partially filled. Must be greater than 0 or None for no limit.

Returns:

out (lnPiArray) – object with padded data

zeromax(mask=False)[source]#

Shift values such that lnpi.max() == 0

Parameters:: mask (bool or array-like of bool) – Optional mask to apply to data. Where mask is True, data is excluded from calculating maximum.

class lnpy.lnpidata.lnPiMasked(lnz, base, mask=None, copy=False)[source]#

Bases: AccessorMixin

Masked array like wrapper for lnPi data.

This is the basic data structure for storing the output from a single TMMC simulation.

Parameters:

lnz (float or sequence of float) – Value(s) of lnz (log of activity)
base (object) – lnPi data object.
mask (None or ndarray of bool) – Mask using “masked” convention. Where mask is True, values are excluded.
copy (bool, optional) – If True, copy the data. If False, attempt to use view.

Notes

Note that in most cases, lnPiMasked should not be called directly. Rather, a constructor like from_data() should be used to construct the object.

Note the the value of lnz is the value to reweight to.

Basic terminology:

T : temperature.
k : Boltzmann’s constant.
beta : Inverse temperature = 1/(k T).
mu : chemical potential.
lnz : log of activity = ln(z).
z : activity = beta * mu.
lnPi : log of macrostate distribution.

See also

numpy.ma.MaskedArray

Methods:

`from_data`(lnz, lnz_data, data[, mask, ...])	Create `lnPiMasked` object from raw data.
`filled`([fill_value])	Filled view or reweighted data
`local_argmax`(args, *kwargs)	Calculate index of maximum of masked data.
`local_max`(args, *kwargs)	Calculate index of maximum of masked data.
`local_maxmask`(args, *kwargs)	Calculate mask where `self.ma == self.local_max()`
`edge_distance`(ref, args, *kwargs)	Distance of local maximum value to nearest background point.
`new_like`([lnz, base, mask, copy])	Create new object with optional parameters
`pad`([axes, ffill, bfill, limit])	Pad nan values in underlying data to values
`zeromax`()	Shift so that lnpi.max() == 0 on reference
`reweight`(lnz)	Create new object at specified value of lnz
`or_mask`(mask)	New object with logical or of self.mask and mask
`and_mask`(mask)	New object with logical and of self.mask and mask
`from_table`(path, lnz[, state_kws, sep, ...])	Create lnPi object from text file table with columns [n_0,...,n_ndim, lnpi]
`from_dataarray`(da[, state_as_attrs])	Create a lnPi object from `xarray.DataArray`
`list_from_masks`(masks[, convention])	Create list of lnpis corresponding to masks[i]
`list_from_labels`(labels[, features, ...])	Create sequence of lnpis from labels array.
`decorate_accessor`(name[, single_create])	Register a property name to class of type accessor(self).
`register_accessor`(name, accessor[, ...])	Register a property name to class of type accessor(self)

Attributes:

`dtype`	Type (dtype) of underling data
`state_kws`	State variables.
`extra_kws`	Extra parameters.
`ma`	Masked array view of data reweighted data
`data`	Reweighted data
`mask`	Where True, values are masked out.
`shape`	Shape of lnPiArray
`lnz`	Value of log(activity) evaluated at
`betamu`	Alias to self.lnz
`volume`	Accessor to self.state_kws['volume'].
`beta`	Accessor to self.state_kws['beta'].
`edge_distance_matrix`	Matrix of distance from each element to a background (i.e., masked) point.
`xge`	Accessor to `xGrandCanonical`.
`xce`	Accessor to `xCanonical`.

classmethod from_data(lnz, lnz_data, data, mask=None, state_kws=None, extra_kws=None, fill_value=None, copy=False)[source]#

Create lnPiMasked object from raw data.

Parameters:

lnz (float or sequence of float) – Value of lnz to reweight data to.
lnz_data (float or sequence of float) – Value of lnz at which data was collected
{data}
{mask_masked}
{state_kws}
{extra_kws}
{fill_value}
{copy}

Returns:

out (lnPiMasked)

property dtype#: Type (dtype) of underling data

property state_kws#: State variables.

property extra_kws#: Extra parameters.

property ma#: Masked array view of data reweighted data

filled(fill_value=None)[source]#: Filled view or reweighted data

property data#: Reweighted data

property mask#: Where True, values are masked out.

property shape#: Shape of lnPiArray

property lnz#: Value of log(activity) evaluated at

property betamu#: Alias to self.lnz

property volume#: Accessor to self.state_kws[‘volume’].

property beta#: Accessor to self.state_kws[‘beta’].

local_argmax(*args, **kwargs)[source]#

Calculate index of maximum of masked data.

Parameters:

*args – Positional arguments to argmax
**kwargs – Keyword arguments to argmax

local_max(*args, **kwargs)[source]#

Calculate index of maximum of masked data.

Parameters:

*args – Positional arguments to argmax
**kwargs – Keyword arguments to argmax

See also

numpy.ma.MaskedArray.max

local_maxmask(*args, **kwargs)[source]#: Calculate mask where self.ma == self.local_max()

edge_distance_matrix[source]#: Matrix of distance from each element to a background (i.e., masked) point.

See also

lnpy.utils.distance_matrix

edge_distance(ref, *args, **kwargs)[source]#

Distance of local maximum value to nearest background point.

If edge_distance is too small, the value of properties calculated from this lnPi cannot be trusted. This usually is due to the data being reweighted to too high a value of lnz, or not sampled to sufficiently high values of N.

new_like(lnz=None, base=None, mask=None, copy=False)[source]#

Create new object with optional parameters

Parameters:

lnz (float or sequence of float) – Value(s) of lnz (log of activity)
base (object) – lnPi data object.
mask (None or ndarray of bool) – Mask using “masked” convention. Where mask is True, values are excluded.
copy (bool, optional) – If True, copy the data. If False, attempt to use view.

pad(axes=None, ffill=True, bfill=False, limit=None)[source]#

Pad nan values in underlying data to values

Parameters:

ffill (bool, default True) – Do forward filling
bfill (bool, default False) – Do back filling
limit (int, default None) – The maximum number of consecutive NaN values to forward fill. In other words, if there is a gap with more than this number of consecutive NaNs, it will only be partially filled. Must be greater than 0 or None for no limit.
inplace (bool, default False)

Returns:

out (lnPiMasked) – padded object

See also

lnPiArray.pad

zeromax()[source]#: Shift so that lnpi.max() == 0 on reference

See also

lnPiArray.zeromax

reweight(lnz)[source]#: Create new object at specified value of lnz

or_mask(mask)[source]#: New object with logical or of self.mask and mask

and_mask(mask)[source]#: New object with logical and of self.mask and mask

classmethod from_table(path, lnz, state_kws=None, sep='\\s+', names=None, csv_kws=None, **kwargs)[source]#

Create lnPi object from text file table with columns [n_0,…,n_ndim, lnpi]

Parameters:

path (path-like) – file object to be read
lnz (array-like) – \(\beta \mu\) for each component
state_kws (dict, optional) – define state variables, like volume, beta
sep (string, optional) – separator for file read
names (sequence of str)
csv_kws (dict, optional) – optional arguments to pandas.read_csv
**kwargs – Passed to lnPi constructor

classmethod from_dataarray(da, state_as_attrs=None, **kwargs)[source]#

Create a lnPi object from xarray.DataArray

Parameters:

da (DataArray) – DataArray containing the lnPi data
state_as_attrs (bool, optional) – If True, get state_kws from da.attrs.
**kwargs – Extra arguments to from_data()

Returns:

lnPiMasked

See also

from_data()

list_from_masks(masks, convention='image')[source]#

Create list of lnpis corresponding to masks[i]

Parameters:

masks (sequence of None or ndarray of bool) – Masks using “masked” convention. Where mask[i] is True, values are excluded for sample i.
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

Returns:

lnpis (list) – list of lnpis corresponding to each mask

See also

lnpy.utils.masks_change_convention

list_from_labels(labels, features=None, include_boundary=False, check_features=True, **kwargs)[source]#

Create sequence of lnpis from labels array.

Parameters:

labels (ndarray of int) – Each unique value i in labels indicates a mask. That is labels == i is a mask for feature i.
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
check_features (bool) – if True, then make sure each feature is in labels
**kwargs – Extra arguments to to labels_to_masks()

Returns:

outputs (list of lnPiMasked)

xge[source]#: Accessor to xGrandCanonical.

xce[source]#: Accessor to xCanonical.

classmethod decorate_accessor(name, single_create=False)[source]#

Examples

>>> class parent(AccessorMixin):
...     pass

>>> @parent.decorate_accessor("hello")
... class hello(AccessorMixin):
...     def __init__(self, parent):
...         self._parent = parent
...
...     def there(self):
...         return f"{type(self._parent)}"

>>> x = parent()
>>> x.hello.there()
"<class 'lnpy.extensions.parent'>"

classmethod register_accessor(name, accessor, single_create=False)[source]#

Examples

>>> class parent(AccessorMixin):
...     pass
>>> class hello(AccessorMixin):
...     def __init__(self, parent):
...         self._parent = parent
...
...     def there(self):
...         return f"{type(self._parent)}"

>>> parent.register_accessor("hello", hello)
>>> x = parent()
>>> x.hello.there()
"<class 'lnpy.extensions.parent'>"

lnPi data classes and routines (lnpidata)

Contents

lnPi data classes and routines (lnpidata)#

lnPi data classes and routines (`lnpidata`)#