machinegnostics 0.0.1__py3-none-any.whl

machinegnostics/metrics/accuracy.py

@@ -0,0 +1,67 @@
+import numpy as np
+import pandas as pd
+import logging
+from machinegnostics.magcal.util.logging import get_logger
+from machinegnostics.metrics.mean import mean
+
+def accuracy_score(y_true:np.ndarray, y_pred:np.ndarray, verbose:bool=False) -> float:
+    """
+    Computes the accuracy classification score.
+
+    Supports input as numpy arrays, lists, or pandas Series/DataFrame columns.
+
+    Parameters
+    ----------
+    y_true : array-like or pandas Series/DataFrame column of shape (n_samples,)
+        Ground truth (correct) target values.
+
+    y_pred : array-like or pandas Series/DataFrame column of shape (n_samples,)
+        Estimated targets as returned by a classifier.
+    verbose : bool, optional
+        If True, enables detailed logging for debugging purposes. Default is False.
+
+    Returns
+    -------
+    accuracy : float
+        The accuracy score as a float in the range [0, 1].
+
+    Examples
+    --------
+    >>> y_true = [0, 1, 2, 2, 0]
+    >>> y_pred = [0, 0, 2, 2, 0]
+    >>> accuracy_score(y_true, y_pred)
+    0.8
+
+    >>> import pandas as pd
+    >>> df = pd.DataFrame({'true': [1, 0, 1], 'pred': [1, 1, 1]})
+    >>> accuracy_score(df['true'], df['pred'])
+    """
+    logger = get_logger('accuracy_score', level=logging.WARNING if not verbose else logging.INFO)
+    logger.info("Calculating Accuracy Score...")
+    # Check for empty input
+    if y_true is None or y_pred is None:
+        logger.error("y_true and y_pred must not be None.")
+        raise ValueError("y_true and y_pred must not be None.")
+    # If input is a DataFrame, raise error (must select column)
+    if isinstance(y_true, pd.DataFrame) or isinstance(y_pred, pd.DataFrame):
+        logger.error("y_true and y_pred must be 1D array-like or pandas Series, not DataFrame. Select a column.")
+        raise ValueError("y_true and y_pred must be 1D array-like or pandas Series, not DataFrame. Select a column.")
+
+    # Convert pandas Series to numpy array
+    if isinstance(y_true, pd.Series):
+        y_true = y_true.values
+    if isinstance(y_pred, pd.Series):
+        y_pred = y_pred.values
+
+    # Convert to numpy arrays and flatten
+    y_true = np.asarray(y_true).flatten()
+    y_pred = np.asarray(y_pred).flatten()
+
+    if y_true.shape != y_pred.shape:
+        raise ValueError("Shape of y_true and y_pred must be the same.")
+
+    correct = np.sum(y_true == y_pred)
+    total = y_true.size
+    accuracy = correct / total
+    logger.info("Accuracy score calculation complete.")
+    return accuracy

machinegnostics/metrics/auto_correlation.py

