dcmri.Aorta#

class dcmri.Aorta(organs='comp', heartlung='pfcomp', sequence='SS', **params)[source]#

Whole-body model for the aorta signal.

This model uses a whole body model to predict the signal in the aorta (see Whole body).

See also

AortaKidneys, AortaLiver

Parameters:

  • organs (str, optional) – Model for the organs in the whole-body model. The options are ‘comp’ (one compartment) and ‘2cxm’ (two-compartment exchange). Defaults to ‘comp’.

  • heartlung (str, optional) – Model for the heart-lung system in the whole-body model. Options are ‘comp’ (compartment), ‘pfcomp’ (plug-flow compartment) or ‘chain’. Defaults to ‘pfcomp’.

  • sequence (str, optional) – imaging sequence model. Possible values are ‘SS’ (steady-state), ‘SR’ (saturation-recovery), ‘SSI’ (steady state with inflow correction) and ‘lin’ (linear). Defaults to ‘SS’.

  • params (dict, optional) – values for the model parameters, specified as keyword parameters. Defaults are used for any that are not provided. See table Aorta parameters. for a list of parameters and their default values.

Notes

In the table below, if Bounds is None, the parameter is fixed during training. Otherwise it is allowed to vary between the bounds given.

Aorta parameters.#

Parameter

Value

Bounds

Usage

General

dt

0.25

None

Always

tmax

120

None

Always

dose_tolerance

0.1

None

Always

t0

0

None

Always

field_strength

3

None

Always

Injection

agent

‘gadoxetate’

None

Always

weight

70

None

Always

dose

0.0125

None

Always

rate

1

None

Always

BAT

60

[0, inf]

Always

Sequence

TS

0

None

Always

TR

0.005

None

sequence in [‘SS’, ‘SSI’]

FA

15

None

sequence in [‘SR’, ‘SS’, ‘SSI’]

TC

0.1

None

sequence == ‘SR’

TF

0

None

sequence == ‘SSI’

Aorta

CO

100

[0, 300]

Always

Thl

10

[0, 30]

Always

Dhl

0.2

[0.05, 0.95]

heartlung in [‘pfcomp’, ‘chain’]

To

20

[0, 60]

Always

Eo

0.15

[0, 0.5]

organs == ‘2cxm’

Toe

120

[0, 800]

organs == ‘2cxm’

Eb

0.05

[0.01, 0.15]

Always

R10

0.7

None

Always

S0

1

None

Always

Example

Use the model to fit minipig aorta data with inflow correction:

>>> import numpy as np
>>> import pydmr
>>> import dcmri as dc

Read the dataset:

>>> datafile = dc.fetch('minipig_renal_fibrosis')
>>> data = pydmr.read(datafile, 'nest')
>>> rois, pars = data['rois']['Pig']['Test'], data['pars']['Pig']['Test']

Initialize the tissue:

>>> aorta = dc.Aorta(
...     sequence='SSI',
...     heartlung='chain',
...     organs='comp',
...     field_strength=pars['B0'],
...     t0=15,
...     agent="gadoterate",
...     weight=pars['weight'],
...     dose=pars['dose'],
...     rate=pars['rate'],
...     TR=pars['TR'],
...     FA=pars['FA'],
...     TS=pars['TS'],
...     CO=60,
...     R10=1/dc.T1(pars['B0'], 'blood'),
... )

Create an array of time points:

>>> time = pars['TS'] * np.arange(len(rois['Aorta']))

Train the system to the data:

>>> aorta.train(time, rois['Aorta'])

Plot the reconstructed signals and concentrations:

>>> aorta.plot(time, rois['Aorta'])

Print the model parameters:

>>> aorta.print_params(round_to=4)

(Source code, png, hires.png, pdf)

../_images/dcmri-Aorta-1.png

Methods

conc()

Aorta blood concentration

cost(xdata, ydata[, metric])

Return the goodness-of-fit

export_params([type])

Return model parameters with their descriptions

load([file, path, filename])

Load the saved state of the model

params(*args[, round_to])

Return the parameter values

plot(xdata, ydata[, ref, xlim, fname, show])

Plot the model fit against data

predict(xdata)

Predict the data at given xdata

print_params([round_to])

Print the model parameters and their uncertainties

relax()

Aorta longitudinal relation rate

save([file, path, filename])

Save the current state of the model

set_free([pop])

Set the free model parameters.

train(xdata, ydata, **kwargs)

Train the free parameters
conc()[source]#

Aorta blood concentration

Parameters:

t (array-like) – Time points of the concentration (sec)

Returns:

Concentration in M

Return type:

numpy.ndarray

