dcmri.AortaKidneys#

class dcmri.AortaKidneys(organs='comp', heartlung='pfcomp', kidneys='2CF', sequence='SS', agent='gadoterate', **params)[source]#

Joint model for signals from aorta and both kidneys.

This model uses a whole body model to simultaneously predict signals in aorta and kidneys (see Whole body).

See also

Aorta, Kidney

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 ‘pfcomp’ (plug-flow compartment) or ‘chain’. Defaults to ‘pfcomp’.

  • kidneys (str, optional) – Model for the kidneys. Options are ‘2CF’ (Two-compartment filtration) and ‘HF’ (High-flow). Defaults to ‘2CF’.

  • 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’.

  • agent (str, optional) – Generic name of the contrast agent injected. Defaults to ‘gadoterate’.

  • params (dict, optional) – values for the model parameters, specified as keyword parameters. Defaults are used for any that are not provided. See table AortaKidneys 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.

AortaKidneys parameters.#

Parameter

Description

Value

Unit

Bounds

Usage

General

dt

Prediction time step

0.25

sec

None

Always

tmax

Maximum time predicted

120

sec

None

Always

dose_tolerance

Stopping criterion whole body model

0.1

None

Always

t0

Baseline duration

0

None

Always

field_strength

B0-field

3

T

None

Always

Injection

weight

Subject weight

70

kg

None

Always

dose

Contrast agent dose

0.0125

mL/kg

None

Always

rate

Contrast agent injection rate

1

mL/kg

None

Always

Sequence

TR

Repetition time

0.005

sec

None

sequence in [‘SS’, ‘SSI’]

FA

Flip angle

15

deg

None

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

TC

Time to k-space center

0.1

sec

None

sequence == ‘SR’

TS

Sampling duration

0

sec

None

Always

TF

Inflow time

0

sec

None

sequence == ‘SSI’

Aorta

BAT

Bolus arrival time

60

sec

[0, inf]

Always

CO

Cardiac output

100

mL/sec

[0, 300]

Always

Thl

Heart-lung transit time

10

sec

[0, 30]

Always

Dhl

Heart-lung dispersion

0.2

[0.05, 0.95]

heartlung in [‘pfcomp’, ‘chain’]

To

Organs transit time

20

sec

[0, 60]

Always

Eo

Organs extraction fraction

0.15

[0, 0.5]

organs == ‘2cxm’

Toe

Organs extracellular transit time

120

sec

[0, 800]

organs == ‘2cxm’

Eb

Body extraction fraction

0.05

[0.01, 0.15]

Always

R10a

Arterial precontrast R1

0.7

/sec

None

Always

S0a

Arterial signal scale factor

1

a.u.

None

Always

Kidneys

H

Hematocrit

0.45

None

Always

RPF

Renal plasma flow

20

mL/sec

[0, 100]

Always

DRF

Differential renal function

0.5

[0, 1.0]

Always

DRPF

Differential renal plasma flow

0.5

[0, 1.0]

kidneys == ‘2CF’

FF

Filtration fraction

0.1

[0, 0.3]

agent in [‘gadoxetate’, ‘gadobenate’]

Left kidney

Ta_lk

Left kidney arterial delay

0

sec

[0, 3]

Always

vp_lk

Left kidney plasma volume

0.15

mL/cm3

[0, 0.3]

Always

Tt_lk

Left kidney tubular transit time

120

sec

[0, inf]

Always

R10_lk

Left kidney precontrast R1

0.65

1/sec

None

Always

S0_lk

Left kidney signal scale factor

1.0

a.u.

[0, inf]

Always

vol_lk

Left kidney volume

150

cm3

None

Always

Right kidney

Ta_rk

Right kidney arterial delay

0

sec

[0, 3]

Always

vp_rk

Right kidney plasma volume

0.15

mL/cm3

[0, 0.3]

Always

Tt_rk

Right kidney tubular transit time

120

sec

[0, inf]

Always

R10_rk

Right kidney precontrast R1

0.65

/sec

None

Always

S0_rk

Right kidney signal scale factor

1.0

a.u.

[0, inf]

Always

vol_rk

Right kidney volume

150

cm3

None

Always

Example

Use the model to fit minipig 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']

Create an array of time points:

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

Initialize the tissue:

>>> aorta_kidneys = dc.AortaKidneys(
...     sequence='SSI',
...     heartlung='chain',
...     organs='comp',
...     agent="gadoterate",
...     dt=0.25,
...     field_strength=pars['B0'],
...     weight=pars['weight'],
...     dose=pars['dose'],
...     rate=pars['rate'],
...     R10a=1/dc.T1(pars['B0'], 'blood'),
...     R10_lk=1/dc.T1(pars['B0'], 'kidney'),
...     R10_rk=1/dc.T1(pars['B0'], 'kidney'),
...     vol_lk=85,
...     vol_rk=85,
...     TR=pars['TR'],
...     FA=pars['FA'],
...     TS=pars['TS'],
...     CO=60,
...     t0=15,
... )

Define time and signal data

