Dimension

class csdmpy.Dimension(*args, **kwargs)[source]

Bases: object

Dimension class.

An instance of this class describes a dimension of a multi-dimensional system. In version 1.0 of the CSD model, there are three subtypes of the Dimension class:

Creating an instance of a dimension object

There are two ways of creating a new instance of a Dimension class.

From a python dictionary containing valid keywords.

>>> from csdmpy import Dimension
>>> dimension_dictionary = {
...     "type": "linear",
...     "description": "test",
...     "increment": "5 G",
...     "count": 10,
...     "coordinates_offset": "10 mT",
...     "origin_offset": "10 T",
... }
>>> x = Dimension(dimension_dictionary)

Here, dimension_dictionary is the python dictionary.

From valid keyword arguments.

>>> x = Dimension(
...     type="linear",
...     description="test",
...     increment="5 G",
...     count=10,
...     coordinates_offset="10 mT",
...     origin_offset="10 T",
... )

Attributes Summary

type

The dimension subtype.

description

Brief description of the dimension object.

application

Application metadata dictionary of the dimension object.

coordinates

Coordinates, \({\bf X}_k\), along the dimension.

coords

Alias for the coordinates attribute.

absolute_coordinates

Absolute coordinates, \(\bf X_k^{\rm{abs}}\), along the dimension.

count

Number of coordinates, \(N_k \ge 1\), along the dimension.

increment

Increment along a linear dimension.

coordinates_offset

Offset corresponding to the zero of the indexes array, \(\mathbf{J}_k\).

origin_offset

Origin offset, \(o_k\), along the dimension.

complex_fft

If true, the coordinates are the ordered as the output of a complex fft.

quantity_name

Quantity name associated with the physical quantities specifying dimension.

label

Label associated with the dimension.

labels

Ordered list of labels along the Labeled dimension.

period

Period of the dimension.

axis_label

Formatted string for displaying label along the dimension axis.

data_structure

JSON serialized string describing the Dimension class instance.

Methods Summary

to

Convert the coordinates along the dimension to the unit, unit.

dict

Return Dimension object as a python dictionary.

to_dict

Alias to the dict() method of the class.

is_quantitative

Return True if the dependent variable is quantitative.

copy

Return a copy of the Dimension object.

reciprocal_coordinates

Return reciprocal coordinates assuming Nyquist-Shannon theorem.

reciprocal_increment

Return reciprocal increment assuming Nyquist-Shannon theorem.

Attributes Documentation

type

The dimension subtype.

There are three valid subtypes of Dimension class. The valid literals are given by the DimObjectSubtype enumeration.

>>> print(x.type)
linear
Returns:

A string with a valid dimension subtype.

Raises:

AttributeError – When the attribute is modified.

description

Brief description of the dimension object.

The default value is an empty string, ‘’. The attribute may be modified, for example,

>>> print(x.description)
This is a test

>>> x.description = "This is a test dimension."
Returns:

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

Raises:

TypeError – When the assigned value is not a string.

application

Application metadata dictionary of the dimension object.

>>> print(x.application)
None

The application attribute is where an application can place its metadata as a python dictionary object using a reverse domain name notation string as the attribute key, for example,

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

A python dictionary containing dimension application metadata.

coordinates

Coordinates, \({\bf X}_k\), along the dimension.

Example

>>> print(x.coordinates)
[100. 105. 110. 115. 120. 125. 130. 135. 140. 145.] G

For linear dimensions, the order of the coordinates also depend on the value of the complex_fft attributes. For examples, when the value of the complex_fft attribute is True, the coordinates are

>>> x.complex_fft = True
>>> print(x.coordinates)
[ 75.  80.  85.  90.  95. 100. 105. 110. 115. 120.] G
Returns:

A Quantity array of coordinates for quantitative dimensions, i.e. linear and monotonic.

Returns:

A Numpy array for labeled dimensions.

Raises:

AttributeError – For dimensions with subtype linear.

coords

Alias for the coordinates attribute.

absolute_coordinates

Absolute coordinates, \(\bf X_k^{\rm{abs}}\), along the dimension.

This attribute is only valid for quantitative dimensions, that is, linear and monotonic dimensions. The absolute coordinates are given as

