ix_of_item_change

mdtools.numpy_helper_functions.ix_of_item_change(a, axis=-1, wrap=False, prepend_zero=False)

Get the indices of an array where its elements change along a given axis.

Deprecated since version 0.0.0.dev1: mdtools.numpy_helper_functions.ix_of_item_change() might be removed in a future release. It is replaced by mdtools.numpy_helper_functions.item_change_ix(), because this function provides additional functionality. mdtools.numpy_helper_functions.item_change_ix() with pin set to "after" is equivalent to mdtools.numpy_helper_functions.ix_of_item_change(). The option tfic is equivalent to prepend_zero.

Todo

Check for modules and scripts using this function before removing it.

Parameters:

• a (array_like) – Array for which to get each index where its elements change along the given axis.

• axis (int, optional) – The axis along which to track changing elements.

• wrap (bool, optional) – If True, the array a is assumed to be continued after the last element along axis by a itself, like when using periodic boundary conditions. Consequently, if the first and the last element of a do not match, this is interpreted as item change and the position (index) of this item change is regarded as zero.

• prepend_zero (bool, optional) – If True, regard the first element of a along the given axis as item change and prepend a 0 to the returned array of indices. Must not be used together with wrap.

Returns:

ix (tuple) – Tuple of arrays, one for each dimension of a, containing the indices where the elements of a change. ix can be used to index a and get the values of the changed elements.

See also

mdtools.numpy_helper_functions.item_change_ix()

Equivalent function with additional features.

Examples

>>> a = np.arange(3)
>>> a
array([0, 1, 2])
>>> mdt.nph.ix_of_item_change(a)
(array([1, 2]),)
>>> mdt.nph.ix_of_item_change(a, wrap=True)
(array([0, 1, 2]),)
>>> ix = mdt.nph.ix_of_item_change(a, prepend_zero=True)
>>> ix
(array([0, 1, 2]),)
>>> a[ix]
array([0, 1, 2])

>>> b = np.array([1, 2, 2, 3, 3, 3, 1])
>>> mdt.nph.ix_of_item_change(b)
(array([1, 3, 6]),)
>>> mdt.nph.ix_of_item_change(b, wrap=True)
(array([1, 3, 6]),)
>>> ix = mdt.nph.ix_of_item_change(b, prepend_zero=True)
>>> ix
(array([0, 1, 3, 6]),)
>>> b[ix]
array([1, 2, 3, 1])

>>> c = np.ones(3)
>>> ix = mdt.nph.ix_of_item_change(c)
>>> ix
(array([], dtype=int64),)
>>> c[ix]
array([], dtype=float64)
>>> mdt.nph.ix_of_item_change(c, wrap=True)
(array([], dtype=int64),)
>>> mdt.nph.ix_of_item_change(c, prepend_zero=True)
(array([0]),)

2-dimensional example:

>>> d = np.array([[1, 3, 3, 3],
...               [3, 1, 3, 3],
...               [3, 3, 1, 3]])
>>> ax = 0
>>> mdt.nph.ix_of_item_change(d, axis=ax)
(array([1, 1, 2, 2]), array([0, 1, 1, 2]))
>>> mdt.nph.ix_of_item_change(d, axis=ax, wrap=True)
(array([0, 0, 1, 1, 2, 2]), array([0, 2, 0, 1, 1, 2]))
>>> ix = mdt.nph.ix_of_item_change(d, axis=ax, prepend_zero=True)
>>> ix
(array([0, 0, 0, 0, 1, 1, 2, 2]), array([0, 1, 2, 3, 0, 1, 1, 2]))
>>> d[ix]
array([1, 3, 3, 3, 3, 1, 3, 1])

