Added r-squared and principal components breakdown with variance explained

Author: Daniel15568

percentify/__init__.py

@@ -1,5 +1,5 @@
 from .core import percent, change, difference, split, display
-from .stats import vif, missing, cv, outliers
+from .stats import vif, missing, cv, outliers, r_squared, variance_explained
 
-__all__ = ["percent", "change", "difference", "split", "display", "vif", "missing", "cv", "outliers"]
+__all__ = ["percent", "change", "difference", "split", "display", "vif", "missing", "cv", "outliers", "r_squared", "variance_explained"]
 __version__ = "0.3.2"

percentify/stats.py

@@ -169,3 +169,89 @@ def _calc(s: pd.Series) -> float:
     for col in numeric.columns:
         result[col] = _round(_calc(numeric[col]), decimals)
     return result
+
+
+def r_squared(y_true: Union[pd.Series, Sequence, np.ndarray], y_pred: Union[pd.Series, Sequence, np.ndarray], decimals: Optional[int] = 2) -> float:
+    """
+    Calculate R-squared (coefficient of determination).
+
+    R² = 1 - (SS_res / SS_tot), expressed as a percentage.
+
+    Args:
+        y_true: Actual values.
+        y_pred: Predicted values.
+        decimals: Number of decimal places to round to.
+
+    Returns:
+        float: R-squared as a percentage (e.g. 87.3 means 87.3%).
+
+    Raises:
+        ValueError: If inputs have different lengths or fewer than 2 values.
+    """
+    y_true = np.asarray(y_true, dtype=float)
+    y_pred = np.asarray(y_pred, dtype=float)
+
+    if len(y_true) != len(y_pred):
+        raise ValueError("`y_true` and `y_pred` must have the same length.")
+
+    if len(y_true) < 2:
+        raise ValueError("Need at least 2 values to compute R-squared.")
+
+    ss_res = np.sum((y_true - y_pred) ** 2)
+    ss_tot = np.sum((y_true - np.mean(y_true)) ** 2)
+
+    if ss_tot == 0:
+        return 0.0
+
+    val = (1.0 - ss_res / ss_tot) * 100.0
+    return _round(val, decimals)
+
+
+def variance_explained(df: pd.DataFrame, decimals: Optional[int] = 2, n_components: Optional[int] = None) -> Dict[str, float]:
+    """
+    Calculate the percentage of variance explained by each principal component.
+
+    Performs PCA using eigendecomposition of the covariance matrix.
+
+    Args:
+        df: DataFrame with numeric columns.
+        decimals: Number of decimal places to round to.
+        n_components: Number of components to return. If None, returns all.
+
+    Returns:
+        dict: Component names mapped to their explained variance percentage.
+            e.g. {"PC1": 45.2, "PC2": 23.1, ...}
+
+    Raises:
+        ValueError: If DataFrame has fewer than 2 numeric columns or rows.
+    """
+    numeric = df.select_dtypes(include=[np.number]).dropna()
+
+    if numeric.shape[1] < 2:
+        raise ValueError("DataFrame must have at least 2 numeric columns.")
+
+    if numeric.shape[0] < 2:
+        raise ValueError("DataFrame must have at least 2 non-null rows.")
+
+    X = numeric.values.astype(float)
+    X_centered = X - X.mean(axis=0)
+
+    cov_matrix = np.cov(X_centered, rowvar=False)
+    eigenvalues, _ = np.linalg.eigh(cov_matrix)
+
+    eigenvalues = eigenvalues[::-1]
+    total = eigenvalues.sum()
+
+    if total == 0:
+        return {}
+
+    ratios = eigenvalues / total * 100.0
+
+    if n_components is not None:
+        ratios = ratios[:n_components]
+
+    result = {}
+    for i, r in enumerate(ratios):
+        result[f"PC{i + 1}"] = _round(r, decimals)
+
+    return result

tests/test_stats.py

@@ -1,7 +1,7 @@
 import pytest
 import numpy as np
 import pandas as pd
-from percentify import vif, missing, cv, outliers
+from percentify import vif, missing, cv, outliers, r_squared, variance_explained
 
 
 # ===== Fixtures =====
@@ -240,3 +240,138 @@ def test_outliers_custom_multiplier():
     strict = outliers(s, multiplier=1.0)
     loose = outliers(s, multiplier=3.0)
     assert strict >= loose
