dcmri.AortaLiver#

class dcmri.AortaLiver(kinetics='1I-IC-D', stationary='UE', sequence='SS', free=None, **params)[source]#

Joint model for aorta and liver signals.

This model uses a whole-body model to simultaneously predict signals in aorta and liver.

For more detail on the whole-body model, see Whole body. For more detail on the liver model, see Liver.

Parameters:

  • kinetics (str, optional) – Tracer-kinetic liver model. See table Kinetic models for the liver for options - only single-inlet models are allowed. Defaults to ‘1I-IC-D’.

  • stationary (str, optional) – For intracellular tracers - stationarity regime of the hepatocytes. The options are ‘UE’, ‘E’, ‘U’ or None. For more detail see Liver. Defaults to ‘UE’.

  • sequence (str, optional) – imaging sequence. Possible values are ‘SS’ and ‘SR’. Defaults to ‘SS’.

  • free (dict, optional) – Dictionary with free parameters and their bounds. If not provided, a default set of free parameters is used. Defaults to None.

  • params (dict, optional) – values for the parameters of the tissue, specified as keyword parameters. Defaults are used for any that are not provided. See tables Aorta-Liver parameters and Aorta-Liver parameter defaults for a list of parameters and their default values.

See also

AortaLiver2scan

Example

Use the model to reconstruct concentrations from experimentally derived signals.

>>> import matplotlib.pyplot as plt
>>> import dcmri as dc

Use fake_tissue to generate synthetic test data from experimentally-derived concentrations:

Use fake_liver to generate synthetic test data:

>>> time, aif, vif, roi, gt = dc.fake_liver()

Since this model generates two time curves, the x- and y-data are tuples:

>>> xdata, ydata = (time,time), (aif,roi)

Build an aorta-liver model and parameters to match the conditions of the fake liver data:

>>> model = dc.AortaLiver(
...     dt = 0.5,
...     tmax = 180,
...     weight = 70,
...     agent = 'gadoxetate',
...     field_strength = 3.0,
...     dose = 0.2,
...     rate = 3,
...     t0 = 10,
...     TR = 0.005,
...     FA = 15,
... )

Train the model on the data:

>>> model.train(xdata, ydata, xtol=1e-3)

Plot the reconstructed signals and concentrations and compare against the experimentally derived data:

>>> model.plot(xdata, ydata)

We can also have a look at the model parameters after training:

>>> model.print_params(round_to=3)
-----------------------------------------
Free parameters with their errors (stdev)
-----------------------------------------
Bolus arrival time (BAT): 17.127 (2.838) sec
Cardiac output (CO): 211.047 (13.49) mL/sec
Heart-lung mean transit time (Thl): 12.503 (3.527) sec
Heart-lung transit time dispersion (Dhl): 0.465 (0.063)
Organs mean transit time (To): 28.413 (10.294) sec
Extraction fraction (Eb): 0.01 (0.623)
Liver extracellular mean transit time (Te): 2.915 (0.588) sec
Liver extracellular dispersion (De): 1.0 (0.19)
Liver extracellular volume fraction (ve): 0.176 (0.015) mL/cm3
Hepatocellular uptake rate (khe): 0.005 (0.001) mL/sec/cm3
Hepatocellular transit time (Th): 600.0 (747.22) sec
Organs extraction fraction (Eo): 0.261 (0.324)
Organs extracellular mean transit time (Toe): 81.765 (329.097) sec
------------------
Derived parameters
------------------
Blood precontrast T1 (T10a): 1.629 sec
Mean circulation time (Tc): 40.916 sec
Liver precontrast T1 (T10l): 0.752 sec
Biliary excretion rate (kbh): 0.001 mL/sec/cm3
Hepatocellular tissue uptake rate (Khe): 0.026 mL/sec/cm3
Biliary tissue excretion rate (Kbh): 0.002 mL/sec/cm3

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

../../_images/dcmri-AortaLiver-1.png

Notes

Table Aorta-Liver parameters lists the parameters that are relevant in each regime. Table Aorta-Liver parameter defaults list all possible parameters and their default settings.

Aorta-Liver parameters#

Parameters

When to use

Further detail

dt, tmax

Always

Time axis for forward model

t0, dose_tolerance

Always

For estimating baseline signal

field_strength, weight, agent, dose, rate

Always

Injection protocol

R10a, R10l, S0a, S0l

Always

Precontrast R1 (Relaxation model parameters) and S0 (Sequence parameters)for aorta and liver

FA, TR, TS

Always

Sequence parameters

TC

If sequence is ‘SR’

Sequence parameters

BAT, CO, Thl, Dhl, To, Eo, Tie, Eb

Always

Whole body

H, ve, De

Always

Kinetic models for the liver

khe, khe_i, kh_f, Th, Th_i, Th_f

Depends on stationary

Kinetic models for the liver
Aorta-Liver parameter defaults#

Parameter

Type

Value

