Main Content

l1loss

L1 loss for regression tasks

Since R2021b

collapse all in page

    Syntax

    loss = l1loss(Y,targets)
    loss = l1loss(Y,targets,weights)
    loss = l1loss(___,DataFormat=FMT)
    loss = l1loss(___,Name=Value)

    Description

    The L1 loss operation computes the L1 loss given network predictions and target values. When the Reduction option is "sum" and the NormalizationFactor option is "batch-size", the computed value is known as the mean absolute error (MAE).

    The l1loss function calculates the L1 loss using dlarray data. Using dlarray objects makes working with high dimensional data easier by allowing you to label the dimensions. For example, you can label which dimensions correspond to spatial, time, channel, and batch dimensions using the "S", "T", "C", and "B" labels, respectively. For unspecified and other dimensions, use the "U" label. For dlarray object functions that operate over particular dimensions, you can specify the dimension labels by formatting the dlarray object directly, or by using the DataFormat option.

    loss = l1loss(Y,targets) computes the MAE loss for the predictions Y and the target values targets. The input Y must be a formatted dlarray. The output loss is an unformatted dlarray scalar.

    example

    loss = l1loss(Y,targets,weights) computes the weighted L1 loss using the weight values weights. The output loss is an unformatted dlarray scalar.

    loss = l1loss(___,DataFormat=FMT) computes the loss for the unformatted dlarray object Y and the target values with the format specified by FMT. Use this syntax with any of the input arguments in previous syntaxes.

    loss = l1loss(___,Name=Value) specifies additional options using one or more name-value arguments. For example, l1loss(Y,targets,Reduction="none") computes the L1 loss without reducing the output to a scalar.

    example

    Examples

    collapse all

    Open Live Script

    Create an array of predictions for 12 observations over 10 responses.

    numResponses = 10;
numObservations = 12;

Y = rand(numResponses,numObservations);
dlY = dlarray(Y,'CB');

    View the size and format of the predictions.

    size(dlY)
    ans = 1×2

    10    12


    dims(dlY)
    ans = 
'CB'

    Create an array of random targets.

    targets = rand(numResponses,numObservations);

    View the size of the targets.

    size(targets)
    ans = 1×2

    10    12

    Compute the mean absolute error (MAE) loss between the predictions and the targets using the l1loss function.

    loss = l1loss(dlY,targets)
    loss = 
  1x1 dlarray

    3.1679
    Open Live Script

    Create arrays of predictions and targets for 12 sequences of varying lengths over 10 responses.

    numResponses = 10;
numObservations = 12;
maxSequenceLength = 15;

sequenceLengths = randi(maxSequenceLength,[1 numObservations]);

Y = cell(numObservations,1);
targets = cell(numObservations,1);

for i = 1:numObservations
    Y{i} = rand(numResponses,sequenceLengths(i));
    targets{i} = rand(numResponses,sequenceLengths(i));
end

    View the cell arrays of predictions and targets.

    Y
    Y=12×1 cell array
    {10x13 double}
    {10x14 double}
    {10x2  double}
    {10x14 double}
    {10x10 double}
    {10x2  double}
    {10x5  double}
    {10x9  double}
    {10x15 double}
    {10x15 double}
    {10x3  double}
    {10x15 double}


    targets
    targets=12×1 cell array
    {10x13 double}
    {10x14 double}
    {10x2  double}
    {10x14 double}
    {10x10 double}
    {10x2  double}
    {10x5  double}
    {10x9  double}
    {10x15 double}
    {10x15 double}
    {10x3  double}
    {10x15 double}

    Pad the prediction and target sequences in the second dimension using the padsequences function and also return the corresponding mask.

    [Y,mask] = padsequences(Y,2);
targets = padsequences(targets,2);

    Convert the padded sequences to dlarray with the format "CTB" (channel, time, batch). Because formatted dlarray objects automatically permute the dimensions of the underlying data, keep the order consistent by also converting the targets and mask to formatted dlarray objects with the format "CTB" (channel, batch, time).

    dlY = dlarray(Y,"CTB");
