avgpool

Pool data to average values over spatial dimensions

Syntax

dlY = avgpool(dlX,poolsize)

dlY = avgpool(dlX,'global')

dlY = avgpool(___,'DataFormat',FMT)

dlY = avgpool(___,Name,Value)

Description

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

The avgpool function applies the average pooling operation to 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.

Note

To apply average pooling within a layerGraph object or Layer array, use one of the following layers:

• averagePooling2dLayer

• averagePooling3dLayer

• globalAveragePooling2dLayer

• globalAveragePooling3dLayer

dlY = avgpool(dlX,poolsize) applies the average pooling operation to the formatted dlarray object dlX. The function downsamples the input by dividing it into regions defined by poolsize and calculating the average value of the data in each region. The output dlY is a formatted dlarray with the same dimension labels as dlX.

The function, by default, pools over up to three dimensions of dlX labeled 'S' (spatial). To pool over dimensions labeled 'T' (time), specify a pooling region with a 'T' dimension using the 'PoolFormat' option.

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

dlY = avgpool(___,'DataFormat',FMT) applies the average pooling operation to the unformatted dlarray object dlX with format specified by FMT using any of the previous syntaxes. The output dlY is an unformatted dlarray object with dimensions in the same order as dlX. For example, 'DataFormat','SSCB' specifies data for 2-D average pooling with format 'SSCB' (spatial, spatial, channel, batch).

dlY = avgpool(___,Name,Value) specifies options using one or more name-value pair arguments. For example, 'PoolFormat','T' specifies a pooling region for 1-D pooling with format 'T' (time).

Examples

Perform 2-D Average Pooling

Create a formatted dlarray object containing a batch of 128 28-by-28 images with 3 channels. Specify the format 'SSCB' (spatial, spatial, channel, batch).

miniBatchSize = 128;
inputSize = [28 28];
numChannels = 3;
X = rand(inputSize(1),inputSize(2),numChannels,miniBatchSize);
dlX = dlarray(X,'SSCB');

View the size and format of the input data.

size(dlX)

ans = 1×4

    28    28     3   128

dims(dlX)

ans = 
'SSCB'

Apply 2-D average pooling with 2-by-2 pooling regions using the avgpool function.

poolSize = [2 2];
dlY = avgpool(dlX,poolSize);

View the size and format of the output.

size(dlY)

ans = 1×4

    27    27     3   128

dims(dlY)

ans = 
'SSCB'

Perform 2-D Global Average Pooling

Create a formatted dlarray object containing a batch of 128 28-by-28 images with 3 channels. Specify the format 'SSCB' (spatial, spatial, channel, batch).

miniBatchSize = 128;
inputSize = [28 28];
numChannels = 3;
X = rand(inputSize(1),inputSize(2),numChannels,miniBatchSize);
dlX = dlarray(X,'SSCB');

View the size and format of the input data.

size(dlX)

ans = 1×4

    28    28     3   128

dims(dlX)

ans = 
'SSCB'

Apply 2-D global average pooling using the avgpool function by specifying the 'global' option.

dlY = avgpool(dlX,'global');

View the size and format of the output.

size(dlY)

ans = 1×4

     1     1     3   128

dims(dlY)

ans = 
'SSCB'

Perform 1-D Average Pooling

Create a formatted dlarray object containing a batch of 128 sequences of length 100 with 12 channels. Specify the format 'CBT' (channel, batch, time).

miniBatchSize = 128;
sequenceLength = 100;
numChannels = 12;
X = rand(numChannels,miniBatchSize,sequenceLength);
dlX = dlarray(X,'CBT');

View the size and format of the input data.

size(dlX)

ans = 1×3

    12   128   100

dims(dlX)

ans = 
'CBT'

Apply 1-D average pooling with pooling regions of size 2 with a stride of 2 using the avgpool function by specifying the 'PoolFormat' and 'Stride' options.

poolSize = 2;
dlY = avgpool(dlX,poolSize,'PoolFormat','T','Stride',2);

View the size and format of the output.

size(dlY)

ans = 1×3

    12   128    50

dims(dlY)

ans = 
'CBT'

Input Arguments

dlX — Input data

dlarray

Input data, specified as a formatted or unformatted dlarray object.

If dlX is an unformatted dlarray, then you must specify the format using the 'DataFormat' option.

The function, by default, pools over up to three dimensions of dlX labeled 'S' (spatial). To pool over dimensions labeled 'T' (time), specify a pooling region with a 'T' dimension using the 'PoolFormat' option.

poolsize — Size of pooling regions

positive integer | vector of positive integers

Size of the pooling regions, specified as a numeric scalar or numeric vector.

To pool using a pooling region with edges of the same size, specify poolsize as a scalar. The pooling regions have the same size along all dimensions specified by 'PoolFormat'.

To pool using a pooling region with edges of different sizes, specify poolsize as a vector, where poolsize(i) is the size of corresponding dimension in 'PoolFormat'.

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

character vector | string scalar

Dimension order of unformatted input data, specified as the comma-separated pair consisting of 'DataFormat' and a character vector or string scalar FMT that provides a label for each dimension of the data.

When specifying the format of a dlarray object, each character provides a label for each dimension of the data and must be one of the following:

• 'S' — Spatial

• 'C' — Channel

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

• 'T' — Time (for example, time steps of 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 is not a formatted dlarray.

Example: 'DataFormat','SSCB'

Data Types: char | string

'PoolFormat' — Dimension order of pooling region

character vector | string scalar

Dimension order of the pooling region, specified as the comma-separated pair consisting of 'PoolFormat' and a character vector or string scalar that provides a label for each dimension of the pooling region.

The default value of 'PoolFormat' depends on the task:

Task	Default
1-D pooling	'S' (spatial)
2-D pooling	'SS' (spatial, spatial)
3-D pooling	'SSS' (spatial, spatial, spatial)

The format must have either no 'S' (spatial) dimensions, or as many 'S' (spatial) dimensions as the input data.

The function, by default, pools over up to three dimensions of dlX labeled 'S' (spatial). To pool over dimensions labeled 'T' (time), specify a pooling region with a 'T' dimension using the 'PoolFormat' option.

Example: 'PoolFormat','T'

'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' — Size of padding applied to edges of data

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

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

• 'same' — Padding size 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 amount of padding is applied to both ends of all spatial dimensions.

• Numeric vector — A different amount of padding 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 size of padding applied to the start and the end along the ith spatial dimension.

• Numeric matrix — A different amount of padding 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 size of padding applied to the start of spatial dimension d. The element (2,d) specifies the size of padding applied to the end of spatial dimension d. For example, in 2-D, the format is [top, left; bottom, right].

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

Example: 'Padding','same'

Data Types: single | double

'PaddingValue' — Value used to pad input

0 (default) | 'mean'

Value used to pad input, specified as 0 or 'mean'.

When you use the 'Padding' option to add padding to the input, the value of the padding applied can be one of the following:

• 0 — Input is padded with zeros at the positions specified by the 'Padding' option. The padded areas are included in the calculation of the average value of the pooling regions along the edges.

• 'mean' — Input is padded with the mean of the pooling region at the positions specified by the 'Padding' option. The padded areas are effectively excluded from the calculation of the average value of each pooling region.

Example: 'PaddingValue','mean'

Output Arguments

dlY — Pooled data

dlarray

Pooled data, returned as a dlarray with the same underlying data type as dlX.

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

More About

Average Pooling

The avgpool function pools the input data to average values. For more information, see the definition of Average Pooling Layer on the averagePooling2dLayer reference page.

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).