machinegnostics 0.0.1__py3-none-any.whl

machinegnostics/metrics/mg_r2.py

@@ -0,0 +1,167 @@
+'''
+ManGo - Machine Gnostics Library
+Copyright (C) 2025  ManGo Team
+
+This work is licensed under the terms of the GNU General Public License version 3.0.
+
+Author: Nirmal Parmar
+
+
+'''
+
+from machinegnostics.magcal.util.logging import get_logger
+import logging
+import numpy as np
+
+class EvaluationMetrics:
+    """
+    Class to calculate evaluation metrics for robust regression models.
+
+    This class provides methods to calculate various (gnostic) evaluation metrics for robust regression models, including:
+    - RobR²: Weighted R-squared, a robust version of the coefficient of determination.
+    - GMMFE: Geometric Mean of Multiplicative Fitting Errors, a measure of the geometric mean of fitting errors.
+    - DivI: Divergence of Information, a metric to quantify the divergence between true and predicted values.
+    - EvalMet: An overall evaluation metric combining RobR², GMMFE, and DivI.
+
+    Attributes:
+        y_true (np.ndarray): True target values.
+        y_pred (np.ndarray): Predicted target values.
+        weights (np.ndarray): Weights for each observation. Defaults to an array of ones if not provided.
+        N (int): Number of observations.
+        logger (logging.Logger): Logger instance for logging messages.
+
+    Methods:
+        calculate_rob_r2():
+            Calculate the Weighted R-squared (RobR²).
+        calculate_gmmfe():
+            Calculate the Geometric Mean of Multiplicative Fitting Errors (GMMFE).
+        calculate_divi():
+            Calculate the Divergence of Information (DivI).
+        calculate_evalmet():
+            Calculate the overall evaluation metric (EvalMet).
+        generate_report():
+            Generate a complete evaluation report containing all metrics.
+    
+    Example:
+        
+        >>> from machinegnostics.metrics import EvaluationMetrics
+        >>> y_true = np.array([3, -0.5, 2, 7])
+        >>> y_pred = np.array([2.5, 0.0, 2, 8])
+        >>> evaluator = EvaluationMetrics(y_true, y_pred, verbose=True)
+        >>> report = evaluator.generate_report()
+        >>> print(report)
+    """
+    
+    def __init__(self, 
+                 y_true: np.ndarray, 
+                 y_pred: np.ndarray, 
+                 weights=None,
+                 verbose: bool = False):
+        """
+        Initialize the evaluation metrics calculator.
+
+        Args:
+            y_true (np.ndarray): True target values.
+            y_pred (np.ndarray): Predicted target values.
+            weights (np.ndarray, optional): Weights for each observation. Defaults to None.
+            verbose (bool, optional): If True, enables detailed logging. Defaults to False.
+        """
+        self.logger = get_logger('EvaluationMetrics', level=logging.WARNING if not verbose else logging.INFO)
+        self.logger.info("Initializing EvaluationMetrics...")
+        self.y_true = np.asarray(y_true).ravel()
+        self.y_pred = np.asarray(y_pred).ravel()
+        self.weights = np.ones_like(y_true) if weights is None else np.asarray(weights)
+        self.N = len(y_true)
+        
+    def calculate_rob_r2(self):
+        """Calculate the Weighted R-square (RobR²).
+
+        This metric measures the proportion of variance in the dependent variable that is predictable from the independent variables, using weighted observations.
+
+        Returns:
+            float: The RobR² value, where 1 indicates perfect prediction and values closer to 0 indicate poor prediction.
+        """
+        self.logger.info("Calculating RobR²...")
+        errors = self.y_true - self.y_pred
+        weighted_errors_squared = np.sum(self.weights * (errors ** 2))
+        weighted_total_variance = np.sum(self.weights * (self.y_true - np.mean(self.y_true)) ** 2)
+        
+        rob_r2 = 1 - (weighted_errors_squared / weighted_total_variance)
+        self.logger.info(f"RobR² calculated: {rob_r2}")
+        return rob_r2
+    
+    def calculate_gmmfe(self):
+        """Calculate the Geometric Mean of Multiplicative Fitting Errors (GMMFE).
+
+        This metric calculates the geometric mean of the multiplicative fitting errors between true and predicted values.
+
+        Returns:
+            float: The GMMFE value, where values closer to 1 indicate better fitting.
+        """
+        self.logger.info("Calculating GMMFE...")
+        ratio = self.y_true / (self.y_pred + 1e-10)
+        # avoid invalid value for log
+        ratio = np.where(ratio <= 0, 1e-10, ratio)
+        log_sum = np.sum(np.abs(np.log(ratio))) / self.N
+        gmmfe = np.exp(log_sum)
+        self.logger.info(f"GMMFE calculated: {gmmfe}")
+        return gmmfe
+    
+    def calculate_divi(self):
+        """Calculate the Divergence of Information (DivI).
+
+        This metric quantifies the divergence between the information content of true and predicted values.
+
+        Returns:
+            float: The DivI value, where lower values indicate less divergence and better predictions.
+        """
+        self.logger.info("Calculating DivI...")
+        I_true = self._calculate_information(self.y_true)
+        I_pred = self._calculate_information(self.y_pred)
+        divi = np.sum(I_true / I_pred) / self.N
+        self.logger.info(f"DivI calculated: {divi}")
+        return divi
+    
+    def _calculate_information(self, y):
+        """Helper method to calculate information content.""" # NOTE place holder
+        self.logger.info("Calculating information content...")
+        # This is a simplified version - you might want to implement
+        return np.abs(y) + 1e-10  # Adding small constant to avoid division by zero
+    
+    def calculate_evalmet(self):
+        """Calculate the overall evaluation metric (EvalMet).
+
+        This metric combines RobR², GMMFE, and DivI to provide an overall evaluation of the model's performance.
+
+        Returns:
+            float: The EvalMet value, where higher values indicate better overall performance.
+        """
+        self.logger.info("Calculating EvalMet...")
+        rob_r2 = self.calculate_rob_r2()
+        gmmfe = self.calculate_gmmfe()
+        divi = self.calculate_divi()
+        
+        evalmet = rob_r2 / (gmmfe * divi)
+        self.logger.info(f"EvalMet calculated: {evalmet}")
+        return evalmet
+    
+    def generate_report(self) -> dict:
+        """Generate a complete evaluation report.
+
+        This method calculates all evaluation metrics (RobR², GMMFE, DivI, EvalMet) and returns them in a dictionary format.
+
+        Returns:
+            dict: A dictionary containing all evaluation metrics with their respective values.
+        """
+        self.logger.info("Generating evaluation report...")
+        rob_r2 = self.calculate_rob_r2()
+        gmmfe = self.calculate_gmmfe()
+        divi = self.calculate_divi()
+        evalmet = self.calculate_evalmet()
+        self.logger.info("Evaluation report generated.")
+        return {
+            'RobR²': rob_r2,
+            'GMMFE': gmmfe,
+            'DivI': divi,
+            'EvalMet': evalmet
+        }