@@ -0,0 +1,183 @@
+"""
+Auto-Correlation Metric
+
+This module provides a function to compute the auto-correlation of a data sample.
+
+Author: Nirmal Parmar
+Machine Gnostics
+"""
+
+import logging
+from machinegnostics.magcal.util.logging import get_logger
+import numpy as np
+from machinegnostics.magcal import EGDF, QGDF, DataHomogeneity
+
+def auto_correlation(data: np.ndarray, lag: int = 0, case: str = 'i', verbose: bool = False) -> float:
+    """
+    Calculate the Gnostic auto-correlation of a data sample.
+
+    Auto-correlation measures the similarity between a data sample and a lagged version of itself.
+    This function uses the principles of gnostic theory to compute robust estimates of auto-correlation.
+
+    Parameters:
+    ----------
+    data : np.ndarray
+        The data sample. Must be a 1D numpy array without NaN or Inf values.
+    lag : int, optional, default=0
+        The lag value for which the auto-correlation is computed. Must be non-negative and less than the length of the data.
+    case : str, optional, default='i'
+        Specifies the type of geometry to use:
+        - 'i': Estimation geometry (EGDF).
+        - 'j': Quantifying geometry (QGDF).
+    verbose : bool, optional, default=False
+        If True, enables detailed logging for debugging purposes.
+
+    Returns:
+    -------
+    float
+        The Gnostic auto-correlation coefficient for the given lag.
+
+    Raises:
+    ------
+    ValueError
+        If the input array is empty, contains NaN/Inf values, is not 1D, or if the lag is invalid.
+
+    Examples:
+    ---------
+    Example 1: Compute auto-correlation for a simple dataset
+    >>> import numpy as np
+    >>> from machinegnostics.metrics import auto_correlation
+    >>> data = np.array([1, 2, 3, 4, 5])
+    >>> lag = 1
+    >>> auto_corr = auto_correlation(data, lag=lag, case='i', verbose=False)
+    >>> print(f"Auto-Correlation (lag={lag}, case='i'): {auto_corr}")
+
+    Notes:
+    -----
+    - This metric is robust to data uncertainty and provides meaningful estimates even in the presence of noise or outliers.
+    - Ensure that the input data is preprocessed and cleaned for optimal results.
+    """
+    logger = get_logger('auto_correlation', level=logging.WARNING if not verbose else logging.INFO)
+    logger.info("Starting auto-correlation computation.")
+
+    # Validate inputs
+    if not isinstance(data, np.ndarray):
+        logger.error("Input must be a numpy array.")
+        raise ValueError("Input must be a numpy array.")
+    # flatten data
+    data = data.flatten()
+    if data.ndim != 1:
+        logger.error("Input array must be 1D.")
+        raise ValueError("Input array must be 1D.")
+    if len(data) == 0:
+        logger.error("Input array must not be empty.")
+        raise ValueError("Input array must not be empty.")
+    if np.any(np.isnan(data)):
+        logger.error("Input array must not contain NaN values.")
+        raise ValueError("Input array must not contain NaN values.")
+    if np.any(np.isinf(data)):
+        logger.error("Input array must not contain Inf values.")
+        raise ValueError("Input array must not contain Inf values.")
+    if lag < 0 or lag >= len(data):
+        logger.error("Lag must be non-negative and less than the length of the data.")
+        raise ValueError("Lag must be non-negative and less than the length of the data.")
+    if case not in ['i', 'j']:
+        logger.error("Case must be 'i' for estimation geometry or 'j' for quantifying geometry.")
+        raise ValueError("Case must be 'i' for estimation geometry or 'j' for quantifying geometry.")
+
+    # Shift data by lag
+    data_lagged = np.roll(data, -lag)
+    data_lagged = data_lagged[:-lag] if lag > 0 else data_lagged
+    data = data[:len(data_lagged)]
+
+    # Default arguments for gnostic functions
+    FLUSH = False
+    VERBOSE = False
+
+    if case == 'i':
+        logger.info("Using Estimation Global Distribution Function (EGDF) for irrelevance computation.")
+        # EGDF
+        egdf_data = EGDF(flush=FLUSH, verbose=VERBOSE)
+        egdf_data.fit(data)
+
+        egdf_data_lagged = EGDF(flush=FLUSH, verbose=VERBOSE)
+        egdf_data_lagged.fit(data_lagged)
+
+        # Data Homogeneity
+        logger.info("Performing data homogeneity check.")
+        dh_data = DataHomogeneity(gdf=egdf_data, verbose=VERBOSE, flush=FLUSH)
+        is_homo_data = dh_data.fit()
+
+        dh_data_lagged = DataHomogeneity(gdf=egdf_data_lagged, verbose=VERBOSE, flush=FLUSH)
+        is_homo_data_lagged = dh_data_lagged.fit()
+
+        # data homogeneity check
+        if not is_homo_data:
+            logger.warning("Data is not homogeneous. Switching to S=1 for better results.")
+            logger.info("Fitting EGDF with S=1.")
+            egdf_data = EGDF(flush=FLUSH, verbose=VERBOSE, S=1)
+            egdf_data.fit(data)
+        
+        if not is_homo_data_lagged:
+            logger.warning("Lagged data is not homogeneous. Switching to S=1 for better results.")
+            logger.info("Fitting EGDF with S=1.")
+            egdf_data_lagged = EGDF(flush=FLUSH, verbose=VERBOSE, S=1)
+            egdf_data_lagged.fit(data_lagged)
+
+        # Get irrelevance of the data sample
+        logger.info("Getting irrelevance of the data sample.")
+        hc_data = np.mean(egdf_data.hi, axis=0)
+        hc_data_lagged = np.mean(egdf_data_lagged.hi, axis=0)
+
+    if case == 'j':
+        logger.info("Using Quantifying Global Distribution Function (QGDF) for irrelevance computation.")
+        # EGDF
+        egdf_data = EGDF(flush=FLUSH, verbose=VERBOSE)
+        egdf_data.fit(data)
+
+        egdf_data_lagged = EGDF(flush=FLUSH, verbose=VERBOSE)
+        egdf_data_lagged.fit(data_lagged)
+
+        # Data Homogeneity
+        logger.info("Performing data homogeneity check.")
+        dh_data = DataHomogeneity(gdf=egdf_data, verbose=VERBOSE, flush=FLUSH)
+        is_homo_data = dh_data.fit()
+
+        dh_data_lagged = DataHomogeneity(gdf=egdf_data_lagged, verbose=VERBOSE, flush=FLUSH)
+        is_homo_data_lagged = dh_data_lagged.fit()
+
+        # data homogeneity check
+        if not is_homo_data:
+            logger.info("Data is not homogeneous.")
+        if not is_homo_data_lagged:
+            logger.info("Lagged data is not homogeneous.")
+
+        # QGDF
+        logger.info("Fitting QGDF with S=1.")
+        qgdf_data = QGDF(flush=FLUSH, verbose=VERBOSE)
+        qgdf_data.fit(data)
+
+        qgdf_data_lagged = QGDF(flush=FLUSH, verbose=VERBOSE)
+        qgdf_data_lagged.fit(data_lagged)
+
+        # Get irrelevance of the data sample
+        hc_data = np.mean(qgdf_data.hj, axis=0)
+        hc_data_lagged = np.mean(qgdf_data_lagged.hj, axis=0)
+
+        # Stop overflow by limiting big value in hc up to 1e12
+        hc_data = np.clip(hc_data, 1, 1e12)
+        hc_data_lagged = np.clip(hc_data_lagged, 1, 1e12)
+
+    # Compute correlation
+    def compute_correlation(hc_data_1: np.ndarray, hc_data_2: np.ndarray) -> float:
+        logger.debug("Computing correlation.")
+        numerator = np.sum(hc_data_1 * hc_data_2)
+        denominator = (np.sqrt(np.sum(hc_data_1**2)) * np.sqrt(np.sum(hc_data_2**2))) 
+        corr = numerator / denominator
+        if denominator == 0:
+            return np.nan
+        return corr
+    
+    auto_corr = compute_correlation(hc_data, hc_data_lagged)
+
+    return auto_corr

