Loss¶
Image Loss¶
Module provides different loss functions for calculating the dissimilarities between images.

deepreg.model.loss.image.
dissimilarity_fn
(y_true: tensorflow.Tensor, y_pred: tensorflow.Tensor, name: str, **kwargs) → tensorflow.Tensor¶ Returns the calculated dissimilarity for each batch.
 Parameters
y_true – fixed_image, shape = (batch, f_dim1, f_dim2, f_dim3)
y_pred – warped_moving_image, shape = (batch, f_dim1, f_dim2, f_dim3)
name – name of the dissimilarity function
kwargs – absorb additional parameters
 Returns
shape = (batch,)

deepreg.model.loss.image.
global_mutual_information
(y_true: tensorflow.Tensor, y_pred: tensorflow.Tensor, num_bins: int = 23, sigma_ratio: float = 0.5) → tensorflow.Tensor¶ Differentiable global mutual information loss via Parzen windowing method.
Reference: https://dspace.mit.edu/handle/1721.1/123142, Section 3.1, equation 3.13.5, Algorithm 1
 Parameters
y_true – shape = (batch, dim1, dim2, dim3, ch)
y_pred – shape = (batch, dim1, dim2, dim3, ch)
num_bins – int, number of bins for intensity
sigma_ratio – float, a hyper param for gaussian function
 Returns
shape = (batch,)

deepreg.model.loss.image.
local_normalized_cross_correlation
(y_true: tensorflow.Tensor, y_pred: tensorflow.Tensor, kernel_size: int = 9, kernel_type: str = 'rectangular', **kwargs) → tensorflow.Tensor¶ Local squared zeronormalized crosscorrelation. The loss is based on a moving kernel/window over the y_true/y_pred, within the window the square of zncc is calculated. The kernel can be a rectangular / triangular / gaussian window. The final loss is the averaged loss over all windows.
Reference:
Zeronormalized crosscorrelation (ZNCC): https://en.wikipedia.org/wiki/Crosscorrelation
Code: https://github.com/voxelmorph/voxelmorph/blob/legacy/src/losses.py
 Parameters
y_true – shape = (batch, dim1, dim2, dim3, ch)
y_pred – shape = (batch, dim1, dim2, dim3, ch)
kernel_size – int. Kernel size or kernel sigma for kernel_type=’gauss’.
kernel_type – str (‘triangular’, ‘gaussian’ default: ‘rectangular’)
kwargs – absorb additional parameters
 Returns
shape = (batch,)

deepreg.model.loss.image.
ssd
(y_true: tensorflow.Tensor, y_pred: tensorflow.Tensor) → tensorflow.Tensor¶ Sum of squared distance between y_true and y_pred.
 Parameters
y_true – shape = (batch, dim1, dim2, dim3, ch)
y_pred – shape = (batch, dim1, dim2, dim3, ch)
 Returns
shape = (batch,)
Label Loss¶
Module provides different loss functions for calculating the dissimilarities between labels.

deepreg.model.loss.label.
cauchy_kernel1d
(sigma: int) → tensorflow.Tensor¶ Approximating cauchy kernel in 1d.
 Parameters
sigma – int, defining standard deviation of kernel.
 Returns
shape = (dim, ) or ()

deepreg.model.loss.label.
compute_centroid
(mask: tensorflow.Tensor, grid: tensorflow.Tensor) → tensorflow.Tensor¶ Calculate the centroid of the mask.
 Parameters
mask – shape = (batch, dim1, dim2, dim3)
grid – shape = (dim1, dim2, dim3, 3)
 Returns
shape = (batch, 3), batch of vectors denoting location of centroids.

deepreg.model.loss.label.
compute_centroid_distance
(y_true: tensorflow.Tensor, y_pred: tensorflow.Tensor, grid: tensorflow.Tensor) → tensorflow.Tensor¶ Calculate the L2distance between two tensors’ centroids.
 Parameters
y_true – tensor, shape = (batch, dim1, dim2, dim3)
y_pred – tensor, shape = (batch, dim1, dim2, dim3)
grid – tensor, shape = (dim1, dim2, dim3, 3)
 Returns
shape = (batch,)

deepreg.model.loss.label.
dice_score
(y_true: tensorflow.Tensor, y_pred: tensorflow.Tensor, binary: bool = False) → tensorflow.Tensor¶ Calculates dice score:
num = 2 * y_true * y_pred
denom = y_true + y_pred
dice score = num / denom
where num and denom are summed over the entire image first.
 Parameters
