pyEllipse 0.1.2__py3-none-any.whl

pyEllipse/__init__.py

@@ -0,0 +1,31 @@
+"""
+**Statistical confidence ellipses and Hotelling's T-squared statistic**
+
+The pyEllipse library provides robust computational tools for generating and analyzing 
+confidence ellipses and ellipsoids in multivariate datasets. Built on rigorous statistical 
+foundations, it supports both classical normal-based confidence regions and Hotelling's 
+T-squared ellipses, delivering robust uncertainty quantification for small samples, outlier 
+detection, process control, and high-dimensional data exploration.
+"""
+
+# Import main functions with their proper names
+from .hotelling_parameters import hotelling_parameters
+from .hotelling_coordinates import hotelling_coordinates
+from .confidence_ellipse import confidence_ellipse
+
+__all__ = [
+    "hotelling_parameters",
+    "hotelling_coordinates", 
+    "confidence_ellipse",
+]
+
+# Library metadata
+__title__ = "pyEllipse"
+__description__ = "Statistical confidence ellipses and Hotelling's T-squared ellipses"
+__url__ = "https://github.com/ChristianGoueguel/pyEllipse"
+__license__ = "MIT"
+__version__ = "0.1.1"
+__author__ = "Christian L. Goueguel"
+__maintainer__ = "Christian L. Goueguel"
+__credits__ = ["Christian L. Goueguel"] 
+__email__ = "christian.goueguel@gmail.com"

pyEllipse/confidence_ellipse.py

