dcmri.Kidney#

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

General model for whole kidney signals.

Input function

aif (array-like, default=None): Signal-time curve in a feeding artery. If AIF is set to None, then the parameter ca must be provided (arterial concentrations).

ca (array-like, default=None): Concentration (M) in the arterial input. Must be provided when aif = None, ignored otherwise.

Acquisition parameters

t (array-like, default=None): Time points (sec) of the aif. If t is not provided, the temporal sampling is uniform with interval dt.

dt (float, default=1.0): Sampling interval of the AIF in sec.

field_strength (float, default=3.0): Magnetic field strength in T.

agent (str, default=’gadoterate’): Contrast agent generic name.

n0 (int, default=1): Baseline length in nr of acquisitions.

TR (float, default=0.005): Repetition time, or time between excitation pulses, in sec.

FA (float, default=15): Nominal flip angle in degrees.

Tracer-kinetic parameters

H (float, optional): Hematocrit.

Fp (Plasma flow, mL/sec/cm3): Flow of plasma into the plasma compartment.

Tp (Plasma mean transit time, sec): Transit time of the plasma compartment.

Ft (Tubular flow, mL/sec/cm3): Flow of fluid into the tubuli.

Ta (Arterial delay time, sec): Transit time through the arterial compartment.

Tt (Tubular mean transit time, sec): Transit time of the tubular compartment.

Signal parameters

R10 (float, default=1): Precontrast tissue relaxation rate in 1/sec.

R10a (float, default=1): Precontrast arterial relaxation rate in 1/sec.

S0 (float, default=1): Scale factor for the MR signal (a.u.).

Prediction and training parameters

free (array-like): list of free parameters. The default depends on the kinetics parameter.

free (array-like): 2-element list with lower and upper free of the free parameters. The default depends on the kinetics parameter.

Additional parameters

vol (float, optional): Kidney volume in mL.

See also

Liver

Example

Derive model parameters from simulated data:

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

Use fake_tissue to generate synthetic test data:

>>> time, aif, roi, gt = dc.fake_tissue(R10=1/dc.T1(3.0,'kidney'))

Override the parameter defaults to match the experimental conditions of the synthetic test data:

>>> params = {
...     'aif':aif,
...     'dt':time[1],
...     'agent': 'gadodiamide',
...     'TR': 0.005,
...     'FA': 15,
...     'R10': 1/dc.T1(3.0,'kidney'),
...     'n0': 15,
... }

Train a two-compartment filtration model on the ROI data and plot the fit:

>>> params['kinetics'] = '2CF'
>>> model = dc.Kidney(**params).train(time, roi)
>>> model.plot(time, roi, ref=gt)

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

Methods

`conc`([sum])	Tissue concentration
`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[, 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, returns the total concentrations. Else returns the concentration in the individual compartments. Defaults to True.
Returns:: Concentration in M
Return type:: numpy.ndarray

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

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() → 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: ndarray, ydata: ndarray, 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() → ndarray[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

Examples using `dcmri.Kidney`#

Single-kidney glomerular filtration rate

dcmri.Kidney#

Examples using dcmri.Kidney#

Examples using `dcmri.Kidney`#