final docs clean up

Author: Daniel15568

.github/workflows/docs.yml

@@ -0,0 +1,37 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches: ["main"]
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Configure Git Credentials
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Cache MkDocs build
+        uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ github.sha }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+
+      - name: Install docs dependencies
+        run: pip install mkdocs-material
+
+      - name: Build and deploy to gh-pages
+        run: mkdocs gh-deploy --force

README.md

@@ -1,186 +1,84 @@
 #                                               Percentify
 
-[![Downloads](https://static.pepy.tech/badge/percentify)](https://pepy.tech/project/percentify )
+[![Downloads](https://static.pepy.tech/badge/percentify)](https://pepy.tech/project/percentify)
 [![PyPI version](https://img.shields.io/pypi/v/percentify.svg?style=flat&color=blue)](https://pypi.org/project/percentify/)
 [![Python Versions](https://img.shields.io/pypi/pyversions/percentify.svg?style=flat&color=green)](https://pypi.org/project/percentify/)
 [![License](https://img.shields.io/pypi/l/percentify.svg?style=flat&color=orange)](LICENSE)
+[![Docs](https://img.shields.io/badge/docs-percentify-14b8a6)](https://data-centt.github.io/percentify/)
 [![Build Status](https://github.com/data-centt/percentify/actions/workflows/python-app.yml/badge.svg)](https://github.com/data-centt/percentify/actions/workflows/python-app.yml)
 
 **Percentify is a niche data science library for practitioners and learners alike, drawing its main dependencies from pandas and numpy, and including everyday statistics.**
 
-Following the **Pareto principle**, Percentify brings the 20% of operations that make up 80% of daily data work to the forefront, each as a single, readable function call. No more digging through six-line recipes and hard-to-remember import paths for the checks you run on every dataset.
+Following the **Pareto principle**, Percentify brings the 20% of operations that make up 80% of daily data work to the forefront — each as a single, readable function call. It does not aim to compete with pandas, scipy, statsmodels, or scikit-learn; it stands on their shoulders and works alongside them, naming the library each function draws from so you always know where to dig deeper.
 
-Percentify **does not aim to compete** with pandas, scipy, statsmodels, or scikit-learn; it stands on their shoulders and works *alongside* them. The goal is to make the core concepts easy to learn, quick to use, and simple to remember. Every function names the underlying library it draws from, so the moment you need the full, configurable version, you know exactly where to go.
+## 📖 Documentation
 
-Every function takes a pandas `DataFrame` (or `Series`) and hands back a clean `DataFrame` you can read, sort, or feed straight into the next step.
-
----
+**Full guide, every function, and live examples → [data-centt.github.io/percentify](https://data-centt.github.io/percentify/)**
 
 ## 📦 Installation
-```
+
+```bash
 pip install percentify
 ```
 
 Requires `numpy` and `pandas`.
 
----
-
-## 📊 The Toolkit
-
-### `change`: Percentage Change
-Two numbers, two columns, or a whole series at once.
-```python
-from percentify import change
-
-change(100, 150)                       # → 50.0   (a 50% increase)
+## Quick example
 
-change(df["forecast"], df["actual"])   # element-wise % change between two columns
-
-change(df["revenue"])                  # period-over-period % change down the column
-# 0     NaN
-# 1    50.0
-# 2   -40.0
-
-change(df)                             # every numeric column at once
-```
-
-### `vif`: Variance Inflation Factor (Multicollinearity)
-The classic multicollinearity check, without the six-line loop.
-> _Similar Concept:_ `statsmodels.stats.outliers_influence.variance_inflation_factor`
-```python
-from percentify import vif
-
-vif(df)
-#   feature   VIF
-# 0  income  8.40
-# 1    debt  7.90
-# 2     age  1.20
-
-vif(df, flag=5.0)   # only rows above the threshold (your problem columns)
-```
-
-### `missing`: Missing Data Profiling
-No more `df.isnull().sum() / len(df) * 100`.
-> _Underlying library:_ `pandas.DataFrame.isna`
 ```python
+import pandas as pd
 from percentify import missing
 
+df = pd.DataFrame({
+    "salary": [50000, None, 60000, None],
+    "age":    [25, 30, None, 40],
+    "city":   ["NY", "LA", "SF", "LA"],
+})
+
 missing(df)
 #    column  missing_pct
-# 0  salary        12.40
-# 1     age         3.10
-# 2    name         0.00
+# 0  salary         50.0
+# 1     age         25.0
+# 2    city          0.0
 ```
 
-### `cv`: Coefficient of Variation
-Relative variability (std ÷ mean), as a percentage.
-> _Underlying library:_ `scipy.stats.variation`
-```python
-from percentify import cv
+One import, one line — a clean, sorted DataFrame you can read or feed into the next step.
 
-cv(df["salary"])   # → 34.2   (a single Series returns a number)
-cv(df)             # → DataFrame of every numeric column, most variable first
-```
+## What's inside
 
-### `outliers`: Percentage of Outliers (IQR Method)
-Stop rewriting the IQR bounds from scratch.
-> _Similar Concept:_ `scipy.stats.iqr`
-```python
-from percentify import outliers
+| Function | What it answers |
+|---|---|
+| `change` | Growth — as numbers, columns, or a whole series |
+| `vif` | Which features are collinear? |
+| `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? |
+| `difference` | How far apart are two values or columns? |
+| `split` | How does a total divide across weights or groups? |
+| `display` | Format numbers or a column as clean "%" strings |
 
-outliers(df["salary"])   # → 4.7
-outliers(df)             # → DataFrame of every numeric column
-```
-
-### `r_squared`: R-Squared
-```python
-from percentify import r_squared
-
-r_squared(y_true, y_pred)   # → 87.3
-```
-> _Similar Concepts:_ `sklearn.metrics.r2_score`
-
-### `pca_variance`: PCA Variance Breakdown
-Columns are standardized by default, so a feature measured in large units (e.g.
-dollars) can't dominate the result just because of its scale. Pass
-`standardize=False` for covariance-based PCA on the raw values.
-> _Similar Concept:_ `sklearn.decomposition.PCA` (`.explained_variance_ratio_`)
-```python
-from percentify import pca_variance
-
-pca_variance(df)
-#   component  variance_explained  cumulative
-# 0       PC1               45.2        45.2
-# 1       PC2               23.1        68.3
-# 2       PC3               12.8        81.1
-
-pca_variance(df, standardize=False)   # covariance-based (scale-sensitive)
-```
-
-### `difference`: Symmetric % Difference
-How far apart two values or columns are, regardless of direction (use `change` when direction matters).
-> _Similar Concept:_ `numpy` / `pandas` arithmetic
-```python
-from percentify import difference
-
-difference(10, 20)   # → 66.67  (order-independent)
-
-difference(df["sensor_a"], df["sensor_b"])   # element-wise % gap between two columns
-```
-
-### `split`: Proportional Allocation
-Distribute a total across weights or groups.
-> _Similar Concept:_ `numpy` / `pandas` arithmetic
-```python
-from percentify import split
-
-split(10000, [2, 3, 5])           # → [2000.0, 3000.0, 5000.0]
-
-split(10000, df["population"])    # allocate a budget by population (aligned Series)
-```
-
-### `display`: Percentage Formatting
-Turn numbers or a whole column into clean "%" strings for reports.
-> _Similar Concept:_ `pandas.Series.map` + string formatting
-```python
-from percentify import display
-
-display(0.45, multiply=True)              # → "45.0%"
-
-display(df["conv_rate"], multiply=True)   # → column of "4.5%" strings
-```
-
----
+→ See the **[documentation](https://data-centt.github.io/percentify/)** for a worked, real-output example of every function.
 
 ## 🛟 Friendly by design
 
-Built for early-career analysts as much as seasoned ones:
-
-- **No cryptic tracebacks.** Hand it a text column where numbers are needed and you get a clear `PercentifyWarning` ("numeric columns required") plus an empty result — not an Arrow/NumPy stack trace.
-- **Sensible defaults.** Results come back sorted worst-first (most collinear, most missing, most variable), and PCA is standardized out of the box.
+- **No cryptic tracebacks.** Hand a function a text column where numbers are needed and you get a clear `PercentifyWarning`, not an Arrow/NumPy stack trace.
+- **Sensible defaults.** Results come back sorted worst-first, and PCA is standardized out of the box.
 - **DataFrames everywhere**, so the output drops straight into your notebook, your next filter, or your model.
 
-Catch or silence the warnings like any other:
-```python
-import warnings
-from percentify import PercentifyWarning
-
-warnings.filterwarnings("ignore", category=PercentifyWarning)
-```
-
----
-
 ## 🤝 Contributing
 
 Contributions are welcome — but they must follow the repo's guiding principle:
 
 > **Keep each method as direct-to-output as possible.** A percentify function should return the single most common answer in one line, and point users to the underlying library (pandas, scipy, statsmodels, scikit-learn) for the full, configurable version when the simplest output isn't what they're after.
 
 If your idea keeps things that simple and direct:
+
 - Open an issue first to discuss it
 - Fork the repo
 - Create a branch
 - Commit your changes
 - Open a pull request
 
-> Anything that adds knobs and options for their own sake, or duplicates what the parent libraries already do well, is out of scope please those cases should point to the source library instead.
+Anything that adds knobs and options for their own sake, or duplicates what the parent libraries already do well, is out of scope — those cases should point to the source library instead.

percentify/stats.py

@@ -224,7 +224,9 @@ def cv(data: Union[pd.Series, pd.DataFrame], decimals: Optional[int] = 2) -> Uni
     return result.sort_values("cv", ascending=False).reset_index(drop=True)
 
 
-def outliers(data: Union[pd.Series, pd.DataFrame], decimals: Optional[int] = 2, multiplier: float = 1.5) -> Union[float, pd.DataFrame]:
+def outliers(
+    data: Union[pd.Series, pd.DataFrame], decimals: Optional[int] = 2, multiplier: float = 1.5
+) -> Union[float, pd.DataFrame]:
     """
     Calculate the percentage of outliers using the IQR method.
 
@@ -272,7 +274,11 @@ def _calc(s: pd.Series) -> float:
     return result.sort_values("outlier_pct", ascending=False).reset_index(drop=True)
 
 
-def r_squared(y_true: Union[pd.Series, Sequence, np.ndarray], y_pred: Union[pd.Series, Sequence, np.ndarray], decimals: Optional[int] = 2) -> float:
+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).
 
@@ -311,7 +317,10 @@ def r_squared(y_true: Union[pd.Series, Sequence, np.ndarray], y_pred: Union[pd.S
     return _round(val, decimals)
 
 
-def pca_variance(df: pd.DataFrame, decimals: Optional[int] = 2, n_components: Optional[int] = None, standardize: bool = True) -> pd.DataFrame:
+def pca_variance(
+    df: pd.DataFrame, decimals: Optional[int] = 2, n_components: Optional[int] = None,
+    standardize: bool = True,
+) -> pd.DataFrame:
     """
     Calculate the percentage of variance explained by each principal component.