From 315a80ae3cb65da2aa6308abd483f2f8643f1c8b Mon Sep 17 00:00:00 2001 From: Taehoon Lee Date: Wed, 30 May 2018 01:43:37 +0900 Subject: [PATCH] Improve docstrings of applications (#10310) --- docs/templates/applications.md | 82 ++++++++++------------- keras/applications/densenet.py | 15 ++--- keras/applications/inception_resnet_v2.py | 16 ++--- keras/applications/inception_v3.py | 15 ++--- keras/applications/nasnet.py | 27 ++++---- keras/applications/resnet50.py | 15 ++--- keras/applications/vgg16.py | 15 ++--- keras/applications/vgg19.py | 15 ++--- 8 files changed, 79 insertions(+), 121 deletions(-) diff --git a/docs/templates/applications.md b/docs/templates/applications.md index bf4e076744a..40aff1f3998 100644 --- a/docs/templates/applications.md +++ b/docs/templates/applications.md @@ -20,10 +20,11 @@ Weights are downloaded automatically when instantiating a model. They are stored - [NASNet](#nasnet) - [MobileNetV2](#mobilenetv2) -All of these architectures (except Xception and MobileNet) are compatible with both TensorFlow and Theano, and upon instantiation the models will be built according to the image data format set in your Keras configuration file at `~/.keras/keras.json`. For instance, if you have set `image_data_format=channels_last`, then any model loaded from this repository will get built according to the TensorFlow data format convention, "Height-Width-Depth". +All of these architectures are compatible with all the backends (TensorFlow, Theano, and CNTK), and upon instantiation the models will be built according to the image data format set in your Keras configuration file at `~/.keras/keras.json`. For instance, if you have set `image_data_format=channels_last`, then any model loaded from this repository will get built according to the TensorFlow data format convention, "Height-Width-Depth". -The Xception model is only available for TensorFlow, due to its reliance on `SeparableConvolution` layers. -The MobileNet model is only available for TensorFlow, due to its reliance on `DepthwiseConvolution` layers. +Note that: +- For `Keras < 2.1.7`, The Xception model is only available for TensorFlow, due to its reliance on `SeparableConvolution` layers. +- For `Keras < 2.1.5`, The MobileNet model is only available for TensorFlow, due to its reliance on `DepthwiseConvolution` layers. ----- @@ -200,9 +201,7 @@ Xception V1 model, with weights pre-trained on ImageNet. On ImageNet, this model gets to a top-1 validation accuracy of 0.790 and a top-5 validation accuracy of 0.945. -Note that this model is only available for the TensorFlow backend, -due to its reliance on `SeparableConvolution` layers. Additionally it only supports -the data format `'channels_last'` (height, width, channels). +Note that this model only supports the data format `'channels_last'` (height, width, channels). The default input size for this model is 299x299. @@ -256,8 +255,7 @@ keras.applications.vgg16.VGG16(include_top=True, weights='imagenet', input_tenso VGG16 model, with weights pre-trained on ImageNet. -This model is available for both the Theano and TensorFlow backend, and can be built both -with `'channels_first'` data format (channels, height, width) or `'channels_last'` data format (height, width, channels). +This model can be built both with `'channels_first'` data format (channels, height, width) or `'channels_last'` data format (height, width, channels). The default input size for this model is 224x224. @@ -312,8 +310,7 @@ keras.applications.vgg19.VGG19(include_top=True, weights='imagenet', input_tenso VGG19 model, with weights pre-trained on ImageNet. -This model is available for both the Theano and TensorFlow backend, and can be built both -with `'channels_first'` data format (channels, height, width) or `'channels_last'` data format (height, width, channels). +This model can be built both with `'channels_first'` data format (channels, height, width) or `'channels_last'` data format (height, width, channels). The default input size for this model is 224x224. @@ -369,8 +366,7 @@ keras.applications.resnet50.ResNet50(include_top=True, weights='imagenet', input ResNet50 model, with weights pre-trained on ImageNet. -This model is available for both the Theano and TensorFlow backend, and can be built both -with `'channels_first'` data format (channels, height, width) or `'channels_last'` data format (height, width, channels). +This model and can be built both with `'channels_first'` data format (channels, height, width) or `'channels_last'` data format (height, width, channels). The default input size for this model is 224x224. @@ -425,8 +421,7 @@ keras.applications.inception_v3.InceptionV3(include_top=True, weights='imagenet' Inception V3 model, with weights pre-trained on ImageNet. -This model is available for both the Theano and TensorFlow backend, and can be built both -with `'channels_first'` data format (channels, height, width) or `'channels_last'` data format (height, width, channels). +This model and can be built both with `'channels_first'` data format (channels, height, width) or `'channels_last'` data format (height, width, channels). The default input size for this model is 299x299. @@ -481,8 +476,7 @@ keras.applications.inception_resnet_v2.InceptionResNetV2(include_top=True, weigh Inception-ResNet V2 model, with weights pre-trained on ImageNet. -This model is available for Theano, TensorFlow and CNTK backends, and can be built both -with `'channels_first'` data format (channels, height, width) or `'channels_last'` data format (height, width, channels). +This model and can be built both with `'channels_first'` data format (channels, height, width) or `'channels_last'` data format (height, width, channels). The default input size for this model is 299x299. @@ -537,20 +531,17 @@ keras.applications.mobilenet.MobileNet(input_shape=None, alpha=1.0, depth_multip MobileNet model, with weights pre-trained on ImageNet. -Note that only TensorFlow is supported for now, -therefore it only works with the data format -`image_data_format='channels_last'` in your Keras config at `~/.keras/keras.json`. -To load a MobileNet model via `load_model`, import the custom objects `relu6` and `DepthwiseConv2D` and pass them to the `custom_objects` parameter. +Note that this model only supports the data format `'channels_last'` (height, width, channels). + +To load a MobileNet model via `load_model`, import the custom object `relu6` and pass it to the `custom_objects` parameter. E.g. ```python model = load_model('mobilenet.h5', custom_objects={ - 'relu6': mobilenet.relu6, - 'DepthwiseConv2D': mobilenet.DepthwiseConv2D}) + 'relu6': mobilenet.relu6}) ``` - The default input size for this model is 224x224. ### Arguments @@ -618,16 +609,11 @@ keras.applications.densenet.DenseNet169(include_top=True, weights='imagenet', in keras.applications.densenet.DenseNet201(include_top=True, weights='imagenet', input_tensor=None, input_shape=None, pooling=None, classes=1000) ``` -Optionally loads weights pre-trained -on ImageNet. Note that when using TensorFlow, -for best performance you should set -`image_data_format='channels_last'` in your Keras config -at ~/.keras/keras.json. +DenseNet models, with weights pre-trained on ImageNet. -The model and the weights are compatible with -TensorFlow, Theano, and CNTK. The data format -convention used by the model is the one -specified in your Keras config file. +This model and can be built both with `'channels_first'` data format (channels, height, width) or `'channels_last'` data format (height, width, channels). + +The default input size for this model is 224x224. ### Arguments @@ -681,12 +667,7 @@ keras.applications.nasnet.NASNetLarge(input_shape=None, include_top=True, weight keras.applications.nasnet.NASNetMobile(input_shape=None, include_top=True, weights='imagenet', input_tensor=None, pooling=None, classes=1000) ``` -Neural Architecture Search Network (NASNet) model, with weights pre-trained on ImageNet. - -Note that only TensorFlow is supported for now, -therefore it only works with the data format -`image_data_format='channels_last'` in your Keras config at `~/.keras/keras.json`. - +Neural Architecture Search Network (NASNet) models, with weights pre-trained on ImageNet. The default input size for the NASNetLarge model is 331x331 and for the NASNetMobile model is 224x224. @@ -746,14 +727,21 @@ These weights are released under [the Apache License](https://github.com/tensorf ```python keras.applications.mobilenetv2(input_shape=None, alpha=1.0, depth_multiplier=1, include_top=True, weights='imagenet', input_tensor=None, classes=1000) ``` -MobileNetV2 is a general architecture and can be used for multiple use cases. -Depending on the use case, it can use different input layer size and -different width factors. This allows different width models to reduce -the number of multiply-adds and thereby -reduce inference cost on mobile devices. -The number of parameters and number of multiply-adds -can be modified by using the `alpha` parameter, -which increases/decreases the number of filters in each layer. + +MobileNet model, with weights pre-trained on ImageNet. + +Note that this model only supports the data format `'channels_last'` (height, width, channels). + +To load a MobileNet model via `load_model`, import the custom object `relu6` and pass it to the `custom_objects` parameter. + +E.g. + +```python +model = load_model('mobilenet_v2.h5', custom_objects={ + 'relu6': mobilenet.relu6}) +``` + +The default input size for this model is 224x224. ### Arguments @@ -797,7 +785,7 @@ A Keras model instance. ValueError: in case of invalid argument for `weights`, or invalid input shape or invalid depth_multiplier, alpha, - rows when weights='imagenet + rows when weights='imagenet' ### References diff --git a/keras/applications/densenet.py b/keras/applications/densenet.py index 5d8ff931662..c35027b8cdc 100644 --- a/keras/applications/densenet.py +++ b/keras/applications/densenet.py @@ -119,16 +119,11 @@ def DenseNet(blocks, classes=1000): """Instantiates the DenseNet architecture. - Optionally loads weights pre-trained - on ImageNet. Note that when using TensorFlow, - for best performance you should set - `image_data_format='channels_last'` in your Keras config - at ~/.keras/keras.json. - - The model and the weights are compatible with - TensorFlow, Theano, and CNTK. The data format - convention used by the model is the one - specified in your Keras config file. + Optionally loads weights pre-trained on ImageNet. + Note that the data format convention used by the model is + the one specified in your Keras config at `~/.keras/keras.json`. + When using TensorFlow, for best performance you should + set `"image_data_format": "channels_last"` in the config. # Arguments blocks: numbers of building blocks for the four dense layers. diff --git a/keras/applications/inception_resnet_v2.py b/keras/applications/inception_resnet_v2.py index 867f764e2ee..58d70511449 100644 --- a/keras/applications/inception_resnet_v2.py +++ b/keras/applications/inception_resnet_v2.py @@ -183,18 +183,10 @@ def InceptionResNetV2(include_top=True, """Instantiates the Inception-ResNet v2 architecture. Optionally loads weights pre-trained on ImageNet. - Note that when using TensorFlow, for best performance you should - set `"image_data_format": "channels_last"` in your Keras config - at `~/.keras/keras.json`. - - The model and the weights are compatible with TensorFlow, Theano and - CNTK backends. The data format convention used by the model is - the one specified in your Keras config file. - - Note that the default input image size for this model is 299x299, instead - of 224x224 as in the VGG16 and ResNet models. Also, the input preprocessing - function is different (i.e., do not use `imagenet_utils.preprocess_input()` - with this model. Use `preprocess_input()` defined in this module instead). + Note that the data format convention used by the model is + the one specified in your Keras config at `~/.keras/keras.json`. + When using TensorFlow, for best performance you should + set `"image_data_format": "channels_last"` in the config. # Arguments include_top: whether to include the fully-connected diff --git a/keras/applications/inception_v3.py b/keras/applications/inception_v3.py index 9981e221c2c..49d67e83e62 100644 --- a/keras/applications/inception_v3.py +++ b/keras/applications/inception_v3.py @@ -92,16 +92,11 @@ def InceptionV3(include_top=True, classes=1000): """Instantiates the Inception v3 architecture. - Optionally loads weights pre-trained - on ImageNet. Note that when using TensorFlow, - for best performance you should set - `image_data_format='channels_last'` in your Keras config - at ~/.keras/keras.json. - The model and the weights are compatible with both - TensorFlow and Theano. The data format - convention used by the model is the one - specified in your Keras config file. - Note that the default input image size for this model is 299x299. + Optionally loads weights pre-trained on ImageNet. + Note that the data format convention used by the model is + the one specified in your Keras config at `~/.keras/keras.json`. + When using TensorFlow, for best performance you should + set `"image_data_format": "channels_last"` in the config. # Arguments include_top: whether to include the fully-connected diff --git a/keras/applications/nasnet.py b/keras/applications/nasnet.py index 7f711b67b24..fb1a902ea42 100644 --- a/keras/applications/nasnet.py +++ b/keras/applications/nasnet.py @@ -80,10 +80,11 @@ def NASNet(input_shape=None, default_size=None): '''Instantiates a NASNet model. - Note that only TensorFlow is supported for now, - therefore it only works with the data format - `image_data_format='channels_last'` in your Keras config - at `~/.keras/keras.json`. + Optionally loads weights pre-trained on ImageNet. + Note that the data format convention used by the model is + the one specified in your Keras config at `~/.keras/keras.json`. + When using TensorFlow, for best performance you should + set `"image_data_format": "channels_last"` in the config. # Arguments input_shape: Optional shape tuple, the input shape @@ -315,10 +316,11 @@ def NASNetLarge(input_shape=None, classes=1000): '''Instantiates a NASNet model in ImageNet mode. - Note that only TensorFlow is supported for now, - therefore it only works with the data format - `image_data_format='channels_last'` in your Keras config - at `~/.keras/keras.json`. + Optionally loads weights pre-trained on ImageNet. + Note that the data format convention used by the model is + the one specified in your Keras config at `~/.keras/keras.json`. + When using TensorFlow, for best performance you should + set `"image_data_format": "channels_last"` in the config. # Arguments input_shape: Optional shape tuple, only to be specified @@ -381,10 +383,11 @@ def NASNetMobile(input_shape=None, classes=1000): '''Instantiates a Mobile NASNet model in ImageNet mode. - Note that only TensorFlow is supported for now, - therefore it only works with the data format - `image_data_format='channels_last'` in your Keras config - at `~/.keras/keras.json`. + Optionally loads weights pre-trained on ImageNet. + Note that the data format convention used by the model is + the one specified in your Keras config at `~/.keras/keras.json`. + When using TensorFlow, for best performance you should + set `"image_data_format": "channels_last"` in the config. # Arguments input_shape: Optional shape tuple, only to be specified diff --git a/keras/applications/resnet50.py b/keras/applications/resnet50.py index e4eadff3312..e130519c90a 100644 --- a/keras/applications/resnet50.py +++ b/keras/applications/resnet50.py @@ -132,16 +132,11 @@ def ResNet50(include_top=True, weights='imagenet', classes=1000): """Instantiates the ResNet50 architecture. - Optionally loads weights pre-trained - on ImageNet. Note that when using TensorFlow, - for best performance you should set - `image_data_format='channels_last'` in your Keras config - at ~/.keras/keras.json. - - The model and the weights are compatible with both - TensorFlow and Theano. The data format - convention used by the model is the one - specified in your Keras config file. + Optionally loads weights pre-trained on ImageNet. + Note that the data format convention used by the model is + the one specified in your Keras config at `~/.keras/keras.json`. + When using TensorFlow, for best performance you should + set `"image_data_format": "channels_last"` in the config. # Arguments include_top: whether to include the fully-connected diff --git a/keras/applications/vgg16.py b/keras/applications/vgg16.py index c31ff3b9b5a..334f97b4d37 100644 --- a/keras/applications/vgg16.py +++ b/keras/applications/vgg16.py @@ -40,16 +40,11 @@ def VGG16(include_top=True, weights='imagenet', classes=1000): """Instantiates the VGG16 architecture. - Optionally loads weights pre-trained - on ImageNet. Note that when using TensorFlow, - for best performance you should set - `image_data_format='channels_last'` in your Keras config - at ~/.keras/keras.json. - - The model and the weights are compatible with both - TensorFlow and Theano. The data format - convention used by the model is the one - specified in your Keras config file. + Optionally loads weights pre-trained on ImageNet. + Note that the data format convention used by the model is + the one specified in your Keras config at `~/.keras/keras.json`. + When using TensorFlow, for best performance you should + set `"image_data_format": "channels_last"` in the config. # Arguments include_top: whether to include the 3 fully-connected diff --git a/keras/applications/vgg19.py b/keras/applications/vgg19.py index 600e01a75fb..3931f802bee 100644 --- a/keras/applications/vgg19.py +++ b/keras/applications/vgg19.py @@ -40,16 +40,11 @@ def VGG19(include_top=True, weights='imagenet', classes=1000): """Instantiates the VGG19 architecture. - Optionally loads weights pre-trained - on ImageNet. Note that when using TensorFlow, - for best performance you should set - `image_data_format='channels_last'` in your Keras config - at ~/.keras/keras.json. - - The model and the weights are compatible with both - TensorFlow and Theano. The data format - convention used by the model is the one - specified in your Keras config file. + Optionally loads weights pre-trained on ImageNet. + Note that the data format convention used by the model is + the one specified in your Keras config at `~/.keras/keras.json`. + When using TensorFlow, for best performance you should + set `"image_data_format": "channels_last"` in the config. # Arguments include_top: whether to include the 3 fully-connected