@@ -0,0 +1,248 @@
+"""
+**Module to compute coordinate points for confidence regions based on 
+normal or Hotelling's T-squared distributions**
+"""
+import numpy as np
+import pandas as pd
+from scipy import stats
+from typing import Optional, Literal
+import warnings
+
+
+def confidence_ellipse(
+    data: pd.DataFrame,
+    x: str,
+    y: str,
+    z: Optional[str] = None,
+    group_by: Optional[str] = None,
+    conf_level: float = 0.95,
+    robust: bool = False,
+    distribution: Literal["normal", "hotelling"] = "normal"
+) -> pd.DataFrame:
+    """
+    This module generates coordinate points for visualizing confidence regions in multivariate data. 
+    It supports both 2D confidence ellipses and 3D confidence ellipsoids at user-specified 
+    confidence levels, with options for normal distribution assumptions or Hotelling's T-squared 
+    distribution for small sample sizes.
+    
+    Parameters
+    ----------
+    *   `data` : Input data frame containing the variables.
+    
+    *   `x` : Column name for the x-axis variable.
+    
+    *   `y` : Column name for the y-axis variable.
+    
+    *   `z` : Column name for the z-axis variable (None by default).
+        If provided, computes a 3D ellipsoid instead of a 2D ellipse.
+    
+    *   `group_by` : Column name for the grouping variable (None by default).
+        This grouping variable should be categorical.
+    
+    *   `conf_level` : Confidence level for the ellipse/ellipsoid (between 0 and 1).
+    
+    *   `robust` : When `True`, uses robust estimation methods for location and scale.
+        Uses sklearn's `EllipticEnvelope` for robust covariance estimation.
+    
+    *   `distribution` : Distribution used to calculate the quantile for the ellipse.
+        Options are:
+
+        - `'normal'`: Uses chi-square distribution (appropriate for large samples)
+        - `'hotelling'`: Uses Hotelling's T² distribution (better for small samples)
+    
+    Returns
+    -------
+    DataFrame containing the coordinate points:
+
+        - For 2D: columns 'x' and 'y'
+        - For 3D: columns 'x', 'y', and 'z'
+        If group_by is specified, includes the grouping column.
+    """
+    if not isinstance(data, pd.DataFrame):
+        raise TypeError("Input 'data' must be a pandas DataFrame.")
+    
+    if x not in data.columns:
+        raise ValueError(f"Column '{x}' not found in data.")
+    
+    if y not in data.columns:
+        raise ValueError(f"Column '{y}' not found in data.")
+    
+    if not isinstance(conf_level, (int, float)):
+        raise TypeError("'conf_level' must be numeric.")
+    
+    if conf_level <= 0 or conf_level >= 1:
+        raise ValueError("'conf_level' must be between 0 and 1.")
+    
+    if distribution not in ["normal", "hotelling"]:
+        raise ValueError("'distribution' must be either 'normal' or 'hotelling'.")
+    
+    if z is None:
+        # 2D ellipse
+        if group_by is None:
+            selected_data = data[[x, y]].values
+            ellipse_coord = _transform_2d(selected_data, conf_level, robust, distribution)
+            result = pd.DataFrame(ellipse_coord, columns=['x', 'y'])
+        else:
+            if group_by not in data.columns:
+                raise ValueError(f"Column '{group_by}' not found in data.")
+            results = []
+            for group_name, group_data in data.groupby(group_by):
+                selected_data = group_data[[x, y]].values
+                ellipse_coord = _transform_2d(selected_data, conf_level, robust, distribution)
+                group_df = pd.DataFrame(ellipse_coord, columns=['x', 'y'])
+                group_df[group_by] = group_name
+                results.append(group_df)
+            result = pd.concat(results, ignore_index=True)
+        return result
+    else:
+        # 3D ellipsoid
+        if z not in data.columns:
+            raise ValueError(f"Column '{z}' not found in data.")
+        
+        if group_by is None:
+            selected_data = data[[x, y, z]].values
+            ellipsoid_coord = _transform_3d(selected_data, conf_level, robust, distribution)
+            result = pd.DataFrame(ellipsoid_coord, columns=['x', 'y', 'z'])
+        else:
+            if group_by not in data.columns:
+                raise ValueError(f"Column '{group_by}' not found in data.")    
+            results = []
+            for group_name, group_data in data.groupby(group_by):
+                selected_data = group_data[[x, y, z]].values
+                ellipsoid_coord = _transform_3d(selected_data, conf_level, robust, distribution)
+                group_df = pd.DataFrame(ellipsoid_coord, columns=['x', 'y', 'z'])
+                group_df[group_by] = group_name
+                results.append(group_df)
+            result = pd.concat(results, ignore_index=True)
+        return result
+
+
+def _transform_2d(
+    x: np.ndarray,
+    conf_level: float,
+    robust: bool,
+    distribution: str
+) -> np.ndarray:
+    """
+    Transform 2D data to ellipse coordinates.
+    
+    Parameters
+    ----------
+    x : np.ndarray
+        2D array of shape (n_samples, 2)
+    conf_level : float
+        Confidence level
+    robust : bool
+        Whether to use robust estimation
+    distribution : str
+        Either 'normal' or 'hotelling'
+    
+    Returns
+    -------
+    np.ndarray
+        Array of ellipse coordinates
+    """
+    n = x.shape[0]
+    
+    if n < 3:
+        raise ValueError("At least 3 observations are required.")
+    
+    if not robust:
+        mean_vec = np.mean(x, axis=0)
+        cov_matrix = np.cov(x, rowvar=False)
+    else:
+        from sklearn.covariance import EllipticEnvelope
+        try:
+            robust_cov = EllipticEnvelope(support_fraction=0.9, random_state=42)
+            robust_cov.fit(x)
+            mean_vec = robust_cov.location_
+            cov_matrix = robust_cov.covariance_
+        except Exception as e:
+            warnings.warn(f"Robust estimation failed: {e}. Using classical estimates.")
+            mean_vec = np.mean(x, axis=0)
+            cov_matrix = np.cov(x, rowvar=False)
+    
+    if np.any(np.isnan(cov_matrix)):
+        raise ValueError("Covariance matrix contains NA values.")
+    
+    eigenvalues, eigenvectors = np.linalg.eigh(cov_matrix)
+    theta = np.linspace(0, 2 * np.pi, 361)
+    
+    if distribution == "normal":
+        quantile = stats.chi2.ppf(conf_level, 2)
+    else:  # hotelling
+        quantile = ((2 * (n - 1)) / (n - 2)) * stats.f.ppf(conf_level, 2, n - 2)
+    
+    X = np.sqrt(eigenvalues[0] * quantile) * np.cos(theta)
+    Y = np.sqrt(eigenvalues[1] * quantile) * np.sin(theta)
+    R = np.column_stack([X, Y]) @ eigenvectors.T
+    result = R + mean_vec
+    return result
+
+
+def _transform_3d(
+    x: np.ndarray,
+    conf_level: float,
+    robust: bool,
+    distribution: str
+) -> np.ndarray:
+    """
+    Transform 3D data to ellipsoid coordinates.
+    
+    Parameters
+    ----------
+    x : np.ndarray
+        3D array of shape (n_samples, 3)
+    conf_level : float
+        Confidence level
+    robust : bool
+        Whether to use robust estimation
+    distribution : str
+        Either 'normal' or 'hotelling'
+    
+    Returns
+    -------
+    np.ndarray
+        Array of ellipsoid coordinates
+    """
+    n = x.shape[0]
+    
+    if n < 3:
+        raise ValueError("At least 3 observations are required.")
+    
+    if not robust:
+        mean_vec = np.mean(x, axis=0)
+        cov_matrix = np.cov(x, rowvar=False)
+    else:
+        from sklearn.covariance import EllipticEnvelope
+        try:
+            robust_cov = EllipticEnvelope(support_fraction=0.9, random_state=42)
+            robust_cov.fit(x)
+            mean_vec = robust_cov.location_
+            cov_matrix = robust_cov.covariance_
+        except Exception as e:
+            warnings.warn(f"Robust estimation failed: {e}. Using classical estimates.")
+            mean_vec = np.mean(x, axis=0)
+            cov_matrix = np.cov(x, rowvar=False)
+    
+    if np.any(np.isnan(cov_matrix)):
+        raise ValueError("Covariance matrix contains NA values.")
+    
+    eigenvalues, eigenvectors = np.linalg.eigh(cov_matrix)
+    theta = np.linspace(0, 2 * np.pi, 50)
+    phi = np.linspace(0, np.pi, 50)
+    theta_grid, phi_grid = np.meshgrid(theta, phi)
+    theta_flat = theta_grid.flatten()
+    phi_flat = phi_grid.flatten()
+    
+    if distribution == "normal":
+        quantile = stats.chi2.ppf(conf_level, 3)
+    else:  # hotelling
+        quantile = ((3 * (n - 1)) / (n - 3)) * stats.f.ppf(conf_level, 3, n - 3)
+    
+    X = np.sqrt(eigenvalues[0] * quantile) * np.sin(phi_flat) * np.cos(theta_flat)
+    Y = np.sqrt(eigenvalues[1] * quantile) * np.sin(phi_flat) * np.sin(theta_flat)
+    Z = np.sqrt(eigenvalues[2] * quantile) * np.cos(phi_flat)
+    R = np.column_stack([X, Y, Z]) @ eigenvectors.T
+    result = R + mean_vec
+    return result

