maxpool

Pool data to maximum value

Syntax

dlY = maxpool(dlX,poolsize)

[dlY,indx,inputSize] = maxpool(dlX,poolsize)

___ = maxpool(___,Name,Value)

dlY = maxpool(dlX,'global')

___ = maxpool(___,'DataFormat',FMT)

Description

The maximum pooling operation performs downsampling by dividing the input into pooling regions and computing the maximum value of each region.

Note

This function applies the maximum pooling operation to dlarray data. If you want to apply maximum pooling within a layerGraph object or Layer array, use one of the following layers:

• maxPooling2dLayer

• maxPooling3dLayer

dlY = maxpool(dlX,poolsize) performs downsampling by dividing the input dlX into rectangular or cuboidal regions defined by poolsize and computing the maximum value of the data in each region. The input dlX is a formatted dlarray with dimension labels. Pooling acts on spatial dimensions labeled 'S'. The output dlY is a formatted dlarray with the same dimension labels as dlX.

[dlY,indx,inputSize] = maxpool(dlX,poolsize) also returns the linear indices of the maximum value within each pooled region and the size of the input feature map dlX for use with the maxunpool operation.

___ = maxpool(___,Name,Value) specifies options using one or more name-value pair arguments. For example, 'Stride',3 sets the stride of the pooling operation.

dlY = maxpool(dlX,'global') computes the global maximum over the spatial dimensions of the input dlX. This syntax is equivalent to setting poolsize in the previous syntaxes to the size of the 'S' dimensions of dlX.

___ = maxpool(___,'DataFormat',FMT) also specifies the dimension format FMT when dlX is not a formatted dlarray, in addition to the input arguments in previous syntaxes. The output dlY is an unformatted dlarray with the same dimension order as dlX.

Examples

Pool Data to Maximum Values

Pool data to maximum values over two spatial dimensions.

Create the input data as a single observation of random values with a height and width of six and a single channel.

height = 6;
width = 6;
channels = 1;
observations = 1;

X = rand(height,width,channels,observations);
dlX = dlarray(X,'SSCB')

dlX = 
  6(S) × 6(S) × 1(C) × 1(B) dlarray

    0.1781    0.8819    0.1564    0.4820    0.2518    0.7302
    0.1280    0.6692    0.8555    0.1206    0.2904    0.3439
    0.9991    0.1904    0.6448    0.5895    0.6171    0.5841
    0.1711    0.3689    0.3763    0.2262    0.2653    0.1078
    0.0326    0.4607    0.1909    0.3846    0.8244    0.9063
    0.5612    0.9816    0.4283    0.5830    0.9827    0.8797

Pool the data to maximum values over pooling regions of size 2 using a stride of 2.

dlY = maxpool(dlX,2,'Stride',2)

dlY = 
  3(S) × 3(S) × 1(C) × 1(B) dlarray

    0.8819    0.8555    0.7302
    0.9991    0.6448    0.6171
    0.9816    0.5830    0.9827

Pool Data to Global Maximum Value

Pool data to its global maximum value.

Create the input data as an unformatted dlarray. The data contains a single observation of random values with a height of four, a width of six, and a single channel.

height = 4;
width = 6;
channels = 1;
observations = 1;

X = rand(height,width,channels,observations);
dlX = dlarray(X)

dlX = 
  4×6 dlarray

    0.8147    0.6324    0.9575    0.9572    0.4218    0.6557
    0.9058    0.0975    0.9649    0.4854    0.9157    0.0357
    0.1270    0.2785    0.1576    0.8003    0.7922    0.8491
    0.9134    0.5469    0.9706    0.1419    0.9595    0.9340

Pool the data to the global maximum value. Specify the dimension format of the input data.

dlY = maxpool(dlX,'global','DataFormat','SSCB')

dlY = 
  1×1 dlarray

    0.9706

Input Arguments

dlX — Input data

dlarray

Input data, specified as a dlarray with or without dimension labels. When dlX is not a formatted dlarray, you must specify the dimension label format using 'DataFormat',FMT.

Pooling acts on dimensions that you specify as spatial dimensions using the 'S' dimension label. dlX must have at least one 'S' dimension. You can specify up to three dimensions in dlX as 'S' dimensions. The maxpool operation divides the data along each 'S' dimension into regions defined by poolsize. The function computes the maximum of all values within each pooling region.

Data Types: single | double

poolsize — Size of pooling regions

numeric scalar | numeric vector

Size of the pooling regions, specified as a numeric scalar or numeric vector. If you specify poolsize as a scalar, the pooling regions have the same size along all spatial dimensions. To use rectangular or cuboidal pooling regions that have different sizes along each spatial dimension, specify poolsize as a vector with the same length as the number of spatial dimensions.

Example: 3

Data Types: single | double

Name-Value Pair 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: 'Stride',2 specifies the stride of the pooling regions as 2.

'DataFormat' — Dimension order of unformatted data

