# 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'])
```