"""Calculates the recognitionrate from the given input
Calculates the recognition rate from the given input, which is identical
to the CMC value for the given ``rank``.
It is identical to the CMC value for the given ``rank``.
The input has a specific format, which is a list of two-element tuples.
Each of the tuples contains the negative :math:`\\{S_p^-\\}` and the positive :math:`\\{S_p^+\\}` scores for one probe item :math:`p`, or ``None`` in case of open set recognition.
To read the lists from score files in 4 or 5 column format, please use the :py:func:`bob.measure.load.cmc_four_column` or :py:func:`bob.measure.load.cmc_five_column` function.
The input has a specific format, which is a list of two-element tuples. Each
of the tuples contains the negative :math:`\\{S_p^-\\}` and the positive
:math:`\\{S_p^+\\}` scores for one probe item :math:`p`, or ``None`` in case
of open set recognition. To read the lists from score files in 4 or 5 column
format, please use the :py:func:`bob.measure.load.cmc_four_column` or
If **threshold** is set to ``None``, the rank 1 recognition rate is defined as the number of test items, for which the highest positive :math:`\\max\\{S_p^+\\}` score is greater than or equal to all negative scores, divided by the number of all probe items :math:`P`:
If ``threshold`` is set to ``None``, the rank 1 recognition rate is defined
as the number of test items, for which the highest positive
:math:`\\max\\{S_p^+\\}` score is greater than or equal to all negative
scores, divided by the number of all probe items :math:`P`:
For a given rank :math:`r>1`, up to :math:`r` negative scores that are higher than the highest positive score are allowed to still count as correctly classified in the top :math:`r` rank.
For a given rank :math:`r>1`, up to :math:`r` negative scores that are higher
than the highest positive score are allowed to still count as correctly
classified in the top :math:`r` rank.
If ``threshold`` :math:`\\theta` is given, **all** scores below threshold will be filtered out.
Hence, if all positive scores are below threshold :math:`\\max\\{S_p^+\\} < \\theta`, the probe will be misclassified **at any rank**.
If ``threshold`` :math:`\\theta` is given, **all** scores below threshold
will be filtered out. Hence, if all positive scores are below threshold
:math:`\\max\\{S_p^+\\} < \\theta`, the probe will be misclassified **at any
rank**.
For open set recognition, i.e., when there exist a tuple including negative scores without corresponding positive scores (``None``), and **all** negative scores are below ``threshold`` :math:`\\max\\{S_p^+\\} < \\theta`, the probe item is correctly rejected, **and it does not count into the denominator** :math:`P`.
When no ``threshold`` is provided, the open set probes will **always** count as misclassified, regardless of the ``rank``.
For open set recognition, i.e., when there exist a tuple including negative
scores without corresponding positive scores (``None``), and **all** negative
scores are below ``threshold`` :math:`\\max\\{S_p^+\\} < \\theta`, the probe
item is correctly rejected, **and it does not count into the denominator**
:math:`P`. When no ``threshold`` is provided, the open set probes will
**always** count as misclassified, regardless of the ``rank``.
.. warn:
For open set tests, this rate does not correspond to a standard rate.
Please use :py:func:`detection_identification_rate` and :py:func:`false_alarm_rate` instead.
Please use :py:func:`detection_identification_rate` and
:py:func:`false_alarm_rate` instead.
Parameters:
**Parameters:**
cmc_scores (list): A list in the format ``[(negatives, positives), ...]``
containing the CMC scores loaded with one of the functions
CMC scores loaded with one of the functions (:py:func:`bob.measure.load.cmc_four_column` or :py:func:`bob.measure.load.cmc_five_column`).
Each pair contains the ``negative`` and the ``positive`` scores for **one probe item**.
Each pair can contain up to one empty array (or ``None``), i.e., in case of open set recognition.
Each pair contains the ``negative`` and the ``positive`` scores for **one
probe item**. Each pair can contain up to one empty array (or ``None``),
i.e., in case of open set recognition.
``threshold`` : float or ``None``
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).
threshold (Optional[float]): 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`` : int or ``None``
The rank for which the recognition rate should be computed, 1 by default.
rank (Optional[int]):
The rank for which the recognition rate should be computed, 1 by default.
**Returns:**
``RR`` : float
The (open set) recognition rate for the given rank, a value between 0 and 1.
Returns:
float: The (open set) recognition rate for the given rank, a value between
0 and 1.
"""
# If no scores are given, the recognition rate is exactly 0.
"""detection_identification_rate(cmc_scores, threshold, rank) -> dir
"""Computes the `detection and identification rate` for the given threshold.
This value is designed to be used in an open set identification protocol, and
defined in Chapter 14.1 of [LiJain2005]_.
Although the detection and identification rate is designed to be computed on
an open set protocol, it uses only the probe elements, for which a
corresponding gallery element exists. For closed set identification
protocols, this function is identical to :py:func:`recognition_rate`. The
only difference is that for this function, a ``threshold`` for the scores
need to be defined, while for :py:func:`recognition_rate` it is optional.
Parameters:
Computes the `detection and identification rate` for the given threshold.
This value is designed to be used in an open set identification protocol, and defined in Chapter 14.1 of [LiJain2005]_.
cmc_scores (list): A list in the format ``[(negatives, positives), ...]``
containing the CMC scores loaded with one of the functions
(:py:func:`bob.measure.load.cmc_four_column` or
:py:func:`bob.measure.load.cmc_five_column`).
Although the detection and identification rate is designed to be computed on an open set protocol, it uses only the probe elements, for which a corresponding gallery element exists.
For closed set identification protocols, this function is identical to :py:func:`recognition_rate`.
The only difference is that for this function, a ``threshold`` for the scores need to be defined, while for :py:func:`recognition_rate` it is optional.
Each pair contains the ``negative`` and the ``positive`` scores for **one
probe item**. Each pair can contain up to one empty array (or ``None``),
i.e., in case of open set recognition.
**Parameters:**
threshold (float): The decision threshold :math:`\\tau``.
"""Computes the `false alarm rate` for the given threshold,.
This value is designed to be used in an open set identification protocol, and
defined in Chapter 14.1 of [LiJain2005]_.
The false alarm rate is designed to be computed on an open set protocol, it
uses only the probe elements, for which **no** corresponding gallery element
exists.
Parameters:
Computes the `false alarm rate` for the given threshold,.
This value is designed to be used in an open set identification protocol, and defined in Chapter 14.1 of [LiJain2005]_.
cmc_scores (list): A list in the format ``[(negatives, positives), ...]``
containing the CMC scores loaded with one of the functions
(:py:func:`bob.measure.load.cmc_four_column` or
:py:func:`bob.measure.load.cmc_five_column`).
The false alarm rate is designed to be computed on an open set protocol, it uses only the probe elements, for which **no** corresponding gallery element exists.
Each pair contains the ``negative`` and the ``positive`` scores for **one
probe item**. Each pair can contain up to one empty array (or ``None``),
i.e., in case of open set recognition.
**Parameters:**
threshold (float): The decision threshold :math:`\\tau``.
