dataeval 0.63.0__py3-none-any.whl → 0.65.0__py3-none-any.whl

dataeval/_internal/metrics/divergence.py

@@ -3,27 +3,104 @@ This module contains the implementation of HP Divergence
 using the Fast Nearest Neighbor and Minimum Spanning Tree algorithms
 """
 
-from typing import Any, Callable, Dict, Literal
+from dataclasses import dataclass
+from typing import Literal
 
 import numpy as np
+from numpy.typing import ArrayLike, NDArray
 
-from dataeval._internal.functional.divergence import divergence_fnn, divergence_mst
-from dataeval._internal.interop import ArrayLike, to_numpy
-from dataeval._internal.metrics.base import EvaluateMixin, MethodsMixin
+from dataeval._internal.interop import to_numpy
+from dataeval._internal.metrics.utils import compute_neighbors, get_method, minimum_spanning_tree
+from dataeval._internal.output import OutputMetadata, set_metadata
 
-_METHODS = Literal["MST", "FNN"]
-_FUNCTION = Callable[[np.ndarray, np.ndarray], int]
+
+@dataclass(frozen=True)
+class DivergenceOutput(OutputMetadata):
+    """
+    Attributes
+    ----------
+    divergence : float
+        Divergence value calculated between 2 datasets ranging between 0.0 and 1.0
+    errors : int
+        The number of differing edges between the datasets
+    """
+
+    divergence: float
+    errors: int
+
+
+def divergence_mst(data: NDArray, labels: NDArray) -> int:
+    """
+    Calculates the estimated label errors based on the minimum spanning tree
+
+    Parameters
+    ----------
+    data : NDArray, shape - (N, ... )
+        Input images to be grouped
+    labels : NDArray
+        Corresponding labels for each data point
+
+    Returns
+    -------
+    int
+        Number of label errors when creating the minimum spanning tree
+    """
+    mst = minimum_spanning_tree(data).toarray()
+    edgelist = np.transpose(np.nonzero(mst))
+    errors = np.sum(labels[edgelist[:, 0]] != labels[edgelist[:, 1]])
+    return errors
 
 
-class Divergence(EvaluateMixin, MethodsMixin[_METHODS, _FUNCTION]):
+def divergence_fnn(data: NDArray, labels: NDArray) -> int:
     """
-    Calculates the estimated HP divergence between two datasets
+    Calculates the estimated label errors based on their nearest neighbors
 
     Parameters
     ----------