>>> ax = 1
>>> mdt.nph.ix_of_item_change(d, axis=ax)
(array([0, 1, 1, 2, 2]), array([1, 1, 2, 2, 3]))
>>> mdt.nph.ix_of_item_change(d, axis=ax, wrap=True)
(array([0, 0, 1, 1, 2, 2]), array([0, 1, 1, 2, 2, 3]))
>>> mdt.nph.ix_of_item_change(d, axis=ax, prepend_zero=True)
(array([0, 0, 1, 1, 1, 2, 2, 2]), array([0, 1, 0, 1, 2, 0, 2, 3]))

3-dimensional example:

>>> e = np.array([[[1, 2, 2],
...                [2, 2, 1]],
...
...               [[2, 2, 1],
...                [1, 2, 2]]])
>>> ax = 0
>>> mdt.nph.ix_of_item_change(e, axis=ax)
(array([1, 1, 1, 1]), array([0, 0, 1, 1]), array([0, 2, 0, 2]))
>>> mdt.nph.ix_of_item_change(e, axis=ax, wrap=True)
(array([0, 0, 0, 0, 1, 1, 1, 1]), array([0, 0, 1, 1, 0, 0, 1, 1]), array([0, 2, 0, 2, 0, 2, 0, 2]))
>>> ix = mdt.nph.ix_of_item_change(e, axis=ax, prepend_zero=True)
>>> ix
(array([0, 0, 0, 0, 0, 0, 1, 1, 1, 1]), array([0, 0, 0, 1, 1, 1, 0, 0, 1, 1]), array([0, 1, 2, 0, 1, 2, 0, 2, 0, 2]))
>>> e[ix]
array([1, 2, 2, 2, 2, 1, 2, 1, 1, 2])

>>> ax = 1
>>> mdt.nph.ix_of_item_change(e, axis=ax)
(array([0, 0, 1, 1]), array([1, 1, 1, 1]), array([0, 2, 0, 2]))
>>> mdt.nph.ix_of_item_change(e, axis=ax, wrap=True)
(array([0, 0, 0, 0, 1, 1, 1, 1]), array([0, 0, 1, 1, 0, 0, 1, 1]), array([0, 2, 0, 2, 0, 2, 0, 2]))
>>> mdt.nph.ix_of_item_change(e, axis=ax, prepend_zero=True)
(array([0, 0, 0, 0, 0, 1, 1, 1, 1, 1]), array([0, 0, 0, 1, 1, 0, 0, 0, 1, 1]), array([0, 1, 2, 0, 2, 0, 1, 2, 0, 2]))

>>> ax = 2
>>> mdt.nph.ix_of_item_change(e, axis=ax)
(array([0, 0, 1, 1]), array([0, 1, 0, 1]), array([1, 2, 2, 1]))
>>> mdt.nph.ix_of_item_change(e, axis=ax, wrap=True)
(array([0, 0, 0, 0, 1, 1, 1, 1]), array([0, 0, 1, 1, 0, 0, 1, 1]), array([0, 1, 0, 2, 0, 2, 0, 1]))
>>> mdt.nph.ix_of_item_change(e, axis=ax, prepend_zero=True)
(array([0, 0, 0, 0, 1, 1, 1, 1]), array([0, 0, 1, 1, 0, 0, 1, 1]), array([0, 1, 0, 2, 0, 2, 0, 1]))

Edge cases:

>>> x = np.array([1])
>>> mdt.nph.ix_of_item_change(x)
(array([], dtype=int64),)
>>> mdt.nph.ix_of_item_change(x, wrap=True)
(array([], dtype=int64),)
>>> mdt.nph.ix_of_item_change(x, prepend_zero=True)
(array([0]),)

>>> x = np.array([])
>>> mdt.nph.ix_of_item_change(x)
(array([], dtype=int64),)
>>> mdt.nph.ix_of_item_change(x, wrap=True)
(array([], dtype=int64),)
>>> ix = mdt.nph.ix_of_item_change(x, prepend_zero=True)
>>> ix
(array([], dtype=int64),)
>>> x[ix]
array([], dtype=float64)

>>> x = np.array(0)
>>> mdt.nph.ix_of_item_change(x)
Traceback (most recent call last):
...
ValueError: The dimension of a must be greater than zero