Improve docstrings of applications (#10310)

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
 

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.

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

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

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

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

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

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