avgpool

Pool data to average values over spatial dimensions

collapse all in page

Syntax

dlY = avgpool(dlX,poolsize)
dlY = avgpool(dlX,poolsize,Name,Value)
dlY = avgpool(dlX,'global')
dlY = avgpool(___,'DataFormat',FMT)

Description

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

Note

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

example

dlY = avgpool(dlX,poolsize) performs downsampling by dividing the input dlX into rectangular or cuboidal regions defined by poolsize and computing the average 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.

example

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

example

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.

example

dlY = avgpool(___,'DataFormat',FMT) 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

collapse all

Pool data to average values over two spatial dimensions.

Create the input data as a dlarray. The data contains 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 average values over pooling regions of size 2 using a stride of 2.

dlY = avgpool(dlX,2,'Stride',2)
dlY = 
  3(S) × 3(S) × 1(C) × 1(B) dlarray

    0.4643    0.4036    0.4041
    0.4324    0.4592    0.3936
    0.5090    0.3967    0.8983

Pool data to its global average 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 average value. Specify the dimension format of the input data.

dlY = avgpool(dlX,'global','DataFormat','SSCB')
dlY = 
  1×1 dlarray

    0.6381

Input Arguments

collapse all

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 avgpool operation divides the data along each 'S' dimension into regions defined by poolsize. Values within each pooling region are averaged.

Data Types: single | double

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 in dlX.

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.

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

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

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

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

collapse all

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.

More About

collapse all

Average Pooling

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

Extended Capabilities

See Also

| | | |

Topics

Introduced in R2019b

Deep Learning Toolbox Documentation

Support