pyEllipse/hotelling_coordinates.py

@@ -0,0 +1,164 @@
+"""
+**Module to compute coordinate points for Hotelling's T-squared confidence ellipses**
+"""
+import numpy as np
+import pandas as pd
+from scipy import stats
+from typing import Union, Optional
+from itertools import product
+
+def hotelling_coordinates(
+    x: Union[np.ndarray, pd.DataFrame],
+    pcx: int = 1,
+    pcy: int = 2,
+    pcz: Optional[int] = None,
+    conf_limit: float = 0.95,
+    pts: int = 200
+) -> pd.DataFrame:
+    """
+    This module computes the boundary coordinate points needed to visualize Hotelling's 
+    T-squared confidence regions. It supports both 2D confidence ellipses and 3D confidence 
+    ellipsoids, calculating points based on the Hotelling's T-squared distribution for any 
+    user-defined confidence interval.
+    
+    Parameters
+    ----------
+    *   `x` : Input matrix or data frame containing scores from PCA, PLS, ICA, or other
+        dimensionality reduction methods. Each column represents a component, and each row an observation.
+
+    *   `pcx` : Component to use for the x-axis (default=1).
+
+    *   `pcy` : Component to use for the y-axis (default=2).
+    
+    *   `pcz` : Component to use for the z-axis for 3D ellipsoids. If None (default), a 2D ellipse is computed.
+    
+    *   `conf_limit` : Confidence level for the ellipse (between 0 and 1). Default is 0.95
+        (95% confidence). Higher values result in larger ellipses.
+    
+    *   `pts` : Number of points to generate for drawing the ellipse. Higher values 
+        result in smoother ellipses but increase computation time.
+    
+    Returns
+    -------
+    DataFrame containing coordinate points:
+
+        - For 2D ellipses: columns 'x' and 'y'
+        - For 3D ellipsoids: columns 'x', 'y', and 'z'
+    """
+    if x is None:
+        raise ValueError("Missing input data.")
+    
+    if isinstance(x, pd.DataFrame):
+        x = x.values
+    elif not isinstance(x, np.ndarray):
+        raise TypeError("Input data must be a numpy array or pandas DataFrame.")
+    
+    if not isinstance(conf_limit, (int, float)) or conf_limit <= 0 or conf_limit >= 1:
+        raise ValueError("Confidence level should be a numeric value between 0 and 1.")
+    
+    x = np.asarray(x, dtype=float)
+    n, p = x.shape
+    
+    if not isinstance(pcx, int) or pcx < 1 or pcx > p:
+        raise ValueError(f"'pcx' must be an integer between 1 and {p}.")
+    
+    if not isinstance(pcy, int) or pcy < 1 or pcy > p:
+        raise ValueError(f"'pcy' must be an integer between 1 and {p}.")
+    
+    if pcx == pcy:
+        raise ValueError("'pcx' and 'pcy' must be different integers.")
+    
+    if not isinstance(pts, int) or pts <= 0:
+        raise ValueError("'pts' should be a positive integer.")
+    
+    if pcz is not None:
+        if not isinstance(pcz, int) or pcz < 1 or pcz > p:
+            raise ValueError(f"'pcz' must be an integer between 1 and {p}.")
+        
+        if pcz == pcx or pcz == pcy:
+            raise ValueError("'pcx', 'pcy', and 'pcz' must be different integers.")
+    
+
+    if pcz is None:
+        result = _compute_ellipse(x, pcx, pcy, n, conf_limit, pts)
+    else:
+        result = _compute_ellipsoid(x, pcx, pcy, pcz, n, conf_limit, pts)
+    return result
+
+
+def _compute_ellipse(
+    x: np.ndarray,
+    pcx: int,
+    pcy: int,
+    n: int,
+    conf_limit: float,
+    pts: int
+) -> pd.DataFrame:
+    """
+    Compute 2D ellipse coordinates.
+    """
+    theta = np.linspace(0, 2 * np.pi, pts)
+    
+    p = 2
+    f_quantile = stats.f.ppf(conf_limit, p, n - p)
+    tsq_limit = ((p * (n - 1)) / (n - p)) * f_quantile
+    
+    x_col = x[:, pcx - 1]
+    y_col = x[:, pcy - 1]
+    x_mean = np.mean(x_col)
+    y_mean = np.mean(y_col)
+    x_var = np.var(x_col, ddof=1)
+    y_var = np.var(y_col, ddof=1)        
+    x_coord = np.sqrt(tsq_limit * x_var) * np.cos(theta) + x_mean
+    y_coord = np.sqrt(tsq_limit * y_var) * np.sin(theta) + y_mean
+
+    return pd.DataFrame({
+        'x': x_coord,
+        'y': y_coord
+    })
+
+
+def _compute_ellipsoid(
+    x: np.ndarray,
+    pcx: int,
+    pcy: int,
+    pcz: int,
+    n: int,
+    conf_limit: float,
+    pts: int
+) -> pd.DataFrame:
+    """
+    Compute 3D ellipsoid coordinates.
+    """
+    theta = np.linspace(0, 2 * np.pi, pts)
+    phi = np.linspace(0, np.pi, pts)
+    theta_grid, phi_grid = np.meshgrid(theta, phi)
+    theta_flat = theta_grid.flatten()
+    phi_flat = phi_grid.flatten()
+    sin_phi = np.sin(phi_flat)
+    cos_phi = np.cos(phi_flat)
+    cos_theta = np.cos(theta_flat)
+    sin_theta = np.sin(theta_flat)
+    
+    p = 3
+    f_quantile = stats.f.ppf(conf_limit, p, n - p)
+    tsq_limit = ((p * (n - 1)) / (n - p)) * f_quantile
+
+    x_col = x[:, pcx - 1]
+    y_col = x[:, pcy - 1]
+    z_col = x[:, pcz - 1]
+    x_mean = np.mean(x_col)
+    y_mean = np.mean(y_col)
+    z_mean = np.mean(z_col)
+    x_var = np.var(x_col, ddof=1)
+    y_var = np.var(y_col, ddof=1)
+    z_var = np.var(z_col, ddof=1)
+    x_coord = np.sqrt(tsq_limit * x_var) * cos_theta * sin_phi + x_mean
+    y_coord = np.sqrt(tsq_limit * y_var) * sin_theta * sin_phi + y_mean
+    z_coord = np.sqrt(tsq_limit * z_var) * cos_phi + z_mean
+    
+    return pd.DataFrame({
+        'x': x_coord,
+        'y': y_coord,
+        'z': z_coord
+    })

