avgpool

Pool data to average values over spatial dimensions

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.

dlY = avgpool(dlX,poolsize,'DataFormat',FMT) specifies the dimension labels FMT when dlX is not a formatted dlarray. The output dlY is an unformatted dlarray with the same dimension order as dlX.

dlY = avgpool(___,Name,Value) specifies options using one or more name-value pair arguments in addition to the input arguments in previous syntaxes. For example, 'Stride',3 sets the stride of the pooling operation.

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

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

Dimension order of unformatted input data, specified as the comma-separated pair consisting of 'DataFormat' and a character array or string 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', or 'T' at most once.

You must specify 'DataFormat' when the input data dlX is an unformatted dlarray.

Example: 'DataFormat','SSCB'

Data Types: char | string

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.

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.

Example: 'Stride',3

Data Types: single | double

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.

Example: 'Padding','same'

Data Types: single | double

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

Introduced in R2019b