y_true – shape = (batch, dim1, dim2, dim3)
y_pred – shape = (batch, dim1, dim2, dim3)
binary – True if the y should be projected to 0 or 1
 Returns
shape = (batch,)

deepreg.model.loss.label.
dice_score_generalized
(y_true: tensorflow.Tensor, y_pred: tensorflow.Tensor, pos_weight: float = 1, neg_weight: float = 0) → tensorflow.Tensor¶ Calculates weighted dice score:
let y_prod = y_true * y_pred and y_sum = y_true + y_pred
num = 2 * (pos_w * y_true * y_pred + neg_w * (1−y_true) * (1−y_pred))
= 2 * ((pos_w+neg_w) * y_prod  neg_w * y_sum + neg_w)
denom = (pos_w * (y_true + y_pred) + neg_w * (1−y_true + 1−y_pred))
= (pos_wneg_w) * y_sum + 2 * neg_w
dice score = num / denom
where num and denom are summed over the entire image first.
 Parameters
y_true – shape = (batch, dim1, dim2, dim3)
y_pred – shape = (batch, dim1, dim2, dim3)
pos_weight – weight of positive class, default = 1
neg_weight – weight of negative class, default = 0
 Returns
shape = (batch,)

deepreg.model.loss.label.
foreground_proportion
(y: tensorflow.Tensor) → tensorflow.Tensor¶ Calculating the percentage of foreground vs background per 3d volume.
 Parameters
y – shape = (batch, dim1, dim2, dim3), a 3D label tensor
 Returns
shape = (batch,)

deepreg.model.loss.label.
gauss_kernel1d
(sigma: int) → tensorflow.Tensor¶ Calculates a gaussian kernel.
 Parameters
sigma – number defining standard deviation for gaussian kernel.
 Returns
shape = (dim, ) or ()

deepreg.model.loss.label.
get_dissimilarity_fn
(config: dict) → Callable¶ Parse arguments from a configuration dictionary and return the loss by averaging batch loss returned by multi or singlescale loss functions.
 Parameters
config – dict, containing configuration for training.
 Returns
loss function, which returns a tensor of shape (batch, )

deepreg.model.loss.label.
jaccard_index
(y_true: tensorflow.Tensor, y_pred: tensorflow.Tensor) → tensorflow.Tensor¶ Calculates jaccard index:
num = y_true * y_pred
denom = y_true + y_pred  y_true * y_pred
jaccard index = num / denom
 Parameters
y_true – shape = (batch, dim1, dim2, dim3)
y_pred – shape = (batch, dim1, dim2, dim3)
 Returns
shape = (batch,)

deepreg.model.loss.label.
multi_scale_loss
(y_true: tensorflow.Tensor, y_pred: tensorflow.Tensor, loss_type: str, loss_scales: list) → tensorflow.Tensor¶ Apply the loss at different scales (gaussian smoothing). It is assumed that loss values are between 0 and 1.
 Parameters
y_true – tensor, shape = (batch, dim1, dim2, dim3)
y_pred – tensor, shape = (batch, dim1, dim2, dim3)
loss_type –
string, indicating which loss to pass to function single_scale_loss.
Supported:
crossentropy
meansquared
dice
dice_generalized
jaccard
loss_scales – list, values of sigma to pass to func gauss_kernel_1d.
 Returns
(batch,)

deepreg.model.loss.label.
separable_filter3d
(tensor: tensorflow.Tensor, kernel: tensorflow.Tensor) → tensorflow.Tensor¶ Creates a 3d separable filter.
Here tf.nn.conv3d accepts the filters argument of shape (filter_depth, filter_height, filter_width, in_channels, out_channels), where the first axis of filters is the depth not batch, and the input to tf.nn.conv3d is of shape (batch, in_depth, in_height, in_width, in_channels).
 Parameters
tensor – shape = (batch, dim1, dim2, dim3)
kernel – shape = (dim4,)
 Returns
shape = (batch, dim1, dim2, dim3)

deepreg.model.loss.label.
single_scale_loss
(y_true: tensorflow.Tensor, y_pred: tensorflow.Tensor, loss_type: str) → tensorflow.Tensor¶ Calculate the loss on two tensors based on defined loss.
 Parameters
