"""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``.