machinegnostics 0.0.1__py3-none-any.whl

machinegnostics/metrics/gmmfe.py

@@ -0,0 +1,108 @@
+'''
+ManGo - Machine Gnostics Library
+Copyright (C) 2025  ManGo Team
+
+Author: Nirmal Parmar
+'''
+
+import numpy as np
+from machinegnostics.magcal.criteria_eval import CriteriaEvaluator
+from machinegnostics.magcal.util.logging import get_logger
+import logging
+
+def gmmfe(y: np.ndarray, y_fit: np.ndarray, verbose: bool = False) -> float:
+    """
+    Compute the Geometric Mean of Model Fit Error (GMMFE) for evaluating the fit between observed data and model predictions.
+
+    The GMMFE is a statistical metric that quantifies the average relative error between the observed and fitted values 
+    on a logarithmic scale. It is particularly useful for datasets with a wide range of values or when the data is 
+    multiplicative in nature.
+
+    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 of the computation process. Default is False.
+
+    Returns
+    -------
+    float
+        The computed Geometric Mean of Model Fit Error (GMMFE) 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 GMMFE is calculated using the formula:
+      GMMFE = exp(Σ(w_i * log(e_i)) / Σ(w_i))
+      where:
+        - e_i = |y_i - y_fit_i| / |y_i| (relative error)
+        - w_i = weights for each data point
+      This formula computes the weighted geometric mean of the relative errors.
+
+    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.gmmfe import gmmfe
+    >>> y = np.array([
+    ...     1.0, 2.0, 3.0, 4.0
+    ... ])
+    >>> y_fit = np.array([
+    ...     1.1, 1.9, 3.2, 3.8
+    ... ])
+    >>> gmmfe(y, y_fit)
+    0.06666666666666667
+    """
+    logger = get_logger('gmmfe', level=logging.WARNING if not verbose else logging.INFO)
+    logger.info("Calculating GMMFE...")
+
+    # validate input types
+    if not isinstance(y, (np.ndarray,)):
+        logger.error("Invalid input type for y.")
+        raise ValueError("y must be a numpy array.")
+    if not isinstance(y_fit, (np.ndarray,)):
+        logger.error("Invalid input type for y_fit.")
+        raise ValueError("y_fit must be a numpy array.")
+    if y.ndim != 1 and y_fit.ndim != 1:
+        logger.error("Invalid input dimensions.")
+        raise ValueError("y and y_fit must be 1D arrays.")
+    if y.shape != y_fit.shape:
+        logger.error("Shape mismatch.")
+        raise ValueError("y and y_fit must have the same shape.")
+    if y.size == 0:
+        logger.error("Empty array.")
+        raise ValueError("y and y_fit must not be empty.")
+    if y.shape != y_fit.shape:
+        logger.error("Shape mismatch.")
+        raise ValueError("y and y_fit must have the same shape.")
+    # inf and nan check
+    if np.any(np.isnan(y)) or np.any(np.isnan(y_fit)):
+        logger.error("Input contains 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("Input contains Inf values.")
+        raise ValueError("y and y_fit must not contain Inf values.")
+    
+    # Convert to numpy arrays and flatten
+    y = np.asarray(y).flatten()
+    y_fit = np.asarray(y_fit).flatten()
+            
+    # generate the GMMFE value
+    ce = CriteriaEvaluator(y, y_fit, verbose=verbose)
+    gmmfe_value = ce._gmmfe()    
+    logger.info("GMMFE calculation completed.")
+    return gmmfe_value

machinegnostics/metrics/hc.py

@@ -0,0 +1,141 @@
+'''
+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.characteristics import GnosticsCharacteristics
+
+def hc(y_true: np.ndarray, y_pred: np.ndarray, case: str = 'i', verbose: bool = False) -> float:
+    """
+    Calculate the Gnostic Characteristics (Hc) metric of the data sample.
+
+    i  - for estimating gnostic relevance
+        For case 'i': Range [0, 1]. Close to one indicates less relevance
+    
+    j  - for estimating gnostic irrelevance
+        For case 'j': Range [0, ∞) (measures strength of relationship). Close to 1 indicates less irrelevance.
+
+    The HC metric is used to evaluate the performance of a model by comparing
+    the predicted values with the true values's relevance or irrelevance.
+    It is calculated as the sum of the characteristics of the model. For standard comparison, irrelevances are calculated with S=1.
+
+    Parameters
+    ----------
+    y_true : array-like
+        True values.
+    y_pred : array-like
+        Predicted values.
+    case : str, optional
+        Case to be used for calculation. Options are 'i' or 'j'. Default is 'i'.
+    verbose : bool, optional
+        If True, enables detailed logging for debugging purposes. Default is False.
+
+    Returns
+    -------
+    float
+        The calculated HC value.
+
+    Example
+    -------
+    >>> y_true = [1, 2, 3]
+    >>> y_pred = [1, 2, 3]
+    >>> from mango.metrics import hc
+    >>> hc_value = hc(y_true, y_pred, case='i')
+    >>> print(hc_value)
+    """
+    logger = get_logger('Hc', level=logging.WARNING if not verbose else logging.INFO)
+    logger.info("Starting HC calculation.")
+
+    # Validate input types
+    if not isinstance(y_true, (list, tuple, np.ndarray)):
+        logger.error("Invalid input type for y_true.")
+        raise TypeError("y_true must be array-like (list, tuple, or numpy array).")
+    if not isinstance(y_pred, (list, tuple, np.ndarray)):
+        logger.error("Invalid input type for y_pred.")
+        raise TypeError("y_pred must be array-like (list, tuple, or numpy array).")
+    if case not in ['i', 'j']:
+        logger.error("Invalid case value.")
+        raise ValueError("case must be either 'i' or 'j'.")
+    # Validate input dimensions
+    if np.ndim(y_true) > 1:
+        logger.error("y_true must be a 1D array.")
+        raise ValueError("y_true must be a 1D array.")
+    if np.ndim(y_pred) > 1:
+        logger.error("y_pred must be a 1D array.")
+        raise ValueError("y_pred must be a 1D array.")
+    # Check for empty arrays
+    if len(y_true) == 0:
+        logger.error("y_true and y_pred must not be empty.")
+        raise ValueError("y_true and y_pred must not be empty.")
+    if len(y_pred) == 0:
+        logger.error("y_true and y_pred must not be empty.")
+        raise ValueError("y_true and y_pred must not be empty.")
+    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.")  
+    # Convert to numpy arrays and flatten if necessary
+    if isinstance(y_true, (list, tuple)):
+        y_true = np.array(y_true)
+    if isinstance(y_pred, (list, tuple)):
+        y_pred = np.array(y_pred)
+    if isinstance(y_true, np.ndarray) and y_true.ndim > 1:
+        y_true = y_true.ravel()
+    if isinstance(y_pred, np.ndarray) and y_pred.ndim > 1:
+        y_pred = y_pred.ravel()
+    # Check for shape mismatch
+    if y_true.shape != y_pred.shape:
+        logger.error("y_true and y_pred must have the same shape.")
+        raise ValueError("y_true and y_pred must have the same shape.")
+    if len(y_true) == 0:
+        logger.error("y_true and y_pred must not be empty.")
+        raise ValueError("y_true and y_pred must not be empty.")
+    if len(y_pred) == 0:
+        logger.error("y_true and y_pred must not be empty.")
+        raise ValueError("y_true and y_pred must not be empty.")
+    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.")
+    
+    # Convert to numpy arrays and flatten
+    y_true = np.asarray(y_true).flatten()
+    y_pred = np.asarray(y_pred).flatten()
+
+    # Calculate the ratio R = Z / Z0
+    R = y_true / y_pred
+
+    # Create an instance of GnosticsCharacteristics
+    logger.info("Creating GnosticsCharacteristics instance.")
+    gnostics = GnosticsCharacteristics(R=R)
+
+    # Calculate q and q1
+    logger.info("Calculating q and q1.")
+    q, q1 = gnostics._get_q_q1()
+
+    # Calculate fi, fj, hi, hj based on the case
+    if case == 'i':
+        hc = gnostics._hi(q, q1)
+    
+    elif case == 'j':
+        hc = gnostics._hj(q, q1)
+    
+    else:
+        logger.error("Invalid case. Use 'i' or 'j'.")
+        raise ValueError("Invalid case. Use 'i' or 'j'.")
+
+    hcsr = np.sum(hc**2)
+
+    # normalize the result
+    hcsr = hcsr / len(y_true)
+    logger.info(f"Gnostic irrelevance Hc calculation completed")
+    return hcsr

machinegnostics/metrics/mae.py

@@ -0,0 +1,72 @@
+import numpy as np
+from machinegnostics.magcal.util.logging import get_logger
+import logging
+from machinegnostics.metrics.mean import mean
+
+def mean_absolute_error(y_true: np.ndarray, y_pred:np.ndarray, verbose: bool = False) -> float:
+    """
+    Computes the mean absolute error (MAE).
+
+    Parameters
+    ----------
+    y_true : array-like
+        True values (targets).
+    y_pred : array-like
+        Predicted values.
+    verbose : bool, optional
+        If True, enables detailed logging. Default is False.
+
+    Returns
+    -------
+    float
+        Average absolute difference between actual and predicted values.
+
+    Raises
+    ------
+    TypeError
+        If y_true or y_pred are not array-like.
+    ValueError
+        If inputs have mismatched shapes or are empty.
+    """
+    logger = get_logger('MAE', level=logging.WARNING if not verbose else logging.INFO)
+    logger.info("Calculating Mean Absolute Error...")
+
+    # Validate input types
+    if not isinstance(y_true, (list, tuple, np.ndarray)):
+        logger.error("Invalid input type for y_true.")
+        raise TypeError("y_true must be array-like (list, tuple, or numpy array).")
+    if not isinstance(y_pred, (list, tuple, np.ndarray)):
+        logger.error("Invalid input type for y_pred.")
+        raise TypeError("y_pred must be array-like (list, tuple, or numpy array).")
+    if isinstance(y_true, (list, tuple)):
+        y_true = np.array(y_true)
+    if isinstance(y_pred, (list, tuple)):
+        y_pred = np.array(y_pred)
+    if isinstance(y_true, np.ndarray) and y_true.ndim > 1:
+        y_true = y_true.ravel()
+    if isinstance(y_pred, np.ndarray) and y_pred.ndim > 1:
+        y_pred = y_pred.ravel()
+    # Check for shape mismatch
+    if y_true.shape != y_pred.shape:
+        logger.error(f"Shape mismatch: y_true shape {y_true.shape} != y_pred shape {y_pred.shape}")
+        raise ValueError(f"Shape mismatch: y_true shape {y_true.shape} != y_pred shape {y_pred.shape}")
+    # Check for empty arrays
+    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.")
+    if y_pred.size == 0:
+        logger.error("y_true and y_pred must not be empty.")
+        raise ValueError("y_true and y_pred must not be empty.")
+    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.")
+
+    # Convert to numpy arrays and flatten
+    y_true = np.asarray(y_true).flatten()
+    y_pred = np.asarray(y_pred).flatten()
+
+    # Compute MAE
+    mae = float(mean(np.abs(y_true - y_pred)))
+
+    logger.info(f"Mean Absolute Error (MAE) calculated.")
+    return mae

machinegnostics/metrics/mean.py

@@ -0,0 +1,117 @@
+'''
+calculate gnostic mean of given sample
+
+method: mean()
+LEL local estimate of location
+
+Authors: Nirmal Parmar
+Machine Gnostics
+'''
+import logging
+from machinegnostics.magcal.util.logging import get_logger
+import numpy as np
+from machinegnostics.magcal import ELDF, QLDF
+from typing import Union
+
+def mean(data: np.ndarray, 
+         S: Union[float, str] = 1, 
+         case: str = 'i',
+         z0_optimize: bool = True, 
+         data_form: str = 'a',
+         tolerance: float = 1e-6,
+         verbose: bool = False) -> float:
+    """
+    Calculate the gnostic mean of the given data.
+
+    The Gnostic mean metric is based on the principles of gnostic theory, which
+    provides robust estimates of data relationships. This metric leverages the concepts
+    of estimating irrelevances and fidelities, and quantifying irrelevances and fidelities, which are robust measures of data uncertainty. These irrelevances are aggregated differently.
+
+    Parameters:
+    -----------
+    data : np.ndarray
+        Input data array.
+    S : float, optional
+        Scaling parameter for ELDF. Default is 1.
+    case : str, optional
+        Case for irrelevance calculation ('i' or 'j'). Default is 'i'. 
+        'i' for estimating irrelevance, 'j' for quantifying irrelevance.
+    z0_optimize : bool, optional
+        Whether to optimize z0 in ELDF. Default is True.
+    data_form : str, optional
+        Data form for ELDF. Default is 'a'. 'a' for additive, 'm' for multiplicative.
+    tolerance : float, optional
+        Tolerance for ELDF fitting. Default is 1e-6.
+    verbose : bool, optional
+        If True, enables detailed logging for debugging purposes.
+
+    Returns:
+    --------
+    float
+        Gnostic mean of the data.
+
+    Example:
+    --------
+    >>> import machinegnostics as mg
+    >>> import numpy as np
+    >>> data = np.array([1, 2, 3, 4, 5])
+    >>> mg.mean(data)
+    """
+    logger = get_logger('mean', level=logging.WARNING if not verbose else logging.INFO)
+    logger.info("Calculating gnostic mean...")
+
+    # flatten data
+    data = np.asarray(data).flatten()
+    # Validate input
+    if not isinstance(data, np.ndarray):
+        logger.error("Input must be a numpy array.")
+        raise TypeError("Input must be a numpy array.")
+    if data.ndim != 1:
+        logger.error("Input data must be a one-dimensional array.")
+        raise ValueError("Input data must be a one-dimensional array.")
+    if len(data) == 0:
+        logger.error("Input data array is empty.")
+        raise ValueError("Input data array is empty.")
+    if np.any(np.isnan(data)):
+        logger.error("Input data contains NaN values.")
+        raise ValueError("Input data contains NaN values.")
+    if np.any(np.isinf(data)):
+        logger.error("Input data contains Inf values.")
+        raise ValueError("Input data contains Inf values.")
+    # Check for valid case
+    if case not in ['i', 'j']:
+        logger.error("Case must be 'i' for estimating variance or 'j' for quantifying variance.")
+        raise ValueError("Case must be 'i' for estimating variance or 'j' for quantifying variance.")
+
+    # arg validation
+    if isinstance(S, str):
+        if S != 'auto':
+            logger.error("S must be a float or 'auto'.")
+            raise ValueError("S must be a float or 'auto'.")
+    elif not isinstance(S, (int, float)):
+        logger.error("S must be a float or 'auto'.")
+        raise TypeError("S must be a float or 'auto'.")
+    # S proper value [0,2] suggested
+    if isinstance(S, (int)):
+        if S < 0 or S > 2:
+            logger.warning("S must be in the range [0, 2].")
+    # Check for valid data_form
+    if data_form not in ['a', 'm']:
+        logger.error("data_form must be 'a' for additive or 'm' for multiplicative.")
+        raise ValueError("data_form must be 'a' for additive or 'm' for multiplicative.")
+    
+    if case == 'i':
+        logger.info("Using estimating geometry for mean calculation.")
+        # Compute eldf
+        eldf = ELDF(homogeneous=True, S=S, z0_optimize=z0_optimize, tolerance=tolerance, data_form=data_form, wedf=False)
+        eldf.fit(data, plot=False)
+        mean_value = eldf.z0
+    else:
+        logger.info("Using quantifying geometry for mean calculation.")
+        # Compute qldf
+        qldf = QLDF(homogeneous=True, S=S, z0_optimize=z0_optimize, tolerance=tolerance, data_form=data_form, wedf=False)
+        qldf.fit(data, plot=False)
+        mean_value = qldf.z0
+    logger.info(f"Gnostic mean calculated.")
+
+    return float(mean_value)

machinegnostics/metrics/median.py

@@ -0,0 +1,122 @@
+'''
+To calculate gnostic median
+
+Author: Nirmal Parmar
+Machine Gnostics
+'''
+
+import numpy as np
+from machinegnostics.magcal import EGDF, QGDF
+from machinegnostics.magcal.util.logging import get_logger
+import logging
+
+def median(data: np.ndarray,
+            case: str = 'i',
+            S: float = 1, 
+            z0_optimize: bool = True, 
+            data_form: str = 'a',
+            tolerance: float = 1e-6,
+            verbose: bool = False) -> float:
+    """
+    Calculate the median of a dataset.
+
+    The Gnostic median metric is based on the principles of gnostic theory, which
+    provides robust estimates of data relationships. This metric leverages the concepts
+    of estimating irrelevances and fidelities, and quantifying irrelevances and fidelities, which are robust measures of data uncertainty. These irrelevances are aggregated differently.
+
+    Parameters:
+    -----------
+    data : np.ndarray
+        Input data array.
+    case : str, optional
+        Case for irrelevance calculation ('i' or 'j'). Default is 'i'. 
+        'i' for estimating irrelevance, 'j' for quantifying irrelevance.
+    S : float, optional
+        Scaling parameter for ELDF. Default is 1.
+    z0_optimize : bool, optional
+        Whether to optimize z0 in ELDF. Default is True.
+    data_form : str, optional
+        Data form for ELDF. Default is 'a'. 'a' for additive, 'm' for multiplicative.
+    tolerance : float, optional
+        Tolerance for ELDF fitting. Default is 1e-6.
+    verbose : bool, optional
+        If True, enables detailed logging for debugging purposes. Default is False.
+
+    Returns:
+    --------
+    float
+        Median of the data.
+
+    Example:
+    --------
+    >>> import machinegnostics as mg
+    >>> import numpy as np
+    >>> data = np.array([1, 2, 3, 4, 5])
+    >>> mg.median(data)
+    3.0
+
+    """
+    logger = get_logger('median', level=logging.WARNING if not verbose else logging.INFO)
+    logger.info("Starting median calculation.")
+
+    # Validate input
+    if not isinstance(data, np.ndarray):
+        logger.error("Input must be a numpy array.")
+        raise TypeError("Input must be a numpy array.")
+    if data.ndim != 1:
+        logger.error("Input data must be a one-dimensional array.")
+        raise ValueError("Input data must be a one-dimensional array.")
+    if len(data) == 0:
+        logger.error("Input data array is empty.")
+        raise ValueError("Input data array is empty.")
+    if np.any(np.isnan(data)):
+        logger.error("Input data contains NaN values.")
+        raise ValueError("Input data contains NaN values.")
+    if np.any(np.isinf(data)):
+        logger.error("Input data contains Inf values.")
+        raise ValueError("Input data contains Inf values.")
+    # Check for valid case
+    if case not in ['i', 'j']:
+        logger.error("Case must be 'i' for estimating variance or 'j' for quantifying variance.")
+        raise ValueError("Case must be 'i' for estimating variance or 'j' for quantifying variance.")
+    
+    # Validate input
+    if not isinstance(data, np.ndarray):
+        raise TypeError("Input must be a numpy array.")
+    if data.ndim != 1:
+        raise ValueError("Input data must be a one-dimensional array.")
+    if len(data) == 0:
+        raise ValueError("Input data array is empty.")
+    
+
+    # arg validation
+    if isinstance(S, str):
+        if S != 'auto':
+            logger.error("S must be a float or 'auto'.")
+            raise ValueError("S must be a float or 'auto'.")
+    elif not isinstance(S, (int, float)):
+        logger.error("S must be a float or 'auto'.")
+        raise TypeError("S must be a float or 'auto'.")
+    # S proper value [0,2] suggested
+    if isinstance(S, (int)):
+        if S < 0 or S > 2:
+            logger.warning("S must be in the range [0, 2].")
+    # Check for valid data_form
+    if data_form not in ['a', 'm']:
+        logger.error("data_form must be 'a' for additive or 'm' for multiplicative.")
+        raise ValueError("data_form must be 'a' for additive or 'm' for multiplicative.")
+    
+    if case == 'i':
+        logger.info("Using estimating geometry for median calculation.")
+        # egdf
+        egdf = EGDF(homogeneous=True, S=S, z0_optimize=z0_optimize, tolerance=tolerance, data_form=data_form)
+        egdf.fit(data, plot=False)
+        median_value = egdf.z0
+    else:
+        logger.info("Using quantifying geometry for median calculation.")
+        # qgdf
+        qgdf = QGDF(homogeneous=True, S=S, z0_optimize=z0_optimize, tolerance=tolerance, data_form=data_form)
+        qgdf.fit(data, plot=False)
+        median_value = qgdf.z0
+        logger.info("Gnostic median calculated.")
+    return float(median_value)