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
The dimension subtype.
Brief description of the dimension object.
Application metadata dictionary of the dimension object.
Coordinates, \({\bf X}_k\), along the dimension.
Alias for the coordinates attribute.
Absolute coordinates, \(\bf X_k^{\rm{abs}}\), along the dimension.
Number of coordinates, \(N_k \ge 1\), along the dimension.
Increment along a linear dimension.
Offset corresponding to the zero of the indexes array, \(\mathbf{J}_k\).
Origin offset, \(o_k\), along the dimension.
If true, the coordinates are the ordered as the output of a complex fft.
Quantity name associated with the physical quantities specifying dimension.
Label associated with the dimension.
Ordered list of labels along the Labeled dimension.
Period of the dimension.
Formatted string for displaying label along the dimension axis.
JSON serialized string describing the Dimension class instance.
Methods Summary
Convert the coordinates along the dimension to the unit, unit.
Return Dimension object as a python dictionary.
Alias to the dict() method of the class.
Return True if the dependent variable is quantitative.
Return a copy of the Dimension object.
Return reciprocal coordinates assuming Nyquist-Shannon theorem.
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 oflabels
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
andlabel
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'}