dcmri.AortaPortalLiver#

class dcmri.AortaPortalLiver(kinetics='2I-EC', stationary='UE', sequence='SS', free=None, **params)[source]#

Joint model for aorta, portal vein and liver signals.

This model uses a whole-body model to simultaneously predict signals in aorta, portal vein 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 dual-inlet models are allowed. Defaults to ‘2I-EC’.

  • 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 ‘SSI’ (steady-state with aortic inflow correction). 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

AortaLiver

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, _ = dc.fake_liver(sequence='SSI')

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

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

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

>>> model = dc.AortaPortalLiver(
...     kinetics = '2I-IC',
...     sequence = 'SSI',
...     dt = 0.5,
...     tmax = 180,
...     weight = 70,
...     agent = 'gadoxetate',
...     dose = 0.2,
...     rate = 3,
...     field_strength = 3.0,
...     t0 = 10,
...     TR = 0.005,
...     FA = 15,
...     TS = 0.5,
... )

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 stdev
--------------------------------
First bolus arrival time (BAT): 14.616 (1.1) sec
Cardiac output (CO): 100.09 (2.736) mL/sec
Heart-lung mean transit time (Thl): 14.402 (1.375) sec
Heart-lung dispersion (Dhl): 0.391 (0.013)
Organs blood mean transit time (To): 27.811 (5.291) sec
Organs extraction fraction (Eo): 0.29 (0.105)
Organs extravascular mean transit time (Toe): 70.621 (102.614) sec
Body extraction fraction (Eb): 0.013 (0.23)
Aorta inflow time (TF): 0.409 (0.014) sec
Liver extracellular volume fraction (ve): 0.479 (0.112) mL/cm3
Liver plasma flow (Fp): 0.018 (0.001) mL/sec/cm3
Arterial flow fraction (fa): 0.087 (0.074)
Arterial transit time (Ta): 2.398 (1.356) sec
Hepatocellular uptake rate (khe): 0.006 (0.003) mL/sec/cm3
Hepatocellular mean transit time (Th): 683.604 (2554.75) sec
Gut mean transit time (Tg): 10.782 (0.614) sec
Gut dispersion (Dg): 0.893 (0.07)
----------------------------
Fixed and derived parameters
----------------------------
Hematocrit (H): 0.45
Arterial venous blood flow (Fa): 0.002 mL/sec/cm3
Portal venous blood flow (Fv): 0.016 mL/sec/cm3
Extracellular mean transit time (Te): 27.216 sec
Biliary tissue excretion rate (Kbh): 0.001 mL/sec/cm3
Hepatocellular tissue uptake rate (Khe): 0.012 mL/sec/cm3
Biliary excretion rate (kbh): 0.001 mL/sec/cm3

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

../../_images/dcmri-AortaPortalLiver-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, S0v, S0l

Always

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

FA, TR, TS

Always

Sequence parameters

TF

If sequence is ‘SSI’

To model aorta inflow effects

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

Always

Whole body

Tg , Dg

Always

Gut dispersion

H, ve, Fp, fa, Ta, Tg, khe, khe_i, kh_f, Th, Th_i, Th_f.

Depends on kinetics and 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

S0v

Signal

1

[0, inf]

Free

S0l

Signal

1

[0, inf]

Free

Sequence

FA

Sequence

15

[0, inf]

Fixed

S0

Sequence

1

[0, inf]

Fixed

TF

Sequence

0.5

[0, 10]

Free

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

Portal vein

Tg

Kinetic

15

[0.1, 60]

Free

Dg

Kinetic

0.85

[0, 1]

Free

uv

Kinetic

1

[0, 1]

Free

Liver

H

Kinetic

0.45

[0, 1]

Fixed

ve

Kinetic

0.3

[0.01, 0.6]

Free

Fp

Kinetic

0.01

[0, 0.1]

Free

fa

Kinetic

0.2

[0, 0.1]

Free

Ta

Kinetic

0.5

[0, 3]

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.

cost(time, signal[, 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(time, signal[, xlim, ref, fname, show])

Plot the model fit against data

predict(time)

Predict the signals at given time

print_params([round_to])

Print the model parameters and their uncertainties

relax()

Relaxation rates in aorta, portal vein and liver.

save([file, path, filename])

Save the current state of the model

set_free([pop])

Set the free model parameters.

train(time, signal, **kwargs)

Train the free parameters
conc(sum=True)[source]#

Concentrations in aorta. portal vein 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, portal-venous blood concentrations, liver concentrations.

Return type:

tuple

cost(time, signal, metric='NRMS') → float[source]#

Return the goodness-of-fit

Parameters:

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

  • signal (array-like) – tuple of 3 arrays with signals for aorta, portal vein 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’: Bayesian 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(time: tuple, signal: tuple, xlim=None, ref=None, fname=None, show=True)[source]#

Plot the model fit against data

Parameters:

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

  • signal (array-like) – tuple of 3 arrays with signals for aorta, portal vein 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(time: tuple) → tuple[source]#

Predict the signals at given time

Parameters:

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

Returns:

tuple of 3 arrays with signals for aorta, portal vein 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, portal vein and liver.

Returns:

time points, aorta blood R1, portal-venous blood R1, liver blood 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(time: tuple, signal: tuple, **kwargs)[source]#

Train the free parameters

Parameters:

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

  • signal (array-like) – tuple of 3 arrays with signals for aorta, portal vein 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:

the trained model

Return type:

AortaPortalLiver