+
+
+# ===== r_squared =====
+
+def test_r_squared_perfect():
+    y = [1, 2, 3, 4, 5]
+    assert r_squared(y, y) == 100.0
+
+
+def test_r_squared_good_fit():
+    y_true = [1, 2, 3, 4, 5]
+    y_pred = [1.1, 1.9, 3.2, 3.8, 5.1]
+    result = r_squared(y_true, y_pred)
+    assert 90 < result < 100
+
+
+def test_r_squared_bad_fit():
+    y_true = [1, 2, 3, 4, 5]
+    y_pred = [5, 4, 3, 2, 1]
+    result = r_squared(y_true, y_pred)
+    assert result < 0
+
+
+def test_r_squared_with_numpy():
+    y_true = np.array([1, 2, 3, 4, 5])
+    y_pred = np.array([1, 2, 3, 4, 5])
+    assert r_squared(y_true, y_pred) == 100.0
+
+
+def test_r_squared_with_series():
+    y_true = pd.Series([1, 2, 3, 4, 5])
+    y_pred = pd.Series([1.1, 2.1, 2.9, 4.0, 5.1])
+    result = r_squared(y_true, y_pred)
+    assert result > 0
+
+
+def test_r_squared_mismatched_length():
+    with pytest.raises(ValueError):
+        r_squared([1, 2, 3], [1, 2])
+
+
+def test_r_squared_too_few():
+    with pytest.raises(ValueError):
+        r_squared([1], [1])
+
+
+def test_r_squared_custom_decimals():
+    y_true = [1, 2, 3, 4, 5]
+    y_pred = [1.1, 1.9, 3.2, 3.8, 5.1]
+    result = r_squared(y_true, y_pred, decimals=4)
+    str_val = str(result)
+    if "." in str_val:
+        assert len(str_val.split(".")[1]) <= 4
+
+
+# ===== variance_explained =====
+
+def test_variance_explained_returns_all_components():
+    np.random.seed(42)
+    df = pd.DataFrame({
+        "a": np.random.randn(100),
+        "b": np.random.randn(100),
+        "c": np.random.randn(100),
+    })
+    result = variance_explained(df)
+    assert len(result) == 3
+    assert "PC1" in result
+    assert "PC2" in result
+    assert "PC3" in result
+
+
+def test_variance_explained_sums_to_100():
+    np.random.seed(42)
+    df = pd.DataFrame({
+        "a": np.random.randn(100),
+        "b": np.random.randn(100),
+        "c": np.random.randn(100),
+    })
+    result = variance_explained(df, decimals=None)
+    assert pytest.approx(sum(result.values()), abs=0.01) == 100.0
+
+
+def test_variance_explained_sorted_descending():
+    np.random.seed(42)
+    df = pd.DataFrame({
+        "a": np.random.randn(100),
+        "b": np.random.randn(100),
+        "c": np.random.randn(100),
+    })
+    result = variance_explained(df)
+    values = list(result.values())
+    assert values == sorted(values, reverse=True)
+
+
+def test_variance_explained_correlated_features():
+    np.random.seed(42)
+    x = np.random.randn(100)
+    df = pd.DataFrame({
+        "a": x,
+        "b": x + np.random.randn(100) * 0.01,
+        "c": np.random.randn(100),
+    })
+    result = variance_explained(df)
+    assert result["PC1"] > 50
+
+
+def test_variance_explained_n_components():
+    np.random.seed(42)
+    df = pd.DataFrame({
+        "a": np.random.randn(100),
+        "b": np.random.randn(100),
+        "c": np.random.randn(100),
+    })
+    result = variance_explained(df, n_components=2)
+    assert len(result) == 2
+    assert "PC1" in result
+    assert "PC2" in result
+    assert "PC3" not in result
+
+
+def test_variance_explained_too_few_columns():
+    df = pd.DataFrame({"a": [1, 2, 3]})
+    with pytest.raises(ValueError):
+        variance_explained(df)
+
+
+def test_variance_explained_ignores_non_numeric():
+    np.random.seed(42)
+    df = pd.DataFrame({
+        "a": np.random.randn(50),
+        "b": np.random.randn(50),
+        "name": ["foo"] * 50,
+    })
+    result = variance_explained(df)
+    assert len(result) == 2