===================================== Getting Started With `csdmpy` package ===================================== We have put together a set of guidelines for importing the `csdmpy` package and related methods and attributes. We encourage the users to follow these guidelines to promote consistency, amongst others. Import the package using .. doctest:: >>> import csdmpy as cp To load a `.csdf` or a `.csdfe` file, use the :meth:`~csdmpy.load` method of the `csdmpy` module. In the following example, we load a sample test file. .. doctest:: >>> filename = cp.tests.test01 # replace this with your file's name. >>> testdata1 = cp.load(filename) Here, ``testdata1`` is an instance of the CSDM class. At the root level, the :ref:`csdm_api` object includes various useful optional attributes that may contain additional information about the dataset. One such useful attribute is the :attr:`~csdmpy.csdm.CSDM.description` key, which briefs the end-users on the contents of the dataset. To access the value of this attribute use, .. doctest:: >>> testdata1.description 'A simulated sine curve.' --------------------------------------------------------------- Accessing the dimensions and dependent variables of the dataset --------------------------------------------------------------- An instance of the CSDM object may include multiple dimensions and dependent variables. Collectively, the dimensions form a multi-dimensional grid system, and the dependent variables populate this grid. In `csdmpy`, dimensions and dependent variables are structured as python's tuple object. To access these tuples, use the :attr:`~csdmpy.csdm.CSDM.dimensions` and :attr:`~csdmpy.csdm.CSDM.dependent_variables` attribute of the CSDM object, respectively. For example, .. doctest:: >>> x = testdata1.dimensions >>> y = testdata1.dependent_variables In this example, the dataset contains one dimension and one dependent variable, and therefore, `x` and `y` are tuples with a single instance. .. doctest:: >>> print('x is a {0} of length {1}.'.format(type(x).__name__, len(x))) x is a tuple of length 1. >>> print('y is a {0} of length {1}.'.format(type(y).__name__, len(y))) y is a tuple of length 1. You may access the instances of individual dimension and dependent variable by using the proper indexing. For example, the dimension and dependent variable at index 0 may be accessed using ``x[0]`` and ``y[0]``, respectively. Every instance of the :ref:`dim_api` object has its own set of attributes that further describe the respective dimension. For example, a Dimension object may have an optional :attr:`~csdmpy.dimensions.Dimension.description` attribute, .. doctest:: >>> x[0].description 'A temporal dimension.' Similarly, every instance of the :ref:`dv_api` object has its own set of attributes. In this example, the :attr:`~csdmpy.dependent_variables.DependentVariable.description` attribute from the dependent variable is >>> y[0].description 'A response dependent variable.' Coordinates along the dimension ******************************* Every dimension object contains a list of coordinates associated with every grid index along the dimension. To access these coordinates, use the :attr:`~csdmpy.dimensions.Dimension.coordinates` attribute of the respective :ref:`dim_api` instance. In this example, the coordinates are .. doctest:: >>> x[0].coordinates .. note:: ``x[0].coordinates`` returns a `Quantity `_ instance from the `Astropy `_ package. The `csdmpy` module utilizes the units library from `astropy.units `_ module to handle physical quantities. The numerical `value` and the `unit` of the physical quantities are accessed through the Quantity instance, using the ``value`` and the ``unit`` attributes, respectively. Please refer to the `astropy.units `_ documentation for details. In the `csdmpy` module, the ``Quantity.value`` is a `Numpy array `_. For instance, in the above example, the underlying Numpy array from the coordinates attribute is accessed as .. doctest:: >>> x[0].coordinates.value array([0. , 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9]) Components of the dependent variable ************************************ Every dependent variable object has at least one component. The number of components of the dependent variable is determined from the :attr:`~csdmpy.dependent_variables.DependentVariable.quantity_type` attribute of the dependent variable object. For example, a scalar quantity has one-component, while a vector quantity may have multiple components. To access the components of the dependent variable, use the :attr:`~csdmpy.dependent_variables.DependentVariable.components` attribute of the respective :ref:`dv_api` instance. For example, .. doctest:: >>> y[0].components array([[ 0.0000000e+00, 5.8778524e-01, 9.5105654e-01, 9.5105654e-01, 5.8778524e-01, 1.2246469e-16, -5.8778524e-01, -9.5105654e-01, -9.5105654e-01, -5.8778524e-01]], dtype=float32) The :attr:`~csdmpy.dependent_variables.DependentVariable.components` attribute is a Numpy array. Note, the number of dimensions of this array is :math:`d+1`, where :math:`d` is the number of :ref:`dim_api` objects from the :attr:`~csdmpy.csdm.CSDM.dimensions` attribute. The additional dimension in the Numpy array corresponds to the number of components of the dependent variable. For instance, in this example, there is a single dimension, `i.e.`, :math:`d=1` and, therefore, the value of the :attr:`~csdmpy.dependent_variables.DependentVariable.components` attribute holds a two-dimensional Numpy array of shape .. doctest:: >>> y[0].components.shape (1, 10) where the first element of the shape tuple, `1`, is the number of components of the dependent variable and the second element, `10`, is the number of points along the dimension, `i.e.`, ``x[0].coordinates``. -------------------- Plotting the dataset -------------------- It is always helpful to represent a scientific dataset with visual aids such as a plot or a figure instead of columns of numbers. As such, throughout this documentation, we provide a figure or two for every example dataset. We make use of Python's `Matplotlib library `_ for generating these figures. The users may, however, use their favorite plotting library. .. Attention:: Although we show code for visualizing the dataset, this documentation is not a guide for data visualization. The following snippet plots the dataset from this example. Here, the `axis_label` is an attribute of both Dimension and DependentVariable instances, and the `name` is an attribute of the DependentVariable instance. .. doctest:: >>> import matplotlib.pyplot as plt >>> plt.plot(x[0].coordinates, y[0].components[0]) # doctest: +SKIP >>> plt.xlabel(x[0].axis_label) # doctest: +SKIP >>> plt.ylabel(y[0].axis_label[0]) # doctest: +SKIP >>> plt.title(y[0].name) # doctest: +SKIP >>> plt.show() .. figure:: _images/test.* :figclass: figure-polaroid .. seealso:: :ref:`csdm_api`, :ref:`dim_api`, :ref:`dv_api`, `Quantity `_, `numpy array `_, `Matplotlib library `_