(9)\[\mathbf{X}_k^\mathrm{abs} = \mathbf{X}_k + o_k \mathbf{1}\]

where \(\mathbf{X}_k\) are the coordinates along the dimension and \(o_k\) is the origin_offset. For example, consider

>>> print(x.origin_offset)
10.0 T
>>> print(x.coordinates[:5])
[100. 105. 110. 115. 120.] G

then the absolute coordinates are

>>> print(x.absolute_coordinates[:5])
[100100. 100105. 100110. 100115. 100120.] G

For linear dimensions, the order of the absolute_coordinates further depend on the value of the complex_fft attributes. For examples, when the value of the complex_fft attribute is True, the absolute coordinates are

>>> x.complex_fft = True
>>> print(x.absolute_coordinates[:5])
[100075. 100080. 100085. 100090. 100095.] G
Returns:

A Quantity array of absolute coordinates for quantitative dimensions, i.e linear and monotonic.

Raises:

AttributeError – For labeled dimensions.

count

Number of coordinates, \(N_k \ge 1\), along the dimension.

Example

>>> print(x.count)
10
>>> x.count = 5
Returns:

An Integer specifying the number of coordinates along the dimension.

Raises:

TypeError – When the assigned value is not an integer.

increment

Increment along a linear dimension.

The attribute is only valid for Dimension instances with the subtype linear. When assigning a value, the dimensionality of the value must be consistent with the dimensionality of other members specifying the dimension.

Example

>>> print(x.increment)
5.0 G
>>> x.increment = "0.1 G"
>>> print(x.coordinates)
[100.  100.1 100.2 100.3 100.4 100.5 100.6 100.7 100.8 100.9] G
Returns:

A Quantity instance with the increment along the dimension.

Raises:
  • AttributeError – For dimension with subtypes other than linear.

  • TypeError – When the assigned value is not a string containing a quantity or a Quantity object.

coordinates_offset

Offset corresponding to the zero of the indexes array, \(\mathbf{J}_k\).

When assigning a value, the dimensionality of the value must be consistent with the dimensionality of the other members specifying the dimension.

Example

>>> print(x.coordinates_offset)
10.0 mT
>>> x.coordinates_offset = "0 T"
>>> print(x.coordinates)
[ 0.  5. 10. 15. 20. 25. 30. 35. 40. 45.] G

The attribute is invalid for labeled dimensions.

Returns:

A Quantity instance with the coordinates offset.

Raises:
  • AttributeError – For labeled dimensions.

  • TypeError – When the assigned value is not a string containing a quantity or a Quantity object.

origin_offset

Origin offset, \(o_k\), along the dimension.

When assigning a value, the dimensionality of the value must be consistent with the dimensionality of other members specifying the dimension.

Example

>>> print(x.origin_offset)
10.0 T
>>> x.origin_offset = "1e5 G"

The origin offset only affect the absolute_coordinates along the dimension. This attribute is invalid for labeled dimensions.

Returns:

A Quantity instance with the origin offset.

Raises:
  • AttributeError – For labeled dimensions.

  • TypeError – When the assigned value is not a string containing a quantity or a Quantity object.

complex_fft

If true, the coordinates are the ordered as the output of a complex fft.

This attribute is only valid for the Dimension instances with linear subtype. The value of this attribute is a boolean specifying if the coordinates along the dimension are evaluated as the output of a complex fast Fourier transform (FFT) routine. For example, consider the following Dimension object,

>>> test = Dimension(type="linear", increment="1", count=10)
>>> test.complex_fft
False
>>> print(test.coordinates)
[0. 1. 2. 3. 4. 5. 6. 7. 8. 9.]

>>> test.complex_fft = True
>>> print(test.coordinates)
[-5. -4. -3. -2. -1.  0.  1.  2.  3.  4.]
Returns:

A Boolean.

Raises:

TypeError – When the assigned value is not a boolean.

quantity_name

Quantity name associated with the physical quantities specifying dimension.

The attribute is invalid for the labeled dimension.

>>> print(x.quantity_name)
magnetic flux density
Returns:

A string with the quantity name.

Raises:
  • AttributeError – For labeled dimensions.

  • NotImplementedError – When assigning a value.

label

Label associated with the dimension.

Example