Bounds

Free/Fixed

Simulation

dt

Simulation

0.5

[0, inf]

Fixed

tmax

Simulation

120

[0, inf]

Fixed

dose_tolerance

Simulation

0.1

[0, 1]

Fixed

Injection

field_strength

Injection

3

[0, inf]

Fixed

weight

Injection

70

[0, inf]

Fixed

agent

Injection

‘gadoxetate’

None

Fixed

dose

Injection

0.0125

[0, inf]

Fixed

rate

Injection

1

[0, inf]

Fixed

Signal

R10a

Signal

0.7

[0, inf]

Fixed

R10l

Signal

0.7

[0, inf]

Fixed

S0a

Signal

1

[0, inf]

Free

S0l

Signal

1

[0, inf]

Free

Sequence

FA

Sequence

15

[0, inf]

Fixed

S0

Sequence

1

[0, inf]

Fixed

TC

Sequence

0.1

[0, inf]

Fixed

TR

Sequence

0.005

[0, inf]

Fixed

TS

Sequence

0

[0, inf]

Fixed

Whole body

BAT

Whole body

1200

[0, inf]

Free

CO

Whole body

100

[0, inf]

Free

Thl

Whole body

10

[0, 30]

Free

Dhl

Whole body

0.2

[0.05, 0.95]

Free

To

Whole body

20

[0, 60]

Free

Eo

Whole body

0.15

[0, 0.5]

Free

Toe

Whole body

120

[0, 800]

Free

Eb

Whole body

0.05

[0.01, 0.15]

Free

Liver

H

Kinetic

0.45

[0, 1]

Fixed

Te

Kinetic

30

[0.1, 60]

Free

De

Kinetic

0.85

[0, 1]

Free

ve

Kinetic

0.3

[0.01, 0.6]

Free

khe

Kinetic

0.003

[0, 0.1]

Free

khe_i

Kinetic

0.003

[0, 0.1]

Free

khe_f

Kinetic

0.003

[0, 0.1]

Free

Th

Kinetic

1800

[600, 36000]

Free

Th_i

Kinetic

1800

[600, 36000]

Free

Th_f

Kinetic

1800

[600, 36000]

Free

vol

Kinetic

1000

[0, 10000]

Free

Methods

conc([sum])

Concentrations in aorta and liver.

cost(xdata, ydata[, metric])

Return the goodness-of-fit

export_params()

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[, xlim, ref, 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()

Relaxation rates in aorta and liver.

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(sum=True)[source]#

Concentrations in aorta and liver.

Parameters:

sum (bool, optional) – If set to true, the liver concentrations are the sum over both compartments. If set to false, the compartmental concentrations are returned individually. Defaults to True.

Returns:

time points, aorta blood concentrations, liver

concentrations.

Return type:

tuple

cost(xdata, ydata, metric='NRMS') → float[source]#

Return the goodness-of-fit

Parameters:

  • xdata (tuple) – tuple of 2 arrays with time points for aorta and liver, in that order. The two arrays can be different in length and value.

  • ydata (array-like) – tuple of 2 arrays with signals for aorta and liver, in that order. The arrays can be different in length and value but each has to have the same length as its corresponding array of time points.

  • 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() → list#

Return model parameters with their descriptions

Returns:

Dictionary with one item for each model parameter. The key is the parameter symbol (short name), and the value is a 4-element list with [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: tuple, ydata: tuple, xlim=None, ref=None, fname=None, show=True)[source]#

Plot the model fit against data

Parameters:

  • xdata (tuple) – tuple of 2 arrays with time points for aorta and liver, in that order. The two arrays can be different in length and value.

  • ydata (array-like) – tuple of 2 arrays with signals for aorta and liver, in that order. The arrays can be different in length and value but each has to have the same length as its corresponding array of time points.

  • 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: tuple) → tuple[source]#

Predict the data at given xdata

Parameters:

xdata (tuple) – tuple of 2 arrays with time points for aorta and liver, in that order. The two arrays can be different in length and value.

Returns:

tuple of 2 arrays with signals for aorta and liver, in

that order. The arrays can be different in length and value but each has to have the same length as its corresponding array of time points.

Return type:

tuple

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]#

Relaxation rates in aorta and liver.

Returns:

time points, aorta blood R1, liver

R1.

Return type:

tuple

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: tuple, ydata: tuple, **kwargs)[source]#

Train the free parameters

Parameters:

  • xdata (tuple) – tuple of 2 arrays with time points for aorta and liver, in that order. The two arrays can be different in length and value.

  • ydata (array-like) – tuple of 2 arrays with signals for aorta and liver, in that order. The arrays can be different in length and value but each has to have the same length as its corresponding array of time points.

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

Returns:

A reference to the model instance.

Return type:

Model

Examples using dcmri.AortaLiver#

Clinical - rifampicin induced inhibition (short protocol)

Clinical - rifampicin induced inhibition (short protocol)