csdmpy

The csdmpy is a python package for importing and exporting files serialized with the core scientific dataset model file-format. The package supports a \(p\)-component dependent variable, \(\mathbf{U} \equiv \{\mathbf{U}_{0}, \ldots,\mathbf{U}_{q}, \ldots,\mathbf{U}_{p-1} \}\), which is discretely sampled at \(M\) unique points in a \(d\)-dimensional space \((\mathbf{X}_0, \ldots \mathbf{X}_k, \ldots \mathbf{X}_{d-1})\). Besides, the package also supports multiple dependent variables, \(\mathbf{U}_i\), sharing the same \(d\)-dimensional space.

Here, every dataset is an instance of the CSDM class, which holds a list of dimensions and dependent variables. Every dimension, \(\mathbf{X}_k\), is an instance of the Dimension class, while every dependent variable, \(\mathbf{U}_i\), is an instance of the DependentVariable class.

Methods

Methods Summary

parse_dict

Parse a CSDM compliant python dictionary and return a CSDM object.

load

Loads a .csdf/.csdfe file and returns an instance of the CSDM class.

loads

Loads a JSON serialized string as a CSDM object.

new

Creates a new instance of the CSDM class containing a 0D{0} dataset.

as_dimension

Generate and return a Dimension object from a 1D numpy array.

as_dependent_variable

Generate and return a DependentVariable object from a 1D or 2D numpy array.

as_csdm

Generate and return a view of the nD numpy array as a csdm object.

plot

A supplementary function for plotting basic 1D and 2D datasets only.

join

Join dependent-variables of CSDM objects sharing the same dimensions into one CSDM object.

Method Documentation

csdmpy.parse_dict(dictionary)[source]

Parse a CSDM compliant python dictionary and return a CSDM object.

Parameters:

dictionary – A CSDM compliant python dictionary.

csdmpy.load(filename=None, application=False, verbose=False)[source]

Loads a .csdf/.csdfe file and returns an instance of the CSDM class.

The file must be a JSON serialization of the CSD Model.

Example

>>> data1 = cp.load('local_address/file.csdf') 
>>> data2 = cp.load('url_address/file.csdf') 
Parameters:
  • filename (str) – A local or a remote address to the .csdf or `.csdfe file.

  • application (bool) – If true, the application metadata from application that last serialized the file will be imported. Default is False.

  • verbose (bool) – If the filename is a URL, this option will show the progress bar for the file download status, when True.

Returns:

A CSDM instance.

csdmpy.loads(string)[source]

Loads a JSON serialized string as a CSDM object.

Parameters:

string – A JSON serialized CSDM string.

Returns:

A CSDM object.

Example

>>> object_from_string = cp.loads(cp.new('A test dump').dumps())
>>> print(object_from_string.data_structure)  
{
  "csdm": {
    "version": "1.0",
    "timestamp": "2019-10-21T20:33:17Z",
    "description": "A test dump",
    "dimensions": [],
    "dependent_variables": []
  }
}
csdmpy.new(description='')[source]

Creates a new instance of the CSDM class containing a 0D{0} dataset.

Parameters:

description (str) – A string describing the csdm object. This is optional.

Example

>>> import csdmpy as cp
>>> empty_data = cp.new(description='Testing Testing 1 2 3')
>>> print(empty_data.data_structure)
{
  "csdm": {
    "version": "1.0",
    "description": "Testing Testing 1 2 3"
  }
}
Returns:

A CSDM instance.

csdmpy.as_csdm(array, unit='', quantity_type='scalar')[source]

Generate and return a view of the nD numpy array as a csdm object. The nD array is the dependent variable of the csdm object of the given quantity type. The shape of the nD array is used to generate Dimension object of linear subtype.

Parameters:
  • array – The nD numpy array.

  • unit – The unit for the dependent variable. The default is empty string.

  • quantity_type – The quantity type of the dependent variable.

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.])
)
csdmpy.as_dimension(array, unit='', type=None, **kwargs)[source]

Generate and return a Dimension object from a 1D numpy array.

Parameters:
  • array – A 1D numpy array.

  • unit – The unit of the coordinates along the dimension.

  • type – The dimension type. Valid values are linear, monotonic, labeled, or None. If the value is None, let us decide. The default value is None.

  • kwargs – Additional keyword arguments from the Dimension class.

Example

>>> array = np.arange(15)*0.5
>>> dim_object = cp.as_dimension(array)
>>> print(dim_object)
LinearDimension([0.  0.5 1.  1.5 2.  2.5 3.  3.5 4.  4.5 5.  5.5 6.  6.5 7. ])
>>> array = ['The', 'great', 'circle']
>>> dim_object = cp.as_dimension(array, label='in the sky')
>>> print(dim_object)
LabeledDimension(['The' 'great' 'circle'])
csdmpy.as_dependent_variable(array, **kwargs)[source]

Generate and return a DependentVariable object from a 1D or 2D numpy array.

Parameters:
  • array – A 1D or 2D numpy array.

  • kwargs – Additional keyword arguments from the DependentVariable class.

Example

>>> array = np.arange(1e4).astype(np.complex128)
>>> dim_object = cp.as_dependent_variable(array)
>>> print(dim_object)
DependentVariable(
[[0.000e+00+0.j 1.000e+00+0.j 2.000e+00+0.j ... 9.997e+03+0.j
  9.998e+03+0.j 9.999e+03+0.j]], quantity_type=scalar, numeric_type=complex128)
csdmpy.plot(csdm_object, reverse_axis=None, range=None, **kwargs)[source]

A supplementary function for plotting basic 1D and 2D datasets only.

Parameters:
  • csdm_object – The CSDM object.

  • reverse_axis – An ordered array of boolean specifying which dimensions will be displayed on a reverse axis.

  • range – A list of minimum and maximum coordinates along the dimensions. The range along each dimension is given as [min, max]

  • kwargs

    Additional keyword arguments are used in matplotlib plotting functions. We implement the following matplotlib methods for the one and two-dimensional datasets.

    • The 1D{1} scalar dataset use the plt.plot() method.

    • The 1D{2} vector dataset use the plt.quiver() method.

    • The 2D{1} scalar dataset use the plt.imshow() method if the two dimensions have a linear subtype. If any one of the dimension is monotonic, plt.NonUniformImage() method is used instead.

    • The 2D{2} vector dataset use the plt.quiver() method.

    • The 2D{3} pixel dataset use the plt.imshow(), assuming the pixel dataset as an RGB image.

Returns:

A matplotlib figure instance.

Example

>>> cp.plot(data_object) 
csdmpy.join(objects)[source]

Join dependent-variables of CSDM objects sharing the same dimensions into one CSDM object.

Parameters:

objects – A list of CSDM objects with same dimensions.