Skip to content

DOC: Specify Units for Mutual Information Metrics #18288 #18641

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

Merged
merged 10 commits into from
Oct 12, 2021
Merged

DOC: Specify Units for Mutual Information Metrics #18288 #18641

Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
bf380eb
Update _supervised.py
amrcode Sep 23, 2020
7421170
Update _supervised.py
amrcode Oct 20, 2020
7cb0dbe
Update sklearn/metrics/cluster/_supervised.py to add a period in the …
amrcode Oct 21, 2020
14df87f
Updates from review
amrcode Jan 5, 2021
6c1c787
Fix line lengths
amrcode Jan 5, 2021
b6e1275
Update _supervised.py
amrcode Feb 2, 2021
85aa9ec
Remove trailing whitespace
amrcode Feb 2, 2021
e8ff404
Update math notation
amrcode Jun 11, 2021
bdc8ba9
Fix line lengths
amrcode Jun 11, 2021
26e2064
Remove trailing whitespace
amrcode Jun 11, 2021
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
42 changes: 25 additions & 17 deletions sklearn/metrics/cluster/_supervised.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -710,8 +710,8 @@ def v_measure_score(labels_true, labels_pred, *, beta=1.0):
def mutual_info_score(labels_true, labels_pred, *, contingency=None):
"""Mutual Information between two clusterings.

The Mutual Information is a measure of the similarity between two labels of
the same data. Where :math:`|U_i|` is the number of the samples
The Mutual Information is a measure of the similarity between two labels
of the same data. Where :math:`|U_i|` is the number of the samples
in cluster :math:`U_i` and :math:`|V_j|` is the number of the
samples in cluster :math:`V_j`, the Mutual Information
between clusterings :math:`U` and :math:`V` is given as:
Expand All @@ -725,20 +725,23 @@ def mutual_info_score(labels_true, labels_pred, *, contingency=None):
a permutation of the class or cluster label values won't change the
score value in any way.

This metric is furthermore symmetric: switching ``label_true`` with
``label_pred`` will return the same score value. This can be useful to
measure the agreement of two independent label assignments strategies
on the same dataset when the real ground truth is not known.
This metric is furthermore symmetric: switching :math:`U` (i.e
``label_true``) with :math:`V` (i.e. ``label_pred``) will return the
same score value. This can be useful to measure the agreement of two
independent label assignments strategies on the same dataset when the
real ground truth is not known.

Read more in the :ref:`User Guide <mutual_info_score>`.

Parameters
----------
labels_true : int array, shape = [n_samples]
A clustering of the data into disjoint subsets.
A clustering of the data into disjoint subsets, called :math:`U` in
the above formula.

labels_pred : int array-like of shape (n_samples,)
A clustering of the data into disjoint subsets.
A clustering of the data into disjoint subsets, called :math:`V` in
the above formula.

contingency : {ndarray, sparse matrix} of shape \
(n_classes_true, n_classes_pred), default=None
Expand All @@ -749,7 +752,8 @@ def mutual_info_score(labels_true, labels_pred, *, contingency=None):
Returns
-------
mi : float
Mutual information, a non-negative value
Mutual information, a non-negative value, measured in nats using the
natural logarithm.

Notes
-----
Expand Down Expand Up @@ -810,10 +814,10 @@ def adjusted_mutual_info_score(labels_true, labels_pred, *,
a permutation of the class or cluster label values won't change the
score value in any way.

This metric is furthermore symmetric: switching ``label_true`` with
``label_pred`` will return the same score value. This can be useful to
measure the agreement of two independent label assignments strategies
on the same dataset when the real ground truth is not known.
This metric is furthermore symmetric: switching :math:`U` (``label_true``)
with :math:`V` (``labels_pred``) will return the same score value. This can
be useful to measure the agreement of two independent label assignments
strategies on the same dataset when the real ground truth is not known.

Be mindful that this function is an order of magnitude slower than other
metrics, such as the Adjusted Rand Index.
Expand All @@ -823,10 +827,12 @@ def adjusted_mutual_info_score(labels_true, labels_pred, *,
Parameters
----------
labels_true : int array, shape = [n_samples]
A clustering of the data into disjoint subsets.
A clustering of the data into disjoint subsets, called :math:`U` in
the above formula.

labels_pred : int array-like of shape (n_samples,)
A clustering of the data into disjoint subsets.
A clustering of the data into disjoint subsets, called :math:`V` in
the above formula.

average_method : str, default='arithmetic'
How to compute the normalizer in the denominator. Possible options
Expand All @@ -843,7 +849,8 @@ def adjusted_mutual_info_score(labels_true, labels_pred, *,
ami: float (upperlimited by 1.0)
The AMI returns a value of 1 when the two partitions are identical
(ie perfectly matched). Random partitions (independent labellings) have
an expected AMI around 0 on average hence can be negative.
an expected AMI around 0 on average hence can be negative. The value is
in adjusted nats (based on the natural logarithm).

See Also
--------
Expand Down Expand Up @@ -959,7 +966,8 @@ def normalized_mutual_info_score(labels_true, labels_pred, *,
Returns
-------
nmi : float
score between 0.0 and 1.0. 1.0 stands for perfectly complete labeling
Score between 0.0 and 1.0 in normalized nats (based on the natural
logarithm). 1.0 stands for perfectly complete labeling.

See Also
--------
Expand Down