distclassipy 0.2.0a0__tar.gz → 0.2.2a1__tar.gz

{distclassipy-0.2.0a0 → distclassipy-0.2.2a1}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: distclassipy
-Version: 0.2.0a0
+Version: 0.2.2a1
 Summary: A python package for a distance-based classifier which can use several different distance metrics.
 Author-email: Siddharth Chaini <sidchaini@gmail.com>
 License:                     GNU GENERAL PUBLIC LICENSE
@@ -697,6 +697,7 @@ Requires-Dist: joblib>=1.3.2
 Requires-Dist: numpy>=1.25.2
 Requires-Dist: pandas>=2.0.3
 Requires-Dist: scikit-learn>=1.2.2
+Dynamic: license-file
 
 <h1 align="center">
 <picture align="center">
@@ -740,17 +741,25 @@ X, y = make_classification(
     random_state=0,
     shuffle=False,
 )
+# Example usage of DistanceMetricClassifier
 clf = dcpy.DistanceMetricClassifier()
 clf.fit(X, y)
-print(clf.predict([[0, 0, 0, 0]]), metric="canberra")
+print(clf.predict([[0, 0, 0, 0]], metric="canberra"))
+
+# Example usage of EnsembleDistanceClassifier
+ensemble_clf = dcpy.EnsembleDistanceClassifier(feat_idx=0)
+ensemble_clf.fit(X, y)
+print(ensemble_clf.predict(X))
 ```
 
 ## Features
 - **Distance Metric-Based Classification**: Utilizes a variety of distance metrics for classification.
 - **Customizable for Scientific Goals**: Allows fine-tuning based on scientific objectives by selecting appropriate distance metrics and features, enhancing both computational efficiency and model performance.
 - **Interpretable Results**: Offers improved interpretability of classification outcomes by directly using distance metrics and feature importance, making it ideal for scientific applications.
-- **Efficient and Scalable**: Demonstrates lower computational requirements compared to traditional methods like Random Forests, making it suitable for large datasets
-- **Open Source and Accessible**: Available as an open-source Python package on PyPI, encouraging broad application in astronomy and beyond
+- **Efficient and Scalable**: Demonstrates lower computational requirements compared to traditional methods like Random Forests, making it suitable for large datasets.
+- **Open Source and Accessible**: Available as an open-source Python package on PyPI, encouraging broad application in astronomy and beyond.
+- **(NEW) Ensemble Distance Classification**: Leverages an ensemble approach to use different distance metrics for each quantile, improving classification performance across diverse data distributions.
+- **(NEW) Expanded Distance Metrics**: DistClassiPy now offers 43 built-in distance metrics, an increase from the previous 18. Additionally, users can still define and use custom distance metrics as needed.
 
 ## Documentation
 

{distclassipy-0.2.0a0 → distclassipy-0.2.2a1}/README.md

@@ -40,17 +40,25 @@ X, y = make_classification(
     random_state=0,
     shuffle=False,
 )
+# Example usage of DistanceMetricClassifier
 clf = dcpy.DistanceMetricClassifier()
 clf.fit(X, y)
-print(clf.predict([[0, 0, 0, 0]]), metric="canberra")
+print(clf.predict([[0, 0, 0, 0]], metric="canberra"))
+
+# Example usage of EnsembleDistanceClassifier
+ensemble_clf = dcpy.EnsembleDistanceClassifier(feat_idx=0)
+ensemble_clf.fit(X, y)
+print(ensemble_clf.predict(X))
 ```
 
 ## Features
 - **Distance Metric-Based Classification**: Utilizes a variety of distance metrics for classification.
 - **Customizable for Scientific Goals**: Allows fine-tuning based on scientific objectives by selecting appropriate distance metrics and features, enhancing both computational efficiency and model performance.
 - **Interpretable Results**: Offers improved interpretability of classification outcomes by directly using distance metrics and feature importance, making it ideal for scientific applications.
