indexing1dLayer

1-D indexing layer

Since R2023b

Description

A 1-D indexing layer extracts the data from the specified index of the time or spatial dimensions of the input data.

Creation

Syntax

layer = indexing1dLayer

layer = indexing1dLayer(index)

layer = indexing1dLayer(___,Name=Value)

Description

layer = indexing1dLayer creates a 1-D indexing layer that extracts the data from the first index of the time or spatial dimensions of the input data.

layer = indexing1dLayer(index) creates a 1-D indexing layer object and sets the Index property.

layer = indexing1dLayer(___,Name=Value) sets the 1-D Indexing and Name properties using one or more name-value arguments.

Properties

1-D Indexing

Index — Index of data to extract

"first" (default) | "last"

Index of data to extract, specified as one of these values:

• "first" — Extract data from the first index of the input.

• "last" — Extract data from the last index of the input.

If the layer has a padding mask input, then the layer ignores padding values when it extracts data.

HasPaddingMaskInput — Flag indicating whether layer has mask input

0 (false) (default) | 1 (true)

Flag indicating whether the layer has an input that represents the padding mask, specified as 0 (false) or 1 (true).

If the HasPaddingMaskInput property is 0 (false), then the layer has one input with the name "in", which corresponds to the input data. In this case, the layer treats all elements as data.

If the HasPaddingMaskInput property is 1 (true), then the layer has two inputs with the names "in" and "mask", which correspond to the input data and the mask, respectively. In this case, the padding mask is an array of ones and zeros. The layer uses and ignores elements of the input when the corresponding element in the mask is one or zero, respectively.

Layer

Name — Layer name

"" (default) | character vector | string scalar

Layer name, specified as a character vector or string scalar. For Layer array input, the trainnet and dlnetwork functions automatically assign names to layers with the name "".

The Indexing1DLayer object stores this property as a character vector.

Data Types: char | string

NumInputs — Number of inputs

1 | 2

This property is read-only.

Number of inputs to the layer, returned as 1 or 2.

If the HasPaddingMaskInput property is 0 (false), then the layer has one input with the name "in", which corresponds to the input data. In this case, the layer treats all elements as data.

If the HasPaddingMaskInput property is 1 (true), then the layer has two inputs with the names "in" and "mask", which correspond to the input data and the mask, respectively. In this case, the padding mask is an array of ones and zeros. The layer uses and ignores elements of the input when the corresponding element in the mask is one or zero, respectively.

Data Types: double

InputNames — Input names

"in" | ["in" "mask"]

This property is read-only.

Input names of the layer, returned as a cell array of character vectors.

If the HasPaddingMaskInput property is 0 (false), then the layer has one input with the name "in", which corresponds to the input data. In this case, the layer treats all elements as data.

If the HasPaddingMaskInput property is 1 (true), then the layer has two inputs with the names "in" and "mask", which correspond to the input data and the mask, respectively. In this case, the padding mask is an array of ones and zeros. The layer uses and ignores elements of the input when the corresponding element in the mask is one or zero, respectively.

The Indexing1DLayer object stores this property as a cell array of character vectors.

NumOutputs — Number of outputs

1 (default)

This property is read-only.

Number of outputs from the layer, returned as 1. This layer has a single output only.

Data Types: double

OutputNames — Output names

{'out'} (default)

This property is read-only.

Output names, returned as {'out'}. This layer has a single output only.

Data Types: cell

Examples

Create 1-D Indexing Layer

Create a 1-D indexing layer.

layer = indexing1dLayer

layer = 
  Indexing1DLayer with properties:

                   Name: ''
                  Index: "first"
    HasPaddingMaskInput: 0

   Learnable Parameters
    No properties.

   State Parameters
    No properties.

Use properties method to see a list of all properties.

Include a 1-D indexing layer in a layer graph.

numChannels = 1;

embeddingOutputSize = 64;
numWords = 128;

maxSequenceLength = 100;
maxPosition = maxSequenceLength+1;

numHeads = 4;
numKeyChannels = 4*embeddingOutputSize;

net = dlnetwork;

layers = [ 
    sequenceInputLayer(numChannels)
    wordEmbeddingLayer(embeddingOutputSize,numWords,Name="word-emb")
    embeddingConcatenationLayer(Name="emb-cat")
    positionEmbeddingLayer(embeddingOutputSize,maxPosition,Name="pos-emb");
    additionLayer(2,Name="add")
    selfAttentionLayer(numHeads,numKeyChannels,AttentionMask="causal")
    indexing1dLayer(Name="idx-first")
    fullyConnectedLayer(numWords)
    softmaxLayer];

net = addLayers(net,layers);
net = connectLayers(net,"emb-cat","add/in2");

View the neural network architecture.

plot(net)
axis off
box off

Algorithms

1-D Indexing Layer

A 1-D indexing layer extracts the data from the specified index of the time or spatial dimensions of the input data.

For example:

• For sequence data X represented by a numChannels-by-numObservations-by-numTimeSteps array, where numChannels, numObservations, and numTimeSteps are the numbers of channels, observations, and time steps of the input, respectively, the output is X(:,:,idx), where idx is the index that corresponds to the Index property.

• For 1-D image data X represented by a height-by-numChannels-by-numObservations, where height, numChannels, and numObservations are the height, number of channels, and number of observations of the input images, respectively, the output is X(idx,:,:), where idx is the index that corresponds to the Index property.

Layer Input and Output Formats

Layers in a layer array or layer graph pass data to subsequent layers as formatted dlarray objects. The format of a dlarray object is a string of characters in which each character describes the corresponding dimension of the data. The formats consist of one or more of these characters:

• "S" — Spatial

• "C" — Channel

• "B" — Batch

• "T" — Time

• "U" — Unspecified

For example, you can describe 2-D image data that is represented as a 4-D array, where the first two dimensions correspond to the spatial dimensions of the images, the third dimension corresponds to the channels of the images, and the fourth dimension corresponds to the batch dimension, as having the format "SSCB" (spatial, spatial, channel, batch).

You can interact with these dlarray objects in automatic differentiation workflows, such as those for developing a custom layer, using a functionLayer object, or using the forward and predict functions with dlnetwork objects.

This table shows the supported input formats of Indexing1DLayer objects and the corresponding output format. If the software passes the output of the layer to a custom layer that does not inherit from the nnet.layer.Formattable class, or a FunctionLayer object with the Formattable property set to 0 (false), then the layer receives an unformatted dlarray object with dimensions ordered according to the formats in this table. The formats listed here are only a subset. The layer may support additional formats such as formats with additional "S" (spatial) or "U" (unspecified) dimensions.

Input Format	Output Format
"SCB" (spatial, channel, batch)	"CB" (channel, batch)
"CBT" (channel, batch, time)	"CB" (channel, batch)
"SC" (spatial, channel)	"CU" (channel, unspecified)
"SB" (spatial, batch)	"BU" (batch, unspecified)
"SU" (spatial, unspecified)	"UU" (unspecified, unspecified)

In dlnetwork objects, Indexing1DLayer objects also support these input and output format combinations.

Input Format	Output Format
"CT" (channel, time)	"CU" (channel, unspecified)
"BT" (batch, time)	"BU" (batch, unspecified)
"TU" (time, unspecified)	"UU" (unspecified, unspecified)

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

GPU Code Generation
Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Version History

Introduced in R2023b

R2024a: Code generation support

Generate C or C++ code using MATLAB^® Coder™ or generate CUDA^® code for NVIDIA^® GPUs using GPU Coder™.