cost(xdata, ydata, metric='NRMS')#

Return the goodness-of-fit

Parameters:

  • xdata (array-like) – Array with x-data (time points).

  • ydata (array-like) – Array with y-data (signal values)

  • metric (str, optional) – Which metric to use (see notes for possible values). Defaults to ‘NRMS’.

Returns:

goodness of fit.

Return type:

float

Notes

Available options are:

  • ‘RMS’: Root-mean-square.

  • ‘NRMS’: Normalized root-mean-square.

  • ‘AIC’: Akaike information criterion.

  • ‘cAIC’: Corrected Akaike information criterion for small models.

  • ‘BIC’: Baysian information criterion.

export_params(type='dict')#

Return model parameters with their descriptions

Parameters:

type (str, optional) – Type of output. If ‘dict’, a dictionary is returned. If ‘list’, a list is returned. Defaults to ‘dict’.

Returns:

Dictionary with one item for each model parameter. The key is the short parameter name, and the value is a 4-element list with [long parameter name, value, unit, sdev].

or:

list: List with one element for each model parameter. Each element is a list with [short parameter name, long parameter name, value, unit, sdev].

Return type:

dict

load(file=None, path=None, filename='Model')#

Load the saved state of the model

Parameters:

  • file (str, optional) – complete path of the file. If this is not provided, a file is constructure from path and filename variables. Defaults to None.

  • path (str, optional) – path to store the state if file is not provided. Thos variable is ignored if file is provided. Defaults to current working directory.

  • filename (str, optional) – filename to store the state if file is not provided. If no extension is included, the extension ‘.pkl’ is automatically added. This variable is ignored if file is provided. Defaults to ‘Model’.

Returns:

class instance

Return type:

dict

params(*args, round_to=None)#

Return the parameter values

Parameters:

  • args (tuple) – parameters to get

  • round_to (int, optional) – Round to how many digits. If this is

  • provided (not)

  • None. (the values are not rounded. Defaults to)

Returns:

values of parameter values, or a scalar value if only one parameter is required.

Return type:

list or float

plot(xdata, ydata, ref=None, xlim=None, fname=None, show=True)[source]#

Plot the model fit against data

Parameters:

  • xdata (array-like) – Array with x-data (time points)

  • ydata (array-like) – Array with y-data (signal data)

  • xlim (array_like, optional) – 2-element array with lower and upper boundaries of the x-axis. Defaults to None.

  • ref (tuple, optional) – Tuple of optional test data in the form (x,y), where x is an array with x-values and y is an array with y-values. Defaults to None.

  • fname (path, optional) – Filepath to save the image. If no value is provided, the image is not saved. Defaults to None.

  • show (bool, optional) – If True, the plot is shown. Defaults to True.

predict(xdata)[source]#

Predict the data at given xdata

Parameters:

xdata (array-like) – Either an array with x-values (time points) or a tuple with multiple such arrays

Returns:

Either an array of predicted y-values (if

xdata is an array) or a tuple of such arrays (if xdata is a tuple).

Return type:

tuple or array-like

print_params(round_to=None)#

Print the model parameters and their uncertainties

Parameters:

round_to (int, optional) – Round to how many digits. If this is not provided, the values are not rounded. Defaults to None.

relax()[source]#

Aorta longitudinal relation rate

Parameters:

t (array-like) – Time points of the concentration (sec)

Returns:

Concentration in M

Return type:

numpy.ndarray

save(file=None, path=None, filename='Model')#

Save the current state of the model

Parameters:

  • file (str, optional) – complete path of the file. If this is not provided, a file is constructure from path and filename variables. Defaults to None.

  • path (str, optional) – path to store the state if file is not provided. Thos variable is ignored if file is provided. Defaults to current working directory.

  • filename (str, optional) – filename to store the state if file is not provided. If no extension is included, the extension ‘.pkl’ is automatically added. This variable is ignored if file is provided. Defaults to ‘Model’.

Returns:

class instance

Return type:

dict

set_free(pop=None, **kwargs)#

Set the free model parameters.

Parameters:

pop (str or list) – a single variable or a list of variables to remove from the list of free parameters.

Raises:

  • ValueError – if the pop argument contains a parameter that is not in the list of free parameters.

  • ValueError – If the parameter is not a model parameter, or bounds are not properly formatted.

train(xdata, ydata, **kwargs)[source]#

Train the free parameters

Parameters:

  • xdata (array-like) – Array with x-data (time points)

  • ydata (array-like) – Array with y-data (signal data)

  • kwargs – any keyword parameters accepted by scipy.optimize.curve_fit.

Returns:

A reference to the model instance.

Return type:

Model