>>> t = (time, time, time)
>>> signal = (rois['Aorta'], rois['LeftKidney'], rois['RightKidney'])

Train the system to the data:

>>> aorta_kidneys.train(t, signal)

Plot the reconstructed signals and concentrations:

>>> aorta_kidneys.plot(t, signal)

Print the model parameters:

>>> aorta_kidneys.print_params(round_to=4)
--------------------------------
Free parameters with their stdev
--------------------------------
Bolus arrival time (BAT): 16.7422 (0.2853) sec
Inflow time (TF): 0.2801 (0.0133) sec
Cardiac output (CO): 72.762 (12.4426) mL/sec
Heart-lung mean transit time (Thl): 16.2249 (0.3069) sec
Organs blood mean transit time (To): 14.3793 (1.2492) sec
Body extraction fraction (Eb): 0.0751 (0.0071)
Heart-lung dispersion (Dhl): 0.0795 (0.0041)
Renal plasma flow (RPF): 3.3489 (0.7204) mL/sec
Differential renal function (DRF): 0.9085 (0.0212)
Differential renal plasma flow (DRPF): 0.812 (0.0169)
Left kidney arterial mean transit time (Ta_lk): 0.6509 (0.2228) sec
Left kidney plasma volume (vp_lk): 0.099 (0.0186) mL/cm3
Left kidney tubular mean transit time (Tt_lk): 46.9705 (3.3684) sec
Right kidney arterial mean transit time (Ta_rk): 1.4206 (0.2023) sec
Right kidney plasma volume (vp_rk): 0.1294 (0.0175) mL/cm3
Right kidney tubular mean transit time (Tt_rk): 4497.8301 (39890.3818) sec
Aorta signal scaling factor (S0a): 4912.776 (254.2363) a.u.
----------------------------
Fixed and derived parameters
----------------------------
Filtration fraction (FF): 0.0812
Glomerular Filtration Rate (GFR): 0.2719 mL/sec
Left kidney plasma flow (RPF_lk): 2.7194 mL/sec
Right kidney plasma flow (RPF_rk): 0.6295 mL/sec
Left kidney glomerular filtration rate (GFR_lk): 0.247 mL/sec
Right kidney glomerular filtration rate (GFR_rk): 0.0249 mL/sec
Left kidney plasma flow (Fp_lk): 0.032 mL/sec/cm3
Left kidney plasma mean transit time (Tp_lk): 2.838 sec
Left kidney vascular mean transit time (Tv_lk): 3.0958 sec
Left kidney tubular flow (Ft_lk): 0.0029 mL/sec/cm3
Left kidney filtration fraction (FF_lk): 0.0908
Left kidney extraction fraction (E_lk): 0.0833
Right kidney plasma flow (Fp_rk): 0.0074 mL/sec/cm3
Right kidney plasma mean transit time (Tp_rk): 16.8121 sec
Right kidney vascular mean transit time (Tv_rk): 17.4762 sec
Right kidney tubular flow (Ft_rk): 0.0003 mL/sec/cm3
Right kidney filtration fraction (FF_rk): 0.0395
Right kidney extraction fraction (E_rk): 0.038

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

../_images/dcmri-AortaKidneys-1.png

Methods

conc([sum])

Concentrations in aorta and kidney.

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[, 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 kidney.

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 kidney.

Parameters:

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

Returns:

time points, aorta blood concentrations, left

kidney concentrations, right kidney concentrations.

Return type:

tuple

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

Return the goodness-of-fit

Parameters:

  • xdata (tuple) – Tuple of 3 arrays with time points for aorta, left kidney and right kidney, in that order. The three arrays can all be different in length and value.

  • ydata (tuple) – Tuple of 3 arrays with signals for aorta, left kidney and right kidney, in that order. The three arrays can all be different in length and values but each has to have the same length as its corresponding array of time points.

  • metric (str, optional) – Which metric to use - 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). Defaults to ‘NRMS’.

Returns:

goodness of fit.

Return type:

float

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, xlim=None, ref=None, fname=None, show=True)[source]#

Plot the model fit against data

Parameters:

  • xdata (tuple) – Tuple of 3 arrays with time points for aorta, left kidney and right kidney, in that order. The three arrays can all be different in length and value.

  • ydata (tuple) – Tuple of 3 arrays with signals for aorta, left kidney and right kidney, in that order. The three arrays can all be different in length and values 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)[source]#

Predict the data at given xdata

Parameters:

xdata (tuple) – Tuple of 3 arrays with time points for aorta, left kidney and right kidney, in that order. The three arrays can all be different in length and value.

Returns:

Tuple of 3 arrays with signals for aorta, left

kidney and right kidney, in that order. The three arrays can all 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 kidney.

Returns:

time points, aorta relaxation rate, left kidney

relaxation rate, right kidney relaxation rate.

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

Train the free parameters

Parameters:

  • xdata (tuple) – Tuple of 3 arrays with time points for aorta, left kidney and right kidney, in that order. The three arrays can all be different in length and value.

  • ydata (tuple) – Tuple of 3 arrays with signals for aorta, left kidney and right kidney, in that order. The three arrays can all be different in length and values 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