docs: typing and example of docstring for NerNetwork

deeppavlov/models/ner/network.py

@@ -1,3 +1,4 @@
+from typing import Tuple
 import numpy as np
 import tensorflow as tf
 from functools import partial
@@ -15,6 +16,67 @@
 
 @register('ner')
 class NerNetwork(TFModel):
+    """
+    The ``NerNetwork`` is for Neural Named Entity Recognition and Slot Filling.
+
+    Parameters
+    ----------
+    n_tags : ``int``, required
+        Number of tags in the tag vocabulary.
+    token_emb_dim : ``int`` (default = ``None``)
+        Dimensionality of token embeddings, needed if embedding matrix is not provided.
+    char_emb_dim : ``int`` (default = ``None``)
+        Dimensionality of token embeddings.
+    capitalization_dim : ``int`` (default = ``None``)
+        Dimensionality of capitalization features, if they are provided.
+    pos_features_dim : ``int`` (default = ``None``)
+        Dimensionality of POS features, if they are provided.
+    additional_features : ``int`` (default = ``None``)
+        Some other features.
+    net_type : ``str`` (default = ``'rnn'``)
+        Type of the network, either ``'rnn'`` or ``'cnn'``
+    cell_type : ``str`` (default = ``'lstm'``)
+        Type of the cell in RNN, either ``'lstm'`` or ``'gru'``
+    use_cudnn_rnn : ``bool`` (default = ``False``)
+        Whether to use CUDNN implementation of RNN.
+    two_dense_on_top : ``bool`` (default = ``False``)
+        Additional dense layer before predictions.
+    n_hidden_list : ``Tuple[int]`` (default = ``(100,)``)
+        A list of output feature dimensionality for each layer. A value (100, 200) means that there will be two layers
+        with 100 and 200 units, respectively.
+    cnn_filter_width : ``int`` (default = ``7``)
+        The width of the convolutional kernel for Convolutional Neural Networks.
+    use_crf : ``bool`` (default = ``False``)
+        Whether to use Conditional Random Fields on top of the network (recommended).
+    token_emb_mat : ``numpy.ndarray`` (default = ``None``)
+        Token embeddings matrix.
+    char_emb_mat : ``numpy.ndarray`` (default = ``None``)
+        Character embeddings matrix.
+    use_batch_norm : ``bool`` (default = ``False``)
+        Whether to use Batch Normalization or not. Affects only CNN networks.
+    dropout_keep_prob : ``float`` (default = ``0.5``)
+        Probability of keeping the hidden state, values from 0 to 1. 0.5 works well in most of the cases.
+    embeddings_dropout : ``bool`` (default = ``False``)
+        Whether to use dropout on embeddings or not.
+    top_dropout : ``bool`` (default = ``False``)
+        Whether to use dropout on output units of the network or not.
+    intra_layer_dropout : ``bool`` (default = ``False``)
+        Whether to use dropout between layers or not.
+    l2_reg :``float`` (default = ``0.0``)
+        L2 norm regularization for all kernels.
+    clip_grad_norm :``float`` (default = ``5.0``)
+        Clip the gradients by norm.
+    learning_rate : ``float`` (default = ``3e-3``)
+        Learning rate to use during the training (usually from 0.1 to 0.0001)
+    gpu : ``int`` (default = ``None``)
+        Number of gpu to use.
+    seed : ``int`` (default = ``None``)
+        Random seed.
+    lr_drop_patience : ``int`` (default = ``5``)
+        How many epochs to wait until drop the learning rate.
+    lr_drop_value : ``float`` (default = ``0.1``)
+        Amount of learning rate drop.
+    """
     GRAPH_PARAMS = ["n_tags",  # TODO: add check
                     "char_emb_dim",
                     "capitalization_dim",
@@ -27,33 +89,33 @@ class NerNetwork(TFModel):
                     "cell_type"]
 
     def __init__(self,
-                 n_tags,  # Features dimensions
-                 token_emb_dim=None,
-                 char_emb_dim=None,
-                 capitalization_dim=None,
-                 pos_features_dim=None,
-                 additional_features=None,
-                 net_type='rnn',  # Net architecture
-                 cell_type='lstm',
-                 use_cudnn_rnn=False,
-                 two_dense_on_top=False,
-                 n_hidden_list=(128,),
-                 cnn_filter_width=7,
-                 use_crf=False,
-                 token_emb_mat=None,
-                 char_emb_mat=None,
-                 use_batch_norm=False,
-                 dropout_keep_prob=0.5,  # Regularization
-                 embeddings_dropout=False,
-                 top_dropout=False,
-                 intra_layer_dropout=False,
-                 l2_reg=0.0,
-                 clip_grad_norm=5.0,
-                 learning_rate=3e-3,
-                 gpu=None,
-                 seed=None,
-                 lr_drop_patience=5,
-                 lr_drop_value=0.1,
+                 n_tags: int,  # Features dimensions
+                 token_emb_dim: int = None,
+                 char_emb_dim: int = None,
+                 capitalization_dim: int = None,
+                 pos_features_dim: int = None,
+                 additional_features: int = None,
+                 net_type: str = 'rnn',  # Net architecture
+                 cell_type: str = 'lstm',
+                 use_cudnn_rnn: bool = False,
+                 two_dense_on_top: bool = False,
+                 n_hidden_list: Tuple[int] = (128,),
+                 cnn_filter_width: int = 7,
+                 use_crf: bool = False,
+                 token_emb_mat: np.ndarray = None,
+                 char_emb_mat: np.ndarray = None,
+                 use_batch_norm: bool = False,
+                 dropout_keep_prob: float = 0.5,  # Regularization
+                 embeddings_dropout: bool = False,
+                 top_dropout: bool = False,
+                 intra_layer_dropout: bool = False,
+                 l2_reg: float = 0.0,
+                 clip_grad_norm: float = 5.0,
+                 learning_rate: float = 3e-3,
+                 gpu: int = None,
+                 seed: int = None,
+                 lr_drop_patience: int = 5,
+                 lr_drop_value: float = 0.1,
                  **kwargs):
         tf.set_random_seed(seed)
         np.random.seed(seed)