CSDM — csdmpy 0.1.1 documentation

# CSDM

class `csdmpy.csdm.` `CSDM`(filename='', version=None, description='')

  Bases: `object`

  Create an instance of a CSDM class.

  This class is based on the root CSDM object of the core scientific dataset (CSD) model. The class is a composition of the DependentVariable and Dimension instances, where an instance of the DependentVariable class describes a \(p\)-component dependent variable, and an instance of the Dimension class describes a dimension of a \(d\)-dimensional space. Additional attributes of this class is listed below.

  Attributes Summary

  `version` | Version number of the CSD model on file.
  `description` | Description of the dataset.
  `read_only` | If True, the data-file is serialized as read only, otherwise, False.
  `timestamp` | Timestamp from when the file was last serialized.
  `geographic_coordinate` | Geographic coordinate, if present, from where the file was last serialized.
  `dimensions` | Tuple of Dimension instances.
  `dependent_variables` | Tuple of DependentVariable instances.
  `application` | Application metadata dictionary of the CSDM object.
  `data_structure` | Json serialized string describing the CSDM class instance.
  `filename` | Local file address of the current file.

  Methods Summary

  `add_dimension`(*args, **kwargs) | Add a new Dimension instance to the CSDM instance.
  `add_dependent_variable`(*args, **kwargs) | Add a new DependentVariable instance to the CSDM instance.
  `save`([filename, read_only, version, …]) | Serialize the CSDM instance as a JSON data-exchange file.
  `copy`() | Create a copy of the current CSDM instance.

  Attributes Documentation

  `version`

    Version number of the CSD model on file.

  `description`

    Description of the dataset.

    The default value is an empty string, ‘’.

    Example

        >>> print(data.description)
        A simulated sine curve.

    Returns

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

    Raises

      TypeError – When the assigned value is not a string.

  `read_only`

    If True, the data-file is serialized as read only, otherwise, False.

    By default, the CSDM object loads a copy of the .csdf(e) file, irrespective of the value of the read_only attribute. The value of this attribute may be toggled at any time after the file import. When serializing the .csdf(e) file, if the value of the read_only attribute is found True, the file will be serialized as read only.

  `timestamp`

    Timestamp from when the file was last serialized.

    The timestamp stamp is a string representation of the Coordinated Universal Time (UTC) formatted according to the iso-8601 standard.

    Raises

      AttributeError – When the attribute is modified.

  `geographic_coordinate`

    Geographic coordinate, if present, from where the file was last serialized.

    The geographic coordinates correspond to the location where the file was last serialized. If present, the geographic coordinates are described with three attributes, the required latitude and longitude, and an optional altitude.

    Raises

      AttributeError – When the attribute is modified.

  `dimensions`

    Tuple of Dimension instances.

  `dependent_variables`

    Tuple of DependentVariable instances.

  `application`

    Application metadata dictionary of the CSDM object.

        >>> print(data.application)
        {}

    By default, the application attribute is an empty dictionary, that is, the application metadata stored by the previous application is ignored upon file import.

    The application metadata may, however, be retained with a request via the `load()` method. This feature may be useful to related applications where application metadata might contain additional information. The attribute may be updated with a python dictionary.

    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,

    Example

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

    Returns

      Python dictionary object with the application metadata.

  `data_structure`

    Json serialized string describing the CSDM class instance.

    The data_structure attribute is only intended for a quick preview of the dataset. This JSON serialized string from this attribute avoids displaying large datasets. Do not use the value of this attribute to save the data to a file, instead use the `save()` methods of the instance.

    Raises

      AttributeError – When modified.

  `filename`

    Local file address of the current file.

  Methods Documentation

  `add_dimension`(*args, **kwargs)

    Add a new Dimension instance to the CSDM instance.

    There are three ways to add a new independent variable.

    From a python dictionary containing valid keywords.

        >>> import csdmpy as cp
        >>> datamodel = cp.new()
        >>> py_dictionary = {
        ...     'type': 'linear',
        ...     'increment': '5 G',
        ...     'count': 50,
        ...     'coordinates_offset': '-10 mT'
        ... }
        >>> datamodel.add_dimension(py_dictionary)

    From a list of valid keyword arguments.

        >>> datamodel.add_dimension(
        ...     type = 'linear',
        ...     increment = '5 G',
        ...     count = 50,
        ...     coordinates_offset = '-10 mT'
        ... )

    From an Dimension instance.

        >>> from csdmpy import Dimension
        >>> datamodel = cp.new()
        >>> var1 = Dimension(type = 'linear',
        ...                  increment = '5 G',
        ...                  count = 50,
        ...                  coordinates_offset = '-10 mT')
        >>> datamodel.add_dimension(var1)
        >>> print(datamodel.data_structure)
        {
          "csdm": {
            "version": "1.0",
            "dimensions": [
              {
                "type": "linear",
                "count": 50,
                "increment": "5.0 G",
                "coordinates_offset": "-10.0 mT",
                "quantity_name": "magnetic flux density"
              }
            ],
            "dependent_variables": []
          }
        }

    For the last method, the instance `var1` is added to the `datamodel` as a reference, i.e., if the instance `var1` is destroyed, the `datamodel` instance will become corrupt. As a recommendation always pass a copy of the Dimension instance to the `add_dimension()` method. We provide the later alternative for it is useful for copying an Dimension instance from one CSDM instance to another.

  `add_dependent_variable`(*args, **kwargs)

    Add a new DependentVariable instance to the CSDM instance.

    There are again three ways to add a new dependent variable instance.

    From a python dictionary containing valid keywords.

        >>> import numpy as np

        >>> datamodel = cp.new()

        >>> numpy_array = (100*np.random.rand(3,50)).astype(np.uint8)
        >>> py_dictionary = {
        ...     'type': 'internal',
        ...     'components': numpy_array,
        ...     'name': 'star',
        ...     'unit': 'W s',
        ...     'quantity_name': 'energy',
        ...     'quantity_type': 'pixel_3'
        ... }
        >>> datamodel.add_dependent_variable(py_dictionary)

    From a list of valid keyword arguments.

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

    From a DependentVariable instance.

        >>> from csdmpy import DependentVariable
        >>> var1 = DependentVariable(type='internal',
        ...                          name='star',
        ...                          unit='W s',
        ...                          quantity_type='pixel_3',
        ...                          components=numpy_array)
        >>> datamodel.add_dependent_variable(var1)

    If passing a DependentVariable instance, as a general recommendation, always pass a copy of the DependentVariable instance to the `add_dependent_variable()` method. We provide the later alternative as it is useful for copying a DependentVariable instance from one CSDM instance to another.

  `save`(filename='', read_only=False, version='1.0', output_device=None)

    Serialize the CSDM instance as a JSON data-exchange file.

    The serialized file is saved with two file extensions. When every instance of the DependentVariable class from the CSDM instance has an internal subtype, the corresponding CSDM instance is serialized with a .csdf file extension. If any single DependentVariable instance has an external subtype, the CSDM instance is serialized with a .csdfe file extension. We use the two different file extensions to alert the end use of the possible deserialization error associated with the .csdfe file extensions when the external data file is inaccessible.

    Important

    Irrespective of the subtypes from the serialized JSON file, by default, all instances of DependentVariable class are assigned an internal subtype upon import with base64 as the value of the encoding attribute. The user may, however, change these attribute at any time after the file import and before serializing to a file.

    Parameters

      - filename (str) – The filename of the serialized file.

      - read_only (bool) – If true, the file is serialized as read_only.

      - version (str) – The file is serialized with the given CSD model version.

      - output_device (object) – Object where the data is written.

    Example

        >>> data.save('my_file.csdf')

  `copy`()

    Create a copy of the current CSDM instance.

    Returns

      A CSDM instance.