>>> print(x.label)
field strength
>>> x.label = 'magnetic field strength'
Returns:

A string containing the label.

Raises:

TypeError – When the assigned value is not a string.

labels

Ordered list of labels along the Labeled dimension.

Consider the following labeled dimension,

>>> x2 = Dimension(type="labeled", labels=["Cu", "Ag", "Au"])

then the labels along the labeled dimensions are

>>> print(x2.labels)
['Cu' 'Ag' 'Au']

Note

For Labeled dimension, the coordinates attribute is an alias of labels attribute. For example,

>>> bool(np.all(x2.coordinates == x2.labels))
True

In the above example, x2 is an instance of the Dimension class with labeled subtype.

Returns:

A Numpy array with labels along the dimension.

Raises:

AttributeError – For dimensions with subtype other than labeled.

period

Period of the dimension.

The default value of the period is infinity, i.e., the dimension is non-periodic.

Example

>>> print(x.period)
inf G
>>> x.period = '1 T'

To assign a dimension as non-periodic, one of the following may be used,

>>> x.period = "1/0 T"
>>> x.period = "infinity µT"
>>> x.period = "∞ G"

Attention

The physical quantity of the period must be consistent with other physical quantities specifying the dimension.

Returns:

A Quantity instance with the period of the dimension.

Raises:
  • AttributeError – For labeled dimensions.

  • TypeError – When the assigned value is not a string containing a quantity or a Quantity object.

axis_label

Formatted string for displaying label along the dimension axis.

This attribute is not a part of the original core scientific dataset model, however, it is a convenient supplementary attribute that provides a formatted string ready for labeling dimension axes. For quantitative dimensions, this attributes returns a string, label / unit, if the label is a non-empty string, otherwise, quantity_name / unit. Here quantity_name and label are the attributes of the Dimension instances, and unit is the unit associated with the coordinates along the dimension. For examples,

>>> x.label
'field strength'
>>> x.axis_label
'field strength / (G)'

For labeled dimensions, this attribute returns label.

Returns:

A formatted string of label.

Raises:

AttributeError – When assigned a value.

data_structure

JSON serialized string describing the Dimension class instance.

This supplementary attribute is useful for a quick preview of the dimension object. The attribute cannot be modified.

>>> print(x.data_structure)
{
  "type": "linear",
  "count": 10,
  "increment": "5.0 G",
  "coordinates_offset": "10.0 mT",
  "origin_offset": "10.0 T",
  "quantity_name": "magnetic flux density",
  "label": "field strength",
  "description": "This is a test",
  "reciprocal": {
    "quantity_name": "electrical mobility"
  }
}
Returns:

A json serialized string of the dimension object.

Raises:

AttributeError – When modified.

Method Documentation

to(unit='', equivalencies=None, update_attrs=False)[source]

Convert the coordinates along the dimension to the unit, unit.

This method is a wrapper of the to method from the Quantity class and is only valid for physical dimensions.

Example

>>> print(x.coordinates)
[100. 105. 110. 115. 120. 125. 130. 135. 140. 145.] G
>>> x.to('mT')
>>> print(x.coordinates)
[10.  10.5 11.  11.5 12.  12.5 13.  13.5 14.  14.5] mT
Parameters:
  • unit – A string containing a unit with the same dimensionality as the coordinates along the dimension.

  • equivalencies – Convert to equivalent units

  • update_attrs – Update attribute units if equivalencies is None.

Raises:

AttributeError – For labeled dimensions.

dict()[source]

Return Dimension object as a python dictionary.

Example

>>> x.dict() 
{'type': 'linear', 'description': 'This is a test', 'count': 10,
'increment': '5.0 G', 'coordinates_offset': '10.0 mT',
'origin_offset': '10.0 T', 'quantity_name': 'magnetic flux density',
'label': 'field strength'}
to_dict()[source]

Alias to the dict() method of the class.

is_quantitative()[source]

Return True if the dependent variable is quantitative.

Example

>>> x.is_quantitative()
True
copy()[source]

Return a copy of the Dimension object.

reciprocal_coordinates()[source]

Return reciprocal coordinates assuming Nyquist-Shannon theorem.

reciprocal_increment()[source]

Return reciprocal increment assuming Nyquist-Shannon theorem.