Merge pull request #1 from data-centt/main

compare

Author: dmitriy1ikobe

CONTRIBUTING.md

@@ -0,0 +1,30 @@
+# Contributing to Percentify
+
+Thank you for your interest in contributing to Percentify! We welcome contributions, but ask that you follow the project's guiding principles to keep the library focused and simple.
+
+## Guiding Principles
+
+Percentify is built on the idea of simplicity and directness. 
+
+> 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.
+
+- **No unnecessary knobs and options**: Anything that adds parameters for their own sake, or duplicates what the parent libraries already do well, is out of scope. For those cases, users should be pointed to the source library instead.
+- **Keep it compact**: We try to keep the API surface compact on purpose. Please discuss big new features in an issue before writing code.
+
+## Technical Requirements
+
+**It must support Polars.**
+Every function in Percentify accepts both pandas and Polars objects (via the `@_backend_aware` decorator) and returns the same kind. Any new contribution must maintain this parity. You should not require the user to manually convert between backends or pass specific flags.
+
+## Contribution Workflow
+
+If your idea keeps things simple, direct, and adheres to the principles above, here is how you can contribute:
+
+1. **Discuss first**: Open an issue to discuss your proposed change or feature. This saves time and ensures your contribution aligns with the project's goals.
+2. **Fork and Branch**: Fork the repository and create a new branch for your feature or bugfix.
+3. **Develop**: Write your code, ensuring it supports both pandas and Polars.
+4. **Test**: (Include any testing guidelines if applicable, e.g., using `pytest`).
+5. **Commit and Push**: Commit your changes with clear, descriptive commit messages.
+6. **Pull Request**: Open a pull request against the main branch. Reference the issue you opened in step 1.
+
+We look forward to reviewing your contributions!

README.md

@@ -1,4 +1,3 @@
-
 <p align="center">
   <img src="https://raw.githubusercontent.com/data-centt/percentify/main/asset/log.png" alt="Percentify logo" height="140">
 </p>
@@ -19,7 +18,7 @@ Exploratory stats and data-quality diagnostics for pandas and **Polars** DataFra
 
 Where a function wraps an existing library (pandas, scipy, statsmodels, scikit-learn), it names it, so you always know where to dig deeper.
 
-## ⭐ The flagship: `profiler`
+## ⭐  `profiler`
 
 **pandas `.describe()` tells you what your data _is_. `profiler()` tells you what to _do_ about it:** every issue ranked worst-first, each with its fix.
 
@@ -48,6 +47,17 @@ pip install percentify
 
 Requires Python 3.10+, `numpy`, and `pandas` 2.0+.
 
+## How to use percentify
+
+Import the function that matches the question you want to answer, pass in a pandas or Polars object, and use the returned DataFrame or scalar directly in your notebook, report, or pipeline.
+
+```python
+from percentify import missing, profiler
+
+missing(df)                  # quick column-level check
+profiler(df, target="churn")  # ranked data-quality issues and fixes
+```
+
 ## Quick example
 
 ```python
@@ -69,6 +79,124 @@ missing(df)
 
 One import, one line. A clean, sorted DataFrame you can read or feed into the next step.
 
+## Examples
+
+These are short, recipe-style examples that go beyond the one-liner above and are intentionally not covered in the [documentation](https://data-centt.github.io/percentify/documentation/). The docs show each function in isolation; these show how to chain them into a real workflow.
+
+### A 30-second data-quality gate
+
+Drop this into CI to block training on a dataset that isn't ready:
+
+```python
+import pandas as pd
+from percentify import profiler
+
+df = pd.read_parquet("train.parquet")
+report = profiler(df, target="label")
+
+assert report.errors.empty, report.to_frame()
+assert report.health >= 80, f"health too low: {report.health}"
+```
+
+### Rank correlations by significance
+
+Pull the pairs that are both strong *and* unlikely to be noise:
+
+```python
+import pandas as pd
+from percentify import correlate
+
+df = pd.DataFrame({
+    "x":   range(50),
+    "y":   [v * 0.9 + (v % 3) for v in range(50)],
+    "z":   [v * 0.05 for v in range(50)],
+    "w":   [v % 7 for v in range(50)],
+})
+
+print(correlate(df).sort_values("p_value").head(5))
+```
+
+### Build a transform pipeline from `skew_report`
+
+Let `skew_report` tell you what to apply, then apply it:
+
+```python
+import numpy as np
+import pandas as pd
+from percentify import skew_report
+
+df = pd.DataFrame({
+    "income": [30_000, 35_000, 1_200_000, 40_000, 28_000],
+    "visits": [1, 1, 1, 50, 2],
+})
+
+plan = skew_report(df)
+print(plan[["feature", "skew", "suggested_transform"]])
+#    feature   skew suggested_transform
+# 0   income  2.27              log1p
+# 1   visits  2.19              log1p
+
+df["income_log"] = np.log1p(df["income"])     # numpy / pandas, not percentify
+df["visits_log"] = np.log1p(df["visits"])
+```
+
+### Interpret PCA with both calls
+
+Variance tells you *how much* of the signal each axis carries; loadings tell you *what it means*:
+
+```python
+import pandas as pd
+from percentify import pca_variance, pca_loadings
+
+df = pd.DataFrame({
+    "height_cm": [160, 170, 180, 175, 165],
+    "weight_kg": [55,  68,  82,  74,  60],
+    "age":       [25,  35,  45,  30,  28],
+})
+
+print(pca_variance(df))    # PC1 carries most of the variance
+print(pca_loadings(df))    # PC1 = (height, weight) with similar signs
+```
+
+### Drop collinear columns before modelling
+
+Use `vif` with a threshold to get a drop-list you can feed straight into `df.drop`:
+
+```python
+import pandas as pd
+from percentify import vif
+
+df = pd.DataFrame({
+    "price":  [10, 12, 11, 13, 9,  14, 8,  12],
+    "cost":   [ 6,  7,  7,  8, 5,   8, 4,   7],   # tracks price
+    "margin": [ 4,  5,  4,  5, 4,   6, 4,   5],   # = price - cost
+    "stock":  [100, 80, 90, 70, 110, 60, 120, 85],
+})
+
+to_drop = vif(df, flag=5.0)["feature"].tolist()
+print(to_drop)                # e.g. ['cost', 'margin']
+clean = df.drop(columns=to_drop)
+```
+
+### Month-over-month KPI table
+
+`change` over a DataFrame applies period-over-period growth to every numeric column at once:
+
+```python
+import pandas as pd
+from percentify import change
+
+kpis = pd.DataFrame({
+    "revenue": [100, 120, 150, 135, 180],
+    "signups": [400, 420, 470, 460, 510],
+}, index=["Jan", "Feb", "Mar", "Apr", "May"])
+
+print(change(kpis))
+```
+
+- [Worked examples for every function](https://data-centt.github.io/percentify/documentation/)
+- [Project documentation](https://data-centt.github.io/percentify/)
+
 ## What's inside
 
 | Function | What it answers |
@@ -114,6 +242,3 @@ If your idea keeps things that simple and direct:
 - 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; those cases should point to the source library instead.
-I try to keep it compact on purpose, to discuss big new features first.