Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix doc of accuracy function #7091

Closed
wants to merge 2 commits into from
Closed

Fix doc of accuracy function #7091

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
295e893
Fix doc of accuracy function
wanghaoshuang Dec 28, 2017
2910302
Merge branch 'develop' of /~https://github.com/PaddlePaddle/Paddle into…
wanghaoshuang Dec 28, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
151 changes: 111 additions & 40 deletions python/paddle/v2/fluid/layers/nn.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -151,7 +151,7 @@ def embedding(input, size, is_sparse=False, param_attr=None, dtype='float32'):

Args:
input(Variable): Input to the function
size(tuple|list|None): Shape of the look up table parameter
size(tuple|list|None): Shape of the look up table parameter
is_sparse(bool): Boolean flag that specifying whether the input is sparse
param_attr(ParamAttr): Parameters for this layer
dtype(np.dtype|core.DataType|str): The type of data : float32, float_16, int etc
Expand Down Expand Up @@ -446,8 +446,79 @@ def square_error_cost(input, label, **kwargs):

def accuracy(input, label, k=1, correct=None, total=None, **kwargs):
"""
This function computes the accuracy using the input and label.
The output is the top_k inputs and their indices.
This function computes the top-k accuracy using the input and label.
Commonly, it is used for multiclass classification.
Lets say we had only "cat", "dog", "house", "mouse" as classes.
The input gives you a probability for each class. Such as:

.. code-block:: text

0.1; 0.2; 0.0; 0.7

The Top-1 class is "mouse". The top-2 classes are {mouse, dog}.
If the correct class was "dog", it would be counted as "correct"
for the Top-2 accuracy, but as wrong for the Top-1 accuracy.

And the following examples will explain how accuracy function works:

.. code-block:: text

* Case 1
input is a tensor as below:
input.data = [[0.4, 0.5],
[0.7, 0.3],
[0.1, 0.9]]
input.dims = [3, 2]

label is a tensor as below:
label.data = [[0],
[1],
[1]]
label.dims = [3, 1]

then accuracy=(1.0 / 3.0) with k=1
and accuracy=(1.0 / 1.0) with k=2

* Case 2
input is a tensor as below:
input.data = [[0.3, 0.2, 0.5],
[0.7, 0.2, 0.1],
[0.1, 0.6, 0.3],
[0.3, 0.1, 0.6]]
input.dims = [4, 3]

label is a tensor as below:
label.data = [[0],
[1],
[0],
[2]]
label.dims = [4, 1]

then accuracy=(2.0 / 4.0) with k=1
and accuracy=(3.0 / 4.0) with k=2

Args:
input (Variable): The input variable which is a Tensor
with dims.size > 1. Usually, it is the output
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Need to explain the shape of this input, like: batch_size * topk.

of softmax operator.
label (Variable): The label variable which is a Tensor.
The last dim of label tensor must be 1.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The last dim of label tensor must be 1.

Need more clear explain about the shape, same as below.

correct (Variable): It is a Tensor used for collecting number
of correct samples in a batch.
total (Variable): It is a Tensor used for collecting total number
of samples in a batch.


Returns:
accuracy: The Top-k accuracy for input and label.

Examples:
.. code-block:: python

label = fluid.layers.data(name="label", shape=[batch_size, 1],
dtype="int64")
prediction = fluid.layers.fc(input=layer_1, size=20, act="softmax")
acc = fluid.layers.accuracy(input=prediction, label=label, k=3)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Need examples on how to accumulate accuracy across batches.

"""
helper = LayerHelper("accuracy", **kwargs)
topk_out = helper.create_tmp_variable(dtype=input.dtype)
Expand Down Expand Up @@ -699,9 +770,9 @@ def _get_default_param_initializer():

def sequence_pool(input, pool_type, **kwargs):
"""
This function add the operator for sequence pooling.
It pools features of all time-steps of each instance, and is applied
on top of the input using pool_type mentioned in the parameters.
This function add the operator for sequence pooling.
It pools features of all time-steps of each instance, and is applied
on top of the input using pool_type mentioned in the parameters.

It supports four pool_type:

Expand Down Expand Up @@ -730,7 +801,7 @@ def sequence_pool(input, pool_type, **kwargs):

Args:
input(variable): The input variable which is a LoDTensor.
pool_type (string): The pooling type of sequence_pool.
pool_type (string): The pooling type of sequence_pool.
It supports average, sum, sqrt and max.

Returns:
Expand All @@ -740,7 +811,7 @@ def sequence_pool(input, pool_type, **kwargs):

.. code-block:: python

x = fluid.layers.data(name='x', shape=[7, 1],
x = fluid.layers.data(name='x', shape=[7, 1],
dtype='float32', lod_level=1)
avg_x = fluid.layers.sequence_pool(input=x, pool_type='average')
sum_x = fluid.layers.sequence_pool(input=x, pool_type='sum')
Expand Down Expand Up @@ -788,7 +859,7 @@ def sequence_first_step(input, **kwargs):

.. code-block:: python

x = fluid.layers.data(name='x', shape=[7, 1],
x = fluid.layers.data(name='x', shape=[7, 1],
dtype='float32', lod_level=1)
x_first_step = fluid.layers.sequence_first_step(input=x)
"""
Expand Down Expand Up @@ -821,7 +892,7 @@ def sequence_last_step(input, **kwargs):