targets = dlarray(targets,"CTB");
mask = dlarray(mask,"CTB");

    View the sizes of the prediction scores, targets, and mask.

    size(dlY)
    ans = 1×3

    10    12    15


    size(targets)
    ans = 1×3

    10    12    15


    size(mask)
    ans = 1×3

    10    12    15

    Compute the mean absolute error (MAE) between the predictions and the targets. To prevent the loss values calculated from padding from contributing to the loss, set the Mask option to the mask returned by the padsequences function.

    loss = l1loss(dlY,targets,Mask=mask)
    loss = 
  1x1 dlarray

   32.6172

    Input Arguments

    collapse all

    Predictions, specified as a formatted or unformatted dlarray object, or a numeric array. When Y is not a formatted dlarray, you must specify the dimension format using the DataFormat argument.

    If Y is a numeric array, targets must be a dlarray object.

    Target responses, specified as a formatted or unformatted dlarray or a numeric array.

    The size of each dimension of targets must match the size of the corresponding dimension of Y.

    If targets is a formatted dlarray, then its format must be the same as the format of Y, or the same as DataFormat if Y is unformatted.

    If targets is an unformatted dlarray or a numeric array, then the function applies the format of Y or the value of DataFormat to targets.

    Tip

    Formatted dlarray objects automatically permute the dimensions of the underlying data to have the order "S" (spatial), "C" (channel), "B" (batch), "T" (time), then "U" (unspecified). To ensure that the dimensions of Y and targets are consistent, when Y is a formatted dlarray, also specify targets as a formatted dlarray.

    Weights, specified as a formatted or unformatted dlarray or a numeric array.

    If weights is a vector and Y has two or more nonsingleton dimensions, then weights must be a formatted dlarray, where the dimension label of the nonsingleton dimension is either "C" (channel) or "B" (batch) and has a size that matches the size of the corresponding dimension in Y.

    If weights is a formatted dlarray with two or more nonsingleton dimensions, then its format must match the format of Y.

    If weights is not a formatted dlarray and has two or more nonsingleton dimensions, then its size must match the size of Y and the function uses the same format as Y. Alternatively, to specify the weights format, use the WeightsFormat option.

    Name-Value Arguments

    Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

    Example: loss = l1loss(Y,targets,Reduction="none") specifies to compute the L1 loss without reducing the output to a scalar

    Mask indicating which elements to include for loss computation, specified as a dlarray object, a logical array, or a numeric array with the same size as Y.

    The function includes and excludes elements of the input data for loss computation when the corresponding value in the mask is 1 and 0, respectively.

    If Mask is a formatted dlarray object, then its format must match that of Y. If Mask is not a formatted dlarray object, then the function uses the same format as Y.

    If you specify the DataFormat argument, then the function also uses the specified format for the mask.

    The size of each dimension of Mask must match the size of the corresponding dimension in Y. The default value is a logical array of ones.

    Tip

    Formatted dlarray objects automatically permute the dimensions of the underlying data to have this order: "S" (spatial), "C" (channel), "B" (batch), "T" (time), and "U" (unspecified). For example, dlarray objects automatically permute the dimensions of data with format "TSCSBS" to have format "SSSCBT".

    To ensure that the dimensions of Y and the mask are consistent, when Y is a formatted dlarray, also specify the mask as a formatted dlarray.

    Loss value array reduction mode, specified as "sum" or "none".

    If the Reduction argument is "sum", then the function sums all elements in the array of loss values. In this case, the output loss is a scalar.

    If the Reduction argument is "none", then the function does not reduce the array of loss values. In this case, the output loss is an unformatted dlarray object of the same size as Y.

    Divisor for normalizing the reduced loss when Reduction is "sum", specified as one of the following:

    • "batch-size" — Normalize the loss by dividing it by the number of observations in Y.

    • "all-elements" — Normalize the loss by dividing it by the number of elements of Y.

    • "mask-included" — Normalize the loss by dividing the loss values by the product of the number of observations and the number of included elements specified by the mask for each observation independently. To use this option, you must specify a mask using the Mask option.

    • "none" — Do not normalize the loss.

    Description of the data dimensions, specified as a character vector or string scalar.

    A data format is a string of characters, where each character describes the type of the corresponding data dimension.

    The characters are:

    • "S" — Spatial

    • "C" — Channel

    • "B" — Batch

    • "T" — Time

    • "U" — Unspecified

    For example, consider an array containing a batch of sequences where the first, second, and third dimensions correspond to channels, observations, and time steps, respectively. You can specify that this array has the format "CBT" (channel, batch, time).

    You can specify multiple dimensions labeled "S" or "U". You can use the labels "C", "B", and "T" once each, at most. The software ignores singleton trailing "U" dimensions after the second dimension.

    If the input data is not a formatted dlarray object, then you must specify the DataFormat option.

    For more information, see Deep Learning Data Formats.

    Data Types: char | string

    Description of the dimensions of the weights, specified as a character vector or string scalar.

    A data format is a string of characters, where each character describes the type of the corresponding data dimension.

    The characters are:

    • "S" — Spatial

    • "C" — Channel

    • "B" — Batch

    • "T" — Time

    • "U" — Unspecified

    For example, consider an array containing a batch of sequences where the first, second, and third dimensions correspond to channels, observations, and time steps, respectively. You can specify that this array has the format "CBT" (channel, batch, time).

    You can specify multiple dimensions labeled "S" or "U". You can use the labels "C", "B", and "T" once each, at most. The software ignores singleton trailing "U" dimensions after the second dimension.

    If weights is a numeric vector and Y has two or more nonsingleton dimensions, then you must specify the WeightsFormat option.

    If weights is not a vector, or weights and Y are both vectors, then the default value of WeightsFormat is the same as the format of Y.

    For more information, see Deep Learning Data Formats.

    Data Types: char | string

    Output Arguments

    collapse all

    L1 loss, returned as an unformatted dlarray. The output loss is an unformatted dlarray with the same underlying data type as the input Y.

    The size of loss depends on the Reduction option.

    Algorithms

    collapse all

    L1 Loss

    The L1 loss operation computes the L1 loss given network predictions and target values. When the Reduction option is "sum" and the NormalizationFactor option is "batch-size", the computed value is known as the mean absolute error (MAE).

    For each element Yj of the input, the l1loss function computes the corresponding element-wise loss values using

    lossj=|Yj−Tj|,

    where Yj is a predicted value and Tj is the corresponding target value.

    To reduce the loss values to a scalar, the function then reduces the element-wise loss using the formula

    loss=1N∑jmjwjlossj,

    where N is the normalization factor, mj is the mask value for element j, and wj is the weight value for element j.

    If you do not opt to reduce the loss, then the function applies the mask and the weights to the loss values directly:

    lossj*=mjwjlossj

    Deep Learning Array Formats

    Most deep learning networks and functions operate on different dimensions of the input data in different ways.

    For example, an LSTM operation iterates over the time dimension of the input data, and a batch normalization operation normalizes over the batch dimension of the input data.

    To provide input data with labeled dimensions or input data with additional layout information, you can use data formats.

    A data format is a string of characters, where each character describes the type of the corresponding data dimension.

    The characters are:

    • "S" — Spatial

    • "C" — Channel

    • "B" — Batch

    • "T" — Time

    • "U" — Unspecified

    For example, consider an array containing a batch of sequences where the first, second, and third dimensions correspond to channels, observations, and time steps, respectively. You can specify that this array has the format "CBT" (channel, batch, time).

    To create formatted input data, create a dlarray object and specify the format using the second argument.

    To provide additional layout information with unformatted data, specify the formats using the DataFormat and WeightsFormat arguments.

    For more information, see Deep Learning Data Formats.

    Extended Capabilities

    Version History

    Introduced in R2021b

    See Also

    | | | | | | | | |

    Topics