Skip to content
GitLab
Commit 5b829ad6 authored by André Anjos's avatar André Anjos 💬
Browse files

Fix documentation building (no more warnings)

parent f34105de
Pipeline #4145 failed with stage
in 7 minutes and 48 seconds
Hide whitespace changes
Inline Side-by-side
bob/measure/__init__.py
View file @ 5b829ad6
......@@ -180,13 +180,13 @@ def recognition_rate(cmc_scores, threshold = None, rank = 1):
probe item**. Each pair can contain up to one empty array (or ``None``),
i.e., in case of open set recognition.
threshold (Optional[float]): Decision threshold. If not ``None``, **all**
threshold (:obj:`float`, optional): Decision threshold. If not ``None``, **all**
scores will be filtered by the threshold. In an open set recognition
problem, all open set scores (negatives with no corresponding positive)
for which all scores are below threshold, will be counted as correctly
rejected and **removed** from the probe list (i.e., the denominator).
rank (Optional[int]):
rank (:obj:`int`, optional):
The rank for which the recognition rate should be computed, 1 by default.
......@@ -350,7 +350,7 @@ def detection_identification_rate(cmc_scores, threshold, rank = 1):
threshold (float): The decision threshold :math:`\\tau``.
rank (Optional[int]): The rank for which the curve should be plotted
rank (:obj:`int`, optional): The rank for which the curve should be plotted
Returns:
......
bob/measure/load.py
View file @ 5b829ad6
......@@ -22,10 +22,10 @@ def open_file(filename, mode='rt'):
Parameters:
filename (str, file): The name of the score file to open, or a file-like
object open for reading. If a file name is given, the according file
might be a raw text file or a (compressed) tar file containing a raw text
file.
filename (:obj:`str`, :obj:`file`): The name of the score file to open, or
a file-like object open for reading. If a file name is given, the
according file might be a raw text file or a (compressed) tar file
containing a raw text file.
Returns:
......@@ -74,8 +74,8 @@ def four_column(filename):
Parameters:
filename (str, file): The file object that will be opened with
:py:func:`open_file` containing the scores.
filename (:obj:`str`, :obj:`file`): The file object that will be opened
with :py:func:`open_file` containing the scores.
Returns:
......@@ -119,8 +119,8 @@ def split_four_column(filename):
Parameters:
filename (str, file): The file object that will be opened with
:py:func:`open_file` containing the scores.
filename (:obj:`str`, :obj:`file`): The file object that will be opened
with :py:func:`open_file` containing the scores.
Returns:
......@@ -155,8 +155,8 @@ def cmc_four_column(filename):
Parameters:
filename (str, file): The file object that will be opened with
:py:func:`open_file` containing the scores.
filename (:obj:`str`, :obj:`file`): The file object that will be opened
with :py:func:`open_file` containing the scores.
Returns:
......@@ -201,7 +201,7 @@ def five_column(filename):
Parameters:
filename (str, file): The file object that will be opened with
filename (:obj:`str`, :obj:`file`): The file object that will be opened with
:py:func:`open_file` containing the scores.
......@@ -248,7 +248,7 @@ def split_five_column(filename):
Parameters:
filename (str, file): The file object that will be opened with
filename (:obj:`str`, :obj:`file`): The file object that will be opened with
:py:func:`open_file` containing the scores.
......@@ -284,7 +284,7 @@ def cmc_five_column(filename):
Parameters:
filename (str, file): The file object that will be opened with
filename (:obj:`str`, :obj:`file`): The file object that will be opened with
:py:func:`open_file` containing the scores.
......@@ -317,12 +317,12 @@ def load_score(filename, ncolumns=None):
Parameters:
filename (str, file): The file object that will be opened with
:py:func:`open_file` containing the scores.
filename (:obj:`str`, :obj:`file`): The file object that will be opened
with :py:func:`open_file` containing the scores.
ncolumns (Optional[int]): 4, 5 or None (the default), specifying the number
of columns in the score file. If None is provided, the number of columns
will be guessed.
ncolumns (:obj:`int`, optional): 4, 5 or None (the default), specifying the
number of columns in the score file. If None is provided, the number of
columns will be guessed.
Returns:
......
bob/measure/main.cpp
View file @ 5b829ad6
......@@ -102,7 +102,7 @@ static auto det_doc = bob::extension::FunctionDoc(
"[0] X axis values in the normal deviate scale for the false-accepts\n\n"
"[1] Y axis values in the normal deviate scale for the false-rejections\n\n"
"You can plot the results using your preferred tool to first create a plot using rows 0 and 1 from the returned value and then replace the X/Y axis annotation using a pre-determined set of tickmarks as recommended by NIST. "
"The derivative scales are computed with the :py:func:`ppndf` function."
"The derivative scales are computed with the :py:func:`bob.measure.ppndf` function."
)
.add_prototype("negatives, positives, n_points", "curve")
.add_parameter("negatives, positives", "array_like(1D, float)", "The list of negative and positive scores to compute the DET for")
......@@ -264,7 +264,7 @@ static auto eer_threshold_doc = bob::extension::FunctionDoc(
.add_prototype("negatives, positives, [is_sorted]", "threshold")
.add_parameter("negatives, positives", "array_like(1D, float)", "The set of negative and positive scores to compute the threshold")
.add_parameter("is_sorted", "bool", "[Default: ``False``] Are both sets of scores already in ascendantly sorted order?")
.add_return("threshold", "float", "The threshold (i.e., as used in :py:func:`farfrr`) where FAR and FRR are as close as possible")
.add_return("threshold", "float", "The threshold (i.e., as used in :py:func:`bob.measure.farfrr`) where FAR and FRR are as close as possible")
;
static PyObject* eer_threshold(PyObject*, PyObject* args, PyObject* kwds) {
BOB_TRY
......@@ -344,7 +344,7 @@ BOB_CATCH_FUNCTION("min_weighted_error_rate_threshold", 0)
static auto min_hter_threshold_doc = bob::extension::FunctionDoc(
"min_hter_threshold",
"Calculates the :py:func:`min_weighted_error_rate_threshold` with ``cost=0.5``"
"Calculates the :py:func:`bob.measure.min_weighted_error_rate_threshold` with ``cost=0.5``"
)
.add_prototype("negatives, positives, [is_sorted]", "threshold")
.add_parameter("negatives, positives", "array_like(1D, float)", "The set of negative and positive scores to compute the threshold")
......@@ -390,7 +390,7 @@ static auto precision_recall_doc = bob::extension::FunctionDoc(
"where :math:`tp` are the true positives, :math:`fp` are the false positives and :math:`fn` are the false negatives.\n\n"
"``positives`` holds the score information for samples that are labeled to belong to a certain class (a.k.a., 'signal' or 'client'). "
"``negatives`` holds the score information for samples that are labeled **not** to belong to the class (a.k.a., 'noise' or 'impostor'). "
"For more precise details about how the method considers error rates, see :py:func:`farfrr`."
"For more precise details about how the method considers error rates, see :py:func:`bob.measure.farfrr`."
)
.add_prototype("negatives, positives, threshold", "precision, recall")
.add_parameter("negatives, positives", "array_like(1D, float)", "The set of negative and positive scores to compute the measurements")
......@@ -429,7 +429,7 @@ BOB_CATCH_FUNCTION("precision_recall", 0)
static auto f_score_doc = bob::extension::FunctionDoc(
"f_score",
"This method computes the F-score of the accuracy of the classification",
"The F-score is a weighted mean of precision and recall measurements, see :py:func:`precision_recall`. "
"The F-score is a weighted mean of precision and recall measurements, see :py:func:`bob.measure.precision_recall`. "
"It is computed as:\n\n"
".. math::\n\n"
" \\mathrm{f-score} = (1 + w^2)\\frac{\\mathrm{precision}\\cdot{}\\mathrm{recall}}{w^2\\cdot{}\\mathrm{precision} + \\mathrm{recall}}\n\n"
......
bob/measure/openbr.py
View file @ 5b829ad6
......@@ -50,9 +50,9 @@ def write_matrix(
The mask file defines, which values are positives, negatives or to be
ignored. Usually, the file name extension is ``.mask``
model_names (Optional[str]): If given, the matrix will be written in the
same order as the given model names. The model names must be identical
with the second column in the 5-column ``score_file``.
model_names (:obj:`str`, optional): If given, the matrix will be written in
the same order as the given model names. The model names must be
identical with the second column in the 5-column ``score_file``.
.. note::
......@@ -62,25 +62,27 @@ def write_matrix(
Only the scores of the given models will be considered.
probe_names (Optional[list]): A list of strings. If given, the matrix will
be written in the same order as the given probe names (the ``path`` of
the probe). The probe names are identical to the third column of the
4-column (or the fourth column of the 5-column) ``score_file``. Only the
scores of the given probe names will be considered in this case.
probe_names (:obj:`list`, optional): A list of strings. If given, the
matrix will be written in the same order as the given probe names (the
``path`` of the probe). The probe names are identical to the third
column of the 4-column (or the fourth column of the 5-column)
``score_file``. Only the scores of the given probe names will be
considered in this case.
score_file_format (Optional[str]): One of ``('4column', '5column')``. The
format, in which the ``score_file`` is; defaults to ``'4column'``
score_file_format (:obj:`str`, optional): One of ``('4column',
'5column')``. The format, in which the ``score_file`` is; defaults to
``'4column'``
gallery_file_name (Optional[str]): The name of the gallery file that will
be written in the header of the OpenBR files.
gallery_file_name (:obj:`str`, optional): The name of the gallery file that
will be written in the header of the OpenBR files.
probe_file_name (Optional[str]): The name of the probe file that will be
written in the header of the OpenBR files.
probe_file_name (:obj:`str`, optional): The name of the probe file that
will be written in the header of the OpenBR files.
search (Optional[int]): If given, the scores will be sorted per probe,
keeping the specified number of highest scores. If the given number is
higher than the models, ``NaN`` values will be added, and the mask will
contain ``0x00`` values.
search (:obj:`int`, optional): If given, the scores will be sorted per
probe, keeping the specified number of highest scores. If the given
number is higher than the models, ``NaN`` values will be added, and the
mask will contain ``0x00`` values.
Returns:
......@@ -229,39 +231,41 @@ def write_score_file(
score_file (str): Path to the 4 or 5 column style score file that should be
written.
models_ids (Optional[list]): A list of strings with the client ids of the
models that will be written in the first column of the score file. If
given, the size must be identical to the number of models (gallery
models_ids (:obj:`list`, optional): A list of strings with the client ids
of the models that will be written in the first column of the score file.
If given, the size must be identical to the number of models (gallery
templates) in the OpenBR files. If not given, client ids of the model
will be identical to the **gallery index** in the matrix file.
probes_ids (Optional[list]): A list of strings with the client ids of the
probes that will be written in the second/third column of the four/five
column score file. If given, the size must be identical to the number of
probe templates in the OpenBR files. It will be checked that the OpenBR
mask fits to the model/probe client ids. If not given, the probe ids
will be estimated automatically, i.e., to fit the OpenBR matrix.
probes_ids (:obj:`list`, optional): A list of strings with the client ids
of the probes that will be written in the second/third column of the
four/five column score file. If given, the size must be identical to the
number of probe templates in the OpenBR files. It will be checked that
the OpenBR mask fits to the model/probe client ids. If not given, the
probe ids will be estimated automatically, i.e., to fit the OpenBR
matrix.
model_names (Optional[list]): A list of strings with the model path written
in the second column of the five column score file. If not given, the
model index in the OpenBR file will be used.
model_names (:obj:`list`, optional): A list of strings with the model path
written in the second column of the five column score file. If not given,
the model index in the OpenBR file will be used.
.. note::
This entry is ignored in the four column score file format.
probe_names (Optional[list]): A list of probe path to be written in the
third/fourth column in the four/five column score file. If given, the
probe_names (:obj:`list`, optional): A list of probe path to be written in
the third/fourth column in the four/five column score file. If given, the
size must be identical to the number of probe templates in the OpenBR
files. If not given, the probe index in the OpenBR file will be used.
score_file_format (Optional[str]): One of ``('4column', '5column')``. The
format, in which the ``score_file`` is; defaults to ``'4column'``
score_file_format (:obj:`str`, optional): One of ``('4column',
'5column')``. The format, in which the ``score_file`` is; defaults to
``'4column'``
replace_nan (Optional[float]): If NaN values are encountered in the OpenBR
matrix (which are not ignored due to the mask being non-NULL), this value
will be written instead. If ``None``, the values will not be written in
the score file at all.
replace_nan (:obj:`float`, optional): If NaN values are encountered in the
OpenBR matrix (which are not ignored due to the mask being non-NULL),
this value will be written instead. If ``None``, the values will not be
written in the score file at all.
Returns:
......
bob/measure/plot.py
View file @ 5b829ad6
......@@ -15,11 +15,11 @@ def log_values(min_step = -4, counts_per_step = 4):
Parameters:
min_step (Optional[int]): The power of 10 that will be the minimum value.
min_step (:obj:`int`, optional): The power of 10 that will be the minimum value.
E.g., the default ``-4`` will result in the first number to be
:math:`10^{-4}` = ``0.00001`` or ``0.01%``
counts_per_step (Optional[int]): The number of values that will be put
counts_per_step (:obj:`int`, optional): The number of values that will be put
between two adjacent powers of 10. With the default value ``4`` (and
default values of ``min_step``), we will get ``log_list[0] == 1e-4``,
``log_list[4] == 1e-3``, ..., ``log_list[16] == 1``.
......@@ -65,22 +65,22 @@ def roc(negatives, positives, npoints=100, CAR=False, **kwargs):
"positive" (signal, class) samples of your classifier. See
(:py:func:`bob.measure.roc`)
npoints (Optional[int]): The number of points for the plot. See
npoints (:obj:`int`, optional): The number of points for the plot. See
(:py:func:`bob.measure.roc`)
CAR (Optional[bool]): If set to ``True``, it will plot the CAR over FAR in
CAR (:obj:`bool`, optional): If set to ``True``, it will plot the CAR over FAR in
using :py:func:`matplotlib.pyplot.semilogx`, otherwise the FAR over FRR
linearly using :py:func:`matplotlib.pyplot.plot`.
kwargs (Optional[dict]): Extra plotting parameters, which are passed
kwargs (:obj:`dict`, optional): Extra plotting parameters, which are passed
directly to :py:func:`matplotlib.pyplot.plot`.
Returns:
:py:class:`matplotlib.pyplot.line`: The line that was added as defined by
the return value of :py:func:`matplotlib.pyplot.plot` or
:py:func:`matplotlib.pyplot.semilogx`.
:py:class:`list` of :py:class:`matplotlib.lines.Line2D`: The lines that
were added as defined by the return value of
:py:func:`matplotlib.pyplot.plot`.
"""
......@@ -123,17 +123,18 @@ def roc_for_far(negatives, positives, far_values = log_values(), **kwargs):
"positive" (signal, class) samples of your classifier. See
(:py:func:`bob.measure.roc`)
far_values (Optional[list]): The values for the FAR, where the CAR should
far_values (:obj:`list`, optional): The values for the FAR, where the CAR should
be plotted; each value should be in range [0,1].
kwargs (Optional[dict]): Extra plotting parameters, which are passed
kwargs (:obj:`dict`, optional): Extra plotting parameters, which are passed
directly to :py:func:`matplotlib.pyplot.plot`.
Returns:
:py:class:`matplotlib.pyplot.line`: The line that was added as defined by
the return value of :py:func:`matplotlib.pyplot.semilogx`.
:py:class:`list` of :py:class:`matplotlib.lines.Line2D`: The lines that
were added as defined by the return value of
:py:func:`matplotlib.pyplot.semilogx`.
"""
......@@ -171,17 +172,18 @@ def precision_recall_curve(negatives, positives, npoints=100, **kwargs):
"positive" (signal, class) samples of your classifier. See
(:py:func:`bob.measure.precision_recall_curve`)
npoints (Optional[int]): The number of points for the plot. See
npoints (:obj:`int`, optional): The number of points for the plot. See
(:py:func:`bob.measure.precision_recall_curve`)
kwargs (Optional[dict]): Extra plotting parameters, which are passed
kwargs (:obj:`dict`, optional): Extra plotting parameters, which are passed
directly to :py:func:`matplotlib.pyplot.plot`.
Returns:
:py:class:`matplotlib.pyplot.line`: The line that was added as defined by
the return value of :py:func:`matplotlib.pyplot.plot`.
:py:class:`list` of :py:class:`matplotlib.lines.Line2D`: The lines that
were added as defined by the return value of
:py:func:`matplotlib.pyplot.plot`.
"""
......@@ -236,17 +238,18 @@ def epc(dev_negatives, dev_positives, test_negatives, test_positives,
"positive" (signal, class) samples of your classifier, from the test set.
See (:py:func:`bob.measure.epc`)
npoints (Optional[int]): The number of points for the plot. See
npoints (:obj:`int`, optional): The number of points for the plot. See
(:py:func:`bob.measure.epc`)
kwargs (Optional[dict]): Extra plotting parameters, which are passed
kwargs (:obj:`dict`, optional): Extra plotting parameters, which are passed
directly to :py:func:`matplotlib.pyplot.plot`.
Returns:
:py:class:`matplotlib.pyplot.line`: The line that was added as defined by
the return value of :py:func:`matplotlib.pyplot.plot`.
:py:class:`list` of :py:class:`matplotlib.lines.Line2D`: The lines that
were added as defined by the return value of
:py:func:`matplotlib.pyplot.plot`.
"""
......@@ -324,20 +327,21 @@ def det(negatives, positives, npoints=100, axisfontsize='x-small', **kwargs):
"positive" (signal, class) samples of your classifier. See
(:py:func:`bob.measure.det`)
npoints (Optional[int]): The number of points for the plot. See
npoints (:obj:`int`, optional): The number of points for the plot. See
(:py:func:`bob.measure.det`)
axisfontsize (Optional[str]): The size to be used by x/y-tick-labels to set
axisfontsize (:obj:`str`, optional): The size to be used by x/y-tick-labels to set
the font size on the axis
kwargs (Optional[dict]): Extra plotting parameters, which are passed
kwargs (:obj:`dict`, optional): Extra plotting parameters, which are passed
directly to :py:func:`matplotlib.pyplot.plot`.
Returns:
:py:class:`matplotlib.pyplot.line`: The line that was added as defined by
the return value of :py:func:`matplotlib.pyplot.plot`.
:py:class:`list` of :py:class:`matplotlib.lines.Line2D`: The lines that
were added as defined by the return value of
:py:func:`matplotlib.pyplot.plot`.
"""
......@@ -401,7 +405,7 @@ def det_axis(v, **kwargs):
numbers it is passed without further inspection to
:py:func:`matplotlib.pyplot.axis`.
kwargs (Optional[dict]): Extra plotting parameters, which are passed
kwargs (:obj:`dict`, optional): Extra plotting parameters, which are passed
directly to :py:func:`matplotlib.pyplot.axis`.
......@@ -461,11 +465,11 @@ def cmc(cmc_scores, logx = True, **kwargs):
cmc_scores (array): 1D float array containing the CMC values (See
:py:func:`bob.measure.cmc`)
logx (Optional[bool]): If set (the default), plots the rank axis in
logx (:obj:`bool`, optional): If set (the default), plots the rank axis in
logarithmic scale using :py:func:`matplotlib.pyplot.semilogx` or in
linear scale using :py:func:`matplotlib.pyplot.plot`
kwargs (Optional[dict]): Extra plotting parameters, which are passed
kwargs (:obj:`dict`, optional): Extra plotting parameters, which are passed
directly to :py:func:`matplotlib.pyplot.plot`.
......@@ -511,23 +515,24 @@ def detection_identification_curve(cmc_scores, far_values = log_values(), rank
cmc_scores (array): 1D float array containing the CMC values (See
:py:func:`bob.measure.cmc`)
rank (Optional[int]): The rank for which the curve should be plotted
rank (:obj:`int`, optional): The rank for which the curve should be plotted
far_values (Optional[list]): The values for the FAR, where the CAR should
far_values (:obj:`list`, optional): The values for the FAR, where the CAR should
be plotted; each value should be in range [0,1].
logx (Optional[bool]): If set (the default), plots the rank axis in
logx (:obj:`bool`, optional): If set (the default), plots the rank axis in
logarithmic scale using :py:func:`matplotlib.pyplot.semilogx` or in
linear scale using :py:func:`matplotlib.pyplot.plot`
kwargs (Optional[dict]): Extra plotting parameters, which are passed
kwargs (:obj:`dict`, optional): Extra plotting parameters, which are passed
directly to :py:func:`matplotlib.pyplot.plot`.
Returns:
:py:class:`matplotlib.pyplot.line`: The line that was added as defined by
the return value of :py:func:`matplotlib.pyplot.plot`.
:py:class:`list` of :py:class:`matplotlib.lines.Line2D`: The lines that
were added as defined by the return value of
:py:func:`matplotlib.pyplot.plot`.
"""
......
doc/guide.rst
View file @ 5b829ad6
......@@ -215,8 +215,8 @@ Plotting
--------
An image is worth 1000 words, they say. You can combine the capabilities of
`Matplotlib`_ with |project| to plot a number of curves. However, you must have that
package installed though. In this section we describe a few recipes.
`Matplotlib`_ with |project| to plot a number of curves. However, you must have
that package installed though. In this section we describe a few recipes.
ROC
===
......@@ -255,18 +255,18 @@ You should see an image like the following one:
pyplot.title('ROC')
As can be observed, plotting methods live in the namespace
:py:mod:`bob.measure.plot`. They work like the :py:func:`matplotlib.pyplot.plot`
itself, except that instead of receiving the x and y point coordinates as
parameters, they receive the two :py:class:`numpy.ndarray` arrays with
negatives and positives, as well as an indication of the number of points the
curve must contain.
As in the :py:func:`matplotlib.pyplot.plot` command, you can pass optional parameters for
the line as shown in the example to setup its color, shape and even the label.
For an overview of the keywords accepted, please refer to the `Matplotlib`_'s
Documentation. Other plot properties such as the plot title, axis labels,
grids, legends should be controlled directly using the relevant `Matplotlib`_'s
controls.
:py:mod:`bob.measure.plot`. They work like the
:py:func:`matplotlib.pyplot.plot` itself, except that instead of receiving the
x and y point coordinates as parameters, they receive the two
:py:class:`numpy.ndarray` arrays with negatives and positives, as well as an
indication of the number of points the curve must contain.
As in the :py:func:`matplotlib.pyplot.plot` command, you can pass optional
parameters for the line as shown in the example to setup its color, shape and
even the label. For an overview of the keywords accepted, please refer to the
`Matplotlib`_'s Documentation. Other plot properties such as the plot title,
axis labels, grids, legends should be controlled directly using the relevant
`Matplotlib`_'s controls.
DET
===
......@@ -358,9 +358,11 @@ This will produce an image like the following one:
CMC
===
The Cumulative Match Characteristics (CMC) curve estimates the probability that the correct model is in the *N* models with the highest similarity to a given probe.
A CMC curve can be plotted using the :py:func:`bob.measure.plot.cmc` function.
The CMC can be calculated from a relatively complex data structure, which defines a pair of positive and negative scores **per probe**:
The Cumulative Match Characteristics (CMC) curve estimates the probability that
the correct model is in the *N* models with the highest similarity to a given
probe. A CMC curve can be plotted using the :py:func:`bob.measure.plot.cmc`
function. The CMC can be calculated from a relatively complex data structure,
which defines a pair of positive and negative scores **per probe**:
.. plot::
......
doc/py_api.rst
View file @ 5b829ad6
.. vim: set fileencoding=utf-8 :
.. Andre Anjos <andre.dos.anjos@gmail.com>
.. Sat 16 Nov 20:52:58 2013
============
Python API
============
This section includes information for using the Python API of :py:mod:`bob.measure`.
This section includes information for using the Python API of
:py:mod:`bob.measure`.
Measurement
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment