suspect.fitting API Reference

suspect.fitting.attenuation_scaling_factor(t1, t2, te, tr)

Calculates the expected attenuation in an MRS signal arising due to T1 and T2 effects, according to the equation: \(\mathrm{e}^{-\frac{TE}{T2}}(1 - \mathrm{e}^{-\frac{TR}{T1}})\)

Parameters:
  • t1 – The T1 of the tissue

  • t2 – The T2 of the tissue

  • te – The echo time of the sequence

  • tr – The repetition time of the sequence

Returns:

The attenuation factor in the observed signal expected due to T1 and T2 effects

Return type:

float

Notes

This function uses the simplified form of the equation, assuming that TE is much shorter than T1 and so the sequence behaves roughly as a 90 pulse followed by a readout, any refocussing pulses do not substantially change the longitudinal magnetisation. If this is not the case then the details of the sequence will be important and a more precise form of this calculation will be required.

suspect.fitting.molar_concentration_factor(f_wm, f_gm, f_csf, te, tr, tissue_params=None)

Calculate the scaling factor necessary to obtain molar metabolite concentrations from a ratio of metabolite to water peak amplitude.

Parameters:
  • f_wm (float) – The fraction of the voxel containing white matter

  • f_gm (float) – The fraction of the voxel containing grey matter

  • f_csf (float) – The fraction of the voxel containing CSF

  • te (float) – The echo time of the sequence

  • tr (float) – The repetition time of the sequence

  • tissue_params (dict, optional) – User supplied values for tissue MR properties including T1 and T2

Returns:

The scaling factor to convert metabolite to water ratios to molar concentrations.

Return type:

float

Notes

The calculation used here follows the form derived in [1].

There are various parameters required for these calculations which can vary, for example with field strength or other conditions. Default values are provided in Suspect (tissue water concentrations are drawn from Gasparovic 2006, relaxation times from Gussew 2012), but they can be overridden by passing in alternative values in the tissue_parameters argument. The relevant parameters are:

Key

Description

Default Value

beta_wm

the water density of white matter

0.65

beta_gm

the water density of grey matter

0.78

beta_csf

the water density of CSF

0.97

h2o_t1_wm

the T1 of water in white matter

1080ms

h2o_t1_gm

the T1 of water in grey matter

1820ms

h2o_t1_csf

the T1 of water in CSF

4160ms

h2o_t2_wm

the T2 of water in white matter

70ms

h2o_t2_gm

the T2 of water in grey matter

100ms

h2o_t2_csf

the T2 of water in CSF

500ms

met_t1

the T1 of metabolites in brain tissue

1400ms

met_t2

the T2 of metabolites in brain tissue

200ms

References

suspect.fitting.tarquin.process(data, wref=None, aq_factor=None, options={})

Runs the Tarquin basis set fitting program to determine metabolite concentrations.

Parameters:
  • data (MRSData) – The water suppressed FID data to be fitted.

  • wref (MRSData) – Optional water reference file for concentration scaling.

  • aq_factor (float) – Absolute quantification factor.

  • options (dict) – Set of Tarquin parameters to override.

Returns:

Output from running Tarquin on the data

Return type:

dict

class suspect.fitting.singlet.GaussianPeak(name, amplitude=1, frequency=0, phase='0', fwhm=20)

Class to represent a Gaussian peak for fitting.

The Gaussian peak is parameterised by 4 values: amplitude, frequency, phase, and FWHM (full width at half maximum).

Each parameter can be specified in three different ways: 1. Passing a numeric value sets the initial guess for that parameter 2. Passing a string of a number fixes that parameter to that value 3. Passing a dictionary allows setting any of the constraints supported

by the underlying LMFit parameter: value, min, max, vary, and expr

By default the phase of the peak will be fixed at 0 and the amplitude and FWHM will be constrained to be bigger than 0 and 1Hz respectively.

Parameters:
  • name – The name of the peak

  • amplitude – The amplitude (area) of the peak

  • frequency – The frequency of the peak in Hertz

  • phase – The phase of the peak in radians

  • fwhm – The full width at half maximum of the peak in Hertz

class suspect.fitting.singlet.Model(peak_models, phase0=0, phase1='0')

A model of an MRS FID signal which can be fitted to data.

This model is created by passing a set of individual peak models, to which it then appends a phase model. By default the first order phase is constrained to be 0.

Parameters:
  • peak_models – The descriptions of the peaks making up the model.

  • phase0 – The estimated zero order phase in radians.

  • phase1 – The estimated first order phase in radians per Hz.

fit(data, baseline_points=4)

Perform a fit of the model to an FID.

Parameters:
  • data – The time domain data to be fitted.

  • baseline_points – The first baseline_points of the FID will be ignored in the fit.

Return type:

ModelResult

classmethod from_dict(model_dict)

Create a model from a dict.

Parameters:

model_dict – dict describing the model.

Returns:

The specified model ready for fitting.

Return type:

Model