.. _how_to_add_dimension:

---------------------------------------
Adding Dimension objects to CSDM object
---------------------------------------

There are three subtypes of Dimension objects,

- LinearDimension
- MonotonicDimension
- LabeledDimension

**Using an instance of the Dimension class**

Please read the topic :ref:`generate_dimension_objects` for details on how to
generate an instance of the Dimension class. Once created, use the dimensions
to generate a CSDM object.


.. doctest::

    >>> linear_dim = cp.LinearDimension(count=10, increment="0.1 C/V")
    >>> new_data = cp.CSDM(dimensions=[linear_dim])
    >>> print(new_data)
    CSDM(
    LinearDimension([0.  0.1 0.2 0.3 0.4 0.5 0.6 0.7 0.8 0.9] C / V)
    )

**Using Python's dictionary objects**

When using python dictionaries, the key-value pairs of the dictionary must
be a valid collection for the given Dimension subtype. For example,

.. doctest::

    >>> # dictionary representation of a linear dimension.
    >>> d0 = {
    ...     "type": "linear",
    ...     "description": "This is a linear dimension",
    ...     "count": 5,
    ...     "increment": "0.1 rad",
    ... }
    >>> # dictionary representation of a monotonic dimension.
    >>> d1 = {
    ...     "type": "monotonic",
    ...     "description": "This is a monotonic dimension",
    ...     "coordinates": ["1 m/s", "2 cm/s", "4 mm/s"],
    ... }
    >>> # dictionary representation of a labeled dimension.
    >>> d2 = {
    ...     "type": "labeled",
    ...     "description": "This is a labeled dimension",
    ...     "labels": ["Cu", "Ag", "Au"],
    ... }
    >>> # add the dictionaries to the CSDM object.
    >>> new_data = cp.CSDM(dimensions=[d0, d1, d2])
    >>> print(new_data)
    CSDM(
    LinearDimension([0.  0.1 0.2 0.3 0.4] rad),
    MonotonicDimension([1.    0.02  0.004] m / s),
    LabeledDimension(['Cu' 'Ag' 'Au'])
    )