pyEllipse/hotelling_parameters.py

@@ -0,0 +1,221 @@
+"""
+**Module to compute Hotelling's T-squared statistics and parameters for confidence ellipses**
+"""
+import numpy as np
+import pandas as pd
+from scipy import stats
+from typing import Union, Optional, Dict
+import sys
+
+
+def hotelling_parameters(
+    x: Union[np.ndarray, pd.DataFrame],
+    k: int = 2,
+    pcx: int = 1,
+    pcy: int = 2,
+    threshold: Optional[float] = None,
+    rel_tol: float = 0.001,
+    abs_tol: float = sys.float_info.epsilon
+) -> Dict:
+    """
+    This module provides functions to calculate Hotelling's T-squared statistics 
+    for multivariate data and to derive parameters for confidence ellipses based 
+    on Hotelling's T-squared distribution.
+
+    Parameters
+    ----------
+    *   `x` : Input matrix or data frame containing scores from PCA, PLS, ICA, or similar methods. Each column represents a component, and each row an observation.
+
+    *   `k` : Number of components to use (default=2). Ignored if threshold is provided.
+
+    *   `pcx` : Component to use for x-axis when `k=2` (default=1).
+
+    *   `pcy` : Component to use for y-axis when `k=2` (default=2). Must be different from `pcx`.
+
+    *   `threshold` : Cumulative explained variance threshold (0 to 1). If provided,
+        determines minimum number of components to explain at least this
+        proportion of total variance.
+
+    *   `rel_tol` : Minimum proportion of total variance a component should explain
+        to be considered non-negligible (0.1% by default).
+
+    *   `abs_tol` : Minimum absolute variance a component should have to be
+        considered non-negligible (default=`sys.float_info.epsilon`).
+    
+    Returns
+    -------
+    Dictionary containing:
+
+        - 'Tsquared': DataFrame with T-squared statistic for each observation
+        - 'Ellipse': DataFrame with semi-axes lengths (only when k=2)
+        - 'cutoff_99pct': T-squared cutoff at 99% confidence
+        - 'cutoff_95pct': T-squared cutoff at 95% confidence
+        - 'nb_comp': Number of components retained
+    """
+    if x is None:
+        raise ValueError("Missing input data.")
+    
+    if isinstance(x, pd.DataFrame):
+        x = x.values
+    elif not isinstance(x, np.ndarray):
+        raise TypeError("Input data must be a numpy array or pandas DataFrame.")
+    
+    if not isinstance(rel_tol, (int, float)) or rel_tol < 0:
+        raise ValueError("'rel_tol' must be a non-negative numeric value.")
+    
+    if not isinstance(abs_tol, (int, float)) or abs_tol < 0:
+        raise ValueError("'abs_tol' must be a non-negative numeric value.")
+    
+    if abs_tol > rel_tol:
+        raise ValueError("'abs_tol' must be less than or equal to 'rel_tol'.")
+    
+    x = np.asarray(x, dtype=float)
+    n, p = x.shape
+
+    if threshold is not None:
+        if not isinstance(threshold, (int, float)) or threshold <= 0 or threshold > 1:
+            raise ValueError("Threshold must be a numeric value between 0 and 1.")
+    else:
+        if not isinstance(k, int) or k < 2 or k > p:
+            raise ValueError(f"'k' must be an integer between 2 and {p}.")
+    
+    if not isinstance(pcx, int) or pcx < 1 or pcx > p:
+        raise ValueError(f"'pcx' must be an integer between 1 and {p}.")
+    
+    if not isinstance(pcy, int) or pcy < 1 or pcy > p:
+        raise ValueError(f"'pcy' must be an integer between 1 and {p}.")
+    
+    if pcx == pcy:
+        raise ValueError("'pcx' and 'pcy' must be different integers.")
+    
+    comp_var = np.var(x, axis=0, ddof=1)
+    total_var = np.sum(comp_var)
+    relative_var = comp_var / total_var
+    nearzero_var = (relative_var < rel_tol) | (comp_var < abs_tol)
+    
+    if threshold is None:
+        result = _process_fixed_comp(x, k, pcx, pcy, nearzero_var, comp_var, relative_var, rel_tol)
+    else:
+        result = _process_threshold(x, threshold, nearzero_var, relative_var)
+    return result
+
+
+def _process_fixed_comp(
+    x: np.ndarray,
+    k: int,
+    pcx: int,
+    pcy: int,
+    nearzero_var: np.ndarray,
+    comp_var: np.ndarray,
+    relative_var: np.ndarray,
+    rel_tol: float
+) -> Dict:
+    """Process with fixed number of components."""
+    result = {}
+    # Check for near-zero variance components
+    if np.any(nearzero_var[:k]):
+        removed_idx = np.where(nearzero_var[:k])[0]
+        print(f"Warning: Components with explained variance lower than 'rel_tol' "
+              f"detected: {removed_idx.tolist()} removed.")
+        x = x[:, ~nearzero_var]
+        k = min(k, x.shape[1])
+    
+    # Compute T-squared
+    try:
+        t2_values = _compute_tsquared(x, k)
+    except Exception as e:
+        raise RuntimeError(f"Error in T-squared calculation: {str(e)}")
+    result['Tsquared'] = t2_values['Tsq']
+    result['cutoff_99pct'] = t2_values['Tsq_limit1']
+    result['cutoff_95pct'] = t2_values['Tsq_limit2']
+    result['nb_comp'] = k
+    
+    # Calculate ellipse parameters for 2D case
+    if k == 2:
+        pcx_idx = pcx - 1
+        pcy_idx = pcy - 1    
+        if relative_var[pcx_idx] < rel_tol:
+            raise ValueError("'pcx' has a relative variance lower than 'rel_tol'. Please check!")
+        if relative_var[pcy_idx] < rel_tol:
+            raise ValueError("'pcy' has a relative variance lower than 'rel_tol'. Please check!")
+        result['Ellipse'] = pd.DataFrame({
+            'a_99pct': [np.sqrt(t2_values['Tsq_limit1'] * comp_var[pcx_idx])],
+            'b_99pct': [np.sqrt(t2_values['Tsq_limit1'] * comp_var[pcy_idx])],
+            'a_95pct': [np.sqrt(t2_values['Tsq_limit2'] * comp_var[pcx_idx])],
+            'b_95pct': [np.sqrt(t2_values['Tsq_limit2'] * comp_var[pcy_idx])]
+        })    
+    return result
+
+
+def _process_threshold(
+    x: np.ndarray,
+    threshold: float,
+    nearzero_var: np.ndarray,
+    relative_var: np.ndarray
+) -> Dict:
+    """Process with cumulative variance threshold."""
+    result = {}
+    # Find number of components needed for threshold
+    cum_var = np.cumsum(relative_var)
+    k_indices = np.where(cum_var >= threshold)[0]
+    
+    if len(k_indices) == 0:
+        raise ValueError("Threshold is too high. Cannot find enough components to meet the threshold.")
+    
+    k = k_indices[0] + 1  
+    if k == 1:
+        print(f"Warning: The specified threshold ({threshold:.3f}) is lower than "
+              f"the variance explained by the first component ({relative_var[0]:.3f}). "
+              f"Using the first two components (k=2).")
+        k = 2
+    
+    # Check for near-zero variance components
+    if np.any(nearzero_var[:k]):
+        removed_idx = np.where(nearzero_var[:k])[0]
+        print(f"Warning: Components with explained variance lower than 'rel_tol' "
+              f"detected within the first {k} components: {removed_idx.tolist()} removed.")
+        x = x[:, ~nearzero_var]
+        relative_var = relative_var[~nearzero_var]
+        cum_var = np.cumsum(relative_var)
+        k_indices = np.where(cum_var >= threshold)[0]
+        k = k_indices[0] + 1 if len(k_indices) > 0 else x.shape[1]
+    
+    # Compute T-squared
+    try:
+        t2_values = _compute_tsquared(x, k)
+    except Exception as e:
+        raise RuntimeError(f"Error in T-squared calculation: {str(e)}")
+    result['Tsquared'] = t2_values['Tsq']
+    result['cutoff_99pct'] = t2_values['Tsq_limit1']
+    result['cutoff_95pct'] = t2_values['Tsq_limit2']
+    result['nb_comp'] = k
+    return result
+
+
+def _compute_tsquared(x: np.ndarray, ncomp: int) -> Dict:
+    """Compute Hotelling's T-squared statistic."""
+    n = x.shape[0]
+    x_subset = x[:, :ncomp]    
+    mean = np.mean(x_subset, axis=0)
+    cov = np.cov(x_subset, rowvar=False)
+
+    # Compute Mahalanobis distance for each observation
+    diff = x_subset - mean
+    inv_cov = np.linalg.inv(cov)
+    md_sq = np.sum(diff @ inv_cov * diff, axis=1)
+
+    # Calculate cutoff values using F-distribution
+    f_99 = stats.f.ppf(0.99, ncomp, n - ncomp)
+    f_95 = stats.f.ppf(0.95, ncomp, n - ncomp)
+    tsq_limit1 = (ncomp * (n - 1) / (n - ncomp)) * f_99
+    tsq_limit2 = (ncomp * (n - 1) / (n - ncomp)) * f_95
+
+    # Calculate T-squared values
+    tsq_values = ((n - ncomp) / (ncomp * (n - 1))) * md_sq
+    tsq_df = pd.DataFrame({'value': tsq_values})
+    
+    return {
+        'Tsq': tsq_df,
+        'Tsq_limit1': tsq_limit1,
+        'Tsq_limit2': tsq_limit2
+    }