.. code-block:: python

x = fluid.layers.data(name='x', shape=[7, 1],
x = fluid.layers.data(name='x', shape=[7, 1],
dtype='float32', lod_level=1)
x_last_step = fluid.layers.sequence_last_step(input=x)
"""
Expand Down Expand Up @@ -1240,17 +1311,17 @@ def lstm_unit(x_t,

def reduce_sum(input, dim=None, keep_dim=False):
"""
Computes the sum of tensor elements over the given dimension.
Computes the sum of tensor elements over the given dimension.

Args:
input (Variable): The input variable which is a Tensor or LoDTensor.
dim (int|None): The dimension along which the sum is performed. If
:attr:`None`, sum all elements of :attr:`input` and return a
Tensor variable with a single element, otherwise must be in the
range :math:`[-rank(input), rank(input))`. If :math:`dim < 0`,
dim (int|None): The dimension along which the sum is performed. If
:attr:`None`, sum all elements of :attr:`input` and return a
Tensor variable with a single element, otherwise must be in the
range :math:`[-rank(input), rank(input))`. If :math:`dim < 0`,
the dimension to reduce is :math:`rank + dim`.
keep_dim (bool): Whether to reserve the reduced dimension in the
output Tensor. The result tensor will have one fewer dimension
keep_dim (bool): Whether to reserve the reduced dimension in the
output Tensor. The result tensor will have one fewer dimension
than the :attr:`input` unless :attr:`keep_dim` is true.

Returns:
Expand Down Expand Up @@ -1284,17 +1355,17 @@ def reduce_sum(input, dim=None, keep_dim=False):

def reduce_mean(input, dim=None, keep_dim=False):
"""
Computes the mean of tensor elements over the given dimension.
Computes the mean of tensor elements over the given dimension.

Args:
input (Variable): The input variable which is a Tensor or LoDTensor.
dim (int|None): The dimension along which the mean is computed. If
:attr:`None`, compute the mean over all elements of :attr:`input`
and return a Tensor variable with a single element, otherwise
must be in the range :math:`[-rank(input), rank(input))`. If
dim (int|None): The dimension along which the mean is computed. If
:attr:`None`, compute the mean over all elements of :attr:`input`
and return a Tensor variable with a single element, otherwise
must be in the range :math:`[-rank(input), rank(input))`. If
:math:`dim < 0`, the dimension to reduce is :math:`rank + dim`.
keep_dim (bool): Whether to reserve the reduced dimension in the
output Tensor. The result tensor will have one fewer dimension
keep_dim (bool): Whether to reserve the reduced dimension in the
output Tensor. The result tensor will have one fewer dimension
than the :attr:`input` unless :attr:`keep_dim` is true.

Returns:
Expand Down Expand Up @@ -1328,22 +1399,22 @@ def reduce_mean(input, dim=None, keep_dim=False):

def reduce_max(input, dim=None, keep_dim=False):
"""
Computes the maximum of tensor elements over the given dimension.
Computes the maximum of tensor elements over the given dimension.

Args:
input (Variable): The input variable which is a Tensor or LoDTensor.
dim (int|None): The dimension along which the maximum is computed.
If :attr:`None`, compute the maximum over all elements of
:attr:`input` and return a Tensor variable with a single element,
otherwise must be in the range :math:`[-rank(input), rank(input))`.
dim (int|None): The dimension along which the maximum is computed.
If :attr:`None`, compute the maximum over all elements of
:attr:`input` and return a Tensor variable with a single element,
otherwise must be in the range :math:`[-rank(input), rank(input))`.
If :math:`dim < 0`, the dimension to reduce is :math:`rank + dim`.
keep_dim (bool): Whether to reserve the reduced dimension in the
output Tensor. The result tensor will have one fewer dimension
keep_dim (bool): Whether to reserve the reduced dimension in the
output Tensor. The result tensor will have one fewer dimension
than the :attr:`input` unless :attr:`keep_dim` is true.

Returns:
Variable: The reduced Tensor variable.

Examples:
.. code-block:: python

Expand Down Expand Up @@ -1372,22 +1443,22 @@ def reduce_max(input, dim=None, keep_dim=False):

def reduce_min(input, dim=None, keep_dim=False):
"""
Computes the minimum of tensor elements over the given dimension.
Computes the minimum of tensor elements over the given dimension.

Args:
input (Variable): The input variable which is a Tensor or LoDTensor.
dim (int|None): The dimension along which the minimum is computed.
If :attr:`None`, compute the minimum over all elements of
:attr:`input` and return a Tensor variable with a single element,
otherwise must be in the range :math:`[-rank(input), rank(input))`.
dim (int|None): The dimension along which the minimum is computed.
If :attr:`None`, compute the minimum over all elements of
:attr:`input` and return a Tensor variable with a single element,
otherwise must be in the range :math:`[-rank(input), rank(input))`.
If :math:`dim < 0`, the dimension to reduce is :math:`rank + dim`.
keep_dim (bool): Whether to reserve the reduced dimension in the
output Tensor. The result tensor will have one fewer dimension
keep_dim (bool): Whether to reserve the reduced dimension in the
output Tensor. The result tensor will have one fewer dimension
than the :attr:`input` unless :attr:`keep_dim` is true.

Returns:
Variable: The reduced Tensor variable.

Examples:
.. code-block:: python

Expand Down