From 3ac709103a0f47a218a7c4283f31fcf4afdb5fcb Mon Sep 17 00:00:00 2001 From: Hao Jin Date: Fri, 20 Jul 2018 13:21:29 -0700 Subject: [PATCH] detailed doc about global pool layers in Gluon (#11832) --- python/mxnet/gluon/nn/conv_layers.py | 122 +++++++++++++++++++++++++-- 1 file changed, 116 insertions(+), 6 deletions(-) diff --git a/python/mxnet/gluon/nn/conv_layers.py b/python/mxnet/gluon/nn/conv_layers.py index 24f30270ad64..e1f9b9fd05a0 100644 --- a/python/mxnet/gluon/nn/conv_layers.py +++ b/python/mxnet/gluon/nn/conv_layers.py @@ -993,7 +993,25 @@ def __init__(self, pool_size=(2, 2, 2), strides=None, padding=0, class GlobalMaxPool1D(_Pooling): - """Global max pooling operation for temporal data.""" + """Gloabl max pooling operation for one dimensional (temporal) data. + + + Parameters + ---------- + layout : str, default 'NCW' + Dimension ordering of data and weight. Only supports 'NCW' layout for now. + 'N', 'C', 'W' stands for batch, channel, and width (time) dimensions + respectively. Pooling is applied on the W dimension. + + + Inputs: + - **data**: 3D input tensor with shape `(batch_size, in_channels, width)` + when `layout` is `NCW`. For other layouts shape is permuted accordingly. + + Outputs: + - **out**: 3D output tensor with shape `(batch_size, channels, 1)` + when `layout` is `NCW`. + """ def __init__(self, layout='NCW', **kwargs): assert layout == 'NCW', "Only supports 'NCW' layout for now" super(GlobalMaxPool1D, self).__init__( @@ -1001,7 +1019,26 @@ def __init__(self, layout='NCW', **kwargs): class GlobalMaxPool2D(_Pooling): - """Global max pooling operation for spatial data.""" + """Global max pooling operation for two dimensional (spatial) data. + + + Parameters + ---------- + layout : str, default 'NCHW' + Dimension ordering of data and weight. Only supports 'NCHW' layout for now. + 'N', 'C', 'H', 'W' stands for batch, channel, height, and width + dimensions respectively. padding is applied on 'H' and 'W' dimension. + + + Inputs: + - **data**: 4D input tensor with shape + `(batch_size, in_channels, height, width)` when `layout` is `NCHW`. + For other layouts shape is permuted accordingly. + + Outputs: + - **out**: 4D output tensor with shape + `(batch_size, channels, 1, 1)` when `layout` is `NCHW`. + """ def __init__(self, layout='NCHW', **kwargs): assert layout == 'NCHW', "Only supports 'NCHW' layout for now" super(GlobalMaxPool2D, self).__init__( @@ -1009,7 +1046,27 @@ def __init__(self, layout='NCHW', **kwargs): class GlobalMaxPool3D(_Pooling): - """Global max pooling operation for 3D data.""" + """Global max pooling operation for 3D data (spatial or spatio-temporal). + + + Parameters + ---------- + layout : str, default 'NCDHW' + Dimension ordering of data and weight. Only supports 'NCDHW' layout for now. + 'N', 'C', 'H', 'W', 'D' stands for batch, channel, height, width and + depth dimensions respectively. padding is applied on 'D', 'H' and 'W' + dimension. + + + Inputs: + - **data**: 5D input tensor with shape + `(batch_size, in_channels, depth, height, width)` when `layout` is `NCW`. + For other layouts shape is permuted accordingly. + + Outputs: + - **out**: 5D output tensor with shape + `(batch_size, channels, 1, 1, 1)` when `layout` is `NCDHW`. + """ def __init__(self, layout='NCDHW', **kwargs): assert layout == 'NCDHW', "Only supports 'NCDHW' layout for now" super(GlobalMaxPool3D, self).__init__( @@ -1017,7 +1074,23 @@ def __init__(self, layout='NCDHW', **kwargs): class GlobalAvgPool1D(_Pooling): - """Global average pooling operation for temporal data.""" + """Global average pooling operation for temporal data. + + Parameters + ---------- + layout : str, default 'NCW' + Dimension ordering of data and weight. Only supports 'NCW' layout for now. + 'N', 'C', 'W' stands for batch, channel, and width (time) dimensions + respectively. padding is applied on 'W' dimension. + + + Inputs: + - **data**: 3D input tensor with shape `(batch_size, in_channels, width)` + when `layout` is `NCW`. For other layouts shape is permuted accordingly. + + Outputs: + - **out**: 3D output tensor with shape `(batch_size, channels, 1)`. + """ def __init__(self, layout='NCW', **kwargs): assert layout == 'NCW', "Only supports 'NCW' layout for now" super(GlobalAvgPool1D, self).__init__( @@ -1025,7 +1098,25 @@ def __init__(self, layout='NCW', **kwargs): class GlobalAvgPool2D(_Pooling): - """Global average pooling operation for spatial data.""" + """Global average pooling operation for spatial data. + + Parameters + ---------- + layout : str, default 'NCHW' + Dimension ordering of data and weight. Only supports 'NCHW' layout for now. + 'N', 'C', 'H', 'W' stands for batch, channel, height, and width + dimensions respectively. + + + Inputs: + - **data**: 4D input tensor with shape + `(batch_size, in_channels, height, width)` when `layout` is `NCHW`. + For other layouts shape is permuted accordingly. + + Outputs: + - **out**: 4D output tensor with shape + `(batch_size, channels, 1, 1)` when `layout` is `NCHW`. + """ def __init__(self, layout='NCHW', **kwargs): assert layout == 'NCHW', "Only supports 'NCHW' layout for now" super(GlobalAvgPool2D, self).__init__( @@ -1033,7 +1124,26 @@ def __init__(self, layout='NCHW', **kwargs): class GlobalAvgPool3D(_Pooling): - """Global max pooling operation for 3D data.""" + """Global average pooling operation for 3D data (spatial or spatio-temporal). + + Parameters + ---------- + layout : str, default 'NCDHW' + Dimension ordering of data and weight. Can be 'NCDHW', 'NDHWC', etc. + 'N', 'C', 'H', 'W', 'D' stands for batch, channel, height, width and + depth dimensions respectively. padding is applied on 'D', 'H' and 'W' + dimension. + + + Inputs: + - **data**: 5D input tensor with shape + `(batch_size, in_channels, depth, height, width)` when `layout` is `NCDHW`. + For other layouts shape is permuted accordingly. + + Outputs: + - **out**: 5D output tensor with shape + `(batch_size, channels, 1, 1, 1)` when `layout` is `NCDHW`. + """ def __init__(self, layout='NCDHW', **kwargs): assert layout == 'NCDHW', "Only supports 'NCDHW' layout for now" super(GlobalAvgPool3D, self).__init__(