-- **Efficient and Scalable**: Demonstrates lower computational requirements compared to traditional methods like Random Forests, making it suitable for large datasets
-- **Open Source and Accessible**: Available as an open-source Python package on PyPI, encouraging broad application in astronomy and beyond
+- **Efficient and Scalable**: Demonstrates lower computational requirements compared to traditional methods like Random Forests, making it suitable for large datasets.
+- **Open Source and Accessible**: Available as an open-source Python package on PyPI, encouraging broad application in astronomy and beyond.
+- **(NEW) Ensemble Distance Classification**: Leverages an ensemble approach to use different distance metrics for each quantile, improving classification performance across diverse data distributions.
+- **(NEW) Expanded Distance Metrics**: DistClassiPy now offers 43 built-in distance metrics, an increase from the previous 18. Additionally, users can still define and use custom distance metrics as needed.
 
 ## Documentation
 

{distclassipy-0.2.0a0 → distclassipy-0.2.2a1}/distclassipy/__init__.py

@@ -22,7 +22,17 @@ You should have received a copy of the GNU General Public License
 along with this program.  If not, see <https://www.gnu.org/licenses/>.
 """
 
-from .classifier import DistanceMetricClassifier  # noqa
-from .distances import Distance  # noqa
+from .classifier import (
+    DistanceMetricClassifier,
+    EnsembleDistanceClassifier,
+)
+from .distances import _ALL_METRICS
 
-__version__ = "0.2.0a0"
+__version__ = "0.2.2a1"
+
+__all__ = [
+    "DistanceMetricClassifier",
+    "EnsembleDistanceClassifier",
+    "Distance",
+    "_ALL_METRICS",
+]

{distclassipy-0.2.0a0 → distclassipy-0.2.2a1}/distclassipy/classifier.py

@@ -3,6 +3,21 @@
 This module contains the DistanceMetricClassifier introduced by Chaini et al. (2024)
 in "Light Curve Classification with DistClassiPy: a new distance-based classifier"
 
+
+.. autoclass:: distclassipy.classifier.DistanceMetricClassifier
+   :members:
+   :inherited-members:
+   :exclude-members: set_fit_request, set_predict_request
+
+.. autoclass:: distclassipy.classifier.EnsembleDistanceClassifier
+   :members:
+   :inherited-members:
+   :exclude-members: set_fit_request, set_predict_request
+
+.. doctest-skip::
+
+.. skip::
+
 Copyright (C) 2024  Siddharth Chaini
 -----
 This program is free software: you can redistribute it and/or modify
@@ -19,7 +34,7 @@ You should have received a copy of the GNU General Public License
 along with this program.  If not, see <https://www.gnu.org/licenses/>.
 """
 
-from typing import Callable
+from typing import Callable, Tuple
 
 import numpy as np
 
@@ -28,15 +43,18 @@ import pandas as pd
 import scipy
 
 from sklearn.base import BaseEstimator, ClassifierMixin
+from sklearn.metrics import accuracy_score
+from sklearn.model_selection import train_test_split
 from sklearn.utils.multiclass import unique_labels
-from sklearn.utils.validation import check_X_y, check_array, check_is_fitted
+from sklearn.utils.validation import check_is_fitted, check_array
 
-from .distances import Distance
+from . import distances
+from .distances import _ALL_METRICS
 
 # Hardcoded source packages to check for distance metrics.
 METRIC_SOURCES_ = {
     "scipy.spatial.distance": scipy.spatial.distance,
-    "distances.Distance": Distance(),
+    "distclassipy.distances": distances,
 }
 
 
@@ -44,7 +62,7 @@ def initialize_metric_function(metric):
     """Set the metric function based on the provided metric.
 
     If the metric is a string, the function will look for a corresponding
-    function in scipy.spatial.distance or distances.Distance. If the metric
+    function in scipy.spatial.distance or distclassipy.distances. If the metric
     is a function, it will be used directly.
     """
     if callable(metric):
