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"
}
}
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.