pyellipse-0.1.2.dist-info/METADATA

@@ -0,0 +1,313 @@
+Metadata-Version: 2.4
+Name: pyEllipse
+Version: 0.1.2
+Summary: Tools for creating and analyzing confidence ellipses, including Hotelling's T-squared ellipses for multivariate statistical analysis and data visualization.
+License: MIT
+License-File: LICENSE
+Keywords: statistics,confidence-ellipse,hotelling,multivariate,visualization
+Author: Christian L. Goueguel
+Author-email: christian.goueguel@gmail.com
+Requires-Python: >=3.9,<3.13
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Provides-Extra: all
+Provides-Extra: plotting
+Requires-Dist: matplotlib (>=3.7.0,<4.0.0)
+Requires-Dist: numpy (>=1.24.0,<2.0.0)
+Requires-Dist: pandas (>=2.0.0,<3.0.0)
+Requires-Dist: plotly (>=5.14.0,<6.0.0) ; extra == "plotting" or extra == "all"
+Requires-Dist: scikit-learn (>=1.3.0,<2.0.0)
+Requires-Dist: scipy (>=1.11.0,<2.0.0)
+Requires-Dist: seaborn (>=0.12.0,<0.13.0) ; extra == "plotting" or extra == "all"
+Project-URL: Bug Tracker, https://github.com/ChristianGoueguel/pyEllipse/issues
+Project-URL: Documentation, https://christiangoueguel.github.io/pyEllipse
+Project-URL: Homepage, https://github.com/ChristianGoueguel/pyEllipse
+Project-URL: Repository, https://github.com/ChristianGoueguel/pyEllipse
+Description-Content-Type: text/markdown
+
+# pyEllipse
+
+A Python package for computing Hotelling's T² statistics and generating confidence ellipse/ellipsoid coordinates for multivariate data analysis and visualization.
+
+[![PyPI version](https://badge.fury.io/py/pyellipse.svg)](https://badge.fury.io/py/pyellipse)
+[![Python Versions](https://img.shields.io/pypi/pyversions/pyellipse.svg)](https://pypi.org/project/pyellipse/)
+[![License](https://img.shields.io/github/license/ChristianGoueguel/pyEllipse.svg)](https://github.com/ChristianGoueguel/pyEllipse/blob/main/LICENSE)
+![PyPI - Downloads](https://img.shields.io/pypi/dd/pyEllipse)
+![PyPI - Downloads](https://img.shields.io/pypi/dw/pyEllipse)
+![PyPI - Downloads](https://img.shields.io/pypi/dm/pyEllipse)
+![PyPI - Format](https://img.shields.io/pypi/format/pyEllipse)
+![PyPI - Status](https://img.shields.io/pypi/status/pyEllipse)
+![PyPI - Implementation](https://img.shields.io/pypi/implementation/pyEllipse)
+
+## Overview
+
+`pyEllipse` provides three main functions for analyzing multivariate data:
+
+1. __`hotelling_parameters`__ - Calculate Hotelling's T² statistics and ellipse parameters
+2. __`hotelling_coordinates`__ - Generate Hotelling's ellipse/ellipsoid coordinates from PCA/PLS scores
+3. __`confidence_ellipse`__ - Compute confidence ellipse/ellipsoid coordinates from raw data with grouping support
+
+## Installation
+
+```bash
+pip install pyEllipse
+```
+
+## Usage Examples
+
+### Example 1: Hotelling's T² statistic and confidence ellipse from PCA Scores
+
+```python
+import numpy as np
+import pandas as pd
+import matplotlib.pyplot as plt
+plt.style.use('bmh')
+from mpl_toolkits.mplot3d import Axes3D
+from sklearn.preprocessing import StandardScaler
+from sklearn.decomposition import PCA
+from pathlib import Path
+from pyEllipse import hotelling_parameters, hotelling_coordinates, confidence_ellipse
+```
+
+```python
+def load_wine_data():
+    """Load wine dataset and add cultivar labels"""
+    wine_df = pd.read_csv('data/wine.csv')
+    
+    # Add cultivar labels based on standard Wine dataset structure
+    cultivar = []
+    for i in range(len(wine_df)):
+        if i < 59:
+            cultivar.append('Cultivar 1')
+        elif i < 130:
+            cultivar.append('Cultivar 2')
+        else:
+            cultivar.append('Cultivar 3')
+    
+    wine_df['Cultivar'] = cultivar
+    return wine_df
+```
+
+```python
+wine_df = load_wine_data()
+X = wine_df.drop('Cultivar', axis=1)
+y = wine_df['Cultivar']
+
+# Perform PCA
+pca = PCA()
+SS = StandardScaler()
+X = SS.fit_transform(X)
+pca_scores = pca.fit_transform(X)
+explained_var = pca.explained_variance_ratio_
+```
+
+```python
+plt.style.use('bmh')
+# Calculate T² statistics
+results = hotelling_parameters(pca_scores, k=2)
+t2 = results['Tsquared'].values
+
+# Generate ellipse coordinates for plotting
+ellipse_95 = hotelling_coordinates(pca_scores, pcx=1, pcy=2, conf_limit=0.95)
+ellipse_99 = hotelling_coordinates(pca_scores, pcx=1, pcy=2, conf_limit=0.99)
+
+# Plot the PCA scores with Hotelling's T² ellipse
+plt.figure(figsize=(8, 6))
+scatter = plt.scatter(
+    pca_scores[:, 0], pca_scores[:, 1], 
+    c=t2, cmap='jet', alpha=0.85, s=70, label='Wine samples'
+    )
+cbar = plt.colorbar(scatter)
+cbar.set_label('Hotelling T² Statistic', rotation=270, labelpad=20)
+
+plt.plot(ellipse_95['x'], ellipse_95['y'], 'r-', linewidth=1, label='95% Confidence level')
+plt.plot(ellipse_99['x'], ellipse_99['y'], 'k-', linewidth=1, label='99% Confidence level')
+plt.xlim(-1000, 1000)
+plt.ylim(-50, 60)
+plt.xlabel(f'PC1 ({explained_var[0]*100:.2f}%)', fontsize=14, labelpad=10, fontweight='bold')
+plt.ylabel(f'PC2 ({explained_var[1]*100:.2f}%)', fontsize=14, labelpad=10, fontweight='bold')
+plt.title("Hotelling's T² Ellipse from PCA Scores", fontsize=16, pad=10, fontweight='bold')
+plt.legend(
+    loc='upper left', fontsize=10, frameon=True, framealpha=0.9, 
+    edgecolor='black', shadow=True, facecolor='white', borderpad=1
+    )
+plt.show()
+```
+
+![Hotelling Ellipse](https://raw.githubusercontent.com/ChristianGoueguel/pyEllipse/main/images/example1_hotelling_ellipse.png)
+
+### Example 2: Grouped Confidence Ellipses
+
+```python
+wine_df['PC1'] = pca_scores[:, 0]
+wine_df['PC2'] = pca_scores[:, 1]
+
+colors = ['red', 'blue', 'green']
+cultivars = wine_df['Cultivar'].unique()
+color_map = {cultivar: color for cultivar, color in zip(cultivars, colors)}
+point_colors = wine_df['Cultivar'].map(color_map)
+
+# Plott PCA scores with confidence ellipses for each cultivar
+plt.figure(figsize=(8, 6))
+
+for i, cultivar in enumerate(cultivars):
+    mask = wine_df['Cultivar'] == cultivar
+    plt.scatter(
+        wine_df.loc[mask, 'PC1'], wine_df.loc[mask, 'PC2'], # type: ignore
+        c=colors[i], alpha=0.6, s=70, label=cultivar
+        ) 
+
+ellipse_coords = confidence_ellipse(
+    data=wine_df,
+    x='PC1',
+    y='PC2',
+    group_by='Cultivar',
+    conf_level=0.95,
+    robust=True,
+    distribution='hotelling'
+)
+
+for i, cultivar in enumerate(cultivars):
+    ellipse_data = ellipse_coords[ellipse_coords['Cultivar'] == cultivar]
+    plt.plot(
+        ellipse_data['x'], ellipse_data['y'], 
+        color=colors[i], linewidth=1, linestyle='-', label=f'{cultivar} (95% CI)'
+        )
+
+plt.xlim(-1000, 1000)
+plt.ylim(-50, 60)
+plt.xlabel(f'PC1 ({explained_var[0]*100:.2f}%)', fontsize=14, labelpad=10, fontweight='bold')
+plt.ylabel(f'PC2 ({explained_var[1]*100:.2f}%)', fontsize=14, labelpad=10, fontweight='bold')
+plt.title("PCA Scores with Cultivar Group Confidence Ellipses", fontsize=16, pad=10, fontweight='bold')
+plt.legend(
+    loc='upper left', fontsize=10, frameon=True, framealpha=0.9, 
+    edgecolor='black', shadow=True, facecolor='white', borderpad=1
+    )
+plt.show()
+```
+
+![Hotelling Ellipse](https://raw.githubusercontent.com/ChristianGoueguel/pyEllipse/main/images/grouped_ellipses.png)
+
+### Example 3: Grouped 3D Confidence Ellipsoids
+
+```python
+wine_df['PC1'] = pca_scores[:, 0]
+wine_df['PC2'] = pca_scores[:, 1]
+wine_df['PC3'] = pca_scores[:, 2]
+
+colors = ['red', 'blue', 'green']
+light_colors = ['lightcoral', 'lightblue', 'lightgreen']
+cultivars = wine_df['Cultivar'].unique()
+
+ellipse_coords = confidence_ellipse(
+    data=wine_df,
+    x='PC1',
+    y='PC2',
+    z='PC3',
+    group_by='Cultivar',
+    conf_level=0.95,
+    robust=True,
+    distribution='hotelling'
+)
+
+fig = plt.figure(figsize=(10, 6), facecolor='white')
+ax = fig.add_subplot(111, projection='3d', facecolor='white')
+
+for i, cultivar in enumerate(cultivars):
+    mask = wine_df['Cultivar'] == cultivar
+    ax.scatter(
+        wine_df.loc[mask, 'PC1'], 
+        wine_df.loc[mask, 'PC2'], 
+        wine_df.loc[mask, 'PC3'], # type: ignore
+        c=colors[i], 
+        alpha=0.8, 
+        s=50, 
+        label=cultivar, 
+        edgecolors='black', 
+        linewidth=0.5
+        )
+     
+    ellipse_data = ellipse_coords[ellipse_coords['Cultivar'] == cultivar]
+    n_points = int(np.sqrt(len(ellipse_data)))
+    
+    x_2d = ellipse_data['x'].values.reshape(n_points, -1)
+    y_2d = ellipse_data['y'].values.reshape(n_points, -1)
+    z_2d = ellipse_data['z'].values.reshape(n_points, -1)
+    
+    ax.plot_surface(
+        x_2d, 
+        y_2d, 
+        z_2d, 
+        color=light_colors[i], 
+        alpha=0.4, 
+        linewidth=0, 
+        antialiased=True
+        )
+
+ax.set_xlabel(f'PC1 ({explained_var[0]*100:.2f}%)', fontsize=12, labelpad=5, fontweight='bold')
+ax.set_ylabel(f'PC2 ({explained_var[1]*100:.2f}%)', fontsize=12, labelpad=5, fontweight='bold')
+ax.set_zlabel(f'PC3 ({explained_var[2]*100:.2f}%)', fontsize=12, labelpad=1, fontweight='bold')
+ax.set_title('3D PCA Scores with 95% Confidence Ellipsoids', fontsize=16, fontweight='bold')
+ax.legend(
+    loc='upper right', fontsize=10, frameon=True, framealpha=0.9, 
+    edgecolor='black', shadow=True, facecolor='white', borderpad=1
+    )
+ax.grid(True, alpha=0.3, color='gray')
+ax.view_init(elev=20, azim=65)
+plt.tight_layout()
+plt.show()
+```
+
+![Hotelling Ellipse](https://raw.githubusercontent.com/ChristianGoueguel/pyEllipse/main/images/3d_ellipsoids.png)
+
+## Key Differences Between Functions
+
+| Feature | `hotelling_parameters` | `hotelling_coordinates` | `confidence_ellipse` |
+|---------|----------------|-----------------|---------------------|
+| __Input__ | Component scores | Component scores | Raw data |
+| __Purpose__ | T² statistics | Plot coordinates | Plot coordinates |
+| __Grouping__ | -- | -- | Yes |
+| __Robust__ | -- | -- | Yes |
+| __2D/3D__ | 2D only for ellipse params | Both | Both |
+| __Distribution__ | Hotelling only | Hotelling only | Normal or Hotelling |
+| __Use Case__ | Outlier detection, QC | Visualizing PCA | Exploratory data analysis |
+
+## When to Use Each Function
+
+### Use `hotelling_parameters` when:
+
+- You need T² statistics for outlier detection
+- You want confidence cutoff values
+- You're performing quality control or process monitoring
+- You need ellipse parameters (semi-axes lengths)
+
+### Use `hotelling_coordinates` when:
+
+- You have PCA/PLS component scores
+- You want to visualize confidence regions on score plots
+- You need precise control over which components to plot
+- You're creating publication-quality figures from multivariate models
+
+### Use `confidence_ellipse` when:
+
+- You're working with raw data (not scores)
+- You need to compare multiple groups
+- You want robust estimation for outlier-resistant analysis
+- You need flexibility in distribution choice (normal vs Hotelling)
+
+## References
+
+1. Hotelling, H. (1931). The generalization of Student's ratio. *Annals of Mathematical Statistics*, 2(3), 360-378.
+2. Brereton, R. G. (2016). Hotelling's T-squared distribution, its relationship to the F distribution and its use in multivariate space. *Journal of Chemometrics*, 30(1), 18-21.
+3. Raymaekers, J., & Rousseeuw, P. J. (2019). Fast robust correlation for high dimensional data. *Technometrics*, 63(2), 184-198.
+4. Jackson, J. E. (1991). *A User's Guide to Principal Components*. Wiley.
+

pyellipse-0.1.2.dist-info/RECORD

@@ -0,0 +1,8 @@
+pyEllipse/__init__.py,sha256=e8UsmSroKa_4DUI65geZqkqkACibcE91yuANBwbfp54,1214
+pyEllipse/confidence_ellipse.py,sha256=jPWGWN9WHvB6GzA7K6x3lJrRk8CNOMIkE_2QWTH7yRM,8700
+pyEllipse/hotelling_coordinates.py,sha256=7nBtc9KHHLCsPgswWsBj2F7iNJKxgkGQOGVLOAspTwE,5162
+pyEllipse/hotelling_parameters.py,sha256=7Xp49JWiaCJETgBE1ZDMWeJBV5Qr9dTqd35S6gVFKZg,8211
+pyellipse-0.1.2.dist-info/METADATA,sha256=X9RWd-WO6POieGkNXxEe2nakdrfJo1xmcBFFvzAQmMY,11601
+pyellipse-0.1.2.dist-info/WHEEL,sha256=M5asmiAlL6HEcOq52Yi5mmk9KmTVjY2RDPtO4p9DMrc,88
+pyellipse-0.1.2.dist-info/licenses/LICENSE,sha256=aymc_9IU1zNJ7d2BKxzdgscT-atdAp7farpWhrGnXQ8,1078
+pyellipse-0.1.2.dist-info/RECORD,,

pyellipse-0.1.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.2.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pyellipse-0.1.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Christian L. Goueguel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.