@@ -78,7 +96,7 @@ def initialize_metric_function(metric):
             raise ValueError(
                 f"{metric} metric not found. Please pass a string of the "
                 "name of a metric in scipy.spatial.distance or "
-                "distances.Distance, or pass a metric function directly. For a "
+                "distclassipy.distances, or pass a metric function directly. For a "
                 "list of available metrics, see: "
                 "https://sidchaini.github.io/DistClassiPy/distances.html or "
                 "https://docs.scipy.org/doc/scipy/reference/spatial.distance.html"
@@ -86,7 +104,7 @@ def initialize_metric_function(metric):
     return metric_fn_, metric_arg_
 
 
-class DistanceMetricClassifier(BaseEstimator, ClassifierMixin):
+class DistanceMetricClassifier(ClassifierMixin, BaseEstimator):
     """A distance-based classifier that supports different distance metrics.
 
     The distance metric classifier determines the similarity between features in a
@@ -113,16 +131,6 @@ class DistanceMetricClassifier(BaseEstimator, ClassifierMixin):
 
         .. versionadded:: 0.1.0
 
-
-    Attributes
-    ----------
-    scale : bool
-        Indicates whether the data is scaled.
-    central_stat : str
-        The statistic used for calculating central tendency.
-    dispersion_stat : str
-        The statistic used for calculating dispersion.
-
     References
     ----------
     .. [1] "Light Curve Classification with DistClassiPy: a new distance-based
@@ -135,25 +143,29 @@ class DistanceMetricClassifier(BaseEstimator, ClassifierMixin):
     >>> X, y = make_classification(n_samples=1000, n_features=4,
     ...                            n_informative=2, n_redundant=0,
     ...                            random_state=0, shuffle=False)
-    >>> clf = dcpy.DistanceMetricClassifier(metric="canberra")
+    >>> clf = dcpy.DistanceMetricClassifier()
     >>> clf.fit(X, y)
     DistanceMetricClassifier(...)
-    >>> print(clf.predict([[0, 0, 0, 0]]))
+    >>> print(clf.predict([[0, 0, 0, 0]], metric="canberra"))
     [0]
     """
 
     def __init__(
         self,
+        metric: str | Callable = None,
         scale: bool = True,
         central_stat: str = "median",
         dispersion_stat: str = "std",
-    ):
+    ) -> None:
         """Initialize the classifier with specified parameters."""
+        self.metric = metric
         self.scale = scale
         self.central_stat = central_stat
         self.dispersion_stat = dispersion_stat
 
-    def fit(self, X: np.array, y: np.array, feat_labels: list[str] = None):
+    def fit(
+        self, X: np.array, y: np.array, feat_labels: list[str] = None
+    ) -> "DistanceMetricClassifier":
         """Calculate the feature space centroid for all classes.
 
         This function calculates the feature space centroid in the training
@@ -177,11 +189,8 @@ class DistanceMetricClassifier(BaseEstimator, ClassifierMixin):
         self : object
             Fitted estimator.
         """
-        X, y = check_X_y(X, y)
+        X, y = self._validate_data(X, y)
         self.classes_ = unique_labels(y)
-        self.n_features_in_ = X.shape[
-            1
-        ]  # Number of features seen during fit - required for sklearn compatibility.
 
         if feat_labels is None:
             feat_labels = [f"Feature_{x}" for x in range(X.shape[1])]
@@ -233,8 +242,8 @@ class DistanceMetricClassifier(BaseEstimator, ClassifierMixin):
     def predict(
         self,
         X: np.array,
-        metric: str | Callable = "euclidean",
-    ):
+        metric: str | Callable = None,
+    ) -> np.ndarray:
         """Predict the class labels for the provided X.
 
         The prediction is based on the distance of each data point in the input sample
@@ -248,6 +257,10 @@ class DistanceMetricClassifier(BaseEstimator, ClassifierMixin):
         metric : str or callable, default="euclidean"
             The distance metric to use for calculating the distance between features.
 
+            .. versionchanged:: 0.2.0
+               The metric is now specified at prediction time rather
+               than during initialization, providing greater flexibility.
+
         Returns
         -------
         y : ndarray of shape (n_samples,)
@@ -256,7 +269,7 @@ class DistanceMetricClassifier(BaseEstimator, ClassifierMixin):
         See Also
         --------
         scipy.spatial.dist : Other distance metrics provided in SciPy
-        distclassipy.Distance : Distance metrics included with DistClassiPy
+        distclassipy.distances : Distance metrics included with DistClassiPy
 
         Notes
         -----
@@ -264,10 +277,14 @@ class DistanceMetricClassifier(BaseEstimator, ClassifierMixin):
         which allows SciPy to use an optimized C version of the code instead of the
         slower Python version.
         """