-    method : Literal["MST, "FNN"], default "MST"
+    data : NDArray, shape - (N, ... )
+        Input images to be grouped
+    labels : NDArray
+        Corresponding labels for each data point
+
+    Returns
+    -------
+    int
+        Number of label errors when finding nearest neighbors
+    """
+    nn_indices = compute_neighbors(data, data)
+    errors = np.sum(np.abs(labels[nn_indices] - labels))
+    return errors
+
+
+DIVERGENCE_FN_MAP = {"FNN": divergence_fnn, "MST": divergence_mst}
+
+
+@set_metadata("dataeval.metrics")
+def divergence(data_a: ArrayLike, data_b: ArrayLike, method: Literal["FNN", "MST"] = "FNN") -> DivergenceOutput:
+    """
+    Calculates the divergence and any errors between the datasets
+
+    Parameters
+    ----------
+    data_a : ArrayLike, shape - (N, P)
+        A dataset in an ArrayLike format to compare.
+        Function expects the data to have 2 dimensions, N number of observations in a P-dimensionial space.
+    data_b : ArrayLike, shape - (N, P)
+        A dataset in an ArrayLike format to compare.
+        Function expects the data to have 2 dimensions, N number of observations in a P-dimensionial space.
+    method : Literal["MST, "FNN"], default "FNN"
         Method used to estimate dataset divergence
 
+    Returns
+    -------
+    DivergenceOutput
+        The divergence value (0.0..1.0) and the number of differing edges between the datasets
+
+    Notes
+    -----
+    The divergence value indicates how similar the 2 datasets are
+    with 0 indicating approximately identical data distributions.
+
     Warning
     -------
         MST is very slow in this implementation, this is unlike matlab where
@@ -40,63 +117,20 @@ class Divergence(EvaluateMixin, MethodsMixin[_METHODS, _FUNCTION]):
 
     Examples
     --------
-    Initialize the Divergence class:
+    Evaluate the datasets:
 
-    >>> divert = Divergence()
-
-    Specify the method:
-
-    >>> divert = Divergence(method="FNN")
+    >>> divergence(datasetA, datasetB)
+    DivergenceOutput(divergence=0.28, errors=36.0)
     """
-
-    def __init__(self, method: _METHODS = "MST") -> None:
-        self._set_method(method)
-
-    @classmethod
-    def _methods(cls) -> Dict[str, _FUNCTION]:
-        return {"FNN": divergence_fnn, "MST": divergence_mst}
-
-    def evaluate(self, data_a: ArrayLike, data_b: ArrayLike) -> Dict[str, Any]:
-        """
-        Calculates the divergence and any errors between the datasets
-
-        Parameters
-        ----------
-        data_a : ArrayLike, shape - (N, P)
-            A dataset in an ArrayLike format to compare.
-            Function expects the data to have 2 dimensions, N number of observations in a P-dimesionial space.
-        data_b : ArrayLike, shape - (N, P)
-            A dataset in an ArrayLike format to compare.
-            Function expects the data to have 2 dimensions, N number of observations in a P-dimesionial space.
-
-        Returns
-        -------
-        Dict[str, Any]
-            divergence : float
-                divergence value between 0.0 and 1.0
-            error : int
-                the number of differing edges between the datasets
-
-        Notes
-        -----
-        The divergence value indicates how similar the 2 datasets are
-        with 0 indicating approximately identical data distributions.
-
-        Examples
-        --------
-        Evaluate the datasets:
-
-        >>> divert.evaluate(datasetA, datasetB)
-        {'divergence': 0.28, 'error': 36.0}
-        """
-        a = to_numpy(data_a)
-        b = to_numpy(data_b)
-        N = a.shape[0]
-        M = b.shape[0]
-
-        stacked_data = np.vstack((a, b))
-        labels = np.vstack([np.zeros([N, 1]), np.ones([M, 1])])
-
-        errors = self._method(stacked_data, labels)
-        dp = max(0.0, 1 - ((M + N) / (2 * M * N)) * errors)
-        return {"divergence": dp, "error": errors}
+    div_fn = get_method(DIVERGENCE_FN_MAP, method)
+    a = to_numpy(data_a)
+    b = to_numpy(data_b)
+    N = a.shape[0]
+    M = b.shape[0]
+
+    stacked_data = np.vstack((a, b))
+    labels = np.vstack([np.zeros([N, 1]), np.ones([M, 1])])
+
+    errors = div_fn(stacked_data, labels)
+    dp = max(0.0, 1 - ((M + N) / (2 * M * N)) * errors)
+    return DivergenceOutput(dp, errors)

dataeval/_internal/metrics/diversity.py

@@ -0,0 +1,211 @@
+from dataclasses import dataclass
+from typing import Dict, List, Literal, Optional, Sequence
+
+import numpy as np
+from numpy.typing import NDArray
+
+from dataeval._internal.metrics.utils import entropy, get_counts, get_method, get_num_bins, preprocess_metadata
+from dataeval._internal.output import OutputMetadata, set_metadata
+
+
+@dataclass(frozen=True)
+class DiversityOutput(OutputMetadata):
+    """
+    Attributes
+    ----------
+    diversity_index : NDArray[np.float64]
+        Diversity index for classes and factors
+    """
+
+    diversity_index: NDArray[np.float64]
+
+
+def diversity_shannon(
+    data: NDArray,
+    names: List[str],
+    is_categorical: List[bool],
+    subset_mask: Optional[NDArray[np.bool_]] = None,
+) -> NDArray:
+    """
+    Compute diversity for discrete/categorical variables and, through standard
+    histogram binning, for continuous variables.
+
+    We define diversity as a normalized form of the Shannon entropy.
+
+    diversity = 1 implies that samples are evenly distributed across a particular factor
+    diversity = 0 implies that all samples belong to one category/bin
+
+    Parameters
+    ----------
+    subset_mask: Optional[NDArray[np.bool_]]
+        Boolean mask of samples to bin (e.g. when computing per class).  True -> include in histogram counts
+
+    Notes
+    -----
+    For continuous variables, histogram bins are chosen automatically.  See `numpy.histogram` for details.
+
+    Returns
+    -------
+    diversity_index: NDArray
+        Diversity index per column of X
+
+    See Also
+    --------
+    numpy.histogram
+    """
+
+    # entropy computed using global auto bins so that we can properly normalize
+    ent_unnormalized = entropy(data, names, is_categorical, normalized=False, subset_mask=subset_mask)
+    # normalize by global counts rather than classwise counts
+    num_bins = get_num_bins(data, names, is_categorical=is_categorical, subset_mask=subset_mask)
+    return ent_unnormalized / np.log(num_bins)
+
+
+def diversity_simpson(
+    data: NDArray,
+    names: List[str],
+    is_categorical: List[bool],
+    subset_mask: Optional[NDArray[np.bool_]] = None,
+) -> NDArray:
+    """
+    Compute diversity for discrete/categorical variables and, through standard
+    histogram binning, for continuous variables.
+
+    We define diversity as a normalized form of the inverse Simpson diversity
+    index.
+
+    diversity = 1 implies that samples are evenly distributed across a particular factor
+    diversity = 1/num_categories implies that all samples belong to one category/bin
+
+    Parameters
+    ----------
+    subset_mask: Optional[NDArray[np.bool_]]
+        Boolean mask of samples to bin (e.g. when computing per class).  True -> include in histogram counts
+
+    Notes
+    -----
+    For continuous variables, histogram bins are chosen automatically.  See
+        numpy.histogram for details.
+    The expression is undefined for q=1, but it approaches the Shannon entropy
+        in the limit.
+    If there is only one category, the diversity index takes a value of 1 =
+        1/N = 1/1.  Entropy will take a value of 0.
+
+    Returns
+    -------
+    NDArray
+        Diversity index per column of X
+
+    See Also
+    --------
+    numpy.histogram
+    """
+
+    hist_counts, _ = get_counts(data, names, is_categorical, subset_mask)
+    # normalize by global counts, not classwise counts
+    num_bins = get_num_bins(data, names, is_categorical)
+
+    ev_index = np.empty(len(names))
+    # loop over columns for convenience
+    for col, cnts in enumerate(hist_counts.values()):
+        # relative frequencies
+        p_i = cnts / cnts.sum()
+        # inverse Simpson index normalized by (number of bins)
+        ev_index[col] = 1 / np.sum(p_i**2) / num_bins[col]
+
+    return ev_index
+
+
+DIVERSITY_FN_MAP = {"simpson": diversity_simpson, "shannon": diversity_shannon}
+
+
+@set_metadata("dataeval.metrics")
+def diversity(
+    class_labels: Sequence[int], metadata: List[Dict], method: Literal["shannon", "simpson"] = "simpson"
+) -> DiversityOutput:
+    """
+    Compute diversity for discrete/categorical variables and, through standard
+    histogram binning, for continuous variables.
+
+    diversity = 1 implies that samples are evenly distributed across a particular factor
+    diversity = 0 implies that all samples belong to one category/bin
+
+    Parameters
+    ----------
+    class_labels: Sequence[int]
+        List of class labels for each image
+    metadata: List[Dict]
+        List of metadata factors for each image
+    metric: Literal["shannon", "simpson"], default "simpson"
+        string variable indicating which diversity index should be used.
+        Permissible values include "simpson" and "shannon"
+
+    Notes
+    -----
+    - For continuous variables, histogram bins are chosen automatically. See numpy.histogram for details.
+
+    Returns
+    -------
+    DiversityOutput
+        Diversity index per column of self.data or each factor in self.names
+
+    See Also
+    --------
+    numpy.histogram
+    """
+    diversity_fn = get_method(DIVERSITY_FN_MAP, method)
+    data, names, is_categorical = preprocess_metadata(class_labels, metadata)
+    diversity_index = diversity_fn(data, names, is_categorical, None).astype(np.float64)
+    return DiversityOutput(diversity_index)
+
+
+@set_metadata("dataeval.metrics")
+def diversity_classwise(
+    class_labels: Sequence[int], metadata: List[Dict], method: Literal["shannon", "simpson"] = "simpson"
+) -> DiversityOutput:
+    """
+    Compute diversity for discrete/categorical variables and, through standard
+    histogram binning, for continuous variables.
+
+    We define diversity as a normalized form of the inverse Simpson diversity
+    index.
+
+    diversity = 1 implies that samples are evenly distributed across a particular factor
+    diversity = 1/num_categories implies that all samples belong to one category/bin
+
+    Parameters
+    ----------
+    class_labels: Sequence[int]
+        List of class labels for each image
+    metadata: List[Dict]
+        List of metadata factors for each image
+
+    Notes
+    -----
+    - For continuous variables, histogram bins are chosen automatically. See numpy.histogram for details.
+    - The expression is undefined for q=1, but it approaches the Shannon entropy in the limit.
+    - If there is only one category, the diversity index takes a value of 1 = 1/N = 1/1. Entropy will take a value of 0.
+
+    Returns
+    -------
+    DiversityOutput
+        Diversity index [n_class x n_factor]
+
+    See Also
+    --------
+    numpy.histogram
+    """
+    diversity_fn = get_method(DIVERSITY_FN_MAP, method)
+    data, names, is_categorical = preprocess_metadata(class_labels, metadata)
+    class_idx = names.index("class_label")
+    class_lbl = data[:, class_idx]
+
+    u_classes = np.unique(class_lbl)
+    num_factors = len(names)
+    diversity = np.empty((len(u_classes), num_factors))
+    diversity[:] = np.nan
+    for idx, cls in enumerate(u_classes):
+        subset_mask = class_lbl == cls
+        diversity[idx, :] = diversity_fn(data, names, is_categorical, subset_mask)
+    div_no_class = np.concatenate((diversity[:, :class_idx], diversity[:, (class_idx + 1) :]), axis=1)
+    return DiversityOutput(div_no_class)