DimArray API¶
DimArray methods are list below by topic, along with examples. Functions are provided in a separate page functions reference API.
Create a DimArray¶
-
DimArray.
__init__
(values=None, axes=None, dims=None, labels=None, copy=False, dtype=None, _indexing=None, _indexing_broadcast=None, **kwargs)[source]¶ Initialize a DimArray instance
Parameters: - values : numpy-like array, or DimArray instance, or dict
If values is not provided, will initialize an empty array with dimensions inferred from axes (in that case axes= must be provided).
- axes : list or tuple, optional
axis values as ndarrays, whose order matches axis names (the dimensions) provided via dims= parameter. Each axis can also be provided as a tuple (str, array-like) which contains both axis name and axis values, in which case dims= becomes superfluous. axes= can also be provided with a list of Axis objects If axes= is omitted, a standard axis np.arange(shape[i]) is created for each axis i.
- dims : list or tuple, optional
dimensions (or axis names) This parameter can be omitted if dimensions are already provided by other means, such as passing a list of tuple to axes=. If axes are passed as keyword arguments (via **kwargs), dims= is used to determine the order of dimensions. If dims is not provided by any of the means mentioned above, default dimension names are given x0, x1, …`xn`, where n is the number of dimensions.
- dtype : numpy data type, optional
passed to np.array()
- copy : bool, optional
passed to np.array()
- **kwargs : keyword arguments
metadata
Notes
- metadata passed this way cannot have name already taken by other
- parameters such as “values”, “axes”, “dims”, “dtype” or “copy”.
Examples
Basic:
>>> DimArray([[1,2,3],[4,5,6]]) # automatic labelling dimarray: 6 non-null elements (0 null) 0 / x0 (2): 0 to 1 1 / x1 (3): 0 to 2 array([[1, 2, 3], [4, 5, 6]])
>>> DimArray([[1,2,3],[4,5,6]], dims=['items','time']) # axis names only dimarray: 6 non-null elements (0 null) 0 / items (2): 0 to 1 1 / time (3): 0 to 2 array([[1, 2, 3], [4, 5, 6]])
>>> DimArray([[1,2,3],[4,5,6]], axes=[list("ab"), np.arange(1950,1953)]) # axis values only dimarray: 6 non-null elements (0 null) 0 / x0 (2): 'a' to 'b' 1 / x1 (3): 1950 to 1952 array([[1, 2, 3], [4, 5, 6]])
More general case:
>>> a = DimArray([[1,2,3],[4,5,6]], axes=[list("ab"), np.arange(1950,1953)], dims=['items','time']) >>> b = DimArray([[1,2,3],[4,5,6]], axes=[('items',list("ab")), ('time',np.arange(1950,1953))]) >>> c = DimArray([[1,2,3],[4,5,6]], {'items':list("ab"), 'time':np.arange(1950,1953)}) # here dims can be omitted because shape = (2, 3) >>> np.all(a == b) and np.all(a == c) True >>> a dimarray: 6 non-null elements (0 null) 0 / items (2): 'a' to 'b' 1 / time (3): 1950 to 1952 array([[1, 2, 3], [4, 5, 6]])
Empty data
>>> a = DimArray(axes=[('items',list("ab")), ('time',np.arange(1950,1953))])
Metadata
>>> a = DimArray([[1,2,3],[4,5,6]], name='test', units='none')
Modify shape¶
-
DimArray.
transpose
(*dims)¶ Permute dimensions
Analogous to numpy, but also allows axis names
Parameters: - *dims : int or str
variable list of dimensions
Returns: - transposed_array : DimArray
Examples
>>> import dimarray as da >>> a = da.DimArray(np.zeros((2,3)), ['x0','x1']) >>> a dimarray: 6 non-null elements (0 null) 0 / x0 (2): 0 to 1 1 / x1 (3): 0 to 2 array([[0., 0., 0.], [0., 0., 0.]]) >>> a.T dimarray: 6 non-null elements (0 null) 0 / x1 (3): 0 to 2 1 / x0 (2): 0 to 1 array([[0., 0.], [0., 0.], [0., 0.]]) >>> (a.T == a.transpose(1,0)).all() and (a.T == a.transpose('x1','x0')).all() True
-
DimArray.
swapaxes
(axis1, axis2)¶ Swap two axes
analogous to numpy’s swapaxes, but can provide axes by name
Parameters: - axis1, axis2 : int or str
axes to swap (transpose)
Returns: - transposed_array : DimArray
Examples
>>> from dimarray import DimArray >>> a = DimArray(np.arange(2*3*4).reshape(2,3,4)) >>> a.dims ('x0', 'x1', 'x2') >>> b = a.swapaxes('x2',0) # put 'x2' at the first position >>> b.dims ('x2', 'x1', 'x0') >>> b.shape (4, 3, 2)
-
DimArray.
reshape
(*newdims, **kwargs)¶ Add/remove/flatten dimensions to conform array to new dimensions
Parameters: - newdims : tuple or list or variable list of dimension names {str}
Any dimension now present in the array is added as singleton dimension Any dimension name containing a comma is interpreting as a flattening command. All dimensions to flatten have to exist already.
- transpose : bool
if True, transpose dimensions to match new order (default True) otherwise, raise and Error if tranpose is needed (closer to original numpy’s behaviour)
Returns: - reshaped_array : DimArray
with reshaped_array.dims == tuple(newdims)
Examples
>>> from dimarray import DimArray >>> a = DimArray([7,8]) >>> a dimarray: 2 non-null elements (0 null) 0 / x0 (2): 0 to 1 array([7, 8])
>>> a.reshape(('x0','new')) dimarray: 2 non-null elements (0 null) 0 / x0 (2): 0 to 1 1 / new (1): None to None array([[7], [8]])
>>> b = DimArray(np.arange(2*2*2).reshape(2,2,2)) >>> b dimarray: 8 non-null elements (0 null) 0 / x0 (2): 0 to 1 1 / x1 (2): 0 to 1 2 / x2 (2): 0 to 1 array([[[0, 1], [2, 3]], <BLANKLINE> [[4, 5], [6, 7]]])
>>> c = b.reshape('x0','x1,x2') >>> c dimarray: 8 non-null elements (0 null) 0 / x0 (2): 0 to 1 1 / x1,x2 (4): (0, 0) to (1, 1) array([[0, 1, 2, 3], [4, 5, 6, 7]])
>>> c.reshape('x0,x1','x2') dimarray: 8 non-null elements (0 null) 0 / x0,x1 (4): (0, 0) to (1, 1) 1 / x2 (2): 0 to 1 array([[0, 1], [2, 3], [4, 5], [6, 7]])
-
DimArray.
flatten
(*dims, **kwargs)¶ Flatten all or a subset of dimensions
Parameters: - dims : list or tuple of axis names, optional
by default, all dimensions
- reverse : bool, optional
if True, reverse behaviour: dims are interpreted as the dimensions to keep, and all the other dimensions are flattened default is False
- insert : int, optional
position where to insert the flattened axis (by default, any flattened dimension is inserted at the position of the first axis involved in flattening)
Returns: - flattened_array : DimArray
appropriately reshaped, with collapsed dimensions as first axis (tuples)
- This is useful to do a regional mean with missing values
Notes
A tuple of axis names can be passed via the “axis” parameter of the transformation to trigger flattening prior to reducing an axis.
Examples
Flatten all dimensions
>>> from dimarray import DimArray >>> a = DimArray([[1,2,3],[4,5,6]]) >>> a dimarray: 6 non-null elements (0 null) 0 / x0 (2): 0 to 1 1 / x1 (3): 0 to 2 array([[1, 2, 3], [4, 5, 6]])
>>> b = a.flatten() >>> b dimarray: 6 non-null elements (0 null) 0 / x0,x1 (6): (0, 0) to (1, 2) array([1, 2, 3, 4, 5, 6])
>>> b.labels (array([(0, 0), (0, 1), (0, 2), (1, 0), (1, 1), (1, 2)], dtype=object),)
Flatten a subset of dimensions only
>>> from dimarray import DimArray >>> np.random.seed(0) >>> values = np.arange(2*3*4).reshape(2,3,4) >>> v = DimArray(values, axes=[('time', [1950,1955]), ('lat', np.linspace(-90,90,3)), ('lon', np.linspace(-180,180,4))]) >>> v dimarray: 24 non-null elements (0 null) 0 / time (2): 1950 to 1955 1 / lat (3): -90.0 to 90.0 2 / lon (4): -180.0 to 180.0 array([[[ 0, 1, 2, 3], [ 4, 5, 6, 7], [ 8, 9, 10, 11]], <BLANKLINE> [[12, 13, 14, 15], [16, 17, 18, 19], [20, 21, 22, 23]]])
>>> w = v.flatten(('lat','lon'), insert=1) >>> w dimarray: 24 non-null elements (0 null) 0 / time (2): 1950 to 1955 1 / lat,lon (12): (-90.0, -180.0) to (90.0, 180.0) array([[ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11], [12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23]])
>>> np.all( w.unflatten() == v ) True
But be careful, the order matter !
>>> v.flatten(('lon','lat'), insert=1) dimarray: 24 non-null elements (0 null) 0 / time (2): 1950 to 1955 1 / lon,lat (12): (-180.0, -90.0) to (180.0, 90.0) array([[ 0, 4, 8, 1, 5, 9, 2, 6, 10, 3, 7, 11], [12, 16, 20, 13, 17, 21, 14, 18, 22, 15, 19, 23]])
Useful to average over a group of dimensions:
>>> v.flatten(('lon','lat'), insert=0).mean(axis=0) dimarray: 2 non-null elements (0 null) 0 / time (2): 1950 to 1955 array([ 5.5, 17.5])
is equivalent to:
>>> v.mean(axis=('lon','lat')) dimarray: 2 non-null elements (0 null) 0 / time (2): 1950 to 1955 array([ 5.5, 17.5])
-
DimArray.
unflatten
(axis=None)¶ undo flatten (inflate array)
Parameters: - axis : int or str or None, optional
axis to unflatten default to None to unflatten all
Returns: - DimArray
-
DimArray.
squeeze
(axis=None)¶ Squeeze singleton axes
Analogous to numpy, but also allows axis name
Parameters: - axis : int or str or None
axis to squeeze default is None, to remove all singleton axes
Returns: - squeezed_array : DimArray
Examples
>>> import dimarray as da >>> a = da.DimArray([[[1,2,3]]]) >>> a dimarray: 3 non-null elements (0 null) 0 / x0 (1): 0 to 0 1 / x1 (1): 0 to 0 2 / x2 (3): 0 to 2 array([[[1, 2, 3]]]) >>> a.squeeze() dimarray: 3 non-null elements (0 null) 0 / x2 (3): 0 to 2 array([1, 2, 3]) >>> a.squeeze(axis='x1') dimarray: 3 non-null elements (0 null) 0 / x0 (1): 0 to 0 1 / x2 (3): 0 to 2 array([[1, 2, 3]])
-
DimArray.
repeat
(values, axis=None)¶ expand the array along an existing axis
Parameters: - values : int or ndarray or Axis instance
int: size of new axis ndarray: values of new axis
- axis : int or str
refer to the dimension along which to repeat
- **kwaxes : key-word arguments
alternatively, axes may be passed as keyword arguments
Returns: - DimArray
See also
newaxis
Examples
>>> import dimarray as da >>> a = da.DimArray(np.arange(3), labels = [[1950., 1951., 1952.]], dims=('time',)) >>> a2d = a.newaxis('lon', pos=1) # lon is now singleton dimension
>>> a2d.repeat(2, axis="lon") dimarray: 6 non-null elements (0 null) 0 / time (3): 1950.0 to 1952.0 1 / lon (2): 0 to 1 array([[0, 0], [1, 1], [2, 2]])
>>> a2d.repeat([30., 50.], axis="lon") dimarray: 6 non-null elements (0 null) 0 / time (3): 1950.0 to 1952.0 1 / lon (2): 30.0 to 50.0 array([[0, 0], [1, 1], [2, 2]])
-
DimArray.
broadcast
(other)¶ repeat array to match target dimensions
Parameters: - other : DimArray or Axes objects or ordered Dictionary of axis values
Returns: - DimArray
Examples
Create some dummy data: # …create some dummy data:
>>> import dimarray as da >>> lon = np.linspace(10, 30, 2) >>> lat = np.linspace(10, 50, 3) >>> time = np.arange(1950,1955) >>> ts = da.DimArray(np.arange(5), axes=[time], dims=['time']) >>> cube = da.DimArray(np.zeros((3,2,5)), axes=[('lat',lat), ('lon',lon), ('time',time)]) # lat x lon x time >>> cube.axes 0 / lat (3): 10.0 to 50.0 1 / lon (2): 10.0 to 30.0 2 / time (5): 1950 to 1954
# …broadcast timeseries to 3D data
>>> ts3D = ts.broadcast(cube) # lat x lon x time >>> ts3D dimarray: 30 non-null elements (0 null) 0 / lat (3): 10.0 to 50.0 1 / lon (2): 10.0 to 30.0 2 / time (5): 1950 to 1954 array([[[0, 1, 2, 3, 4], [0, 1, 2, 3, 4]], <BLANKLINE> [[0, 1, 2, 3, 4], [0, 1, 2, 3, 4]], <BLANKLINE> [[0, 1, 2, 3, 4], [0, 1, 2, 3, 4]]])
Reduce, accumulate¶
-
DimArray.
max
(skipna=False, args=(), **kwargs)¶ Analogous to numpy’s max
max(…, axis=None, skipna=False, …)
Accepts the same parameters as the equivalent numpy function, with modified behaviour of the axis parameter and an additional skipna parameter to handle NaNs (by default considered missing values)
Parameters: - axis : int or str or tuple
axis along which to apply the tranform. Can be given as axis position (int), as axis name (str), as a list or tuple of axes (positions or names) to collapse into one axis before applying transform. If axis is None, just apply the transform on the flattened array consistently with numpy (in this case will return a scalar). Default is None.
- skipna : bool
- If True, treat NaN as missing values (either using MaskedArray or,
when available, specific numpy function)
- “…” stands for any other parameters required by the function, and depends
- on the particular function being called
Returns: - DimArray, or numpy array or scalar (e.g. in some cases if `axis` is None)
- See help on numpy.max or numpy.ma.max for other parameters
- and more information.
See also
apply_along_axis
- is called by this method
to_MaskedArray
- is used if skipna is True
-
DimArray.
min
(skipna=False, args=(), **kwargs)¶ Analogous to numpy’s min
min(…, axis=None, skipna=False, …)
Accepts the same parameters as the equivalent numpy function, with modified behaviour of the axis parameter and an additional skipna parameter to handle NaNs (by default considered missing values)
Parameters: - axis : int or str or tuple
axis along which to apply the tranform. Can be given as axis position (int), as axis name (str), as a list or tuple of axes (positions or names) to collapse into one axis before applying transform. If axis is None, just apply the transform on the flattened array consistently with numpy (in this case will return a scalar). Default is None.
- skipna : bool
- If True, treat NaN as missing values (either using MaskedArray or,
when available, specific numpy function)
- “…” stands for any other parameters required by the function, and depends
- on the particular function being called
Returns: - DimArray, or numpy array or scalar (e.g. in some cases if `axis` is None)
- See help on numpy.min or numpy.ma.min for other parameters
- and more information.
See also
apply_along_axis
- is called by this method
to_MaskedArray
- is used if skipna is True
-
DimArray.
ptp
(skipna=False, args=(), **kwargs)¶ Analogous to numpy’s ptp
ptp(…, axis=None, skipna=False, …)
Accepts the same parameters as the equivalent numpy function, with modified behaviour of the axis parameter and an additional skipna parameter to handle NaNs (by default considered missing values)
Parameters: - axis : int or str or tuple
axis along which to apply the tranform. Can be given as axis position (int), as axis name (str), as a list or tuple of axes (positions or names) to collapse into one axis before applying transform. If axis is None, just apply the transform on the flattened array consistently with numpy (in this case will return a scalar). Default is None.
- skipna : bool
- If True, treat NaN as missing values (either using MaskedArray or,
when available, specific numpy function)
- “…” stands for any other parameters required by the function, and depends
- on the particular function being called
Returns: - DimArray, or numpy array or scalar (e.g. in some cases if `axis` is None)
- See help on numpy.ptp or numpy.ma.ptp for other parameters
- and more information.
See also
apply_along_axis
- is called by this method
to_MaskedArray
- is used if skipna is True
-
DimArray.
median
(skipna=False, args=(), **kwargs)¶ Analogous to numpy’s median
median(…, axis=None, skipna=False, …)
Accepts the same parameters as the equivalent numpy function, with modified behaviour of the axis parameter and an additional skipna parameter to handle NaNs (by default considered missing values)
Parameters: - axis : int or str or tuple
axis along which to apply the tranform. Can be given as axis position (int), as axis name (str), as a list or tuple of axes (positions or names) to collapse into one axis before applying transform. If axis is None, just apply the transform on the flattened array consistently with numpy (in this case will return a scalar). Default is None.
- skipna : bool
- If True, treat NaN as missing values (either using MaskedArray or,
when available, specific numpy function)
- “…” stands for any other parameters required by the function, and depends
- on the particular function being called
Returns: - DimArray, or numpy array or scalar (e.g. in some cases if `axis` is None)
- See help on numpy.median or numpy.ma.median for other parameters
- and more information.
See also
apply_along_axis
- is called by this method
to_MaskedArray
- is used if skipna is True
-
DimArray.
all
(skipna=False, args=(), **kwargs)¶ Analogous to numpy’s all
all(…, axis=None, skipna=False, …)
Accepts the same parameters as the equivalent numpy function, with modified behaviour of the axis parameter and an additional skipna parameter to handle NaNs (by default considered missing values)
Parameters: - axis : int or str or tuple
axis along which to apply the tranform. Can be given as axis position (int), as axis name (str), as a list or tuple of axes (positions or names) to collapse into one axis before applying transform. If axis is None, just apply the transform on the flattened array consistently with numpy (in this case will return a scalar). Default is None.
- skipna : bool
- If True, treat NaN as missing values (either using MaskedArray or,
when available, specific numpy function)
- “…” stands for any other parameters required by the function, and depends
- on the particular function being called
Returns: - DimArray, or numpy array or scalar (e.g. in some cases if `axis` is None)
- See help on numpy.all or numpy.ma.all for other parameters
- and more information.
See also
apply_along_axis
- is called by this method
to_MaskedArray
- is used if skipna is True
-
DimArray.
any
(skipna=False, args=(), **kwargs)¶ Analogous to numpy’s any
any(…, axis=None, skipna=False, …)
Accepts the same parameters as the equivalent numpy function, with modified behaviour of the axis parameter and an additional skipna parameter to handle NaNs (by default considered missing values)
Parameters: - axis : int or str or tuple
axis along which to apply the tranform. Can be given as axis position (int), as axis name (str), as a list or tuple of axes (positions or names) to collapse into one axis before applying transform. If axis is None, just apply the transform on the flattened array consistently with numpy (in this case will return a scalar). Default is None.
- skipna : bool
- If True, treat NaN as missing values (either using MaskedArray or,
when available, specific numpy function)
- “…” stands for any other parameters required by the function, and depends
- on the particular function being called
Returns: - DimArray, or numpy array or scalar (e.g. in some cases if `axis` is None)
- See help on numpy.any or numpy.ma.any for other parameters
- and more information.
See also
apply_along_axis
- is called by this method
to_MaskedArray
- is used if skipna is True
-
DimArray.
prod
(skipna=False, args=(), **kwargs)¶ Analogous to numpy’s prod
prod(…, axis=None, skipna=False, …)
Accepts the same parameters as the equivalent numpy function, with modified behaviour of the axis parameter and an additional skipna parameter to handle NaNs (by default considered missing values)
Parameters: - axis : int or str or tuple
axis along which to apply the tranform. Can be given as axis position (int), as axis name (str), as a list or tuple of axes (positions or names) to collapse into one axis before applying transform. If axis is None, just apply the transform on the flattened array consistently with numpy (in this case will return a scalar). Default is None.
- skipna : bool
- If True, treat NaN as missing values (either using MaskedArray or,
when available, specific numpy function)
- “…” stands for any other parameters required by the function, and depends
- on the particular function being called
Returns: - DimArray, or numpy array or scalar (e.g. in some cases if `axis` is None)
- See help on numpy.prod or numpy.ma.prod for other parameters
- and more information.
See also
apply_along_axis
- is called by this method
to_MaskedArray
- is used if skipna is True
-
DimArray.
sum
(skipna=False, args=(), **kwargs)¶ Analogous to numpy’s sum
sum(…, axis=None, skipna=False, …)
Accepts the same parameters as the equivalent numpy function, with modified behaviour of the axis parameter and an additional skipna parameter to handle NaNs (by default considered missing values)
Parameters: - axis : int or str or tuple
axis along which to apply the tranform. Can be given as axis position (int), as axis name (str), as a list or tuple of axes (positions or names) to collapse into one axis before applying transform. If axis is None, just apply the transform on the flattened array consistently with numpy (in this case will return a scalar). Default is None.
- skipna : bool
- If True, treat NaN as missing values (either using MaskedArray or,
when available, specific numpy function)
- “…” stands for any other parameters required by the function, and depends
- on the particular function being called
Returns: - DimArray, or numpy array or scalar (e.g. in some cases if `axis` is None)
- See help on numpy.sum or numpy.ma.sum for other parameters
- and more information.
See also
apply_along_axis
- is called by this method
to_MaskedArray
- is used if skipna is True
-
DimArray.
mean
(skipna=False, args=(), **kwargs)¶ Analogous to numpy’s mean
mean(…, axis=None, skipna=False, …)
Accepts the same parameters as the equivalent numpy function, with modified behaviour of the axis parameter and an additional skipna parameter to handle NaNs (by default considered missing values)
Parameters: - axis : int or str or tuple
axis along which to apply the tranform. Can be given as axis position (int), as axis name (str), as a list or tuple of axes (positions or names) to collapse into one axis before applying transform. If axis is None, just apply the transform on the flattened array consistently with numpy (in this case will return a scalar). Default is None.
- skipna : bool
- If True, treat NaN as missing values (either using MaskedArray or,
when available, specific numpy function)
- “…” stands for any other parameters required by the function, and depends
- on the particular function being called
Returns: - DimArray, or numpy array or scalar (e.g. in some cases if `axis` is None)
- See help on numpy.mean or numpy.ma.mean for other parameters
- and more information.
See also
apply_along_axis
- is called by this method
to_MaskedArray
- is used if skipna is True
-
DimArray.
std
(skipna=False, args=(), **kwargs)¶ Analogous to numpy’s std
std(…, axis=None, skipna=False, …)
Accepts the same parameters as the equivalent numpy function, with modified behaviour of the axis parameter and an additional skipna parameter to handle NaNs (by default considered missing values)
Parameters: - axis : int or str or tuple
axis along which to apply the tranform. Can be given as axis position (int), as axis name (str), as a list or tuple of axes (positions or names) to collapse into one axis before applying transform. If axis is None, just apply the transform on the flattened array consistently with numpy (in this case will return a scalar). Default is None.
- skipna : bool
- If True, treat NaN as missing values (either using MaskedArray or,
when available, specific numpy function)
- “…” stands for any other parameters required by the function, and depends
- on the particular function being called
Returns: - DimArray, or numpy array or scalar (e.g. in some cases if `axis` is None)
- See help on numpy.std or numpy.ma.std for other parameters
- and more information.
See also
apply_along_axis
- is called by this method
to_MaskedArray
- is used if skipna is True
-
DimArray.
var
(skipna=False, args=(), **kwargs)¶ Analogous to numpy’s var
var(…, axis=None, skipna=False, …)
Accepts the same parameters as the equivalent numpy function, with modified behaviour of the axis parameter and an additional skipna parameter to handle NaNs (by default considered missing values)
Parameters: - axis : int or str or tuple
axis along which to apply the tranform. Can be given as axis position (int), as axis name (str), as a list or tuple of axes (positions or names) to collapse into one axis before applying transform. If axis is None, just apply the transform on the flattened array consistently with numpy (in this case will return a scalar). Default is None.
- skipna : bool
- If True, treat NaN as missing values (either using MaskedArray or,
when available, specific numpy function)
- “…” stands for any other parameters required by the function, and depends
- on the particular function being called
Returns: - DimArray, or numpy array or scalar (e.g. in some cases if `axis` is None)
- See help on numpy.var or numpy.ma.var for other parameters
- and more information.
See also
apply_along_axis
- is called by this method
to_MaskedArray
- is used if skipna is True
-
DimArray.
argmax
(axis=None, skipna=False)¶ similar to numpy’s argmax, but return axis values instead of integer position
Parameters: - axis : int or str or tuple
axis along which to apply the tranform. Can be given as axis position (int), as axis name (str), as a list or tuple of axes (positions or names) to collapse into one axis before applying transform. If axis is None, just apply the transform on the flattened array consistently with numpy (in this case will return a scalar). Default is None.
- skipna : bool
- If True, treat NaN as missing values (either using MaskedArray or,
when available, specific numpy function)
-
DimArray.
argmin
(axis=None, skipna=False)¶ similar to numpy’s argmin, but return axis values instead of integer position
Parameters: - axis : int or str or tuple
axis along which to apply the tranform. Can be given as axis position (int), as axis name (str), as a list or tuple of axes (positions or names) to collapse into one axis before applying transform. If axis is None, just apply the transform on the flattened array consistently with numpy (in this case will return a scalar). Default is None.
- skipna : bool
- If True, treat NaN as missing values (either using MaskedArray or,
when available, specific numpy function)
-
DimArray.
cumsum
(axis=-1, skipna=False)¶
-
DimArray.
cumprod
(axis=-1, skipna=False)¶
-
DimArray.
diff
(axis=-1, scheme='backward', keepaxis=False, n=1)¶ Analogous to numpy’s diff
Calculate the n-th order discrete difference along given axis.
The first order difference is given by
out[n] = a[n+1] - a[n]
along the given axis, higher order differences are calculated by using diff recursively.Parameters: - axis : int or str or tuple
axis along which to apply the tranform. Can be given as axis position (int), as axis name (str), as a list or tuple of axes (positions or names) to collapse into one axis before applying transform. If axis is None, just apply the transform on the flattened array consistently with numpy (in this case will return a scalar). Default is -1.
- scheme : str, optional
determines the values of the resulting axis - “forward” : diff[i] = x[i+1] - x[i] - “backward”: diff[i] = x[i] - x[i-1] - “centered”: diff[i] = x[i+1/2] - x[i-1/2] Default is “backward”
- keepaxis : bool, optional
if True, keep the initial axis by padding with NaNs Only compatible with “forward” or “backward” differences Default is False
- n : int, optional
The number of times values are differenced. Default is one
Returns: - diff : DimArray
The n order differences. The shape of the output is the same as a except along axis where the dimension is smaller by n.
Examples
Create some example data
>>> import dimarray as da >>> v = da.DimArray([1,2,3,4], ('time', np.arange(1950,1954)), dtype=float) >>> s = v.cumsum() >>> s dimarray: 4 non-null elements (0 null) 0 / time (4): 1950 to 1953 array([ 1., 3., 6., 10.])
diff reduces axis size by one, by default
>>> s.diff() dimarray: 3 non-null elements (0 null) 0 / time (3): 1951 to 1953 array([2., 3., 4.])
The keepaxis= parameter fills array with nan where necessary to keep the axis unchanged. Default is backward differencing: diff[i] = v[i] - v[i-1].
>>> s.diff(keepaxis=True) dimarray: 3 non-null elements (1 null) 0 / time (4): 1950 to 1953 array([nan, 2., 3., 4.])
But other schemes are available to control how the new axis is defined: backward (default), forward and even centered
>>> s.diff(keepaxis=True, scheme="forward") # diff[i] = v[i+1] - v[i] dimarray: 3 non-null elements (1 null) 0 / time (4): 1950 to 1953 array([ 2., 3., 4., nan])
The keepaxis=True option is invalid with the centered scheme, since every axis value is modified by definition:
>>> s.diff(axis='time', scheme='centered') dimarray: 3 non-null elements (0 null) 0 / time (3): 1950.5 to 1952.5 array([2., 3., 4.])
Indexing¶
-
DimArray.
__getitem__
(indices=None, axis=0, indexing=None, tol=None, broadcast=None, keepdims=False, broadcast_arrays=None)¶
-
DimArray.
ix
()¶
-
DimArray.
box
()¶ property to allow indexing without array broadcasting (matlab-like)
-
DimArray.
take
()¶ Retrieve values from a DimArray
Parameters: - indices : int or list or slice (single-dimensional indices)
or a tuple of those (multi-dimensional) or dict of { axis name : axis values }
- axis : None or int or str, optional
if specified and indices is a slice, scalar or an array, assumes indexing is along this axis.
- indexing : {‘label’, ‘position’}, optional
Indexing mode. - “label”: indexing on axis labels (default) - “position”: use numpy-like position index Default value can be changed in dimarray.rcParams[‘indexing.by’]
- tol : None or float or tuple or dict, optional
tolerance when looking for numerical values, e.g. to use nearest neighbor search, default None.
- keepdims : bool, optional
keep singleton dimensions (default False)
- broadcast : bool, optional
if True, use numpy-like fancy indexing and broadcast any indexing array to a common shape, useful for example to sample points along a path. Default to False.
Returns: - indexed_array : DimArray instance or scalar
See also
DimArray.put
,DimArrayOnDisk.read
,DimArray.take_axis
Examples
>>> from dimarray import DimArray >>> v = DimArray([[1,2,3],[4,5,6]], axes=[["a","b"], [10.,20.,30.]], dims=['d0','d1'], dtype=float) >>> v dimarray: 6 non-null elements (0 null) 0 / d0 (2): 'a' to 'b' 1 / d1 (3): 10.0 to 30.0 array([[1., 2., 3.], [4., 5., 6.]])
Indexing via axis values (default)
>>> a = v[:,10] # python slicing method >>> a dimarray: 2 non-null elements (0 null) 0 / d0 (2): 'a' to 'b' array([1., 4.]) >>> b = v.take(10, axis=1) # take, by axis position >>> c = v.take(10, axis='d1') # take, by axis name >>> d = v.take({'d1':10}) # take, by dict {axis name : axis values} >>> (a==b).all() and (a==c).all() and (a==d).all() True
Indexing via integer index (indexing=”position” or ix property)
>>> np.all(v.ix[:,0] == v[:,10]) True >>> np.all(v.take(0, axis="d1", indexing="position") == v.take(10, axis="d1")) True
Multi-dimensional indexing
>>> v["a", 10] # also work with string axis 1.0 >>> v.take(('a',10)) # multi-dimensional, tuple 1.0 >>> v.take({'d0':'a', 'd1':10}) # dict-like arguments 1.0
Take a list of indices
>>> a = v[:,[10,20]] # also work with a list of index >>> a dimarray: 4 non-null elements (0 null) 0 / d0 (2): 'a' to 'b' 1 / d1 (2): 10.0 to 20.0 array([[1., 2.], [4., 5.]]) >>> b = v.take([10,20], axis='d1') >>> np.all(a == b) True
Take a slice:
>>> c = v[:,10:20] # axis values: slice includes last element >>> c dimarray: 4 non-null elements (0 null) 0 / d0 (2): 'a' to 'b' 1 / d1 (2): 10.0 to 20.0 array([[1., 2.], [4., 5.]]) >>> d = v.take(slice(10,20), axis='d1') # `take` accepts `slice` objects >>> np.all(c == d) True >>> v.ix[:,0:1] # integer position: does *not* include last element dimarray: 2 non-null elements (0 null) 0 / d0 (2): 'a' to 'b' 1 / d1 (1): 10.0 to 10.0 array([[1.], [4.]])
Keep dimensions
>>> a = v[["a"]] >>> b = v.take("a",keepdims=True) >>> np.all(a == b) True
tolerance parameter to achieve “nearest neighbour” search
>>> v.take(12, axis="d1", tol=5) dimarray: 2 non-null elements (0 null) 0 / d0 (2): 'a' to 'b' array([1., 4.])
# Matlab like multi-indexing
>>> v = DimArray(np.arange(2*3*4).reshape(2,3,4)) >>> v[[0,1],:,[0,0,0]].shape (2, 3, 3) >>> v[[0,1],:,[0,0]].shape # here broadcast = False (2, 3, 2) >>> v.take(([0,1],slice(None),[0,0]), broadcast=True).shape # that is traditional numpy, with broadcasting on same shape (2, 3) >>> v.values[[0,1],:,[0,0]].shape # a proof of it (2, 3)
>>> a = DimArray(np.arange(2*3).reshape(2,3))
>>> a[a > 3] # FULL ARRAY: return a numpy array in n-d case (at least for now) dimarray: 2 non-null elements (0 null) 0 / x0,x1 (2): (1, 1) to (1, 2) array([4, 5])
>>> a[a.x0 > 0] # SINGLE AXIS: only first axis dimarray: 3 non-null elements (0 null) 0 / x0 (1): 1 to 1 1 / x1 (3): 0 to 2 array([[3, 4, 5]])
>>> a[:, a.x1 > 0] # only second axis dimarray: 4 non-null elements (0 null) 0 / x0 (2): 0 to 1 1 / x1 (2): 1 to 2 array([[1, 2], [4, 5]])
>>> a[a.x0 > 0, a.x1 > 0] dimarray: 2 non-null elements (0 null) 0 / x0 (1): 1 to 1 1 / x1 (2): 1 to 2 array([[4, 5]])
Sample points along a path, a la numpy, with broadcast=True
>>> a.take(([0,0,1],[1,2,2]), broadcast=True) dimarray: 3 non-null elements (0 null) 0 / x0,x1 (3): (0, 1) to (1, 2) array([1, 2, 5])
Ellipsis (only one supported)
>>> a = DimArray(np.arange(2*3*4*5).reshape(2,3,4,5)) >>> a[0,...,0].shape (3, 4) >>> a[...,0,0].shape (2, 3)
-
DimArray.
put
()¶ Modify values of a DimArray
Parameters: - indices : int or list or slice (single-dimensional indices)
or a tuple of those (multi-dimensional) or dict of { axis name : axis values }
- axis : None or int or str, optional
if specified and indices is a slice, scalar or an array, assumes indexing is along this axis.
- indexing : {‘label’, ‘position’}, optional
Indexing mode. - “label”: indexing on axis labels (default) - “position”: use numpy-like position index Default value can be changed in dimarray.rcParams[‘indexing.by’]
- tol : None or float or tuple or dict, optional
tolerance when looking for numerical values, e.g. to use nearest neighbor search, default None.
- broadcast : bool, optional
if True, use numpy-like fancy indexing and broadcast any indexing array to a common shape, useful for example to sample points along a path. Default to False.
Returns: - None (inplace=True) or DimArray instance or scalar (inplace=False)
See also
DimArray.take
,DimArrayOnDisk.write
Re-indexing¶
-
DimArray.
reindex_axis
(values, axis=0, fill_value=nan, raise_error=False, method=None)¶ reindex an array along an axis
Parameters: - values : array-like or Axis
new axis values
- axis : int or str, optional
axis number or name
- fill_value: bool, optional
Fill data to use for missing axis value, if raise_error is False.
- raise_error : bool, optional
if True, raise error when an axis value is not present otherwise just replace with fill_value. Defaulf is False
- method : {None, ‘left’, ‘right’}
method to fill the gaps (default None) If ‘left’ or ‘right’, just pass along to numpy.searchsorted.
Returns: - dimarray: DimArray instance
Examples
Basic reindexing: fill missing values with NaN
>>> import dimarray as da >>> a = da.DimArray([1,2,3],axes=[('x0', [1,2,3])]) >>> b = da.DimArray([3,4],axes=[('x0',[1,3])]) >>> b.reindex_axis([1,2,3]) dimarray: 2 non-null elements (1 null) 0 / x0 (3): 1 to 3 array([ 3., nan, 4.])
Or replace with anything else, like -9999
>>> b.reindex_axis([1,2,3], fill_value=-9999) dimarray: 3 non-null elements (0 null) 0 / x0 (3): 1 to 3 array([ 3, -9999, 4])
-
DimArray.
reindex_like
(other, **kwargs)¶ reindex_like : re-index like another dimarray / axes instance
Applies reindex_axis on each axis to match another DimArray
Parameters: - other : DimArray or Axes instance
- **kwargs :
Returns: - DimArray
Notes
only reindex axes which are present in other
Examples
>>> import dimarray as da >>> b = da.DimArray([3,4],('x0',[1,3])) >>> c = da.DimArray([[1,2,3], [1,2,3]],[('x1',["a","b"]),('x0',[1, 2, 3])]) >>> b.reindex_like(c) dimarray: 2 non-null elements (1 null) 0 / x0 (3): 1 to 3 array([ 3., nan, 4.])
-
DimArray.
sort_axis
(axis=0, key=None, kind='quicksort')¶ sort an axis
Parameters: - a : DimArray (this argument is pre-assigned when using as bound method)
- axis : int or str, optional
axis by position (int) or name (str) (default: 0)
- key : callable or dict-like, optional
function that is called on each axis label and whose return value is used for sorting instead of axis label. Any other object with __getitem__ attribute may also be used as key, such as a dictionary. If None (the default), axis label is used for sorting.
- kind : str, optional
sort algorigthm (see numpy.sort for more info)
Returns: - sorted : new DimArray with sorted axis
Examples
Basic
>>> from dimarray import DimArray >>> a = DimArray([10,20,30], labels=[2, 0, 1]) >>> a dimarray: 3 non-null elements (0 null) 0 / x0 (3): 2 to 1 array([10, 20, 30])
>>> a.sort_axis() dimarray: 3 non-null elements (0 null) 0 / x0 (3): 0 to 2 array([20, 30, 10])
>>> a.sort_axis(key=lambda x: -x) dimarray: 3 non-null elements (0 null) 0 / x0 (3): 2 to 0 array([10, 30, 20])
Multi-dimensional
>>> a = DimArray([[10,20,30],[40,50,60]], labels=[[0, 1], ['a','c','b']]) >>> a.sort_axis(axis=1) dimarray: 6 non-null elements (0 null) 0 / x0 (2): 0 to 1 1 / x1 (3): 'a' to 'c' array([[10, 30, 20], [40, 60, 50]])
Missing values¶
-
DimArray.
dropna
(axis=0, minvalid=None, na=nan)¶ drop nans along an axis
Parameters: - axis : axis position or name or list of names
- minvalid : int, optional
min number of valid point in each slice along axis values by default all the points
Returns: - DimArray
Examples
1-Dimension
>>> from dimarray import DimArray >>> a = DimArray([1.,2,3],('time',[1950, 1955, 1960])) >>> a.ix[1] = np.nan >>> a dimarray: 2 non-null elements (1 null) 0 / time (3): 1950 to 1960 array([ 1., nan, 3.]) >>> a.dropna() dimarray: 2 non-null elements (0 null) 0 / time (2): 1950 to 1960 array([1., 3.])
Multi-dimensional
>>> a = DimArray([[ np.nan, 2., 3.],[ np.nan, 5., np.nan]]) >>> a dimarray: 3 non-null elements (3 null) 0 / x0 (2): 0 to 1 1 / x1 (3): 0 to 2 array([[nan, 2., 3.], [nan, 5., nan]]) >>> a.dropna(axis=1) dimarray: 2 non-null elements (0 null) 0 / x0 (2): 0 to 1 1 / x1 (1): 1 to 1 array([[2.], [5.]]) >>> a.dropna(axis=1, minvalid=1) # minimum number of valid values, equivalent to `how="all"` in pandas dimarray: 3 non-null elements (1 null) 0 / x0 (2): 0 to 1 1 / x1 (2): 1 to 2 array([[ 2., 3.], [ 5., nan]])
-
DimArray.
fillna
(value, inplace=False, na=nan)¶ Fill NaN with a replacement value
Examples
>>> from dimarray import DimArray >>> a = DimArray([1,2,np.nan]) >>> a.fillna(-99) dimarray: 3 non-null elements (0 null) 0 / x0 (3): 0 to 2 array([ 1., 2., -99.])
-
DimArray.
setna
(value, na=nan, inplace=False)¶ set a value as missing
Parameters: - value : the values to set to na
- na : the replacement value (default np.nan)
Examples
>>> from dimarray import DimArray >>> a = DimArray([1,2,-99]) >>> a.setna(-99) dimarray: 2 non-null elements (1 null) 0 / x0 (3): 0 to 2 array([ 1., 2., nan]) >>> a.setna([-99, 2]) # sequence dimarray: 1 non-null elements (2 null) 0 / x0 (3): 0 to 2 array([ 1., nan, nan]) >>> a.setna(a > 1) # boolean dimarray: 2 non-null elements (1 null) 0 / x0 (3): 0 to 2 array([ 1., nan, -99.]) >>> a = DimArray([[1,2,-99]]) # multi-dim >>> a.setna([-99, a>1]) # boolean dimarray: 1 non-null elements (2 null) 0 / x0 (1): 0 to 0 1 / x1 (3): 0 to 2 array([[ 1., nan, nan]])
To / From other objects¶
-
classmethod
DimArray.
from_pandas
(data, dims=None)[source]¶ Initialize a DimArray from pandas
Parameters: - data : pandas object (Series, DataFrame, Panel, Panel4D)
- dims, optional : dimension (axis) names, otherwise look at ax.name for ax in data.axes
Returns: - a : DimArray instance
Examples
>>> import pandas as pd >>> s = pd.Series([3,5,6], index=['a','b','c']) >>> s.index.name = 'dim0' >>> DimArray.from_pandas(s) dimarray: 3 non-null elements (0 null) 0 / dim0 (3): 'a' to 'c' array([3, 5, 6])
Also work with Multi-Index
>>> panel = pd.Panel(np.arange(2*3*4).reshape(2,3,4)) >>> b = panel.to_frame() # pandas' method to convert Panel to DataFrame via MultiIndex >>> DimArray.from_pandas(b) # doctest: +SKIP dimarray: 24 non-null elements (0 null) 0 / major,minor (12): (0, 0) to (2, 3) 1 / x1 (2): 0 to 1 ...
I/O¶
-
DimArray.
write_nc
(f, name=None, mode='w', clobber=None, format=None, *args, **kwargs)[source]¶ Write to netCDF
Parameters: - f : file name
- name : variable name, optional
must be provided if no attribute “name” is defined
- mode, clobber, format : see netCDF4.Dataset
- **kwargs : passed to netCDF4.Dataset.createVAriable (compression)
See also
DatasetOnDisk
Plotting¶
-
DimArray.
plot
(*args, **kwargs)¶ Plot 1-D or 2-D data.
Wraps matplotlib’s plot()
Parameters: - *args, **kwargs : passed to matplotlib.pyplot.plot
- legend : True (default) or False
Display legend for 2-D data.
- ax : matplotlib.Axis, optional
Provide axis on which to show the plot.
Returns: - lines : list of matplotlib’s Lines2D instances
Examples
>>> from dimarray import DimArray >>> data = DimArray(np.random.rand(4,3), axes=[np.arange(4), ['a','b','c']], dims=['distance', 'label']) >>> data.axes[0].units = 'meters' >>> h = data.plot(linewidth=2) >>> h = data.T.plot(linestyle='-.') >>> h = data.plot(linestyle='-.', legend=False)
-
DimArray.
pcolor
(*args, **kwargs)¶ Plot a quadrilateral mesh.
Wraps matplotlib pcolormesh(). See pcolormesh documentation in matplotlib for accepted keyword arguments.
Examples
>>> from dimarray import DimArray >>> x = DimArray(np.zeros([100,40])) >>> x.pcolor() # doctest: +SKIP >>> x.T.pcolor() # to flip horizontal/vertical axes # doctest: +SKIP
-
DimArray.
contourf
(*args, **kwargs)¶ Plot filled 2-D contours.
Wraps matplotlib contourf(). See contourf documentation in matplotlib for accepted keyword arguments.
Examples
>>> from dimarray import DimArray >>> x = DimArray(np.zeros([100,40])) >>> x[:50,:20] = 1. >>> x.contourf() # doctest: +SKIP >>> x.T.contourf() # to flip horizontal/vertical axes # doctest: +SKIP
-
DimArray.
contour
(*args, **kwargs)¶ Plot 2-D contours.
Wraps matplotlib contour(). See contour documentation in matplotlib for accepted keyword arguments.
Examples
>>> from dimarray import DimArray >>> x = DimArray(np.zeros([100,40])) >>> x[:50,:20] = 1. >>> x.contour() # doctest: +SKIP >>> x.T.contour() # to flip horizontal/vertical axes # doctest: +SKIP