-        check_is_fitted(self, "is_fitted_")
-        X = check_array(X)
+        check_is_fitted(self)
+        X = self._validate_data(X, reset=False)
 
-        metric_fn_, metric_arg_ = initialize_metric_function(metric)
+        metric_to_use = metric if metric is not None else self.metric
+        if metric_to_use is None:
+            # defaults to euclidean
+            metric_to_use = "euclidean"
+        metric_fn_, metric_arg_ = initialize_metric_function(metric_to_use)
 
         if not self.scale:
             dist_arr = scipy.spatial.distance.cdist(
@@ -298,8 +315,8 @@ class DistanceMetricClassifier(BaseEstimator, ClassifierMixin):
     def predict_and_analyse(
         self,
         X: np.array,
-        metric: str | Callable = "euclidean",
-    ):
+        metric: str | Callable = None,
+    ) -> np.ndarray:
         """Predict the class labels for the provided X and perform analysis.
 
         The prediction is based on the distance of each data point in the input sample
@@ -325,7 +342,7 @@ class DistanceMetricClassifier(BaseEstimator, ClassifierMixin):
         See Also
         --------
         scipy.spatial.dist : Other distance metrics provided in SciPy
-        distclassipy.Distance : Distance metrics included with DistClassiPy
+        distclassipy.distances : Distance metrics included with DistClassiPy
 
         Notes
         -----
@@ -334,10 +351,14 @@ class DistanceMetricClassifier(BaseEstimator, ClassifierMixin):
         of the slower Python version.
 
         """
-        check_is_fitted(self, "is_fitted_")
-        X = check_array(X)
+        check_is_fitted(self)
+        X = self._validate_data(X, reset=False)
 
-        metric_fn_, metric_arg_ = initialize_metric_function(metric)
+        metric_to_use = metric if metric is not None else self.metric
+        if metric_to_use is None:
+            # defaults to euclidean
+            metric_to_use = "euclidean"
+        metric_fn_, metric_arg_ = initialize_metric_function(metric_to_use)
 
         if not self.scale:
             dist_arr = scipy.spatial.distance.cdist(
@@ -397,3 +418,290 @@ class DistanceMetricClassifier(BaseEstimator, ClassifierMixin):
         ]
 
         return self.confidence_df_.to_numpy()
