pca_doadings implemented. all bugs fixed and added in documentation

Author: Daniel15568

README.md

@@ -61,8 +61,8 @@ One import, one line. A clean, sorted DataFrame you can read or feed into the ne
 | `missing` | How much of each column is missing? |
 | `cv` | How variable is each column, relative to its mean? |
 | `outliers` | What percentage of each column are outliers? |
-| `r_squared` | How well do predictions fit? |
 | `pca_variance` | How much variance does each principal component explain? |
+| `pca_loadings` | What does each principal component consist of? |
 | `imbalance` | How skewed are the classes in a target column? |
 | `difference` | How far apart are two values or columns? |
 | `split` | How does a total divide across weights or groups? |

docs/documentation.md

@@ -11,7 +11,7 @@ pip install percentify
 Percentify requires `numpy` and `pandas`.
 
 ```python
-from percentify import change, vif, missing, cv, outliers, r_squared, pca_variance
+from percentify import change, vif, missing, cv, outliers, pca_variance, pca_loadings
 ```
 
 ---
@@ -353,53 +353,68 @@ Tune the sensitivity with `multiplier` (e.g. `multiplier=3.0` for a looser bound
 
 ---
 
-## `r_squared`
+## `pca_variance`
 
-R-squared (coefficient of determination), as a percentage.
+The percentage of variance explained by each principal component, plus a running cumulative total.
 
 !!! tip "Similar concept"
-    `sklearn.metrics.r2_score`
+    `sklearn.decomposition.PCA` (`.explained_variance_ratio_`)
 
 **Signature**
 
 ```python
-r_squared(y_true, y_pred, decimals=2)
+pca_variance(df, decimals=2, n_components=None, standardize=True)
 ```
 
 **Example**
 
 ```python
-from percentify import r_squared
+import numpy as np, pandas as pd
+from percentify import pca_variance
+
+np.random.seed(7)
+base = np.random.randn(200)
+df = pd.DataFrame({
+    "height": base + np.random.randn(200) * 0.3,
+    "weight": base + np.random.randn(200) * 0.3,   # shares a signal with height
+    "noise":  np.random.randn(200),
+})
 
-r_squared([1, 2, 3, 4, 5], [1.1, 1.9, 3.2, 3.8, 5.1])
+pca_variance(df)
 ```
 
 ```text
-98.9
+  component  variance_explained  cumulative
+0       PC1               64.04       64.04
+1       PC2               33.34       97.38
+2       PC3                2.62      100.00
 ```
 
-The predictions explain 98.9% of the variance in the true values. Accepts lists, numpy arrays, or pandas Series.
+Read the `cumulative` column to decide how many components to keep — here PC1 + PC2 already capture 97.4% of the variance.
+
+!!! warning "Standardization matters"
+    By default `standardize=True`, so each column is scaled to unit variance first. This stops a column measured in large units (e.g. dollars) from dominating purely because of its scale. Pass `standardize=False` for covariance-based PCA on the raw values.
 
 ---
 
-## `pca_variance`
+## `pca_loadings`
 
-The percentage of variance explained by each principal component, plus a running cumulative total.
+Principal component loadings: what each component is *made of*. Where `pca_variance` tells you how important each PC is, `pca_loadings` shows how much each original feature contributes to it, as a feature-by-component table.
 
 !!! tip "Similar concept"
-    `sklearn.decomposition.PCA` (`.explained_variance_ratio_`)
+    `sklearn.decomposition.PCA` (`.components_`)
 
 **Signature**
 
 ```python
-pca_variance(df, decimals=2, n_components=None, standardize=True)
+pca_loadings(df, decimals=2, n_components=None, standardize=True)
 ```
 
 **Example**
 
 ```python
 import numpy as np, pandas as pd
-from percentify import pca_variance
+from percentify import pca_loadings
 
 np.random.seed(7)
 base = np.random.randn(200)
@@ -409,20 +424,20 @@ df = pd.DataFrame({
     "noise":  np.random.randn(200),
 })
 
-pca_variance(df)
+pca_loadings(df)
 ```
 
 ```text
-  component  variance_explained  cumulative
-0       PC1               64.04       64.04
-1       PC2               33.34       97.38
-2       PC3                2.62      100.00
+feature  PC1   PC2   PC3
+ height 0.71  0.01 -0.71
+ weight 0.71 -0.02  0.71
+  noise 0.01  1.00  0.02
 ```
 
-Read the `cumulative` column to decide how many components to keep — here PC1 + PC2 already capture 97.4% of the variance.
+Read down a column: PC1 is `height` and `weight` together (both `0.71`), while `noise` sits near `0`, so PC1 is the shared height/weight signal. Standardized by default, matching `pca_variance`.
 
-!!! warning "Standardization matters"
-    By default `standardize=True`, so each column is scaled to unit variance first. This stops a column measured in large units (e.g. dollars) from dominating purely because of its scale. Pass `standardize=False` for covariance-based PCA on the raw values.
+!!! note "Sign is arbitrary"
+    A component and its negation are equivalent, so the sign of a loading is not meaningful on its own. Only the relative signs and magnitudes *within* a column matter.
 
 ---
 

docs/index.md

@@ -60,8 +60,8 @@ One import, one line. A clean, sorted DataFrame you can read or feed straight in
 | `missing` | How much of each column is missing? |
 | `cv` | How variable is each column, relative to its mean? |
 | `outliers` | What percentage of each column are outliers? |
-| `r_squared` | How well do predictions fit? |
 | `pca_variance` | How much variance does each principal component explain? |
+| `pca_loadings` | What does each principal component consist of? |
 | `imbalance` | How skewed are the classes in a target column? |
 | `difference` | How far apart are two values or columns (regardless of direction)? |
 | `split` | How does a total divide across weights or groups? |

percentify/__init__.py

@@ -1,12 +1,12 @@
 from .profiling import profiler, ProfileReport, Finding
 from .stats import (
-    change, vif, missing, cv, outliers, r_squared, pca_variance, imbalance,
+    change, vif, missing, cv, outliers, pca_variance, pca_loadings, imbalance,
     difference, split, display, PercentifyWarning,
 )
 
 __all__ = [
     "profiler", "ProfileReport", "Finding",
-    "change", "vif", "missing", "cv", "outliers", "r_squared", "pca_variance", "imbalance",
+    "change", "vif", "missing", "cv", "outliers", "pca_variance", "pca_loadings", "imbalance",
     "difference", "split", "display", "PercentifyWarning",
 ]
 __version__ = "1.0.0"

percentify/stats.py

@@ -1,6 +1,6 @@
 import functools
 import warnings
-from typing import Optional, Sequence, Union
+from typing import Optional, Union
 
 import numpy as np
 import pandas as pd
@@ -324,50 +324,6 @@ def _calc(s: pd.Series) -> float:
     return result.sort_values("outlier_pct", ascending=False).reset_index(drop=True)
 
 
-@_backend_aware
-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 are non-numeric, differ in length, or have < 2 values.
-    """
-    try:
-        y_true = np.asarray(y_true, dtype=float)
-        y_pred = np.asarray(y_pred, dtype=float)
-    except (ValueError, TypeError):
-        raise ValueError("r_squared expects numeric values, but got non-numeric input.")
-
-    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)
-
-
 @_backend_aware
 def pca_variance(
     df: pd.DataFrame, decimals: Optional[int] = 2, n_components: Optional[int] = None,
@@ -443,6 +399,77 @@ def pca_variance(
     })
 
 
+@_backend_aware
+def pca_loadings(
+    df: pd.DataFrame, decimals: Optional[int] = 2, n_components: Optional[int] = None,
+    standardize: bool = True,
+) -> pd.DataFrame:
+    """
+    Principal component loadings: how much each feature contributes to each PC.
+
+    Returns the eigenvectors of the (optionally standardized) covariance matrix
+    as a feature x component table. Read down a column to see what a component
+    is made of. Columns are standardized first by default (matching
+    pca_variance); pass standardize=False for covariance-based loadings.
+
+    Non-numeric columns are ignored. If fewer than 2 usable numeric columns are
+    available, a warning is raised and an empty DataFrame is returned.
+
+    Args:
+        df: DataFrame with numeric columns.
+        decimals: Number of decimal places to round to.
+        n_components: Number of components (columns) to return. If None, all.
+        standardize: If True (default), scale each column to unit variance first.
+
+    Returns:
+        DataFrame with a "feature" column followed by PC1, PC2, ... loadings.
+        Note: the sign of a component is arbitrary, so only the relative signs
+        and magnitudes within a column are meaningful.
+    """
+    if not isinstance(df, pd.DataFrame):
+        raise TypeError(f"pca_loadings expects a pandas DataFrame, got {type(df).__name__}.")
+
+    empty = pd.DataFrame(columns=["feature"])
+    numeric = df.select_dtypes(include=[np.number]).dropna()
+
+    if numeric.shape[1] < 2:
+        _warn("Numeric columns required: pca_loadings needs at least 2 numeric columns.")
+        return empty
+
+    if numeric.shape[0] < 2:
+        _warn("Not enough data: need at least 2 complete (non-null) rows.")
+        return empty
+
+    cols = numeric.columns.tolist()
+    X = numeric.values.astype(float)
+
+    if standardize:
+        keep = X.std(axis=0, ddof=1) > 0
+        if keep.sum() < 2:
+            _warn("Numeric columns required: after dropping constant (zero-variance) "
+                  "columns, fewer than 2 columns remain to standardize for PCA.")
+            return empty
+        cols = [c for c, k in zip(cols, keep) if k]
+        X = X[:, keep]
+        X = (X - X.mean(axis=0)) / X.std(axis=0, ddof=1)
+
+    eigenvalues, eigenvectors = np.linalg.eigh(np.cov(X, rowvar=False))
+
+    if eigenvalues.sum() == 0:
+        _warn("All numeric columns are constant - there are no components to describe.")
+        return empty
+
+    order = np.argsort(eigenvalues)[::-1]
+    eigenvectors = eigenvectors[:, order]
+    if n_components is not None:
+        eigenvectors = eigenvectors[:, :n_components]
+
+    result = pd.DataFrame({"feature": cols})
+    for i in range(eigenvectors.shape[1]):
+        result[f"PC{i + 1}"] = [_round(float(v), decimals) for v in eigenvectors[:, i]]
+    return result
+
+
 @_backend_aware
 def imbalance(data, decimals: Optional[int] = 2) -> pd.DataFrame:
     """

tests/test_polars.py

@@ -4,8 +4,8 @@
 pl = pytest.importorskip("polars")
 import pandas as pd  # noqa: E402
 from percentify import (  # noqa: E402
-    change, vif, missing, cv, outliers, r_squared,
-    pca_variance, imbalance, difference, split, display,
+    change, vif, missing, cv, outliers,
+    pca_variance, pca_loadings, imbalance, difference, split, display,
 )
 
 
@@ -60,6 +60,19 @@ def test_pca_variance_polars():
     assert result.columns == ["component", "variance_explained", "cumulative"]
 
 
+def test_pca_loadings_polars():
+    np.random.seed(1)
+    base = np.random.randn(80)
+    df = pl.DataFrame({
+        "a": base + np.random.randn(80) * 0.05,
+        "b": base + np.random.randn(80) * 0.05,
+        "c": np.random.randn(80),
+    })
+    result = pca_loadings(df)
+    assert isinstance(result, pl.DataFrame)
+    assert result.columns == ["feature", "PC1", "PC2", "PC3"]
+
+
 # ===== Series in -> scalar out =====
 
 def test_cv_polars_series_returns_float():
@@ -70,12 +83,6 @@ def test_outliers_polars_series_returns_float():
     assert isinstance(outliers(pl.Series([1.0, 2, 3, 4, 5, 6, 100])), float)
 
 
-def test_r_squared_polars_series():
-    result = r_squared(pl.Series([1.0, 2, 3, 4, 5]), pl.Series([1.1, 1.9, 3.2, 3.8, 5.1]))
-    assert isinstance(result, float)
-    assert 90 < result < 100
-
-
 # ===== Series in -> polars Series out =====
 
 def test_change_polars_period_over_period():