machinegnostics/metrics/mse.py

@@ -0,0 +1,78 @@
+import numpy as np
+from machinegnostics.magcal.util.logging import get_logger
+import logging
+from machinegnostics.metrics.mean import mean
+
+def mean_squared_error(y_true: np.ndarray, y_pred: np.ndarray, verbose: bool = False) -> float:
+    """
+    Computes the Gnostic mean squared error (MSE).
+
+    The Gnostic MSE 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
+    ----------
+    y_true : array-like
+        True values (targets).
+    y_pred : array-like
+        Predicted values.
+    verbose : bool, optional
+        If True, enables detailed logging for debugging purposes. Default is False.
+
+    Returns
+    -------
+    float
+        Average of squared differences 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('MSE', level=logging.WARNING if not verbose else logging.INFO)
+    logger.info("Calculating Mean Squared Error...")
+
+    # Validate input types
+    if not isinstance(y_true, (list, tuple, np.ndarray)):
+        logger.error("y_true must be array-like (list, tuple, or numpy array).")
+        raise TypeError("y_true must be array-like (list, tuple, or numpy array).")
+    if not isinstance(y_pred, (list, tuple, np.ndarray)):
+        logger.error("y_pred must be array-like (list, tuple, or numpy array).")
+        raise TypeError("y_pred must be array-like (list, tuple, or numpy array).")
+    # 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 shape mismatch
+    if np.shape(y_true) != np.shape(y_pred):
+        logger.error("y_true and y_pred must have the same shape.")
+        raise ValueError("y_true and y_pred must have the same shape.")
+    # 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 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()
+
+    # Check for empty arrays
+    if y_true.size == 0:
+        raise ValueError("y_true and y_pred must not be empty.")
+
+    # Compute MSE
+    mse = float(mean((y_true - y_pred) ** 2))
+    logger.info(f"Gnostic MSE calculated.")
+    return mse

machinegnostics/metrics/precision.py

@@ -0,0 +1,119 @@
+import numpy as np
+import pandas as pd
+from machinegnostics.magcal.util.logging import get_logger
+import logging
+
+def precision_score(y_true:np.ndarray, 
+                    y_pred:np.ndarray, 
+                    average='binary', 
+                    labels=None,
+                    verbose: bool = False) -> float:
+    """
+    Computes the precision classification score.
+
+    Precision is the ratio of true positives to the sum of true and false positives.
+    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 precision 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.
+
+    Returns
+    -------
+    precision : float or array of floats
+        Precision 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]
+    >>> precision_score(y_true, y_pred, average='macro')
+
+    >>> import pandas as pd
+    >>> df = pd.DataFrame({'true': [1, 0, 1], 'pred': [1, 1, 1]})
+    >>> precision_score(df['true'], df['pred'], average='binary')
+    """
+    logger = get_logger('precision_score', level=logging.WARNING if not verbose else logging.INFO)
+    logger.info("Calculating Precision 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 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.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.")
+    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.")
+
+    # Get unique labels
+    if labels is None:
+        labels = np.unique(np.concatenate([y_true, y_pred]))
+    else:
+        labels = np.asarray(labels)
+
+    precisions = []
+    for label in labels:
+        tp = np.sum((y_pred == label) & (y_true == label))
+        fp = np.sum((y_pred == label) & (y_true != label))
+        if tp + fp == 0:
+            precision = 0.0
+        else:
+            precision = tp / (tp + fp)
+        precisions.append(precision)
+
+    precisions = np.array(precisions)
+
+    logger.info("Precision Score calculated.")
+
+    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.")
+        # By convention, use the second label as positive class
+        return precisions[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)
+        return tp / (tp + fp) if (tp + fp) > 0 else 0.0
+    elif average == 'macro':
+        return np.mean(precisions)
+    elif average == 'weighted':
+        support = np.array([np.sum(y_true == label) for label in labels])
+        return np.average(precisions, weights=support)
+    elif average is None:
+        return precisions
+    else:
+        raise ValueError(f"Unknown average type: {average}")

machinegnostics/metrics/r2.py

@@ -0,0 +1,122 @@
+import numpy as np
+from machinegnostics.magcal.util.logging import get_logger
+import logging
+
+def r2_score(y_true:np.ndarray, y_pred:np.ndarray, verbose:bool=False) -> float:
+    """
+    Computes the coefficient of determination (R² score).
+
+    Parameters
+    ----------
+    y_true : array-like
+        True values (targets).
+    y_pred : array-like
+        Predicted values.
+    verbose : bool, optional
+        If True, enables detailed logging for debugging purposes. Default is False.
+
+    Returns
+    -------
+    float
+        Proportion of variance explained (1 is perfect prediction).
+
+    Raises
+    ------
+    TypeError
+        If inputs are not array-like.
+    ValueError
+        If shapes do not match or inputs are empty.
+    """
+    logger = get_logger('R2', level=logging.WARNING if not verbose else logging.INFO)
+    logger.info("Calculating R2 Score...")
+
+    if not isinstance(y_true, (list, tuple, np.ndarray)):
+        logger.error("y_true must be array-like.")
+        raise TypeError("y_true must be array-like.")
+    if not isinstance(y_pred, (list, tuple, np.ndarray)):
+        logger.error("y_pred must be array-like.")
+        raise TypeError("y_pred must be array-like.")
+
+    y_true = np.asarray(y_true).flatten()
+    y_pred = np.asarray(y_pred).flatten()
+
+    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}")
+
+    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.")
+
+    ss_res = np.sum((y_true - y_pred) ** 2)
+    ss_tot = np.sum((y_true - np.mean(y_true)) ** 2)
+
+    if ss_tot == 0:
+        # All values in y_true are identical; R² is not defined
+        return 0.0
+    logger.info("R2 Score calculated.")
+
+    return float(1 - ss_res / ss_tot)
+
+def adjusted_r2_score(y_true:np.ndarray, y_pred:np.ndarray, n_features:int, verbose:bool=False) -> float:
+    """
+    Computes the adjusted R² score.
+
+    Parameters
+    ----------
+    y_true : array-like
+        True values (targets).
+    y_pred : array-like
+        Predicted values.
+    n_features : int
+        Number of features (independent variables) in the model.
+    verbose : bool, optional
+        If True, enables detailed logging for debugging purposes. Default is False.
+
+    Returns
+    -------
+    float
+        Adjusted R² accounting for number of predictors.
+
+    Raises
+    ------
+    ValueError
+        If n_features is invalid (e.g., greater than or equal to number of samples).
+    """
+    logger = get_logger('adjusted_R2', level=logging.WARNING if not verbose else logging.INFO)
+    logger.info("Calculating Adjusted R2 Score...")
+
+    if not isinstance(n_features, int) or n_features < 0:
+        logger.error("n_features must be a non-negative integer.")
+        raise ValueError("n_features must be a non-negative integer.")
+
+    # Convert to numpy arrays and flatten
+    if not isinstance(y_true, (list, tuple, np.ndarray)):
+        logger.error("y_true must be array-like.")
+        raise TypeError("y_true must be array-like.")
+    if not isinstance(y_pred, (list, tuple, np.ndarray)):
+        logger.error("y_pred must be array-like.")
+        raise TypeError("y_pred must be array-like.")
+    y_pred = np.asarray(y_pred).flatten()
+    y_true = np.asarray(y_true).flatten()
+    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}")
+    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.")
+    
+    
+    n = y_true.shape[0]
+
+    if n <= n_features + 1:
+        raise ValueError(
+            f"Adjusted R² is undefined for n = {n} and n_features = {n_features} "
+            "(must have n > n_features + 1)."
+        )
+
+    r2 = r2_score(y_true, y_pred)
+    r2_adj = float(1 - (1 - r2) * (n - 1) / (n - n_features - 1))
+
+    logger.info("Adjusted R2 Score calculated.")
+    return r2_adj

machinegnostics/metrics/recall.py

@@ -0,0 +1,108 @@
+import numpy as np
+import pandas as pd
+from machinegnostics.magcal.util.logging import get_logger
+import logging
+
+def recall_score(y_true:np.ndarray|pd.Series, 
+                 y_pred:np.ndarray|pd.Series, 
+                 average='binary', 
+                 labels=None,
+                 verbose:bool=False) -> float|np.ndarray:
+    """
+    Computes the recall classification score.
+
+    Recall is the ratio of true positives to the sum of true positives and false negatives.
+    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 recall 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.
+
+    Returns
+    -------
+    recall : float or array of floats
+        Recall 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]
+    >>> recall_score(y_true, y_pred, average='macro')
+    0.8333333333333333
+
+    >>> import pandas as pd
+    >>> df = pd.DataFrame({'true': [1, 0, 1], 'pred': [1, 1, 1]})
+    >>> recall_score(df['true'], df['pred'], average='binary')
+    1.0
+    """
+    logger = get_logger('recall_score', level=logging.WARNING if not verbose else logging.INFO)
+    logger.info("Calculating Recall 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:
+        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)
+
+    recalls = []
+    for label in labels:
+        tp = np.sum((y_pred == label) & (y_true == label))
+        fn = np.sum((y_pred != label) & (y_true == label))
+        if tp + fn == 0:
+            recall = 0.0
+        else:
+            recall = tp / (tp + fn)
+        recalls.append(recall)
+
+    recalls = np.array(recalls)
+    
+    logger.info("Recall Score calculated.")
+    if average == 'binary':
+        if len(labels) != 2:
+            raise ValueError("Binary average is only supported for binary classification with 2 classes.")
+        # By convention, use the second label as positive class
+        return recalls[1]
+    elif average == 'micro':
+        tp = 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)
+        return tp / (tp + fn) if (tp + fn) > 0 else 0.0
+    elif average == 'macro':
+        return np.mean(recalls)
+    elif average == 'weighted':
+        support = np.array([np.sum(y_true == label) for label in labels])
+        return np.average(recalls, weights=support)
+    elif average is None:
+        return recalls
+    else:
+        raise ValueError(f"Unknown average type: {average}")

machinegnostics/metrics/rmse.py

@@ -0,0 +1,77 @@
+import numpy as np
+import logging
+from machinegnostics.magcal.util.logging import get_logger
+from machinegnostics.metrics.mean import mean
+
+def root_mean_squared_error(y_true: np.ndarray, y_pred: np.ndarray, verbose: bool = False) -> float:
+    """
+    Computes the Gnostic Root Mean Squared Error (RMSE).
+
+    The Gnostic RMSE 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
+    ----------
+    y_true : array-like
+        True values (targets).
+    y_pred : array-like
+        Predicted values.
+    verbose : bool, optional
+        If True, enables detailed logging for debugging purposes. Default is False.
+
+    Returns
+    -------
+    float
+        Square root of the average of squared errors.
+
+    Examples
+    --------
+    Example 1: Basic usage with simple arrays
+    >>> import numpy as np
+    >>> from machinegnostics.metrics import root_mean_squared_error
+    >>> y_true = np.array([3, -0.5, 2, 7])
+    >>> y_pred = np.array([2.5, 0.0, 2, 8])
+    >>> rmse = root_mean_squared_error(y_true, y_pred, verbose=True)
+    >>> print(f"RMSE: {rmse}")
+
+    Raises
+    ------
+    TypeError
+        If y_true or y_pred are not array-like.
+    ValueError
+        If inputs have mismatched shapes or are empty.
+    """
+    logger = get_logger('RMSE', level=logging.WARNING if not verbose else logging.INFO)
+    logger.info("Calculating Root Mean Squared Error...")
+    # Convert to numpy arrays and flatten
+    y_true = np.asarray(y_true)
+    y_pred = np.asarray(y_pred)
+
+    # Ensure 1D arrays (one column)
+    if y_true.ndim != 1:
+        logger.error("y_true must be a 1D array (single column).")
+        raise ValueError("y_true must be a 1D array (single column).")
+    if y_pred.ndim != 1:
+        logger.error("y_pred must be a 1D array (single column).")
+        raise ValueError("y_pred must be a 1D array (single column).")
+
+    # Validate shapes
+    if len(y_true) != len(y_pred):
+        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 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.")
+
+    # Compute RMSE
+    rmse = float(np.sqrt(mean((y_true - y_pred) ** 2)))
+    logger.info(f"Gnostic RMSE calculated.")
+    return rmse