dcmri.Kidney#

class dcmri.Kidney(kinetics='2CF', sequence='SS', aif=None, ca=None, t=None, dt=1.0, **params)[source]#

General model for whole-kidney signals.

See also

Liver, Tissue

Parameters:

  • kinetics (str, optional) – Kinetic 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), 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 Kidney 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.

Kidney parameters.#

Parameter

Value

Bounds

Usage

General

field_strength

3

None

Always

agent

‘gadoterate’

None

Always

t0

0

None

Always

Sequence

TS

0

None

Always

B1corr

1

None

sequence in [‘SS’]

FA

15

None

sequence in [‘SR’, ‘SS’]

TR

0.005

None

sequence in [‘SS’]

TC

0.1

None

sequence == ‘SR’

TP

0.05

None

sequence == ‘SR’

AIF

B1corr_a

1

None

sequence in [‘SS’]

R10a

0.7

None

Always

Kidney

H

0.45

None

Always

Ta

0

[0, 3]

Always

vol

150

None

Always

Fp

0.02

[0, 0.05]

kinetics == ‘2CF’

vp

0.15

[0, 0.3]

Always

FF

0.1

[0, 0.3]

kinetics == ‘2CF’

Tt

120

[0, inf]

Always

Ft

0.005

[0, 0.05]

Always

R10

0.65

None

Always

S0

1.0

[0, inf]

Always

Example

Use the model to fit minipig data. The AIF is corrupted by inflow effects so for the purpose of this example we will use a standard input function:

>>> 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']
>>> time = pars['TS'] * np.arange(len(rois['LeftKidney']))

Generate an AIF at high temporal resolution (250 msec):

>>> dt = 0.25
>>> t = np.arange(0, np.amax(time) + dt, dt)
>>> ca = dc.aif_tristan(
...    t,
...    agent="gadoterate",
...    dose=pars['dose'],
...    rate=pars['rate'],
...    weight=pars['weight'],
...    CO=60,
...    BAT=time[np.argmax(rois['Aorta'])] - 20,
>>> )

Initialize the tissue:

>>> kidney = dc.Kidney(
...    ca=ca,
...    dt=dt,
...    kinetics='HF',
...    field_strength=pars['B0'],
...    agent="gadoterate",
...    t0=pars['TS'] * pars['n0'],
...    TS=pars['TS'],
...    TR=pars['TR'],
...    FA=pars['FA'],
...    R10a=1/dc.T1(pars['B0'], 'blood'),
...    R10=1/dc.T1(pars['B0'], 'kidney'),
>>> )

Train the kidney on the data:

>>> kidney.set_free(Ta=[0,30])
>>> kidney.train(time, rois['LeftKidney'])

Plot the reconstructed signals and concentrations:

>>> kidney.plot(time, rois['LeftKidney'])

Print the model parameters:

>>> kidney.print_params(round_to=4)
--------------------------------
Free parameters with their stdev
--------------------------------
Arterial mean transit time (Ta): 13.8658 (0.1643) sec
Plasma volume (vp): 0.0856 (0.003) mL/cm3
Tubular flow (Ft): 0.0024 (0.0001) mL/sec/cm3
Tubular mean transit time (Tt): 116.296 (7.6526) sec

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

../_images/dcmri-Kidney-1.png

Methods

conc([sum])

Tissue 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()

Longitudinal relaxation rate R1(t).

save([file, path, filename])

Save the current state of the model

set_free([pop])

Set the free model parameters.

signal()

Pseudocontinuous signal S(t) as a function of time.

time()

Array of time points.

train(xdata, ydata, **kwargs)

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

Tissue concentration

Parameters:

sum (bool, optional) – If True, this returns the total concentration. Else the function returns the concentration in the individual compartments. Defaults to True.

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

Longitudinal relaxation rate R1(t).

Returns:

Relaxation rate. Dimensions are (nt,) for a tissue in

fast water exchange, or (nc,nt) for a multicompartment tissue outside the fast water exchange limit.

Return type:

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

signal()[source]#

Pseudocontinuous signal S(t) as a function of time.

Returns:

Signal as a 1D array.

Return type:

np.ndarray

time()[source]#

Array of time points.

Returns:

time points in seconds.

Return type:

np.ndarray

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