Generating CSDM objects

An empty csdm object

To create a new empty csdm object, import the csdmpy module and create a new instance of the CSDM class following,

>>> import csdmpy as cp
>>> new_data = cp.new(description='A new test dataset')

The new() method returns an instance of the CSDM class with zero dimensions and dependent variables. respectively, i.e., a 0D{0} dataset. In the above example, this instance is assigned to the new_data variable. Optionally, a description may also be provided as an argument of the new() method. The data structure from the above example is

>>> print(new_data.data_structure)
{
  "csdm": {
    "version": "1.0",
    "description": "A new test dataset",
    "dimensions": [],
    "dependent_variables": []
  }
}

From a NumPy array

Perhaps the easiest way to generate a csdm object is to convert the NumPy array holding the dataset as a csdm object using the as_csdm() method, which returns a view of the array as a CSDM object. Here, the NumPy array becomes the dependent variable of the CSDM object of the given quantity_type. Unlike the as_dependent_variable() method, however, the as_csdm() method retains the shape of the Numpy array and uses this information to generate the dimensions of the CSDM object. By default, the dimensions are of a linear subtype with unit increment. Consider the following example.

>>> array = np.arange(30).reshape(3, 10)
>>> csdm_obj = cp.as_csdm(array)
>>> print(csdm_obj)
CSDM(
DependentVariable(
[[[ 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]]], quantity_type=scalar, numeric_type=int64),
LinearDimension([0. 1. 2. 3. 4. 5. 6. 7. 8. 9.]),
LinearDimension([0. 1. 2.])
)

Here, a two-dimensional NumPy array of shape (3, 10) is given as the argument of the as_csdm() method. The resulting CSDM object, csdm_obj, contains a 2D{1} datasets, with two linear dimensions of unit increment and 10 and 3 points, respectively, and a single one-component dependent variable of quantity_type scalar.

Note

The order of the dimensions in the CSDM object is the reverse of the order of axes from the corresponding Numpy array. Thus, the dimension at index 0 of the CSDM object is the last axis of the Numpy array.

You may additionally provide a quantity type as the argument of the as_csdm() method. When the quantity type requires more than one component, see QuantityType, the first axis of the NumPy array must be the number of components. For example,

>>> csdm_obj1 = cp.as_csdm(array, quantity_type='pixel_3')
>>> print(csdm_obj1)
CSDM(
DependentVariable(
[[ 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]], quantity_type=pixel_3, numeric_type=int64),
LinearDimension([0. 1. 2. 3. 4. 5. 6. 7. 8. 9.])
)

Here, the csdm_obj1 object is a 1D{3} datasets, with a single three-component dependent variable. In this case, the length of the NumPy array along axis 0, i.e., 3, is consistent with the number of components required by the quantity type pixel_3. The remaining axes of the NumPy array are used in generating the dimensions of the csdm object. In this example, this corresponds to a single dimension of linear type with 10 points.

The following example generates a 3D{2} vector dataset. Here, the first axis of the four-dimensional Numpy array is the components of the vector dataset, and the remaining three axes become the respective dimensions.

>>> array2 = np.arange(12000).reshape(2,30,20,10)
>>> csdm_obj2 = cp.as_csdm(array2, quantity_type='vector_2')
>>> print(len(csdm_obj2.dimensions), len(csdm_obj2.dependent_variables[0].components))
3 2

An exception will be raised if the quantity_type and the number of points along the first axis of the NumPy array are inconsistent, for example,

>>> csdm_obj_err = cp.as_csdm(array, quantity_type='vector_2')  
ValueError: Expecting exactly 2 components for quantity type, `vector_2`, found 3.
Make sure `array.shape[0]` is equal to the number of components supported by vector_2.

Note

Only a csdm object with a single dependent variable may be created from a NumPy array. To add more dependent variables to the CSDM object, see Adding DependentVariable objects to CSDM object.