machinegnostics/metrics/auto_covariance.py

@@ -0,0 +1,204 @@
+'''
+Gnostic auto-co-variance
+
+Author: Nirmal Parmar
+Machine Gnostics
+'''
+
+from re import VERBOSE
+import numpy as np
+from machinegnostics.magcal import EGDF, QGDF, DataHomogeneity
+from machinegnostics.magcal.util.logging import get_logger
+import logging
+
+def auto_covariance(data: np.ndarray, lag: int = 0, case: str = 'i', verbose: bool = False) -> float:
+    """
+    Calculate the Gnostic auto-covariance of a data sample.
+
+    Auto-covariance measures the relationship between a data sample and a lagged version of itself.
+    This function uses the principles of Gnostic theory to compute robust estimates of auto-covariance.
+
+    Parameters:
+    ----------
+    data : np.ndarray
+        The data sample. Must be a 1D numpy array without NaN or Inf values.
+        The input data should represent a time series or sequential data points.
+    lag : int, optional, default=0
+        The lag value for which the auto-covariance is computed. Must be non-negative and less than the length of the data.
+        A lag of 0 computes the covariance of the data with itself.
+    case : str, optional, default='i'
+        Specifies the type of geometry to use for irrelevance computation:
+        - 'i': Estimation Geometry Distribution Function.
+        - 'j': Quantifying Geometry Distribution Function.
+    verbose : bool, optional, default=False
+        If True, detailed logging information will be printed during the computation.
+
+    Returns:
+    -------
+    float
+        The Gnostic auto-covariance coefficient for the given lag. If the computed value is less than 1e-6, it is set to 0.0.
+
+    Raises:
+    ------
+    ValueError
+        If the input array is invalid (e.g., not a numpy array, contains NaN/Inf values, is not 1D, or is empty).
+        If the lag is negative or greater than or equal to the length of the data.
+        If the case is not one of ['i', 'j'].
+
+    Notes:
+    -----
+    - This function uses Gnostic theory to compute irrelevance values for the data and its lagged version.
+    - Irrelevance values are clipped to avoid overflow, with a maximum value of 1e12.
+    - Homogeneity checks are performed on the data and its lagged version. If the data is not homogeneous, warnings are raised.
+
+    Warnings:
+    --------
+    - If the data or its lagged version is not homogeneous, a warning is printed suggesting the use of a scale parameter ( S = 1 ) for better results.
+
+    Examples:
+    ---------
+    Example 1: Compute auto-covariance for a simple dataset
+    >>> from machinegnostics.metrics import auto_covariance
+    >>> import machinegnostics as mg # alternative import
+    >>> import numpy as np
+    >>> data = np.array([1.0, 2.0, 3.0, 4.0, 5.0])
+    >>> lag = 1
+    >>> auto_covar = auto_covariance(data, lag=lag, case='i')
+    >>> auto_covar = mg.auto_covariance(data, lag=lag, case='i') # alternative usage
+    >>> print(f"Auto-covariance with lag={lag}: {auto_covar}")
+
+    Example 2: Compute auto-covariance for a dataset with QGDF
+    >>> data = np.array([1.0, 2.0, 3.0, 4.0, 5.0])
+    >>> lag = 2
+    >>> auto_covar = auto_covariance(data, lag=lag, case='j')
+    >>> print(f"Auto-covariance with lag={lag}: {auto_covar}")
+
+    Example 3: Handle invalid input
+    >>> data = np.array([1.0, np.nan, 3.0, 4.0, 5.0])
+    >>> lag = 1
+    >>> try:
+    >>>     auto_covar = auto_covariance(data, lag=lag, case='i')
+    >>> except ValueError as e:
+    >>>     print(f"Error: {e}")
+
+    """
+    logger = get_logger('auto_covariance', level=logging.WARNING if not verbose else logging.INFO)
+    # Validate inputs
+    if not isinstance(data, np.ndarray):
+        logger.error("Input must be a numpy array.")
+        raise ValueError("Input must be a numpy array.")
+    # flatten data
+    data = data.flatten()
+    if data.ndim != 1:
+        logger.error("Input array must be 1D.")
+        raise ValueError("Input array must be 1D.")
+    if len(data) == 0:
+        logger.error("Input array must not be empty.")
+        raise ValueError("Input array must not be empty.")
+    if np.any(np.isnan(data)):
+        logger.error("Input array must not contain NaN values.")
+        raise ValueError("Input array must not contain NaN values.")
+    if np.any(np.isinf(data)):
+        logger.error("Input array must not contain Inf values.")
+        raise ValueError("Input array must not contain Inf values.")
+    if lag < 0 or lag >= len(data):
+        logger.error("Lag must be non-negative and less than the length of the data.")
+        raise ValueError("Lag must be non-negative and less than the length of the data.")
+    if case not in ['i', 'j']:
+        logger.error("Case must be 'i' for estimation geometry or 'j' for quantifying geometry.")
+        raise ValueError("Case must be 'i' for estimation geometry or 'j' for quantifying geometry.")
+
+    # Shift data by lag
+    data_lagged = np.roll(data, -lag)
+    data_lagged = data_lagged[:-lag] if lag > 0 else data_lagged
+    data = data[:len(data_lagged)]
+
+    # Default arguments for gnostic functions
+    FLUSH = False
+    VERBOSE = False
+
+    if case == 'i':
+        logger.info("Using Estimation Global Distribution Function (EGDF) for irrelevance computation.")
+        # EGDF
+        egdf_data = EGDF(flush=FLUSH, verbose=VERBOSE)
+        egdf_data.fit(data)
+
+        egdf_data_lagged = EGDF(flush=FLUSH, verbose=VERBOSE)
+        egdf_data_lagged.fit(data_lagged)
+
+        # Data Homogeneity
+        logger.info("Performing data homogeneity check.")
+        dh_data = DataHomogeneity(gdf=egdf_data, verbose=VERBOSE, flush=FLUSH)
+        is_homo_data = dh_data.fit()
+
+        dh_data_lagged = DataHomogeneity(gdf=egdf_data_lagged, verbose=VERBOSE, flush=FLUSH)
+        is_homo_data_lagged = dh_data_lagged.fit()
+
+        # data homogeneity check
+        if not is_homo_data:
+            logger.warning("Data is not homogeneous. Switching to S=1 for better results.")
+            logger.info("Fitting EGDF with S=1.")
+            egdf_data = EGDF(flush=FLUSH, verbose=VERBOSE, S=1)
+            egdf_data.fit(data)
+        
+        if not is_homo_data_lagged:
+            logger.warning("Lagged data is not homogeneous. Switching to S=1 for better results.")
+            logger.info("Fitting EGDF with S=1.")
+            egdf_data_lagged = EGDF(flush=FLUSH, verbose=VERBOSE, S=1)
+            egdf_data_lagged.fit(data_lagged)
+
+        # Get irrelevance of the data sample
+        logger.info("Getting irrelevance of the data sample.")
+        hc_data = np.mean(egdf_data.hi, axis=0)
+        hc_data_lagged = np.mean(egdf_data_lagged.hi, axis=0)
+
+    if case == 'j':
+        logger.info("Using Quantifying Global Distribution Function (QGDF) for irrelevance computation.")
+        # EGDF
+        egdf_data = EGDF(flush=FLUSH, verbose=VERBOSE)
+        egdf_data.fit(data)
+
+        egdf_data_lagged = EGDF(flush=FLUSH, verbose=VERBOSE)
+        egdf_data_lagged.fit(data_lagged)
+
+        # Data Homogeneity
+        logger.info("Performing data homogeneity check.")
+        dh_data = DataHomogeneity(gdf=egdf_data, verbose=VERBOSE, flush=FLUSH)
+        is_homo_data = dh_data.fit()
+
+        dh_data_lagged = DataHomogeneity(gdf=egdf_data_lagged, verbose=VERBOSE, flush=FLUSH)
+        is_homo_data_lagged = dh_data_lagged.fit()
+
+        # data homogeneity check
+        if not is_homo_data:
+            logger.info("Data is not homogeneous.")
+        if not is_homo_data_lagged:
+            logger.info("Lagged data is not homogeneous.")
+
+        # QGDF
+        logger.info("Fitting QGDF with S=1.")
+        qgdf_data = QGDF(flush=FLUSH, verbose=VERBOSE)
+        qgdf_data.fit(data)
+
+        qgdf_data_lagged = QGDF(flush=FLUSH, verbose=VERBOSE)
+        qgdf_data_lagged.fit(data_lagged)
+
+        # Get irrelevance of the data sample
+        hc_data = np.mean(qgdf_data.hj, axis=0)
+        hc_data_lagged = np.mean(qgdf_data_lagged.hj, axis=0)
+
+        # Stop overflow by limiting big value in hc up to 1e12
+        hc_data = np.clip(hc_data, 1, 1e12)
+        hc_data_lagged = np.clip(hc_data_lagged, 1, 1e12)
+
+        
+
+    # Compute auto-covariance
+    numerator = np.sum(hc_data * hc_data_lagged)
+    denominator = (len(data) - lag)
+    if denominator == 0:
+        auto_covar = 0
+    if denominator != 0:
+        auto_covar = numerator / denominator
+
+    return auto_covar

machinegnostics/metrics/cls_report.py

@@ -0,0 +1,130 @@
+import numpy as np
+import pandas as pd
+from machinegnostics.metrics import precision_score, recall_score, f1_score
+from machinegnostics.magcal.util.logging import get_logger
+import logging
+
+def classification_report(
+    y_true:np.ndarray | pd.Series,
+    y_pred:np.ndarray | pd.Series,
+    labels=None,
+    target_names=None,
+    digits=2,
+    output_dict=False,
+    verbose: bool = False
+):
+    """
+    Builds a text summary or dictionary of the precision, recall, F1 score, and support for each class.
+
+    Uses the precision_score, recall_score, and f1_score functions for consistency.
+
+    Parameters
+    ----------
+    y_true : array-like or pandas Series/DataFrame column of shape (n_samples,)
+        Ground truth (correct) target values.
+
+    y_pred : array-like or pandas Series/DataFrame column of shape (n_samples,)
+        Estimated targets as returned by a classifier.
+
+    labels : array-like, default=None
+        List of labels to include in the report. If None, uses sorted unique labels from y_true and y_pred.
+
+    target_names : list of str, default=None
+        Optional display names matching the labels (same order).
+
+    digits : int, default=2
+        Number of digits for formatting output.
+
+    output_dict : bool, default=False
+        If True, return output as a dict for programmatic use. If False, return as a formatted string.
+
+    verbose : bool, optional
+        If True, enables detailed logging for debugging purposes. Default is False.
+
+    Returns
+    -------
+    report : str or dict
+        Text summary or dictionary of the precision, recall, F1 score for each class.
+    """
+    logger = get_logger('classification_report', level=logging.WARNING if not verbose else logging.INFO)
+    logger.info("Generating Classification Report...")
+    # Convert pandas Series to numpy array
+    if isinstance(y_true, pd.Series):
+        y_true = y_true.values
+    if isinstance(y_pred, pd.Series):
+        y_pred = y_pred.values
+
+    # Convert to numpy arrays and flatten
+    y_true = np.asarray(y_true).flatten()
+    y_pred = np.asarray(y_pred).flatten()
+
+    if y_true.shape != y_pred.shape:
+        logger.error("Shape of y_true and y_pred must be the same.")
+        raise ValueError("Shape of y_true and y_pred must be the same.")
+
+    # Get unique labels
+    if labels is None:
+        labels = np.unique(np.concatenate([y_true, y_pred]))
+    else:
+        labels = np.asarray(labels)
+
+    n_labels = len(labels)
+    if target_names is not None:
+        if len(target_names) != n_labels:
+            logger.error("target_names length must match number of labels")
+            raise ValueError("target_names length must match number of labels")
+    else:
+        target_names = [str(label) for label in labels]
+
+    # Use your metric functions for each class
+    precisions = precision_score(y_true, y_pred, average=None, labels=labels)
+    recalls = recall_score(y_true, y_pred, average=None, labels=labels)
+    f1s = f1_score(y_true, y_pred, average=None, labels=labels)
+    supports = np.array([(y_true == label).sum() for label in labels])
+
+    # Weighted averages
+    total_support = supports.sum()
+    avg_precision = np.average(precisions, weights=supports) if total_support > 0 else 0.0
+    avg_recall = np.average(recalls, weights=supports) if total_support > 0 else 0.0
+    avg_f1 = np.average(f1s, weights=supports) if total_support > 0 else 0.0
+
+    if output_dict:
+        report = {}
+        for i, label in enumerate(labels):
+            report[target_names[i]] = {
+                "precision": round(precisions[i], digits),
+                "recall": round(recalls[i], digits),
+                "f1-score": round(f1s[i], digits),
+                "support": int(supports[i])
+            }
+        report["avg/total"] = {
+            "precision": round(avg_precision, digits),
+            "recall": round(avg_recall, digits),
+            "f1-score": round(avg_f1, digits),
+            "support": int(total_support)
+        }
+        return report
+
+    # Build report string
+    header = f"{'Class':<15}{'Precision':>10}{'Recall':>10}{'F1-score':>10}{'Support':>10}\n"
+    report = header
+    report += "=" * len(header) + "\n"
+    for i in range(n_labels):
+        report += (
+            f"{target_names[i]:<15}"
+            f"{precisions[i]:>10.{digits}f}"
+            f"{recalls[i]:>10.{digits}f}"
+            f"{f1s[i]:>10.{digits}f}"
+            f"{supports[i]:>10}\n"
+        )
+    report += "=" * len(header) + "\n"
+    report += (
+        f"{'Avg/Total':<15}"
+        f"{avg_precision:>10.{digits}f}"
+        f"{avg_recall:>10.{digits}f}"
+        f"{avg_f1:>10.{digits}f}"
+        f"{total_support:>10}\n"
+    )
+
+    logger.info("Classification Report generated.")
+    return report

