Main Content

padsequences

Pad or truncate sequence data to same length

    Description

    example

    XPad = padsequences(X,paddingDim) pads the sequences in the cell array X along the dimension specified by paddingDim. The function adds padding at the end of each sequence to match the size of the longest sequence in X. The padded sequences are concatenated and the function returns XPad as an array.

    example

    [XPad,mask] = padsequences(X,paddingDim) additionally returns a logical array representing the positions of original sequence data in XPad, . The position of values of true or 1 in mask correspond to the positions of original sequence data in XPad; values of false or 0 correspond to padded values.

    example

    [___] = padsequences(X,paddingDim,Name,Value) specifies options using one or more name-value arguments in addition to the input and output arguments in previous syntaxes. For example, 'PaddingValue','left' adds padding to the beginning of the original sequence.

    Examples

    collapse all

    Pad sequence data ready for training.

    Load the sequence data.

    s = japaneseVowelsTrainData;

    The preprocessed data contains 270 observations each with 12 sequence features. The length of the observations varies between 7 and 26 time steps.

    Pad the data with zeros to the same length as the longest sequence. The function applies on the right side of the data. Specify the dimension containing the time steps as the padding dimension. For this example, the dimension is 2.

    sPad = padsequences(s,2);

    Examine the size of the padded sequences.

    size(sPad)
    ans = 1×3
    
        12    26   270
    
    

    Use padsequences to extend or cut each sequence to a fixed length by adding or removing data at both ends of the sequence, depending on the length of the original sequence.

    Load the sequence data.

    s = japaneseVowelsTrainData;

    The preprocessed data contains 270 observations each with 12 sequence features. The length of the observations varies between 7 and 26 time steps.

    Process the data so that each sequence is exactly 14 time steps. For shorter sequences, padding is required, while longer sequences need to be truncated. Pad or truncate at both sides of the data. For the padded sequences, apply symmetric padding so that the padded values are mirror reflections of the original sequence values.

    [sPad,mask] = padsequences(s,2,'Length',14,'Direction','both','PaddingValue','symmetric');

    Compare some of the padded sequences with the original sequence. Each observation contains 12 features so extract a single feature to compare.

    Extract the first feature of the 74th observation. This sequence is shorter than 14 time steps.

    s{74}(1,:)
    ans = 1×9
    
        0.6691    0.5291    0.3820    0.3107    0.2546    0.1942    0.0931   -0.0179   -0.1081
    
    
    sPad(1,:,74)
    ans = 1×14
    
        0.5291    0.6691    0.6691    0.5291    0.3820    0.3107    0.2546    0.1942    0.0931   -0.0179   -0.1081   -0.1081   -0.0179    0.0931
    
    
    mask(1,:,74)
    ans = 1×14 logical array
    
       0   0   1   1   1   1   1   1   1   1   1   0   0   0
    
    

    The function centers the sequence and pads at both ends by reflecting the values at the ends of the sequence. The mask shows the location of the original sequence values.

    Extract the first feature of the 28th observation. This sequence is longer than 14 time steps.

    s{28}(1,:)
    ans = 1×16
    
        1.1178    1.0772    1.2365    1.4858    1.6191    1.4893    1.2791    1.4692    1.5592    1.5112    1.5144    1.5871    1.4848    1.2978    1.1336    1.0280
    
    
    sPad(1,:,28)
    ans = 1×14
    
        1.0772    1.2365    1.4858    1.6191    1.4893    1.2791    1.4692    1.5592    1.5112    1.5144    1.5871    1.4848    1.2978    1.1336
    
    
    mask(1,:,28)
    ans = 1×14 logical array
    
       1   1   1   1   1   1   1   1   1   1   1   1   1   1
    
    

    The function centers the sequence and truncates at both ends. The mask shows that all data in the resulting sequence is part of the original sequence.

    Use the padsequences function in conjunction with minibatchqueue to prepare and preprocess sequence data ready for training using a custom training loop.

    The example uses the human activity recognition training data. The data contains six time series of sensor data obtained from a smartphone worn on the body. Each sequence has three features and varies in length. The three features correspond to the accelerometer readings in three different directions.

    Load the training data. Combine the data and labels into a single datastore.

    s = load("HumanActivityTrain.mat");
    
    dsXTrain = arrayDatastore(s.XTrain,'OutputType','same');
    dsYTrain = arrayDatastore(s.YTrain,'OutputType','same');
    
    dsTrain = combine(dsXTrain,dsYTrain);

    Use minibatchqueue to process the mini-batches of sequence data. Define a custom mini-batch preprocessing function preprocessMiniBatch (defined at the end of this example) to pad the sequence data and labels, and one-hot encode the label sequences. To also return the mask of the padded data, specify three output variables for the minibatchqueue object.

    miniBatchSize = 2;
    mbq = minibatchqueue(dsTrain,3,...
        'MiniBatchSize',miniBatchSize,...
        'MiniBatchFcn', @preprocessMiniBatch);

    Check the size of the mini-batches.

    [X,Y,mask] = next(mbq);
    size(X)
    ans = 1×3
    
               3       64480           2
    
    
    size(mask)
    ans = 1×3
    
               3       64480           2
    
    

    Each mini-batch has two observations. The function pads the sequences to the same size as the longest sequence in the mini-batch. The mask is the same size as the padded sequences, and shows the location of the original data values in the padded sequence data.

    size(Y)
    ans = 1×3
    
               5       64480           2
    
    

    The padded labels are one-hot encoded into numeric data ready for training.

    function [xPad,yPad,mask] = preprocessMiniBatch(X,Y)
        [xPad,mask] = padsequences(X,2);
        yPad = padsequences(Y,2);
        yPad = onehotencode(yPad,1);
    end

    Input Arguments

    collapse all

    Sequences to pad, specified as a cell vector of numeric or categorical arrays.

    Data Types: cell

    Dimension along which to pad input sequence data, specified as a positive integer.

    Example: 2

    Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

    Name-Value Arguments

    Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

    Example: padsequences(X,'Length','shortest','Direction','both') truncates the sequences at each end, to match the length of the shortest input sequence.

    Length of padded sequences, specified as one of the following:

    • 'longest' — Pad each input sequence to the same length as the longest input sequence.

    • 'shortest' — Truncate each input sequence to the same length as the shortest input sequence.

    • Positive integer — Pad or truncate each input sequence to the specified length.

    Example: padsequences(X,'Length','shortest')

    Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | char | string

    Direction of padding or truncation, specified as one of the following:

    • 'right' — Pad or truncate at the end of each original sequence.

    • 'left' — Pad or truncate at the beginning of each original sequence.

    • 'both' — Pad or truncate at the beginning and end of each original sequence. Half the required padding or truncation is applied to each end of the sequence.

    Example: padsequences(X,'Direction','both')

    Data Types: char | string

    Value used to pad input, specified as one of the following:

    • 'auto' — Determine the [adding value automatically depending on the data type of the input sequences. Numeric sequences are padded with 0. Categorical sequences are padded with <undefined>.

    • 'symmetric' — Pad each sequence with a mirror reflection of itself.

    • Numeric scalar — Pad each sequence with the specified numeric value.

    • Categorical scalar — Pad each sequence with the specified categorical value.

    Example: padsequences(X,'PaddingValue','symmetric')

    Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | categorical

    Flag to return padded data as a uniform array, specified as a numeric or logical 1 (true) or 0 (false). When you set the value to 0, XPad is returned as a cell vector with the same size and underlying data type as the input X.

    Example: padsequences(X,'UniformOutput',0)

    Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical

    Output Arguments

    collapse all

    Padded sequence data, returned as a numeric array, categorical array, or a cell vector of numeric or categorical arrays.

    If you set the UniformOutput name-value option to true or 1, the function concatenates the padded sequences over the last dimension. The last dimension of XPad has the same size as the number of sequences in input X. XPad is an array with N + 1 dimensions, where N is the number of dimensions of the sequence arrays in X. XPad has the same data type as the arrays in input X.

    If you set the UniformOutput name-value option to false or 0, the function returns the padded sequences as a cell vector with the same size and underlying data type as the input X.

    Position of original sequence data in the padded sequences, returned as a logical array or as a cell vector of logical arrays.

    mask has the same size and data type as XPad. Values of 1 in mask correspond to positions of original sequence values in XPad. Values of 0 correspond to padded values.

    Use mask to excluded padded values from loss calculations using the "Mask" name-value option in the crossentropy function.

    Introduced in R2021a