char array | string

Dimension order of unformatted input data, specified as the comma-separated pair consisting of 'DataFormat' and a character array or string FMT that provides a label for each dimension of the data. Each character in FMT must be one of the following:

• 'S' — Spatial

• 'C' — Channel

• 'B' — Batch (for example, samples and observations)

• 'T' — Time (for example, sequences)

• 'U' — Unspecified

You can specify multiple dimensions labeled 'S' or 'U'. You can use the labels 'C', 'B', and 'T' at most once.

You must specify 'DataFormat' when the input data dlX is not a formatted dlarray.

Example: 'DataFormat','SSCB'

Data Types: char | string

'Stride' — Step size for traversing input data

1 (default) | numeric scalar | numeric vector

Step size for traversing the input data, specified as the comma-separated pair consisting of 'Stride' and a numeric scalar or numeric vector. If you specify 'Stride' as a scalar, the same value is used for all spatial dimensions. If you specify 'Stride' as a vector of the same size as the number of spatial dimensions of the input data, the vector values are used for the corresponding spatial dimensions.

The default value of 'Stride' is 1. If 'Stride' is less than poolsize in any dimension, then the pooling regions overlap.

The Stride parameter is not supported for global pooling using the 'global' option.

Example: 'Stride',3

Data Types: single | double

'Padding' — Padding applied to edges of data

0 (default) | 'same' | numeric scalar | numeric vector | numeric matrix

Padding applied to edges of data, specified as the comma-separated pair consisting of 'Padding' and one of the following:

• 'same' — Padding is set so that the output size is the same as the input size when the stride is 1. More generally, the output size of each spatial dimension is ceil(inputSize/stride), where inputSize is the size of the input along a spatial dimension.

• Numeric scalar — The same padding value is applied to both ends of all spatial dimensions.

• Numeric vector — A different padding value is applied along each spatial dimension. Use a vector of size d, where d is the number of spatial dimensions of the input data. The ith element of the vector specifies the padding applied to the start and the end along the ith spatial dimension.

• Numeric matrix — A different padding value is applied to the start and end of each spatial dimension. Use a matrix of size 2-by-d, where d is the number of spatial dimensions of the input data. The element (1,d) specifies the padding applied to the start of spatial dimension d. The element (2,d) specifies the padding applied to the end of spatial dimension d. For example, in 2-D, the format is [top, left; bottom, right].

The default value of 'Padding' is 0.

The 'Padding' parameter is not supported for global pooling using the 'global' option.

Example: 'Padding','same'

Data Types: single | double

Output Arguments

dlY — Pooled data

dlarray

Pooled data, returned as a dlarray. The output dlY has the same underlying data type as the input dlX.

If the input data dlX is a formatted dlarray, dlY has the same dimension labels as dlX. If the input data is not a formatted dlarray, dlY is an unformatted dlarray with the same dimension order as the input data.

indx — Indices of maximum values

dlarray

Indices of maximum values in each pooled region, returned as a dlarray. Each value in indx represents the location of the corresponding maximum value in dlY, given as a linear index of the values in dlX.

If dlX is a formatted dlarray, indx has the same size and format as the output dlY.

If dlX is not a formatted dlarray, indx is an unformatted dlarray. In that case, indx is returned with the following dimension order: all 'S' dimensions, followed by 'C', 'B', and 'T' dimensions, then all 'U' dimensions. The size of indx matches the size of dlY when dlY is permuted to match the previously stated dimension order.

Use the indx output with the maxunpool function to unpool the output of maxpool.

indx output is not supported when using the 'global' option.

inputSize — Size of input feature map

numeric vector

Size of the input feature map, returned as a numeric vector.

Use the inputSize output with the maxunpool function to unpool the output of maxpool.

inputSize output is not supported when using the 'global' option.

More About

Maximum Pooling

The maxpool function pools the input data to maximum values over the spatial dimensions. For more information, see the definition of Max Pooling Layer on the maxPooling2dLayer reference page.

Compatibility Considerations

maxpool indices output argument changes shape and data type

Behavior changed in R2020a

Starting in R2020a, the data type and shape of the indices output argument of the maxpool function are changed. The maxpool function outputs the indices of the maximum values as a dlarray with the same shape and format as the pooled data, instead of a numeric vector.

The indices output of maxpool remains compatible with the indices input of maxunpool. The maxunpool function accepts the indices of the maximum values as a dlarray with the same shape and format as the input data. To prevent errors, use only the indices output of the maxpool function as the indices input to the maxunpool function.

To reproduce the previous behavior and obtain the indices output as a numeric vector, use the following code:

[dlY,indx,inputSize] = maxpool(dlY,poolsize);
indx = extractdata(indx);
indx = reshape(indx,[],1);

Extended Capabilities

GPU Arrays

Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

Usage notes and limitations:

• When the input argument dlX is a dlarray with underlying data of type gpuArray, this function runs on the GPU.

For more information, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox).