machinegnostics 0.0.1__py3-none-any.whl

machinegnostics/metrics/correlation.py

@@ -0,0 +1,178 @@
+'''
+Gnostic Correlation Metric
+
+This module provides a function to compute the Gnostic correlation between two data samples.
+
+Author: Nirmal Parmar
+Machine Gnostics
+'''
+
+import numpy as np
+from machinegnostics.magcal import EGDF, QGDF, DataHomogeneity
+import logging
+from machinegnostics.magcal.util.logging import get_logger
+
+def correlation(X: np.ndarray, y: np.ndarray, case: str = 'i', verbose: bool = False) -> float:
+    """
+    Calculate the Gnostic correlation coefficient between a feature array X and a target array y.
+
+    Parameters:
+    ----------
+    X : np.ndarray
+        The feature data sample. Must be a numpy array without NaN or Inf values.
+        If X has more than one column, pass each column one by one to this function.
+    y : np.ndarray
+        The target data sample. Must be a 1D numpy array without NaN or Inf values.
+    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 correlation coefficient between the two data samples.
+
+    Examples:
+    ---------
+    Example 1: Compute correlation for two simple datasets
+    >>> import numpy as np
+    >>> from machinegnostics.metrics import correlation
+    >>> X = np.array([1, 2, 3, 4, 5])
+    >>> y = np.array([5, 4, 3, 2, 1])
+    >>> corr = correlation(X, y, case='i', verbose=False)
+    >>> print(f"Correlation (case='i'): {corr}")
+
+    Example 2: For multi-column X
+    >>> X = np.array([[1, 10], [2, 20], [3, 30], [4, 40], [5, 50]])
+    >>> y = np.array([5, 4, 3, 2, 1])
+    >>> for i in range(X.shape[1]):
+    ...     corr = correlation(X[:, i], y)
+    ...     print(f"Correlation for column {i}: {corr}")
+
+    Raises:
+    ------
+    ValueError
+        If the input arrays are not of the same length, are empty, contain NaN/Inf values,
+        or are not 1D numpy arrays. Also raised if `case` is not 'i' or 'j'.
+
+    Notes:
+    -----
+    - If X has more than one column, pass each column separately (e.g., X[:, i]).
+    - y must be a 1D array.
+    - 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.
+    - In cases where data homogeneity is not met, a warning is raised, and the scale
+      parameter is adjusted to improve results.
+    """
+    logger = get_logger('correlation', level=logging.WARNING if not verbose else logging.INFO)
+    logger.info("Starting correlation computation.")
+
+    # Validate inputs
+    if not isinstance(X, np.ndarray) or not isinstance(y, np.ndarray):
+        logger.error("Inputs must be numpy arrays.")
+        raise ValueError("Inputs must be numpy arrays.")
+
+    # Flatten X and y to 1D if possible
+    X = X.flatten()
+    y = y.flatten()
+
+    if len(X) != len(y):
+        logger.error("Input arrays must have the same length.")
+        raise ValueError("Input arrays must have the same length.")
+    if len(X) == 0 or len(y) == 0:
+        logger.error("Input arrays must not be empty.")
+        raise ValueError("Input arrays must not be empty.")
+    if np.any(np.isnan(X)) or np.any(np.isnan(y)):
+        logger.error("Input arrays must not contain NaN values.")
+        raise ValueError("Input arrays must not contain NaN values.")
+    if np.any(np.isinf(X)) or np.any(np.isinf(y)):
+        logger.error("Input arrays must not contain Inf values.")
+        raise ValueError("Input arrays must not contain Inf values.")
+    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.")
+
+    # default arg
+    FLUSH = False
+    VERBOSE = False
+
+    # ...existing code logic, replacing data_1 with X and data_2 with y...
+    if case == 'i':
+        logger.info("Using Estimation Global Distribution Function (EGDF) for correlation computation.")
+        egdf_X = EGDF(flush=FLUSH, verbose=VERBOSE)
+        egdf_X.fit(X)
+
+        egdf_y = EGDF(flush=FLUSH, verbose=VERBOSE)
+        egdf_y.fit(y)
+
+        logger.info("Performing data homogeneity check.")
+        dh_X = DataHomogeneity(gdf=egdf_X, verbose=VERBOSE, flush=FLUSH)
+        is_homo_X = dh_X.fit()
+
+        dh_y = DataHomogeneity(gdf=egdf_y, verbose=VERBOSE, flush=FLUSH)
+        is_homo_y = dh_y.fit()
+
+        if not is_homo_X:
+            logger.warning("X is not homogeneous. Switching to S=1 for better results.")
+            logger.info("Fitting EGDF with S=1.")
+            egdf_X = EGDF(flush=FLUSH, verbose=VERBOSE, S=1)
+            egdf_X.fit(X)
+
+        if not is_homo_y:
+            logger.warning("y is not homogeneous. Switching to S=1 for better results.")
+            logger.info("Fitting EGDF with S=1.")
+            egdf_y = EGDF(flush=FLUSH, verbose=VERBOSE, S=1)
+            egdf_y.fit(y)
+
+        hc_X = np.mean(egdf_X.hi, axis=0)
+        hc_y = np.mean(egdf_y.hi, axis=0)
+
+    if case == 'j':
+        logger.info("Using Estimation Global Distribution Function (EGDF) for correlation computation.")
+        egdf_X = EGDF(flush=FLUSH, verbose=VERBOSE)
+        egdf_X.fit(X)
+
+        egdf_y = EGDF(flush=FLUSH, verbose=VERBOSE)
+        egdf_y.fit(y)
+
+        logger.info("Checking data homogeneity.")
+        dh_X = DataHomogeneity(gdf=egdf_X, verbose=VERBOSE, flush=FLUSH)
+        is_homo_X = dh_X.fit()
+
+        dh_y = DataHomogeneity(gdf=egdf_y, verbose=VERBOSE, flush=FLUSH)
+        is_homo_y = dh_y.fit()
+
+        if not is_homo_X:
+            logger.warning("X is not homogeneous. Switching to S=1 for better results.")
+        if not is_homo_y:
+            logger.warning("y is not homogeneous. Switching to S=1 for better results.")
+
+        logger.info("Using Quantification Global Distribution Function (QGDF) for correlation computation.")
+        qgdf_X = QGDF(flush=FLUSH, verbose=VERBOSE, S=1)
+        qgdf_X.fit(X)
+
+        qgdf_y = QGDF(flush=FLUSH, verbose=VERBOSE)
+        qgdf_y.fit(y)
+
+        hc_X = np.mean(qgdf_X.hj, axis=0)
+        hc_y = np.mean(qgdf_y.hj, axis=0)
+
+        hc_X = np.clip(hc_X, 1, 1e12)
+        hc_y = np.clip(hc_y, 1, 1e12)
+
+    def compute_correlation(hc_X: np.ndarray, hc_y: np.ndarray) -> float:
+        logger.info("Computing correlation.")
+        numerator = np.sum(hc_X * hc_y)
+        denominator = (np.sqrt(np.sum(hc_X**2)) * np.sqrt(np.sum(hc_y**2))) 
+        corr = numerator / denominator
+        if denominator == 0:
+            return np.nan
+        return corr
+
+    corr = compute_correlation(hc_X, hc_y)
+    logger.info("Correlation computed successfully.")
+    return corr

machinegnostics/metrics/cross_variance.py

@@ -0,0 +1,167 @@
+'''
+Gnostic Cross-Variance
+
+Author: Nirmal Parmar
+Machine Gnostics
+'''
+
+import numpy as np
+from machinegnostics.magcal import EGDF, QGDF, DataHomogeneity
+import logging
+from machinegnostics.magcal.util.logging import get_logger
+
+def cross_covariance(X: np.ndarray, y: np.ndarray, case: str = 'i', verbose: bool = False) -> float:
+    """
+    Calculate the Gnostic cross-covariance between a feature array X and a target array y.
+
+    Parameters:
+    ----------
+    X : np.ndarray
+        The feature data sample. Must be a 1D numpy array (single feature/column).
+        If X has more than one column, pass each column separately (e.g., X[:, i]).
+    y : np.ndarray
+        The target data sample. Must be a 1D numpy array without NaN or Inf values.
+    case : str, optional, default='i'
+        Specifies the type of geometry to use:
+        - 'i': Estimation geometry.
+        - 'j': Quantifying geometry.
+    verbose : bool, optional, default=False
+        If True, enables detailed logging for debugging purposes.
+
+    Returns:
+    -------
+    float
+        The Gnostic cross-covariance between the two data samples.
+
+    Examples:
+    ---------
+    Example 1: Compute cross-covariance for two simple datasets
+    >>> import numpy as np
+    >>> from machinegnostics.metrics import cross_covariance
+    >>> X = np.array([1, 2, 3, 4, 5])
+    >>> y = np.array([5, 4, 3, 2, 1])
+    >>> covar = cross_covariance(X, y, case='i', verbose=False)
+    >>> print(f"Cross-Covariance (case='i'): {covar}")
+
+    Example 2: For multi-column X
+    >>> X = np.array([[1, 10], [2, 20], [3, 30], [4, 40], [5, 50]])
+    >>> y = np.array([5, 4, 3, 2, 1])
+    >>> for i in range(X.shape[1]):
+    ...     covar = cross_covariance(X[:, i], y)
+    ...     print(f"Cross-Covariance for column {i}: {covar}")
+
+    Raises:
+    ------
+    ValueError
+        If the input arrays are not of the same length, are empty, contain NaN/Inf values,
+        or are not 1D numpy arrays. Also raised if `case` is not 'i' or 'j'.
+
+    Notes:
+    -----
+    - X must be a 1D numpy array (single column). For multi-column X, pass each column separately.
+    - y must be a 1D numpy array.
+    - 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.
+    - In cases where data homogeneity is not met, a warning is raised, and the scale
+      parameter is adjusted to improve results.
+    """
+    logger = get_logger('cross_covariance', level=logging.WARNING if not verbose else logging.INFO)
+    logger.info("Starting cross-covariance computation.")
+    # Validate inputs
+    if len(X) != len(y):
+        logger.error("Input arrays must have the same length.")
+        raise ValueError("Input arrays must have the same length.")
+    if len(X) == 0 or len(y) == 0:
+        logger.error("Input arrays must not be empty.")
+        raise ValueError("Input arrays must not be empty.")
+    if not isinstance(X, np.ndarray) or not isinstance(y, np.ndarray):
+        logger.error("Inputs must be numpy arrays.")
+        raise ValueError("Inputs must be numpy arrays.")
+    # flatten the arrays if they are not 1D
+    X = X.flatten()
+    y = y.flatten()
+    if X.ndim != 1 or y.ndim != 1:
+        logger.error("X and y must be 1D numpy arrays. For multi-column X, pass each column separately (e.g., X[:, i]).")
+        raise ValueError("X and y must be 1D numpy arrays. For multi-column X, pass each column separately (e.g., X[:, i]).")
+    # avoid inf and nan in data
+    if np.any(np.isnan(X)) or np.any(np.isnan(y)):
+        logger.error("Input arrays must not contain NaN values.")
+        raise ValueError("Input arrays must not contain NaN values.")
+    if np.any(np.isinf(X)) or np.any(np.isinf(y)):
+        logger.error("Input arrays must not contain Inf values.")
+        raise ValueError("Input arrays must not contain Inf values.")
+    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.")
+
+    # ...existing logic unchanged...
+    FLUSH = False
+    VERBOSE = False
+    
+    if case == 'i':
+        logger.info("Using Estimation Global Distribution Function (EGDF) for correlation computation.")
+        egdf_data_1 = EGDF(flush=FLUSH, verbose=VERBOSE)
+        egdf_data_1.fit(X)
+
+        egdf_data_2 = EGDF(flush=FLUSH, verbose=VERBOSE)
+        egdf_data_2.fit(y)
+
+        logger.info("Performing data homogeneity check.")
+        dh_data_1 = DataHomogeneity(gdf=egdf_data_1, verbose=VERBOSE, flush=FLUSH)
+        is_homo_data_1 = dh_data_1.fit()
+
+        dh_data_2 = DataHomogeneity(gdf=egdf_data_2, verbose=VERBOSE, flush=FLUSH)
+        is_homo_data_2 = dh_data_2.fit()
+
+        if not is_homo_data_1:
+            logger.warning("X is not homogeneous. Switching to S=1 for better results.")
+            logger.info("Fitting EGDF with S=1.")
+            egdf_data_1 = EGDF(flush=FLUSH, verbose=VERBOSE, S=1)
+            egdf_data_1.fit(X)
+
+        if not is_homo_data_2:
+            logger.warning("y is not homogeneous. Switching to S=1 for better results.")
+            logger.info("Fitting EGDF with S=1.")
+            egdf_data_2 = EGDF(flush=FLUSH, verbose=VERBOSE, S=1)
+            egdf_data_2.fit(y)
+
+        hc_data_1 = np.mean(egdf_data_1.hi, axis=0)
+        hc_data_2 = np.mean(egdf_data_2.hi, axis=0)
+
+    if case == 'j':
+        logger.info("Using Estimation Global Distribution Function (EGDF) for correlation computation.")
+        egdf_data_1 = EGDF(flush=FLUSH, verbose=VERBOSE)
+        egdf_data_1.fit(X)
+
+        egdf_data_2 = EGDF(flush=FLUSH, verbose=VERBOSE)
+        egdf_data_2.fit(y)
+
+        logger.info("Checking data homogeneity.")
+        dh_data_1 = DataHomogeneity(gdf=egdf_data_1, verbose=VERBOSE, flush=FLUSH)
+        is_homo_data_1 = dh_data_1.fit()
+
+        dh_data_2 = DataHomogeneity(gdf=egdf_data_2, verbose=VERBOSE, flush=FLUSH)
+        is_homo_data_2 = dh_data_2.fit()
+
+        if not is_homo_data_1:
+            logger.warning("X is not homogeneous. Switching to S=1 for better results.")
+        if not is_homo_data_2:
+            logger.warning("y is not homogeneous. Switching to S=1 for better results.")
+
+        logger.info("Using Quantification Global Distribution Function (QGDF) for correlation computation.")
+        qgdf_data_1 = QGDF(flush=FLUSH, verbose=VERBOSE, S=1)
+        qgdf_data_1.fit(X)
+
+        qgdf_data_2 = QGDF(flush=FLUSH, verbose=VERBOSE)
+        qgdf_data_2.fit(y)
+
+        hc_data_1 = np.mean(qgdf_data_1.hj, axis=0)
+        hc_data_2 = np.mean(qgdf_data_2.hj, axis=0)
+
+        hc_data_1 = np.clip(hc_data_1, 1, 1e12)
+        hc_data_2 = np.clip(hc_data_2, 1, 1e12)
+
+    cross_covar = np.mean(hc_data_1 * hc_data_2)
+    logger.info(f"Cross-covariance calculated successfully.")
+    return cross_covar

machinegnostics/metrics/divi.py

@@ -0,0 +1,82 @@
+'''
+ManGo - Machine Gnostics Library
+Copyright (C) 2025  ManGo Team
+
+Author: Nirmal Parmar
+'''
+from machinegnostics.magcal.util.logging import get_logger
+import logging
+import numpy as np
+from machinegnostics.magcal.criteria_eval import CriteriaEvaluator
+
+def divI(y: np.ndarray, y_fit: np.ndarray,  verbose: bool = False) -> float:
+    """
+    Compute the Divergence Information (DivI) for evaluating the fit between observed data and model predictions.
+
+    The DivI is a statistical metric that measures the divergence between the distributions of the observed and fitted values
+    using gnostic characteristics. It is particularly useful for assessing the quality of model fits in various applications.
+
+    Parameters
+    ----------
+    y : np.ndarray
+        The observed data (ground truth). Must be a 1D array of numerical values.
+    y_fit : np.ndarray
+        The fitted data (model predictions). Must be a 1D array of the same shape as `y`.
+    verbose : bool, optional
+        If True, enables detailed logging for debugging purposes. Default is False.
+
+    Returns
+    -------
+    float
+        The computed Divergence Information (DivI) value. 
+
+    Raises
+    ------
+    ValueError
+        If `y` and `y_fit` do not have the same shape.
+    ValueError
+        If `w` is provided and does not have the same shape as `y`.
+    ValueError
+        If `y` or `y_fit` are not 1D arrays.
+
+    Notes
+    -----
+    - The DivI is calculated using gnostic characteristics, which provide a robust way to measure divergence between distributions.
+    
+    References
+    ----------
+    - Kovanic P., Humber M.B (2015) The Economics of Information - Mathematical Gnostics for Data Analysis, Chapter 19.3.4
+
+    Example
+    -------
+    >>> import numpy as np
+    >>> from src.metrics.divi import divI
+    >>> y = np.array([
+    ...     1.0, 2.0, 3.0, 4.0
+    ... ])
+    >>> y_fit = np.array([
+    ...     1.1, 1.9, 3.2, 3.8
+    ... ])
+    >>> divI(y, y_fit)
+    """
+    logger = get_logger('DivI', level=logging.WARNING if not verbose else logging.INFO)
+    logger.info("Starting DivI calculation.")
+    # Ensure y and y_fit are 1D arrays
+    if y.ndim != 1 or y_fit.ndim != 1:
+        logger.error("Both y and y_fit must be 1D arrays.")
+        raise ValueError("Both y and y_fit must be 1D arrays.")
+    
+    # Ensure y and y_fit have the same shape
+    if y.shape != y_fit.shape:
+        logger.error("y and y_fit must have the same shape.")
+        raise ValueError("y and y_fit must have the same shape.")
+    
+    # Convert to numpy arrays and flatten
+    y = np.asarray(y).flatten()
+    y_fit = np.asarray(y_fit).flatten()
+    
+    # Compute the Divergence Information (DivI)
+    evaluator = CriteriaEvaluator(y, y_fit, verbose=verbose)
+    divI_value = evaluator._divI()
+    logger.info(f"Divergence Information (DivI) calculation completed.")
+    return divI_value

machinegnostics/metrics/evalmet.py

@@ -0,0 +1,109 @@
+'''
+ManGo - Machine Gnostics Library
+Copyright (C) 2025  ManGo Team
+
+Author: Nirmal Parmar
+'''
+from machinegnostics.magcal.util.logging import get_logger
+import logging
+import numpy as np
+from machinegnostics.magcal.criteria_eval import CriteriaEvaluator
+
+def evalMet(y: np.ndarray, y_fit: np.ndarray, w: np.ndarray = None, verbose: bool = False) -> float:
+    """
+    Compute the Evaluation Metric (EvalMet) for evaluating the fit between observed data and model predictions.
+
+    The EvalMet is a composite metric that combines Robust R-squared (RobR2), Geometric Mean of Model Fit Error (GMMFE),
+    and Divergence Information (DivI) to provide a comprehensive assessment of model performance.
+
+    Parameters
+    ----------
+    y : np.ndarray
+        The observed data (ground truth). Must be a 1D array of numerical values.
+    y_fit : np.ndarray
+        The fitted data (model predictions). Must be a 1D array of the same shape as `y`.
+    w : np.ndarray, optional
+        Weights for the data points. If not provided, an array of ones is used.
+    verbose : bool, optional
+        If True, enables detailed logging for debugging purposes. Default is False.
+
+    Returns
+    -------
+    float
+        The computed Evaluation Metric (EvalMet) value. 
+
+    Raises
+    ------
+    ValueError
+        If `y` and `y_fit` do not have the same shape.
+    ValueError
+        If `w` is provided and does not have the same shape as `y`.
+    ValueError
+        If `y` or `y_fit` are not 1D arrays.
+
+    Notes
+    -----
+    - The EvalMet is calculated as:
+      EvalMet = RobR2 / (GMMFE . DivI)
+      where:
+        - RobR2 = Robust R-squared value
+        - GMMFE = Geometric Mean of Model Fit Error
+        - DivI = Divergence Information
+
+    References
+    ----------
+    - Kovanic P., Humber M.B (2015) The Economics of Information - Mathematical Gnostics for Data Analysis, Chapter 19.3.4
+
+    Example
+    -------
+    >>> from mango.metrics.evalmet import evalMet
+    >>> import numpy as np
+    >>> y = np.array([
+    ...     1.0, 2.0, 3.0, 4.0
+    ... ])
+    >>> y_fit = np.array([
+    ...     1.1, 1.9, 3.2, 3.8
+    ... ])
+    >>> evalMet(y, y_fit, weights)
+    """
+    logger = get_logger('EvalMet', level=logging.WARNING if not verbose else logging.INFO)
+    logger.info("Starting EvalMet calculation.")
+    # Ensure y and y_fit are 1D arrays
+    if y.ndim != 1 or y_fit.ndim != 1:
+        logger.error("Both y and y_fit must be 1D arrays.")
+        raise ValueError("Both y and y_fit must be 1D arrays.")
+    
+    # Ensure y and y_fit have the same shape
+    if y.shape != y_fit.shape:
+        logger.error("y and y_fit must have the same shape.")
+        raise ValueError("y and y_fit must have the same shape.")
+    
+    # empty check
+    if y.size == 0 or y_fit.size == 0:
+        logger.error("y and y_fit must not be empty.")
+        raise ValueError("y and y_fit must not be empty.")
+    if np.any(np.isnan(y)) or np.any(np.isnan(y_fit)):
+        logger.error("y and y_fit must not contain NaN values.")
+        raise ValueError("y and y_fit must not contain NaN values.")
+    if np.any(np.isinf(y)) or np.any(np.isinf(y_fit)):
+        logger.error("y and y_fit must not contain Inf values.")
+        raise ValueError("y and y_fit must not contain Inf values.")
+    
+    # If weights are not provided, use an array of ones
+    if w is None:
+        w = np.ones_like(y)
+    
+    # Ensure weights have the same shape as y
+    if w.shape != y.shape:
+        logger.error("Weights must have the same shape as y.")
+        raise ValueError("Weights must have the same shape as y.")
+    
+    # Convert to numpy arrays and flatten
+    y = np.asarray(y).flatten()
+    y_fit = np.asarray(y_fit).flatten()
+    
+    # Compute the Evaluation Metric (EvalMet)
+    evaluator = CriteriaEvaluator(y, y_fit, w, verbose=verbose)
+    evalmet = evaluator._evalmet()
+    logger.info(f"EvalMet calculation completed.")
+    return evalmet

machinegnostics/metrics/f1_score.py

@@ -0,0 +1,128 @@
+import numpy as np
+import pandas as pd
+from machinegnostics.magcal.util.logging import get_logger
+import logging
+
+def f1_score(y_true:np.ndarray | pd.Series | list,
+             y_pred:np.ndarray | pd.Series | list,
+             average='binary', 
+             labels=None,
+             verbose:bool=False) -> float | np.ndarray:
+    """
+    Computes the F1 score for classification tasks.
+
+    The F1 score is the harmonic mean of precision and recall.
+    Supports binary and multiclass classification.
+
+    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.
+
+    average : {'binary', 'micro', 'macro', 'weighted', None}, default='binary'
+        - 'binary': Only report results for the class specified by `pos_label` (default for binary).
+        - 'micro': Calculate metrics globally by counting the total true positives, false negatives and false positives.
+        - 'macro': Calculate metrics for each label, and find their unweighted mean.
+        - 'weighted': Calculate metrics for each label, and find their average weighted by support (the number of true instances for each label).
+        - None: Return the F1 score for each class.
+
+    labels : array-like, default=None
+        List of labels to include. If None, uses sorted unique labels from y_true and y_pred.
+
+    verbose : bool, optional
+        If True, enables detailed logging for debugging purposes. Default is False.
+    Returns
+    -------
+    f1 : float or array of floats
+        F1 score(s). Float if average is not None, array otherwise.
+
+    Examples
+    --------
+    >>> y_true = [0, 1, 2, 2, 0]
+    >>> y_pred = [0, 0, 2, 2, 0]
+    >>> f1_score(y_true, y_pred, average='macro')
+    0.7777777777777777
+
+    >>> import pandas as pd
+    >>> df = pd.DataFrame({'true': [1, 0, 1], 'pred': [1, 1, 1]})
+    >>> f1_score(df['true'], df['pred'], average='binary')
+    0.8
+    """
+    logger = get_logger('f1_score', level=logging.WARNING if not verbose else logging.INFO)
+    logger.info("Calculating F1 Score...")
+    # 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:
+        logger.error("Shape mismatch between y_true and y_pred.")
+        raise ValueError("Shape of y_true and y_pred must be the same.")
+    if y_true.size == 0:
+        logger.error("Empty input arrays.")
+        raise ValueError("y_true and y_pred must not be empty.")
+    # inf and nan check
+    if np.any(np.isnan(y_true)) or np.any(np.isnan(y_pred)):
+        logger.error("Input contains 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("Input contains Inf values.")
+        raise ValueError("y_true and y_pred must not contain Inf values.")
+
+    # Get unique labels
+    if labels is None:
+        labels = np.unique(np.concatenate([y_true, y_pred]))
+    else:
+        labels = np.asarray(labels)
+
+    precisions = []
+    recalls = []
+    for label in labels:
+        tp = np.sum((y_pred == label) & (y_true == label))
+        fp = np.sum((y_pred == label) & (y_true != label))
+        fn = np.sum((y_pred != label) & (y_true == label))
+        precision = tp / (tp + fp) if (tp + fp) > 0 else 0.0
+        recall = tp / (tp + fn) if (tp + fn) > 0 else 0.0
+        precisions.append(precision)
+        recalls.append(recall)
+
+    precisions = np.array(precisions)
+    recalls = np.array(recalls)
+    f1s = np.where((precisions + recalls) > 0, 2 * precisions * recalls / (precisions + recalls), 0.0)
+
+    logger.info("F1 Score calculation completed.")
+    if average == 'binary':
+        if len(labels) != 2:
+            logger.error("Binary average is only supported for binary classification with 2 classes.")
+            raise ValueError("Binary average is only supported for binary classification with 2 classes.")
+        return f1s[1]
+    elif average == 'micro':
+        tp = sum(np.sum((y_pred == label) & (y_true == label)) for label in labels)
+        fp = sum(np.sum((y_pred == label) & (y_true != label)) for label in labels)
+        fn = sum(np.sum((y_pred != label) & (y_true == label)) for label in labels)
+        precision = tp / (tp + fp) if (tp + fp) > 0 else 0.0
+        recall = tp / (tp + fn) if (tp + fn) > 0 else 0.0
+        return 2 * precision * recall / (precision + recall) if (precision + recall) > 0 else 0.0
+    elif average == 'macro':
+        return np.mean(f1s)
+    elif average == 'weighted':
+        support = np.array([np.sum(y_true == label) for label in labels])
+        return np.average(f1s, weights=support)
+    elif average is None:
+        return f1s
+    else:
+        logger.error(f"Unknown average type: {average}")
+        raise ValueError(f"Unknown average type: {average}")