gru

Gated recurrent unit

Syntax

dlY = gru(dlX,H0,weights,recurrentWeights,bias)

[dlY,hiddenState] = gru(dlX,H0,weights,recurrentWeights,bias)

[___] = gru(___,'DataFormat',FMT)

Description

The gated recurrent unit (GRU) operation allows a network to learn dependencies between time steps in time series and sequence data.

Note

This function applies the deep learning GRU operation to dlarray data. If you want to apply an GRU operation within a layerGraph object or Layer array, use the following layer:

gruLayer

example

dlY = gru(dlX,H0,weights,recurrentWeights,bias) applies a gated recurrent unit (GRU) calculation to input dlX using the initial hidden state H0, and parameters weights, recurrentWeights, and bias. The input dlX is a formatted dlarray with dimension labels. The output dlY is a formatted dlarray with the same dimension labels as dlX, except for any 'S' dimensions.

The gru function updates the hidden state using the hyperbolic tangent function (tanh) as the state activation function. The gru function uses the sigmoid function given by $σ (x) = {(1 + e^{- x})}^{- 1}$ as the gate activation function.

[dlY,hiddenState] = gru(dlX,H0,weights,recurrentWeights,bias) also returns the hidden state after the GRU operation.

[___] = gru(___,'DataFormat',FMT) also specifies the dimension format FMT when dlX is not a formatted dlarray. The output dlY is an unformatted dlarray with the same dimension order as dlX, except for any 'S' dimensions.

Examples

collapse all

Apply GRU Operation to Sequence Data

Open Live Script

Perform a GRU operation using 100 hidden units.

Create the input sequence data as 32 observations with ten channels and a sequence length of 64.

numFeatures = 10;
numObservations = 32;
sequenceLength = 64;

X = randn(numFeatures,numObservations,sequenceLength);
dlX = dlarray(X,'CBT');

Create the initial hidden state with 100 hidden units. Use the same initial hidden state for all observations.

numHiddenUnits = 100;
H0 = zeros(numHiddenUnits,1);

Create the learnable parameters for the GRU operation.

weights = dlarray(randn(3*numHiddenUnits,numFeatures));
recurrentWeights = dlarray(randn(3*numHiddenUnits,numHiddenUnits));
bias = dlarray(randn(3*numHiddenUnits,1));

Perform the GRU calculation.

[dlY,hiddenState] = gru(dlX,H0,weights,recurrentWeights,bias);

View the size and dimension labels of dlY.

size(dlY)

ans = 1×3

   100    32    64

dlY.dims

ans = 
'CBT'

View the size of hiddenState.

size(hiddenState)

ans = 1×2

   100    32

You can use the hidden state to keep track of the state of the GRU operation and input further sequential data.

Input Arguments

collapse all

`dlX` — Input data
`dlarray` | numeric array

Input data, specified as a dlarray with or without dimension labels or a numeric array. When dlX is not a formatted dlarray, you must specify the dimension label format using 'DataFormat',FMT. If dlX is a numeric array, at least one of H0, weights, recurrentWeights, or bias must be a dlarray.

dlX must contain a sequence dimension labeled 'T'. If dlX has any spatial dimensions labeled 'S', they are flattened into the 'C' channel dimension. If dlX does not have a channel dimension, then one is added. If dlX has any unspecified dimensions labeled 'U', they must be singleton.