DependentVariable — csdmpy 0.1.1 documentation

# DependentVariable

class `csdmpy.dependent_variables.` `DependentVariable`(*args, **kwargs)

  Bases: `object`

  Create an instance of the DependentVariable class.

  The instance of this class represents a dependent variable, \(\mathbf{U}\). A dependent variable holds \(p\)-component data values, where \(p>0\) is an integer. For example, a scalar is single-component (\(p=1\)), a vector may have up to n-components (\(p=n\)), while a second rank symmetric tensor have six unique component (\(p=6\)).

  Creating a new dependent variable.

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

  From a python dictionary containing valid keywords.

      >>> from csdmpy import DependentVariable
      >>> import numpy as np
      >>> numpy_array = np.arange(30).reshape(3,10).astype(np.float32)

      >>> dependent_variable_dictionary = {
      ...     'type': 'internal',
      ...     'components': numpy_array,
      ...     'name': 'star',
      ...     'unit': 'W s',
      ...     'quantity_name': 'energy',
      ...     'quantity_type': 'pixel_3'
      ... }
      >>> y = DependentVariable(dependent_variable_dictionary)

  Here, dependent_variable_dictionary is the python dictionary.

  From valid keyword arguments.

      >>> y = DependentVariable(
      ...         type='internal',
      ...         name='star',
      ...         unit='W s',
      ...         quantity_type='pixel_3',
      ...         components=numpy_array
      ...     )

  Attributes Summary

  `type` | The dependent variable subtype.
  `description` | Brief description of the dependent variables.
  `application` | Application metadata of the DependentVariable object.
  `name` | Name of the dependent variable.
  `unit` | Unit associated with the dependent variable.
  `quantity_name` | Quantity name of the physical quantities associated with the dependent variable.
  `encoding` | The encoding method used in representing the dependent variable.
  `numeric_type` | The numeric type of the data values from the dependent variable.
  `quantity_type` | Quantity type of the dependent variable.
  `component_labels` | List of labels corresponding to the components of the dependent variable.
  `components` | Component array of the dependent variable.
  `components_url` | URL where the data components of the dependent variable are stored.
  `axis_label` | List of formatted string labels for each component of the dependent variable.
  `data_structure` | Json serialized string describing the DependentVariable class instance.

  Methods Summary

  `to`(unit) | Convert the unit of the dependent variable to the unit.

  Attributes Documentation

  `type`

    The dependent variable subtype.

    There are two valid subtypes of DependentVariable class with the following enumeration literals,

    `internal`
    `external`

    corresponding to Internal and External sub class. By default, all instances of the DependentVariable class are assigned as internal upon import. The user may update the value of this attribute, at any time, with a string containing a valid type literal, for example,

        >>> print(y.type)
        internal

        >>> y.type = 'external'

    When type is external, the data values from the corresponding dependent variable are serialized to an external file within the same directory as the .csdfe file.

    Returns

      A string with a valid dependent variable subtype.

    Raises

      ValueError – When an invalid value is assigned.

  `description`

    Brief description of the dependent variables.

    The default value is an empty string, ‘’.

        >>> print(y.description)
        A test image
        >>> y.description = 'A test pixel_3 image'
        >>> print(y.description)
        A test pixel_3 image

    Returns

      A string of UTF-8 allowed characters describing the dependent variable.

    Raises

      TypeError – When the assigned value is not a string.

  `application`

    Application metadata of the DependentVariable object.

        >>> print(y.application)
        {}

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

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

    Please refer to the Core Scientific Dataset Model article for details.

    Returns

      A python dictionary containing dependent variable application metadata.

  `name`

    Name of the dependent variable.

        >>> y.name
        'star'
        >>> y.name = 'rock star'

    Returns

      A string containing the name of the dependent variable.

    Raises

      TypeError – When the assigned value is not a string.

  `unit`

    Unit associated with the dependent variable.

    Note

    The attribute cannot be modified. To convert the unit, use the `to()` method of the class instance.

        >>> y.unit
        Unit("s W")

    Returns

      A Unit object from astropy.unit package.

    Raises

      AttributeError – When assigned a value.

  `quantity_name`

    Quantity name of the physical quantities associated with the dependent variable.

        >>> y.quantity_name
        'energy'

    Returns

      A string with the quantity name associated with the dependent variable physical quantities .

    Raises

      NotImplementedError – When assigning a value.

  `encoding`

    The encoding method used in representing the dependent variable.

    The value of this attribute determines the method used when serializing or deserializing the data values to and from the file. Currently, there are three valid encoding methods:

    `raw`
    `base64`
    `none`

    A value, raw, means that the data values are serialized as binary data. The value, base64, implies that the data values are serialized as base64 strings, while, the value none refers to text-based serialization.

    By default, the encoding attribute of all dependent variable object are set to base64 after import. The user may update this attribute, at any time, with a string containing a valid encoding literal, for example,

        >>> y.encoding = 'base64'

    The value of this attribute will be used in serializing the data to the file, when using the `save()` method.

    Returns

      A string with a valid encoding type.

    Raises

      ValueError – If an invalid encoding value is assigned.

  `numeric_type`

    The numeric type of the data values from the dependent variable.

    There are currently twelve valid numeric types:

    `uint8` | `int8` | `float32` | `complex64`
    `uint16` | `int16` | `float64` | `complex128`
    `uint32` | `int32` |  |
    `uint64` | `int64` |  |

    When assigning a valid value, this attribute updates the dtype of the Numpy array from the corresponding `components` attribute. We recommended the use of the numeric type attribute for updating the dtype of the Numpy array. For example,

        >>> y.numeric_type
        'float32'

        >>> print(y.components)
        [[ 0.  1.  2.  3.  4.  5.  6.  7.  8.  9.]
         [10. 11. 12. 13. 14. 15. 16. 17. 18. 19.]
         [20. 21. 22. 23. 24. 25. 26. 27. 28. 29.]]

        >>> y.numeric_type = 'complex64'

        >>> print(y.components[:,:5])
        [[ 0.+0.j  1.+0.j  2.+0.j  3.+0.j  4.+0.j]
         [10.+0.j 11.+0.j 12.+0.j 13.+0.j 14.+0.j]
         [20.+0.j 21.+0.j 22.+0.j 23.+0.j 24.+0.j]]

    Returns

      A string with a valid numeric type.

    Raises

      ValueError – If an invalid numeric type value is assigned.

  `quantity_type`

    Quantity type of the dependent variable.

    There are currently six valid quantity types,

    `scalar`
    `vector_n`
    `pixel_n`
    `matrix_n_m`
    `symmetric_matrix_n`

    where n and m are integers. The value of the attribute is modified with a string containing a valid quantity type.

        >>> y.quantity_type
        'pixel_3'
        >>> y.quantity_type = 'vector_3'

    Returns

      A string with a valid quantity type.

    Raises

      ValueError – If an invalid value is assigned.

  `component_labels`

    List of labels corresponding to the components of the dependent variable.

        >>> y.component_labels
        ['', '', '']

    To update the component_labels, assign an array of strings with same number of elements as the number of components.

        >>> y.component_labels = ['channel 0', 'channel 1', 'channel 2']

    The individual labels are accessed with proper indexing, for example,

        >>> y.component_labels[2]
        'channel 2'

    Todo

    Check the component labels.

    Returns

      A list of component label strings.

    Raises

      TypeError – When the assigned value is not an array of strings.

  `components`

    Component array of the dependent variable.

    The value of this attribute, \(\mathbb{U}\), is a Numpy array of shape \((p \times N_{d-1} \times ... N_1 \times N_0)\) where \(p\) is the number of components, and \(N_k\) is the number of points from the \(k^\mathrm{th}\) Dimension object.

    Note

    The shape of the components Numpy array, \((p \times N_{d-1} \times ... N_1 \times N_0)\), is reverse the shape of the components array, \((N_0 \times N_1 \times ... N_{d-1} \times p)\), from the CSD model. This is because CSD model utilizes a column-major order to shape the components array relative to the order of the dimension while Numpy utilizes a row-major order.

    The dimensionality of this Numpy array is \(d+1\) where \(d\) is the number of dimension objects. The zeroth axis with \(p\) points is the number of components.

    This attribute can only be updated when the shape of the new array is the same as the shape of the components array.

    For example,

        >>> print(y.components.shape)
        (3, 10)
        >>> y.numeric_type
        'float32'

    is a three-component dependent variable with ten data values per component. The numeric type of the data values, in this example, is float32. To update the components array, assign an array of shape (3, 10) to the components attribute. In the following example, we assign a Numpy array,

        >>> y.components = np.linspace(0,256,30, dtype='u1').reshape(3,10)
        >>> y.numeric_type
        'uint8'

    Notice, the value of the numeric_type attribute is automatically updated based on the dtype of the Numpy array. In this case, from a float32 to uint8. In this other example,

        >>> try:
        ...     y.components = np.random.rand(1,10).astype('u1')
        ... except ValueError as e:
        ...     print(e)
        The shape of `ndarray`, `(1, 10)`, is inconsistent
        with the shape of the components array, `(3, 10)`.

    a ValueError is raised because the shape of the input array (1, 10) is not consistent with the shape of the components array, (3, 10).

    Returns

      A Numpy array of components.

    Raises

      ValueError – When assigning an array whose shape is not consistent with the shape of the components array.

  `components_url`

    URL where the data components of the dependent variable are stored.

    This attribute is only informative and cannot be modified. Its value is a string containing the local or remote address of the file where the data values are stored. The attribute is only valid for dependent variable with type, external.

    Returns

      A string containing the URL.

    Raises

      AttributeError – When assigned a value.

  `axis_label`

    List of formatted string labels for each component of the dependent variable.

    This attribute is not a part of the original core scientific dataset model, however, it is a convenient supplementary attribute that provides formated string ready for labeling the components of the dependent variable. The string at index i is formatted as component_labels[i] / unit if component_labels[i] is a non-empty string, otherwise, quantity_name / unit. Here, quantity_name, component_labels, and unit`are the attributes of the :ref:`dv_api instance. For example,

        >>> y.axis_label
        ['energy / (s * W)', 'energy / (s * W)', 'energy / (s * W)']

    Returns

      A list of formated component label strings.

    Raises

      AttributeError – When assigned a value.

  `data_structure`

    Json serialized string describing the DependentVariable class instance.

    This supplementary attribute is useful for a quick preview of the dependent variable object. For convenience, the values from the components attribute are truncated to the first and the last two numbers per component. The encoding keyword is also hidden from this view.

        >>> print(y.data_structure)
        {
          "type": "internal",
          "description": "A test image",
          "name": "star",
          "unit": "s * W",
          "quantity_name": "energy",
          "numeric_type": "float32",
          "quantity_type": "pixel_3",
          "components": [
            [
              "0.0, 1.0, ..., 8.0, 9.0"
            ],
            [
              "10.0, 11.0, ..., 18.0, 19.0"
            ],
            [
              "20.0, 21.0, ..., 28.0, 29.0"
            ]
          ]
        }

    Returns

      A json serialized string of the dependent variable object.

    Raises

      AttributeError – When modified.

  Method Documentation

  `to`(unit)

    Convert the unit of the dependent variable to the unit.

    Parameters

      unit – A string containing a unit with the same dimensionality as the components of the dependent variable.

        >>> y.unit
        Unit("s W")
        >>> print(y.components[0,5])
        5.0
        >>> y.to('mJ')
        >>> y.unit
        Unit("mJ")
        >>> print(y.components[0,5])
        5000.0

    Note

    This method is a wrapper of the to method from the Quantity class.