Method

class mrsimulator.Method(*, name: str = None, description: str = None, label: str = None, property_units: Dict = {'magnetic_flux_density': 'T', 'rotor_angle': 'rad', 'rotor_frequency': 'Hz'}, channels: List[Union[str, dict, Isotope]], spectral_dimensions: List[SpectralDimension] = [SpectralDimension(name=None, description=None, label=None, property_units={'spectral_width': 'Hz', 'reference_offset': 'Hz', 'origin_offset': 'Hz'}, count=1024, spectral_width=25000.0, reference_offset=0.0, origin_offset=None, reciprocal=None, events=[])], affine_matrix: List = None, simulation: Union[CSDM, ndarray] = None, experiment: Union[CSDM, ndarray] = None, magnetic_flux_density: ConstrainedFloatValue = 9.4, rotor_frequency: ConstrainedFloatValue = 0.0, rotor_angle: ConstrainedFloatValue = 0.9553166181245)

Bases: Parseable

Base Method class. A method class represents the NMR method.

channels

The value is a list of isotope symbols over which the given method applies. An isotope symbol is given as a string with the atomic number followed by its atomic symbol, for example, ‘1H’, ‘13C’, and ‘33S’. The default is an empty list. The number of isotopes in a channel depends on the method. For example, a BlochDecaySpectrum method is a single channel method, in which case, the value of this attribute is a list with a single isotope symbol, [‘13C’].

Example

>>> bloch = Method(channels=['1H'], spectral_dimensions=[{}])
>>> bloch.channels = ['13C']  # Change channels

Type:

List[Union[str, dict, mrsimulator.spin_system.isotope.Isotope]]

spectral_dimensions

The number of spectral dimensions depends on the given method. For example, a BlochDecaySpectrum method is a one-dimensional method and thus requires a single spectral dimension.

Example

>>> bloch = Method(channels=['1H'], spectral_dimensions=[
...     SpectralDimension(count=8, spectral_width=50)
... ])
>>> # or equivalently
>>> bloch = Method(channels=['1H'], spectral_dimensions=[
...     {"count": 8, "spectral_width": 50}
... ])

Type:

List[mrsimulator.method.spectral_dimension.SpectralDimension]

simulation

An object holding the result of the simulation. The initial value of this attribute is None. A value is assigned to this attribute when you run the simulation using the run() method.

Type:

Union[csdmpy.csdm.CSDM, numpy.ndarray]

experiment

An object holding the experimental measurement for the given method, if available. The default value is None.

Example

>>> bloch.experiment = my_dataset 

Type:

Union[csdmpy.csdm.CSDM, numpy.ndarray]

name

Name or id of the method. The default value is None.

Example

>>> bloch.name = 'BlochDecaySpectrum'
>>> bloch.name
'BlochDecaySpectrum'

Type:

str

label

Label for the method. The default value is None.

Example

>>> bloch.label = 'One pulse acquired spectrum'
>>> bloch.label
'One pulse acquired spectrum'

Type:

str

description

A description of the method. The default value is None.

Example

>>> bloch.description = 'Huh!'
>>> bloch.description
'Huh!'

Type:

str

affine_matrix

A (n x n) affine transformation matrix, where n is the number of spectral_dimensions. If provided, the corresponding affine transformation is applied to the computed frequencies. The default is None, i.e., no transformation is applied.

Example

>>> method = Method(channels=['1H'], spectral_dimensions=[{}, {}]) # 2D method
>>> method.affine_matrix = [[1, -1], [0, 1]]
>>> print(method.affine_matrix)
[[1, -1], [0, 1]]

Type:

List

dict(**kwargs)

Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.

get_symmetry_pathways(symmetry_element: str) → List[SymmetryPathway]

Return a list of symmetry pathways of the method.

Parameters:

symmetry_element (str) – The symmetry element, ‘P’ or ‘D’.

Returns:

A list of SymmetryPathway objects.

Single channel example

Example