machinegnostics/metrics/conf_matrix.py

@@ -0,0 +1,93 @@
+import numpy as np
+import pandas as pd
+from machinegnostics.magcal.util.logging import get_logger
+import logging
+
+def confusion_matrix(y_true:np.ndarray | pd.Series,
+                     y_pred:np.ndarray | pd.Series, 
+                     labels=None, verbose=False) -> np.ndarray:
+    """
+    Computes the confusion matrix to evaluate the accuracy of a classification.
+
+    By definition, entry (i, j) in the confusion matrix is the number of observations
+    actually in class i but predicted to be in class j.
+
+    Parameters
+    ----------
+    y_true : array-like or pandas Series/DataFrame column of shape (n_samples,)
+        Ground truth (correct) target values.
+
+    y_pred : array-like or pandas Series/DataFrame column of shape (n_samples,)
+        Estimated targets as returned by a classifier.
+
+    labels : array-like, default=None
+        List of labels to index the matrix. This may be used to reorder or select a subset of labels.
+        If None, labels that appear at least once in y_true or y_pred are used in sorted order.
+    verbose : bool, optional
+        If True, enables detailed logging for debugging purposes. Default is False.
+
+    Returns
+    -------
+    cm : ndarray of shape (n_classes, n_classes)
+        Confusion matrix whose i-th row and j-th column entry indicates the number of samples with
+        true label being i-th class and predicted label being j-th class.
+
+    Examples
+    --------
+    >>> y_true = [2, 0, 2, 2, 0, 1]
+    >>> y_pred = [0, 0, 2, 2, 0, 2]
+    >>> confusion_matrix(y_true, y_pred)
+    array([[2, 0, 0],
+           [0, 0, 1],
+           [1, 0, 2]])
+    """
+    logger = get_logger('confusion_matrix', level=logging.WARNING if not verbose else logging.INFO)
+    logger.info("Calculating Confusion Matrix...")
+    # Convert pandas Series to numpy array
+    if isinstance(y_true, pd.Series):
+        y_true = y_true.values
+    if isinstance(y_pred, pd.Series):
+        y_pred = y_pred.values
+
+    # Convert to numpy arrays and flatten
+    y_true = np.asarray(y_true).flatten()
+    y_pred = np.asarray(y_pred).flatten()
+
+    if y_true.shape != y_pred.shape:
+        logger.error("Shape of y_true and y_pred must be the same.")
+        raise ValueError("Shape of y_true and y_pred must be the same.")
+    if y_true.size == 0:
+        logger.error("y_true and y_pred must not be empty.")
+        raise ValueError("y_true and y_pred must not be empty.")
+    # Ensure 1D arrays
+    if y_true.ndim != 1 or y_pred.ndim != 1:
+        logger.error("y_true and y_pred must be 1D arrays.")
+        raise ValueError("y_true and y_pred must be 1D arrays.")
+    # inf and nan check
+    if np.any(np.isnan(y_true)) or np.any(np.isnan(y_pred)):
+        logger.error("y_true and y_pred must not contain NaN values.")
+        raise ValueError("y_true and y_pred must not contain NaN values.")
+    if np.any(np.isinf(y_true)) or np.any(np.isinf(y_pred)):
+        logger.error("y_true and y_pred must not contain Inf values.")
+        raise ValueError("y_true and y_pred must not contain Inf values.")
+
+    # Determine labels
+    if labels is None:
+        labels = np.unique(np.concatenate([y_true, y_pred]))
+    else:
+        labels = np.asarray(labels)
+    n_labels = len(labels)
+    label_to_index = {label: idx for idx, label in enumerate(labels)}
+
+    # Initialize confusion matrix
+    cm = np.zeros((n_labels, n_labels), dtype=int)
+
+    # Populate confusion matrix
+    for true, pred in zip(y_true, y_pred):
+        if true in label_to_index and pred in label_to_index:
+            i = label_to_index[true]
+            j = label_to_index[pred]
+            cm[i, j] += 1
+
+    logger.info("Confusion Matrix calculation completed.")
+    return cm