+
+    def score(self, X, y, metric: str | Callable = None) -> float:
+        """Return the mean accuracy on the given test data and labels.
+
+        Parameters
+        ----------
+        X : array-like of shape (n_samples, n_features)
+            Test samples.
+        y : array-like of shape (n_samples,)
+            True labels for X.
+        metric : str or callable, default="euclidean"
+            The distance metric to use for calculating the distance between features.
+
+        Returns
+        -------
+        score : float
+            Mean accuracy of self.predict(X) wrt. y.
+        """
+        metric_to_use = metric if metric is not None else self.metric
+        y_pred = self.predict(X, metric=metric_to_use)
+        return accuracy_score(y, y_pred)
+
+
+class EnsembleDistanceClassifier(ClassifierMixin, BaseEstimator):
+    """An ensemble classifier that uses different metrics for each quantile.
+
+    This classifier splits the data into quantiles based on a specified
+    feature and uses different distance metrics for each quantile to
+    construct an ensemble classifier for each quantile, generally leading
+    to better performance.
+    Note, however, this involves fitting the training set for each metric
+    to evaluate performance, making this more computationally expensive.
+
+    .. versionadded:: 0.2.0
+    """
+
+    def __init__(
+        self,
+        feat_idx: int,
+        scale: bool = True,
+        central_stat: str = "median",
+        dispersion_stat: str = "std",
+        metrics_to_consider: list[str] = None,
+        random_state: int = None,
+    ) -> None:
+        """Initialize the classifier with specified parameters.
+
+        Parameters
+        ----------
+        feat_idx : int
+            The index of the feature to be used for quantile splitting.
+        scale : bool, default=True
+            Whether to scale the distance between the test object and the centroid.
+        central_stat : str, default="median"
+            The statistic used to calculate the central tendency of the data.
+        dispersion_stat : str, default="std"
+            The statistic used to calculate the dispersion of the data.
+        metrics_to_consider : list of str, optional
+            A list of distance metrics to evaluate. If None, all available
+            metrics within DistClassiPy will be considered.
+        random_state : int, RandomState instance or None, optional (default=None)
+            Controls the randomness of the estimator. Pass an int for reproducible
+            output across multiple function calls.
+
+            .. versionadded:: 0.2.1
+        """
+        self.feat_idx = feat_idx
+        self.scale = scale
+        self.central_stat = central_stat
+        self.dispersion_stat = dispersion_stat
+        self.metrics_to_consider = metrics_to_consider
+        self.random_state = random_state
+
+    def fit(
+        self, X: np.ndarray, y: np.ndarray, n_quantiles: int = 4
+    ) -> "EnsembleDistanceClassifier":
+        """Fit the ensemble classifier using the best metrics for each quantile.
+
+        Parameters
+        ----------
+        X : np.ndarray
+            The input feature matrix.
+        y : np.ndarray
+            The target labels.
+        n_quantiles : int, default=4
+            The number of quantiles to split the data into.
+
+        Returns
+        -------
+        self : object
+            Fitted estimator.
+        """
+        self.clf_ = DistanceMetricClassifier(
+            scale=self.scale,
+            central_stat=self.central_stat,
+            dispersion_stat=self.dispersion_stat,
+        )
+
+        # Find best metrics based on training set quantiles
+        self.quantile_scores_df_, self.best_metrics_per_quantile_, self.group_bins = (
+            self.evaluate_metrics(X, y, n_quantiles)
+        )
+
+        # Ensure the bins work with values outside of training data
+        self.group_bins[0] = -np.inf
+        self.group_bins[-1] = np.inf
+
+        self.group_labels = [f"Quantile {i+1}" for i in range(n_quantiles)]
+        self.clf_.fit(X, y)
+        self.is_fitted_ = True
+        return self
+
+    def predict(self, X: np.ndarray) -> np.ndarray:
+        """Predict class labels using the best metric for each quantile.
+
+        Parameters
+        ----------
+        X : np.ndarray
+            The input samples.
+
+        Returns
+        -------
+        predictions : np.ndarray
+            The predicted class labels.
+        """
+        check_is_fitted(self)
+        X = self._validate_data(X, reset=False)
+
+        # notes for pred during best:
+        # option 1:
+        # loop through each metric, merge quantiles for each metric
+        # pred on this
+        # option 2, easier, but slower:
+        # loop through each quantile, and append pred
+
+        quantiles = pd.cut(
+            X[:, self.feat_idx], bins=self.group_bins, labels=self.group_labels
+        )
+        grouped_data = pd.DataFrame(X).groupby(quantiles, observed=False)
+        # quantile_indices = quantiles.codes  # Get integer codes for quantiles
+        predictions = np.empty(X.shape[0], dtype=object)  # Change dtype to object
+        for i, (lim, subdf) in enumerate(grouped_data):
+            best_metric = self.best_metrics_per_quantile_.loc[self.group_labels[i]]
+            preds = self.clf_.predict(subdf.to_numpy(), metric=best_metric)
+            predictions[subdf.index] = preds
+        # # Precompute predictions for each quantile
+        # quantile_predictions = {}
+        # for i, label in enumerate(self.group_labels):
+        #     best_metric = self.best_metrics_per_quantile_.loc[label]
+        #     quantile_data = X[quantile_indices == i]
+        #     if quantile_data.size > 0:
+        #         quantile_predictions[i] = self.clf_.predict(
+        #             quantile_data, metric=best_metric
+        #         )
+
+        # Assign predictions to the corresponding indices
+        # for i, preds in quantile_predictions.items():
+        #     predictions[quantile_indices == i] = preds
+
+        return predictions
+
+    def evaluate_metrics(
+        self, X: np.ndarray, y: np.ndarray, n_quantiles: int = 4
+    ) -> Tuple[pd.DataFrame, pd.Series, np.ndarray]:
+        """Evaluate and find the best distance metrics for the specified feature.
+
+        This method uses the standalone `find_best_metrics` function to evaluate
+        different distance metrics and determine the best-performing ones for
+        each quantile.
+
+        Parameters
+        ----------
+        X : np.ndarray
+            The input feature matrix.
+        y : np.ndarray
+            The target labels.
+        n_quantiles : int, default=4
+            The number of quantiles to split the data into.
+
+        Returns
+        -------
+        quantile_scores_df : pd.DataFrame
+            A DataFrame containing the accuracy scores for each metric across
+            different quantiles.
+        best_metrics_per_quantile : pd.Series
+            A Series indicating the best-performing metric for each quantile.
+        group_bins : np.ndarray
+            The bins used for quantile splitting.
+        """
+        return find_best_metrics(
+            self.clf_,
+            X,
+            y,
+            self.feat_idx,
+            n_quantiles,
+            self.metrics_to_consider,
+            self.random_state,
+        )
+
+
+def find_best_metrics(
+    clf: "DistanceMetricClassifier",
+    X: np.ndarray,
+    y: np.ndarray,
+    feat_idx: int,
+    n_quantiles: int = 4,
+    metrics_to_consider: list[str] = None,
+    random_state: int = None,
+) -> Tuple[pd.DataFrame, pd.Series, np.ndarray]:
+    """Evaluate and find the best distance metrics for a given feature.
+
+    This function evaluates different distance metrics to determine which
+    performs best for a specific feature in the dataset. It splits the data
+    into quantiles based on the specified feature and calculates the accuracy
+    of the classifier for each metric within these quantiles.
+
+    .. versionadded:: 0.2.0
+
+    Parameters
+    ----------
+    clf : DistanceMetricClassifier
+        The classifier instance to be used for evaluation.
+    X : np.ndarray
+        The input feature matrix.
+    y : np.ndarray
+        The target labels.
+    feat_idx : int
+        The index of the feature to be used for quantile splitting.
+    n_quantiles : int, default=4
+        The number of quantiles to split the data into.
+    metrics_to_consider : list of str, optional
+        A list of distance metrics to evaluate. If None, all available
+        metrics within DistClassiPy will be considered.
+    random_state : int, RandomState instance or None, optional (default=None)
+        Controls the randomness of the estimator. Pass an int for reproducible
+        output across multiple function calls.
+
+        .. versionadded:: 0.2.1
+
+    Returns
+    -------
+    quantile_scores_df : pd.DataFrame
+        A DataFrame containing the accuracy scores for each metric across
+        different quantiles.
+    best_metrics_per_quantile : pd.Series
+        A Series indicating the best-performing metric for each quantile.
+    group_bins : np.ndarray
+        The bins used for quantile splitting.
+    """
+    X = check_array(X)
+    feature_labels = [f"Feature_{i}" for i in range(X.shape[1])]
+    feature_name = f"Feature_{feat_idx}"
+
+    if metrics_to_consider is None:
+        metrics_to_consider = _ALL_METRICS
+
+    X_df = pd.DataFrame(X, columns=feature_labels)
+    y_df = pd.DataFrame(y, columns=["Target"])
+    quantiles, group_bins = pd.qcut(X_df[feature_name], q=n_quantiles, retbins=True)
+
+    X_train, X_test, y_train, y_test = train_test_split(
+        X_df, y_df, test_size=0.25, stratify=quantiles, random_state=random_state
+    )
+
+    clf.fit(X_train, y_train.to_numpy().ravel())
+    grouped_test_data = X_test.groupby(quantiles, observed=False)
+
+    quantile_scores = []
+    for metric in metrics_to_consider:
+        scores_for_metric = [
+            accuracy_score(
+                y_test.loc[subdf.index], clf.predict(subdf.to_numpy(), metric=metric)
+            )
+            for _, subdf in grouped_test_data
+        ]
+        quantile_scores.append(scores_for_metric)
+
+    quantile_scores = np.array(quantile_scores) * 100
+    quantile_scores_df = pd.DataFrame(
+        data=quantile_scores,
+        index=metrics_to_consider,
+        columns=[f"Quantile {i+1}" for i in range(n_quantiles)],
+    )
+
+    best_metrics_per_quantile = quantile_scores_df.idxmax()
+
+    return quantile_scores_df, best_metrics_per_quantile, group_bins