>>> from mrsimulator.method import Method
>>> method = Method(
...     channels=['1H'],
...     spectral_dimensions=[
...         {
...             "events": [
...                 {
...                     "fraction": 0.5,
...                     "transition_queries": [{"ch1": {"P": [1]}}]
...                 },
...                 {
...                     "fraction": 0.5,
...                     "transition_queries": [{"ch1": {"P": [0]}}]
...                 }
...             ],
...         },
...         {
...             "events": [
...                 {"transition_queries": [{"ch1": {"P": [-1]}}]},
...             ],
...         }
...     ]
... )
>>> pprint(method.get_symmetry_pathways("P"))
[SymmetryPathway(
    ch1(1H): [1] ⟶ [0] ⟶ [-1]
    total: 1.0 ⟶ 0.0 ⟶ -1.0
)]

Dual channels example

Example

>>> from mrsimulator.method import Method
>>> method = Method(
...     channels=['1H', '13C'],
...     spectral_dimensions=[
...         {
...             "events": [{
...                 "fraction": 0.5,
...                 "transition_queries": [
...                     {"ch1": {"P": [1]}},
...                     {"ch1": {"P": [-1]}},
...                 ]
...             },
...             {
...                 "fraction": 0.5,
...                 "transition_queries": [  # selecting double quantum
...                     {"ch1": {"P": [-1]}, "ch2": {"P": [-1]}},
...                     {"ch1": {"P": [1]}, "ch2": {"P": [1]}},
...                 ]
...             }],
...         },
...         {
...             "events": [{
...                 "transition_queries": [ # selecting single quantum
...                     {"ch1": {"P": [-1]}},
...                 ]
...             }],
...         }
...     ]
... )
>>> pprint(method.get_symmetry_pathways("P"))
[SymmetryPathway(
    ch1(1H): [1] ⟶ [-1] ⟶ [-1]
    ch2(13C): None ⟶ [-1] ⟶ None
    total: 1.0 ⟶ -2.0 ⟶ -1.0
),
 SymmetryPathway(
    ch1(1H): [1] ⟶ [1] ⟶ [-1]
    ch2(13C): None ⟶ [1] ⟶ None
    total: 1.0 ⟶ 2.0 ⟶ -1.0
),
 SymmetryPathway(
    ch1(1H): [-1] ⟶ [-1] ⟶ [-1]
    ch2(13C): None ⟶ [-1] ⟶ None
    total: -1.0 ⟶ -2.0 ⟶ -1.0
),
 SymmetryPathway(
    ch1(1H): [-1] ⟶ [1] ⟶ [-1]
    ch2(13C): None ⟶ [1] ⟶ None
    total: -1.0 ⟶ 2.0 ⟶ -1.0
)]

get_transition_pathways(spin_system) → List[TransitionPathway]

Return a list of transition pathways from the given spin system that satisfy the query selection criterion of the method.

Parameters:

spin_system (SpinSystem) – A SpinSystem object.

Returns:

A list of TransitionPathway objects. Each TransitionPathway object is an ordered collection of Transition objects.

Example

>>> from mrsimulator import SpinSystem
>>> from mrsimulator.method.lib import ThreeQ_VAS
>>> sys = SpinSystem(sites=[{'isotope': '27Al'}, {'isotope': '29Si'}])
>>> method = ThreeQ_VAS(channels=['27Al'])
>>> pprint(method.get_transition_pathways(sys))
[|1.5, -0.5⟩⟨-1.5, -0.5| ⟶ |-0.5, -0.5⟩⟨0.5, -0.5|, weight=(1+0j),
 |1.5, -0.5⟩⟨-1.5, -0.5| ⟶ |-0.5, 0.5⟩⟨0.5, 0.5|, weight=(1+0j),
 |1.5, 0.5⟩⟨-1.5, 0.5| ⟶ |-0.5, -0.5⟩⟨0.5, -0.5|, weight=(1+0j),
 |1.5, 0.5⟩⟨-1.5, 0.5| ⟶ |-0.5, 0.5⟩⟨0.5, 0.5|, weight=(1+0j)]