y_true – tensor, shape = (batch, dim1, dim2, dim3)
y_pred – tensor, shape = (batch, dim1, dim2, dim3)
loss_type –
string, indicating which loss to pass to function single_scale_loss.
Supported:
crossentropy
meansquared
dice
dice_generalized
jaccard
 Returns
shape = (batch,)

deepreg.model.loss.label.
squared_error
(y_true: tensorflow.Tensor, y_pred: tensorflow.Tensor) → tensorflow.Tensor¶ Calculates the mean squared difference between y_true, y_pred.
mean((y_true  y_pred)(y_true  y_pred))
 Parameters
y_true – tensor, shape = (batch, dim1, dim2, dim3)
y_pred – shape = (batch, dim1, dim2, dim3)
 Returns
shape = (batch,)

deepreg.model.loss.label.
weighted_binary_cross_entropy
(y_true: tensorflow.Tensor, y_pred: tensorflow.Tensor, pos_weight: float = 1) → tensorflow.Tensor¶ Calculates weighted binary cross entropy:
loss = − pos_w * y_true log(y_pred)  (1−y_true) log(1−y_pred)
 Parameters
y_true – shape = (batch, dim1, dim2, dim3)
y_pred – shape = (batch, dim1, dim2, dim3)
pos_weight – weight of positive class, scalar. Default value is 1
 Returns
shape = (batch,)
Deformation Loss¶
Module provides regularization energy functions for ddf.

deepreg.model.loss.deform.
compute_bending_energy
(ddf: tensorflow.Tensor) → tensorflow.Tensor¶ Calculate the bending energy based on secondorder differentiation of ddf using central finite difference.
 Parameters
ddf – shape = (batch, m_dim1, m_dim2, m_dim3, 3)
 Returns
shape = (batch, )

deepreg.model.loss.deform.
compute_gradient_norm
(ddf: tensorflow.Tensor, l1: bool = False) → tensorflow.Tensor¶ Calculate the L1/L2 norm of the firstorder differentiation of ddf using central finite difference.
 Parameters
ddf – shape = (batch, m_dim1, m_dim2, m_dim3, 3)
l1 – bool true if calculate L1 norm, otherwise L2 norm
 Returns
shape = (batch, )

deepreg.model.loss.deform.
gradient_dx
(fx: tensorflow.Tensor) → tensorflow.Tensor¶ Calculate gradients on xaxis of a 3D tensor using central finite difference. It moves the tensor along axis 1 to calculate the approximate gradient, the x axis, dx[i] = (x[i+1]  x[i1]) / 2.
 Parameters
fx – shape = (batch, m_dim1, m_dim2, m_dim3)
 Returns
shape = (batch, m_dim12, m_dim22, m_dim32)

deepreg.model.loss.deform.
gradient_dxyz
(fxyz: tensorflow.Tensor, fn: Callable) → tensorflow.Tensor¶ Calculate gradients on x,y,zaxis of a tensor using central finite difference. The gradients are calculated along x, y, z separately then stacked together.
 Parameters
fxyz – shape = (…, 3)
fn – function to call
 Returns
shape = (…, 3)

deepreg.model.loss.deform.
gradient_dy
(fy: tensorflow.Tensor) → tensorflow.Tensor¶ Calculate gradients on yaxis of a 3D tensor using central finite difference. It moves the tensor along axis 2 to calculate the approximate gradient, the y axis, dy[i] = (y[i+1]  y[i1]) / 2.
 Parameters
fy – shape = (batch, m_dim1, m_dim2, m_dim3)
 Returns
shape = (batch, m_dim12, m_dim22, m_dim32)

deepreg.model.loss.deform.
gradient_dz
(fz: tensorflow.Tensor) → tensorflow.Tensor¶ Calculate gradients on zaxis of a 3D tensor using central finite difference. It moves the tensor along axis 3 to calculate the approximate gradient, the z axis, dz[i] = (z[i+1]  z[i1]) / 2.
 Parameters
fz – shape = (batch, m_dim1, m_dim2, m_dim3)
 Returns
shape = (batch, m_dim12, m_dim22, m_dim32)

deepreg.model.loss.deform.
local_displacement_energy
(ddf: tensorflow.Tensor, energy_type: str, **kwargs) → tensorflow.Tensor¶ Calculate the displacement energy of the ddf based on finite difference.
 Parameters
ddf – shape = (batch, m_dim1, m_dim2, m_dim3, 3)
energy_type – type of the energy
kwargs – absorb additional arguments
 Returns
shape = (batch,)