Dimension — csdmpy 0.1.1 documentation

# Dimension

class `csdmpy.dimensions.` `Dimension`(*args, **kwargs)

  Bases: `object`

  Create an instance of the Dimension class.

  An instance of this class describes a dimension of a multi-dimensional system. In version 1.0, there are three subtypes of the Dimension class:

  - LinearDimension,

  - MonotonicDimension, and

  - LabeledDimension.

  Creating an instance of a dimension object

  There are two ways of creating a new instance of a Dimension class.

  From a python dictionary containing valid keywords.

      >>> from csdmpy import Dimension
      >>> dimension_dictionary = {
      ...     'type': 'linear',
      ...     'description': 'test',
      ...     'increment': '5 G',
      ...     'count': 10,
      ...     'coordinates_offset': '10 mT',
      ...     'origin_offset': '10 T'
      ... }
      >>> x = Dimension(dimension_dictionary)

  Here, dimension_dictionary is the python dictionary.

  From valid keyword arguments.

      >>> x = Dimension(type = 'linear',
      ...               description = 'test',
      ...               increment = '5 G',
      ...               count = 10,
      ...               coordinates_offset = '10 mT',
      ...               origin_offset = '10 T')

  Attributes Summary

  `type` | The dimension subtype.
  `description` | Brief description of the dimension object.
  `application` | Application metadata dictionary of the dimension object.
  `coordinates` | Coordinates, \({\bf X}_k\), along the dimension.
  `absolute_coordinates` | Absolute coordinates, \({\bf X}_k^\rm{abs}\), along the dimension.
  `count` | Number of coordinates, \(N_k \ge 1\), along the dimension.
  `increment` | Increment along a linear dimension.
  `coordinates_offset` | Offset corresponding to the zero of the indexes array, \(\mathbf{J}_k\).
  `origin_offset` | Origin offset, \(o_k\), along the dimension.
  `complex_fft` | Boolean specifying if the coordinates along the dimension are the output of a complex fft.
  `quantity_name` | Quantity name associated with the physical quantities specifying the dimension.
  `label` | Label associated with the dimension.
  `labels` | Ordered list of labels along the Labeled dimension.
  `period` | Period of the dimension.
  `axis_label` | Formatted string for displaying label along the dimension axis.
  `data_structure` | Json serialized string describing the Dimension class instance.

  Methods Summary

  `to`([unit, equivalencies]) | Convert the coordinates along the dimension to the unit, unit.

  Attributes Documentation

  `type`

    The dimension subtype.

    There are three valid subtypes of Dimension class. The valid literals are given by the DimObjectSubtype enumeration.

        >>> print(x.type)
        linear

    Returns

      A string with a valid dimension subtype.

    Raises

      AttributeError – When the attribute is modified.

  `description`

    Brief description of the dimension object.

    The default value is an empty string, ‘’. The attribute may be modified, for example,

        >>> print(x.description)
        This is a test

        >>> x.description = 'This is a test dimension.'

    Returns

      A string of UTF-8 allows characters describing the dimension.

    Raises

      TypeError – When the assigned value is not a string.

  `application`

    Application metadata dictionary of the dimension object.

        >>> print(x.application)
        {}

    The application attribute is where an application can place its own metadata as a python dictionary object containing application specific metadata, using a reverse domain name notation string as the attribute key, for example,

        >>> x.application = {
        ...     "com.example.myApp" : {
        ...         "myApp_key": "myApp_metadata"
        ...      }
        ... }
        >>> print(x.application)
        {'com.example.myApp': {'myApp_key': 'myApp_metadata'}}

    Returns

      A python dictionary containing dimension application metadata.

  `coordinates`

    Coordinates, \({\bf X}_k\), along the dimension.

    Example

        >>> print(x.coordinates)
        [100. 105. 110. 115. 120. 125. 130. 135. 140. 145.] G

    For linear dimensions, the order of the coordinates also depend on the value of the `complex_fft` attributes. For examples, when the value of the complex_fft attribute is True, the coordinates are

        >>> x.complex_fft = True
        >>> print(x.coordinates)
        [ 75.  80.  85.  90.  95. 100. 105. 110. 115. 120.] G

    Returns

      A Quantity array of coordinates for quantitative dimensions, i.e. linear and monotonic.

    Returns

      A Numpy array for labeled dimensions.

    Raises

      AttributeError – For dimensions with subtype linear.

  `absolute_coordinates`

    Absolute coordinates, \({\bf X}_k^\rm{abs}\), along the dimension.

    This attribute is only valid for quantitative dimensions, that is, linear and monotonic dimensions. The absolute coordinates are given as

    \[\mathbf{X}_k^\mathrm{abs} = \mathbf{X}_k + o_k \mathbf{1}\]

    where \(\mathbf{X}_k\) are the coordinates along the dimension and \(o_k\) is the `origin_offset`. For example, consider

        >>> print(x.origin_offset)
        10.0 T
        >>> print(x.coordinates[:5])
        [100. 105. 110. 115. 120.] G

    then the absolute coordinates are

        >>> print(x.absolute_coordinates[:5])
        [100100. 100105. 100110. 100115. 100120.] G

    For linear dimensions, the order of the absolute_coordinates further depend on the value of the `complex_fft` attributes. For examples, when the value of the complex_fft attribute is True, the absolute coordinates are

        >>> x.complex_fft = True
        >>> print(x.absolute_coordinates[:5])
        [100075. 100080. 100085. 100090. 100095.] G

    Returns

      A Quantity array of absolute coordinates for quantitative dimensions, i.e linear and monotonic.

    Raises

      AttributeError – For labeled dimensions.

  `count`

    Number of coordinates, \(N_k \ge 1\), along the dimension.

    Example

        >>> print(x.count)
        10
        >>> x.count = 5

    Returns

      An Integer specifying the number of coordinates along the dimension.

    Raises

      TypeError – When the assigned value is not an integer.

  `increment`

    Increment along a linear dimension.

    The attribute is only valid for Dimension instances with the subtype linear. When assigning a value, the dimensionality of the value must be consistent with the dimensionality of other members specifying the dimension.

    Example

        >>> print(x.increment)
        5.0 G
        >>> x.increment = "0.1 G"
        >>> print(x.coordinates)
        [100.  100.1 100.2 100.3 100.4 100.5 100.6 100.7 100.8 100.9] G

    Returns

      A Quantity instance with the increment along the dimension.

    Raises

      - AttributeError – For dimension with subtypes other than linear.

      - TypeError – When the assigned value is not a string containing a quantity or a Quantity object.

  `coordinates_offset`

    Offset corresponding to the zero of the indexes array, \(\mathbf{J}_k\).

    When assigning a value, the dimensionality of the value must be consistent with the dimensionality of the other members specifying the dimension.

    Example

        >>> print(x.coordinates_offset)
        10.0 mT
        >>> x.coordinates_offset = "0 T"
        >>> print(x.coordinates)
        [ 0.  5. 10. 15. 20. 25. 30. 35. 40. 45.] G

    The attribute is invalid for labeled dimensions.

    Returns

      A Quantity instance with the coordinates offset.

    Raises

      - AttributeError – For labeled dimensions.

      - TypeError – When the assigned value is not a string containing a quantity or a Quantity object.

  `origin_offset`

    Origin offset, \(o_k\), along the dimension.

    When assigning a value, the dimensionality of the value must be consistent with the dimensionality of other members specifying the dimension.

    Example

        >>> print(x.origin_offset)
        10.0 T
        >>> x.origin_offset = "1e5 G"

    The origin offset only affect the absolute_coordinates along the dimension. This attribute is invalid for labeled dimensions.

    Returns

      A Quantity instance with the origin offset.

    Raises

      - AttributeError – For labeled dimensions.

      - TypeError – When the assigned value is not a string containing a quantity or a Quantity object.

  `complex_fft`

    Boolean specifying if the coordinates along the dimension are the output of a complex fft.

    This attribute is only valid for the Dimension instances with linear subtype. The value of this attribute is a boolean specifying if the coordinates along the dimension are evaluated as the output of a complex fast Fourier transform (FFT) routine. For example, consider the following Dimension object,

        >>> test = Dimension(
        ...            type='linear',
        ...            increment = '1',
        ...            count = 10
        ...        )

        >>> test.complex_fft
        False
        >>> print(test.coordinates)
        [0. 1. 2. 3. 4. 5. 6. 7. 8. 9.]

        >>> test.complex_fft = True
        >>> print(test.coordinates)
        [-5. -4. -3. -2. -1.  0.  1.  2.  3.  4.]

    Returns

      A Boolean.

    Raises

      TypeError – When the assigned value is not a boolean.

  `quantity_name`

    Quantity name associated with the physical quantities specifying the dimension.

    The attribute is invalid for the labeled dimension.

        >>> print(x.quantity_name)
        magnetic flux density

    Returns

      A string with the quantity name.

    Raises

      - AttributeError – For labeled dimensions.

      - NotImplementedError – When assigning a value.

  `label`

    Label associated with the dimension.

    Example

        >>> print(x.label)
        field strength
        >>> x.label = 'magnetic field strength'

    Returns

      A string containing the label.

    Raises

      TypeError – When the assigned value is not a string.

  `labels`

    Ordered list of labels along the Labeled dimension.

    Consider the following labeled dimension,

        >>> x2 = Dimension(
        ...         type='labeled',
        ...         labels=['Cu', 'Ag', 'Au']
        ...      )

    then the lables along the labeled dimension are

        >>> print(x2.labels)
        ['Cu' 'Ag' 'Au']

    Note

    For Labeled dimension, the `coordinates` attribute is an alias of `labels` attribute. For example,

        >>> np.all(x2.coordinates == x2.labels)
        True

    In the above example, `x2` is an instance of the Dimension class with labeled subtype.

    Returns

      A Numpy array with labels along the dimension.

    Raises

      AttributeError – For dimensions with subtype other than labeled.

  `period`

    Period of the dimension.

    The default value of the period is infinity, i.e., the dimension is non-periodic.

    Example

        >>> print(x.period)
        inf G
        >>> x.period = '1 T'

    To assign a dimension as non-periodic, one of the following may be used,

        >>> x.period = '1/0 T'
        >>> x.period = 'infinity µT'
        >>> x.period = '∞ G'

    Attention

    The physical quantity of the period must be consistent with other physical quantities specifying the dimension.

    Returns

      A Quantity instance with the period of the dimension.

    Raises

      - AttributeError – For labeled dimensions.

      - TypeError – When the assigned value is not a string containing a quantity or a Quantity object.

  `axis_label`

    Formatted string for displaying label along the dimension axis.

    This attribute is not a part of the original core scientific dataset model, however, it is a convenient supplementary attribute that provides a formated string ready for labeling dimension axes. For quantitative dimensions, this attributes returns a string, label / unit, if the label is a non-empty string, otherwise, quantity_name / unit. Here `quantity_name` and `label` are the attributes of the Dimension instances, and unit is the unit associated with the coordinates along the dimension. For examples,

        >>> x.label
        'field strength'
        >>> x.axis_label
        'field strength / (G)'

    For labeled dimensions, this attribute returns label.

    Returns

      A formated string of label.

    Raises

      AttributeError – When assigned a value.

  `data_structure`

    Json serialized string describing the Dimension class instance.

    This supplementary attribute is useful for a quick preview of the dimension object. The attribute cannot be modified.

        >>> print(x.data_structure)
        {
          "type": "linear",
          "description": "This is a test",
          "count": 10,
          "increment": "5.0 G",
          "coordinates_offset": "10.0 mT",
          "origin_offset": "10.0 T",
          "quantity_name": "magnetic flux density",
          "label": "field strength"
        }

    Returns

      A json serialized string of the dimension object.

    Raises

      AttributeError – When modified.

  Method Documentation

  `to`(unit='', equivalencies=None)

    Convert the coordinates along the dimension to the unit, unit.

    This method is a wrapper of the to method from the Quantity class and is only valid for physical dimensions.

    Example

        >>> print(x.coordinates)
        [100. 105. 110. 115. 120. 125. 130. 135. 140. 145.] G
        >>> x.to('mT')
        >>> print(x.coordinates)
        [10.  10.5 11.  11.5 12.  12.5 13.  13.5 14.  14.5] mT

    Parameters

      unit – A string containing a unit with the same dimensionality as the coordinates along the dimension.

    Raises

      AttributeError – For labeled dimensions.