json(units=True) → dict

Parse the class object to a JSON compliant python dictionary object.

Parameters:

units – If true, the attribute value is a physical quantity expressed as a string with a number and a unit, else a float.

Returns: dict

classmethod parse_dict_with_units(py_dict)

Parse the physical quantity from a dictionary representation of the Method object, where the physical quantity is expressed as a string with a number and a unit.

Parameters:

py_dict (dict) – A python dict representation of the Method object.

Returns:

A Method object.

plot(df=None, include_legend=False) → figure

Creates a diagram representing the method. By default, only parameters which vary throughout the method are plotted. Figure can be finley adjusted using matplotlib rcParams.

Parameters:

• df (DataFrame) – DataFrame to plot data from. By default DataFrame is calculated from summary() and will show only parameters which vary throughout the method plus ‘p’ symmetry pathway and ‘d’ symmetry pathway if it is not none or defined

• include_legend (bool) – Optional argument to include a key for event colors. Default is False and no key will be included in figure

Returns:

matplotlib.pyplot.figure

Example

>>> from mrsimulator.method.lib import BlochDecaySpectrum
>>> method = BlochDecaySpectrum(channels=["13C"])
>>> fig = method.plot()

Adjusting Figure Size rcParams

>>> import matplotlib as mpl
>>> from mrsimulator.method.lib import FiveQ_VAS
>>> mpl.rcParams["figure.figsize"] = [14, 10]
>>> mpl.rcParams["font.size"] = 14
>>> method = FiveQ_VAS(channels=["27Al"])
>>> fig = method.plot(include_legend=True)

Plotting all Parameters, including Constant

>>> from mrsimulator.method.lib import FiveQ_VAS
>>> method = FiveQ_VAS(channels=["27Al"])
>>> df = method.summary(drop_constant_columns=False)
>>> fig = method.plot(df=df)

reduced_dict(exclude={}) → dict

Returns a reduced dictionary representation of the class object by removing all key-value pair corresponding to keys listed in the exclude argument, and keys with value as None.

Parameters:

exclude – A list of keys to exclude from the dictionary.

Return: A dict.

shape() → tuple

The shape of the method’s spectral dimension array.

Returns:

tuple

Example

>>> from mrsimulator.method import Method
>>> method = Method(
...     channels=['1H'],
...     spectral_dimensions=[{'count': 40}, {'count': 10}]
... )
>>> method.shape()
(40, 10)

summary(drop_constant_columns=True) → DataFrame

Returns a DataFrame giving a summary of the Method. A user can specify optional attributes to include which appear as columns in the DataFrame. A user can also ask to leave out attributes which remain constant throughout the method. Invalid attributes for an Event will be replaced with NAN.

Parameters:

drop_constant_columns ((bool)) – Removes constant properties if True. Default is True.

Returns:

Event number as row and property as column. Invalid properties for an

event type are filled with np.nan

Columns

• (str) type: Event type

• (int) spec_dim_index: Index of spectral dimension which event belongs to

• (str) label: Event label

• (float) duration: Duration of the DelayEvent

• (float) fraction: Fraction of the SpectralEvent

• (MixingQuery) query: MixingQuery object of the MixingEvent

• (float) magnetic_flux_density: Magnetic flux density during event in Tesla

• (float) rotor_frequency: Rotor frequency during event in Hz

• (float) rotor_angle: Rotor angle during event converted to Degrees

• (FrequencyEnum) freq_contrib: Frequency

Return type:

pd.DataFrame df

Example

All Possible Columns

>>> from mrsimulator.method.lib import ThreeQ_VAS
>>> method = ThreeQ_VAS(channels=["17O"])
>>> df = method.summary(drop_constant_columns=False)
>>> pprint(list(df.columns))
['type',
 'spec_dim_index',
 'spec_dim_label',
 'label',
 'duration',
 'fraction',
 'query',
 'magnetic_flux_density',
 'rotor_frequency',
 'rotor_angle',
 'freq_contrib',
 'p',
 'd']