Generating Dimension objects¶

LinearDimension¶

A LinearDimension is where the coordinates are regularly spaced along the dimension. This type of dimension is frequently encountered in many scientific datasets. There are several ways to generate LinearDimension.

Using the Dimension class.

>>> import csdmpy as cp
>>> x = cp.Dimension(type='linear', count=10, increment="0.1 s", label="time", description="A temporal dimension.")
>>> print(x)
LinearDimension([0.  0.1 0.2 0.3 0.4 0.5 0.6 0.7 0.8 0.9] s)


Using the LinearDimension class.

>>> import csdmpy as cp
>>> x1 = cp.LinearDimension(count=10, increment="0.1 s", label="time",
...                          description="A temporal dimension.")
>>> print(x1)
LinearDimension([0.  0.1 0.2 0.3 0.4 0.5 0.6 0.7 0.8 0.9] s)


Using NumPy array

You may also create a LinearDimesion object from a one-dimensional NumPy array using the as_dimension() method.

>>> import numpy as np
>>> array = np.arange(10) * 0.1
>>> x2 = cp.as_dimension(array)
>>> print(x2)
LinearDimension([0.  0.1 0.2 0.3 0.4 0.5 0.6 0.7 0.8 0.9])


Note, the Dimension object x2 is dimensionless. You can create a physical dimension by either providing an appropriate unit as the argument to the as_dimension() method,

>>> x3 = cp.as_dimension(array, unit='s')
>>> print(x3)
LinearDimension([0.  0.1 0.2 0.3 0.4 0.5 0.6 0.7 0.8 0.9] s)


or appropriately multiplying the dimension object x2 with a ScalarQuantity.

>>> x2 *= cp.ScalarQuantity('s')
>>> print(x2)
LinearDimension([0.  0.1 0.2 0.3 0.4 0.5 0.6 0.7 0.8 0.9] s)


The coordinates of the x2 LinearDimension object are

>>> x2.coordinates
<Quantity [0. , 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9] s>


where x2.coordinates is a Quantity array. The value and the unit of the quantity instance are

>>> # To access the numpy array
>>> numpy_array = x.coordinates.value
>>> print('numpy array =', numpy_array)
numpy array = [0.  0.1 0.2 0.3 0.4 0.5 0.6 0.7 0.8 0.9]

>>> # To access the astropy.unit
>>> unit = x.coordinates.unit
>>> print('unit =', unit)
unit = s


respectively.

Note

When generating LinearDimension objects from NumPy array, the NumPy array must be one-dimensional and regularly spaced.

>>> cp.as_dimension(np.arange(20).reshape(2, 10))
ValueError: Cannot convert a 2 dimensional array to a Dimension object.


MonotonicDimension¶

A MonotonicDimension is one where the coordinates along the dimension are sampled monotonically, that is, either strictly increasing or decreasing coordinates. Like the LinearDimension, there are several ways to generate a MonotonicDimension.

Using the Dimension class.

>>> import csdmpy as cp
>>> x = cp.Dimension(type='monotonic',
...                  coordinates=['10ns', '100ns', '1µs', '10µs', '100µs',
...                               '1ms', '10ms', '100ms', '1s', '10s'])
>>> print(x)
MonotonicDimension([1.e+01 1.e+02 1.e+03 1.e+04 1.e+05 1.e+06 1.e+07 1.e+08 1.e+09 1.e+10] ns)


Using the MonotonicDimension class.

>>> import numpy as np
>>> array = np.asarray([-0.28758166, -0.22712233, -0.19913859, -0.17235106,
...                     -0.1701172, -0.10372635, -0.01817061, 0.05936719,
...                     0.18141424, 0.34758913])
>>> x = cp.MonotonicDimension(coordinates=array)*cp.ScalarQuantity('cm')
>>> print(x)
MonotonicDimension([-0.28758166 -0.22712233 -0.19913859 -0.17235106 -0.1701172  -0.10372635
-0.01817061  0.05936719  0.18141424  0.34758913] cm)


In the above example, we generate a dimensionless MonotonicDimension from the NumPy array and then scale its dimensionality by multiplying the object with an appropriate ScalarQuantity.

From numpy arrays.

Use the as_dimension() method to convert a numpy array as a Dimension object.

>>> numpy_array = 10 ** (np.arange(10)/10)
>>> x_dim = cp.as_dimension(numpy_array, unit='A')
>>> print(x_dim)
MonotonicDimension([1.         1.25892541 1.58489319 1.99526231 2.51188643 3.16227766
3.98107171 5.01187234 6.30957344 7.94328235] A)


When generating MonotonicDimension object using the Numpy array, the array must be monotonic, that is, either strictly increasing or decreasing. An exception will be raised otherwise.

>>> numpy_array = np.random.rand(10)
>>> x_dim = cp.as_dimension(numpy_array)
Exception: Invalid array for Dimension object.


LabeledDimension¶

A LabeledDimension is one where the coordinates along the dimension are string labels. You can similarly generate a labeled dimension.

Using the Dimension class.

>>> import csdmpy as cp
>>> x = cp.Dimension(type='labeled',
...                  labels=['The', 'great', 'circle'])
>>> print(x)
LabeledDimension(['The' 'great' 'circle'])


Using the LabeledDimension class.

>>> x = cp.LabeledDimension(labels=['The', 'great', 'circle'])
>>> print(x)
LabeledDimension(['The' 'great' 'circle'])


From numpy arrays or python list.

Use the as_dimension() method to convert a numpy array as a Dimension object.

>>> array = ['The', 'great', 'circle']
>>> x = cp.as_dimension(array)
>>> print(x)
LabeledDimension(['The' 'great' 'circle'])