vistaar 0.3.1__tar.gz

vistaar-0.3.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MyDataIQ contributors
+
+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.

vistaar-0.3.1/MANIFEST.in

@@ -0,0 +1,24 @@
+include LICENSE
+include README.md
+include pyproject.toml
+include VISTAAR_User_Guide.md
+include VISTAAR_User_Guide.pdf
+recursive-include docs *.md
+recursive-include examples *.ipynb
+recursive-include tests *.py
+recursive-include vistaar *.py *.csv *.svg *.typed
+
+prune dist
+prune uploads
+prune reports
+prune .venv
+global-exclude *.html
+global-exclude *.xlsx
+global-exclude *.xls
+global-exclude *.joblib
+global-exclude *.png
+global-exclude *.whl
+global-exclude *.tar.gz
+global-exclude *.pyc
+global-exclude .DS_Store
+recursive-exclude * __pycache__

vistaar-0.3.1/PKG-INFO

@@ -0,0 +1,237 @@
+Metadata-Version: 2.4
+Name: vistaar
+Version: 0.3.1
+Summary: Automated profiling, micro-segmentation, conversion lift, and model explanations for tabular data.
+Author-email: Chinmay Anand <mail@chinmayanand.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/thechinmayanand/vistaar
+Project-URL: Source, https://github.com/thechinmayanand/vistaar
+Project-URL: Release, https://github.com/thechinmayanand/vistaar/releases/tag/v0.3.1
+Keywords: analytics,segmentation,conversion,lift,shap,campaign,uplift
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Requires-Dist: scipy>=1.10
+Requires-Dist: scikit-learn>=1.3
+Requires-Dist: statsmodels>=0.14
+Requires-Dist: plotly>=5.18
+Requires-Dist: openpyxl>=3.1
+Requires-Dist: tqdm>=4.66
+Provides-Extra: ml
+Requires-Dist: xgboost>=2.0; extra == "ml"
+Requires-Dist: lightgbm>=4.0; extra == "ml"
+Requires-Dist: catboost>=1.2; extra == "ml"
+Provides-Extra: shap
+Requires-Dist: shap>=0.44; extra == "shap"
+Provides-Extra: spark
+Requires-Dist: pyspark>=3.4; extra == "spark"
+Provides-Extra: hdbscan
+Requires-Dist: hdbscan>=0.8.33; extra == "hdbscan"
+Provides-Extra: all
+Requires-Dist: xgboost>=2.0; extra == "all"
+Requires-Dist: lightgbm>=4.0; extra == "all"
+Requires-Dist: catboost>=1.2; extra == "all"
+Requires-Dist: shap>=0.44; extra == "all"
+Requires-Dist: pyspark>=3.4; extra == "all"
+Requires-Dist: hdbscan>=0.8.33; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: nbformat>=5; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=5; extra == "dev"
+Dynamic: license-file
+
+# VISTAAR
+
+VISTAAR profiles a conversion table, finds interpretable micro-segments, and reports lift, significance, and ranked opportunities. Pass a pandas or PySpark DataFrame and a binary target. The library stays local: no API key, no cloud service.
+
+The numbers are observational. Relative lift is a segment's conversion rate divided by the overall baseline. Hypothesis tests compare the segment with its complement (everyone else), not with a baseline that includes the segment. A holdout split is used whenever the table is large enough, so the significance flag is not computed on the same rows that chose the rule. Scenario sizing is arithmetic. None of this is a causal effect.
+
+## Install
+
+```bash
+pip install vistaar
+pip install "vistaar[all]"
+```
+
+Optional extras:
+
+| Extra | What it adds |
+| --- | --- |
+| `shap` | SHAP explanations |
+| `ml` | XGBoost, LightGBM, CatBoost |
+| `hdbscan` | Density clustering |
+| `spark` | PySpark, for machines that do not already have it |
+| `all` | All of the above |
+
+```bash
+pip install "vistaar[shap]"
+```
+
+Python 3.10 or newer. Core dependencies are pandas, NumPy, SciPy, scikit-learn, statsmodels, Plotly, openpyxl, and tqdm. SHAP, gradient-boosted libraries, HDBSCAN, and PySpark are imported only when you use them.
+
+From git, with every optional extra:
+
+```bash
+pip install "git+https://github.com/thechinmayanand/vistaar.git#egg=vistaar[all]"
+```
+
+GitHub release (wheel and sdist): https://github.com/thechinmayanand/vistaar/releases/tag/v0.3.1
+
+From a clone, after `python -m build`:
+
+```bash
+pip install dist/vistaar-*.whl
+```
+
+Databricks notes are in [docs/databricks.md](https://github.com/thechinmayanand/vistaar/blob/main/docs/databricks.md). Formulas are in [docs/methodology.md](https://github.com/thechinmayanand/vistaar/blob/main/docs/methodology.md).
+
+## Quickstart
+
+```python
+import vistaar as vt
+
+df = vt.datasets.load_conversion()
+engine = vt.Analytics(data=df, target="converted", id_column="customer_id")
+results = engine.run()
+
+results.summary()
+results.segments()
+results.lift()
+results.opportunities()
+results.shap()
+results.deciles()
+results.campaign(strategy="mass", top_deciles=2)
+results.campaign(strategy="precision", target_precision=0.75, min_customers=100)
+results.plot()
+results.export("analytics_report.html")
+```
+
+`run()` prints a stage bar (tqdm in a notebook or a TTY, one line per stage otherwise) and a timing summary. Pass `progress=False` to silence it. Reports and charts use the `vistaar` palette by default (navy, teal, and grey, no logo). `theme="hdfc"` opts into one built-in corporate theme. See [docs/branding.md](https://github.com/thechinmayanand/vistaar/blob/main/docs/branding.md) and [docs/telco_churn.md](https://github.com/thechinmayanand/vistaar/blob/main/docs/telco_churn.md).
+
+Version 0.3.1 makes that neutral palette the default. Version 0.3 is the campaign autopilot: stratified sampling with a representativeness card, model choice on top-20% capture, a non-overlapping segment portfolio, and an audit trail of each automatic decision. Version 0.2 remains the profit cut, calibration, monitoring, registry, and uplift. The worked notebook is [examples/VISTAAR_end_to_end.ipynb](https://github.com/thechinmayanand/vistaar/blob/main/examples/VISTAAR_end_to_end.ipynb). The reference is [VISTAAR_User_Guide.md](https://github.com/thechinmayanand/vistaar/blob/main/VISTAAR_User_Guide.md).
+
+```python
+inside = results.decile_segments(top_deciles=2)
+profit = results.profit_curve(cost_per_contact=50, value_column="MonthlyCharges", value_multiplier=12)
+results.optimal_cut(cost_per_contact=50, value_per_conversion=400)
+calibration = results.calibration()
+results.save_model("model.joblib")
+loaded = vt.load_model("model.joblib")
+loaded.monitor(new_month, actuals=new_month["churn"])
+registry = vt.Registry("registry")
+registry.register(results, model="catboost")
+registry.promote(challenger, champion=champion)
+uplift = results.uplift()   # needs treatment_column= on Analytics
+results.representativeness()
+results.portfolio()
+results.decisions()
+results.reason_codes(df.head(200))
+```
+
+`load_conversion()` returns a bundled synthetic table (about 8,000 customers) with a planted device × customer-type reversal, an organic × returning interaction, a confounded campaign flag, funnel steps, and leakage columns (`revenue`, `post_purchase_score`, `checkout_started`). Those leakage columns are detected and kept out of segmentation and models.
+
+The same run also supports:
+
+```python
+results.conversion_opportunities()
+results.recommendations()
+results.explore()                          # ranked surprises, with the numbers attached
+results.ask("which segments convert best?")
+results.what_if(target_rate=0.25, definition_contains="returning")
+engine.compare(other_df)                   # PSI and KS
+engine.estimate_effect()                   # only if treatment_column= was set
+```
+
+Individual steps: `engine.profile()`, `engine.segment()`, `engine.calculate_lift(by="device")`, `engine.find_best_conversions()`, `engine.feature_importance()`, `engine.explain_with_shap()`, `engine.detect_anomalies()`, `engine.find_interactions()`, `engine.detect_simpsons()`, `engine.generate_insights()`.
+
+An HTML report with the same sections:
+
+```python
+report = engine.create_report(
+    output="html",
+    include=["profiling", "segmentation", "lift", "opportunities", "shap", "recommendations"],
+)
+report.save("analytics_report.html")
+```
+
+`results.export` also writes `.xlsx`, `.csv` (the segment table), `.json`, `.md`, and `.png` (PNG needs `kaleido`).
+
+## What a segment row means
+
+| Column | Meaning |
+| --- | --- |
+| `conversion_rate`, `n`, `conversions` | Full-sample description of this table |
+| `baseline_rate` | Overall conversion rate in that same table |
+| `absolute_lift` | Segment rate minus the baseline rate |
+| `relative_lift` | Segment rate / baseline rate |
+| `index` | `100 * relative_lift` |
+| `p_value`, `p_value_adjusted`, `significant` | Holdout test against the complement, then Benjamini–Hochberg, when a holdout was used |
+| `wilson_low`, `wilson_high` | Wilson interval for the full-sample rate |
+| `replicates` | The holdout lift has the same sign as the training lift, with enough holdout rows |
+| `observed_excess_conversions` | `(rate - baseline) * n`. Observed contrast, not incremental conversions |
+| `inference` | `holdout_confirmation`, `holdout_underpowered`, `in_sample_post_selection`, or `density_cluster_descriptive` |
+
+The opportunity score is a ranking heuristic. Weights, the min-max scaling, and the 0.35 confidence penalty for non-significant segments are written on the result (`opportunity_methodology`) and in the report. `scenario_extra_conversions_to_baseline` is what the count would be if the rate moved to the baseline. It is not a forecast.
+
+## Configuration
+
+```python
+engine = vt.Analytics(
+    data=df,
+    target="converted",
+    id_column="customer_id",
+    positive_label=1,            # inferred when omitted
+    value_column="cart_value",   # pre-outcome value; leaked revenue is not used
+    date_column="signup_date",
+    treatment_column=None,       # set this to run propensity matching
+    min_segment_size=None,       # default max(50, 2% of rows)
+    max_combination_depth=2,     # 1, 2, or 3
+    random_state=42,
+    test_size=0.30,
+    cv_folds=5,
+    n_bootstrap=200,
+    enable_shap=True,            # skipped with a clear message if shap is absent
+    model_names=("logreg", "random_forest"),
+    spark_sample_limit=100_000,
+    llm_narrative=False,         # True requires an llm_fn you supply
+)
+```
+
+`llm_narrative=True` calls your function with the computed insights. The library never contacts an LLM API on its own. `results.ask()` answers from the computed tables by keyword. Pass `use_llm=True` only when `llm_fn` is set.
+
+## Notebooks
+
+- `examples/01_quickstart.ipynb`
+- `examples/02_segmentation.ipynb`
+- `examples/03_shap.ipynb`
+- `examples/04_databricks.ipynb`
+- `examples/05_telco_churn.ipynb` — IBM Telco churn check. Findings are in [docs/telco_churn.md](https://github.com/thechinmayanand/vistaar/blob/main/docs/telco_churn.md). The CSV is downloaded, not vendored.
+- `examples/VISTAAR_end_to_end.ipynb` — the 0.2 tour: deciles, segments inside the cut, profit, calibration, monitoring, champion/challenger, and Hillstrom uplift.
+
+## Development
+
+```bash
+pip install -e ".[dev,shap]"
+pytest
+```
+
+The wheel build:
+
+```bash
+python -m build
+pip install dist/vistaar-*.whl
+```

vistaar-0.3.1/README.md

@@ -0,0 +1,181 @@
+# VISTAAR
+
+VISTAAR profiles a conversion table, finds interpretable micro-segments, and reports lift, significance, and ranked opportunities. Pass a pandas or PySpark DataFrame and a binary target. The library stays local: no API key, no cloud service.
+
+The numbers are observational. Relative lift is a segment's conversion rate divided by the overall baseline. Hypothesis tests compare the segment with its complement (everyone else), not with a baseline that includes the segment. A holdout split is used whenever the table is large enough, so the significance flag is not computed on the same rows that chose the rule. Scenario sizing is arithmetic. None of this is a causal effect.
+
+## Install
+
+```bash
+pip install vistaar
+pip install "vistaar[all]"
+```
+
+Optional extras:
+
+| Extra | What it adds |
+| --- | --- |
+| `shap` | SHAP explanations |
+| `ml` | XGBoost, LightGBM, CatBoost |
+| `hdbscan` | Density clustering |
+| `spark` | PySpark, for machines that do not already have it |
+| `all` | All of the above |
+
+```bash
+pip install "vistaar[shap]"
+```
+
+Python 3.10 or newer. Core dependencies are pandas, NumPy, SciPy, scikit-learn, statsmodels, Plotly, openpyxl, and tqdm. SHAP, gradient-boosted libraries, HDBSCAN, and PySpark are imported only when you use them.
+
+From git, with every optional extra:
+
+```bash
+pip install "git+https://github.com/thechinmayanand/vistaar.git#egg=vistaar[all]"
+```
+
+GitHub release (wheel and sdist): https://github.com/thechinmayanand/vistaar/releases/tag/v0.3.1
+
+From a clone, after `python -m build`:
+
+```bash
+pip install dist/vistaar-*.whl
+```
+
+Databricks notes are in [docs/databricks.md](https://github.com/thechinmayanand/vistaar/blob/main/docs/databricks.md). Formulas are in [docs/methodology.md](https://github.com/thechinmayanand/vistaar/blob/main/docs/methodology.md).
+
+## Quickstart
+
+```python
+import vistaar as vt
+
+df = vt.datasets.load_conversion()
+engine = vt.Analytics(data=df, target="converted", id_column="customer_id")
+results = engine.run()
+
+results.summary()
+results.segments()
+results.lift()
+results.opportunities()
+results.shap()
+results.deciles()
+results.campaign(strategy="mass", top_deciles=2)
+results.campaign(strategy="precision", target_precision=0.75, min_customers=100)
+results.plot()
+results.export("analytics_report.html")
+```
+
+`run()` prints a stage bar (tqdm in a notebook or a TTY, one line per stage otherwise) and a timing summary. Pass `progress=False` to silence it. Reports and charts use the `vistaar` palette by default (navy, teal, and grey, no logo). `theme="hdfc"` opts into one built-in corporate theme. See [docs/branding.md](https://github.com/thechinmayanand/vistaar/blob/main/docs/branding.md) and [docs/telco_churn.md](https://github.com/thechinmayanand/vistaar/blob/main/docs/telco_churn.md).
+
+Version 0.3.1 makes that neutral palette the default. Version 0.3 is the campaign autopilot: stratified sampling with a representativeness card, model choice on top-20% capture, a non-overlapping segment portfolio, and an audit trail of each automatic decision. Version 0.2 remains the profit cut, calibration, monitoring, registry, and uplift. The worked notebook is [examples/VISTAAR_end_to_end.ipynb](https://github.com/thechinmayanand/vistaar/blob/main/examples/VISTAAR_end_to_end.ipynb). The reference is [VISTAAR_User_Guide.md](https://github.com/thechinmayanand/vistaar/blob/main/VISTAAR_User_Guide.md).
+
+```python
+inside = results.decile_segments(top_deciles=2)
+profit = results.profit_curve(cost_per_contact=50, value_column="MonthlyCharges", value_multiplier=12)
+results.optimal_cut(cost_per_contact=50, value_per_conversion=400)
+calibration = results.calibration()
+results.save_model("model.joblib")
+loaded = vt.load_model("model.joblib")
+loaded.monitor(new_month, actuals=new_month["churn"])
+registry = vt.Registry("registry")
+registry.register(results, model="catboost")
+registry.promote(challenger, champion=champion)
+uplift = results.uplift()   # needs treatment_column= on Analytics
+results.representativeness()
+results.portfolio()
+results.decisions()
+results.reason_codes(df.head(200))
+```
+
+`load_conversion()` returns a bundled synthetic table (about 8,000 customers) with a planted device × customer-type reversal, an organic × returning interaction, a confounded campaign flag, funnel steps, and leakage columns (`revenue`, `post_purchase_score`, `checkout_started`). Those leakage columns are detected and kept out of segmentation and models.
+
+The same run also supports:
+
+```python
+results.conversion_opportunities()
+results.recommendations()
+results.explore()                          # ranked surprises, with the numbers attached
+results.ask("which segments convert best?")
+results.what_if(target_rate=0.25, definition_contains="returning")
+engine.compare(other_df)                   # PSI and KS
+engine.estimate_effect()                   # only if treatment_column= was set
+```
+
+Individual steps: `engine.profile()`, `engine.segment()`, `engine.calculate_lift(by="device")`, `engine.find_best_conversions()`, `engine.feature_importance()`, `engine.explain_with_shap()`, `engine.detect_anomalies()`, `engine.find_interactions()`, `engine.detect_simpsons()`, `engine.generate_insights()`.
+
+An HTML report with the same sections:
+
+```python
+report = engine.create_report(
+    output="html",
+    include=["profiling", "segmentation", "lift", "opportunities", "shap", "recommendations"],
+)
+report.save("analytics_report.html")
+```
+
+`results.export` also writes `.xlsx`, `.csv` (the segment table), `.json`, `.md`, and `.png` (PNG needs `kaleido`).
+
+## What a segment row means
+
+| Column | Meaning |
+| --- | --- |
+| `conversion_rate`, `n`, `conversions` | Full-sample description of this table |
+| `baseline_rate` | Overall conversion rate in that same table |
+| `absolute_lift` | Segment rate minus the baseline rate |
+| `relative_lift` | Segment rate / baseline rate |
+| `index` | `100 * relative_lift` |
+| `p_value`, `p_value_adjusted`, `significant` | Holdout test against the complement, then Benjamini–Hochberg, when a holdout was used |
+| `wilson_low`, `wilson_high` | Wilson interval for the full-sample rate |
+| `replicates` | The holdout lift has the same sign as the training lift, with enough holdout rows |
+| `observed_excess_conversions` | `(rate - baseline) * n`. Observed contrast, not incremental conversions |
+| `inference` | `holdout_confirmation`, `holdout_underpowered`, `in_sample_post_selection`, or `density_cluster_descriptive` |
+
+The opportunity score is a ranking heuristic. Weights, the min-max scaling, and the 0.35 confidence penalty for non-significant segments are written on the result (`opportunity_methodology`) and in the report. `scenario_extra_conversions_to_baseline` is what the count would be if the rate moved to the baseline. It is not a forecast.
+
+## Configuration
+
+```python
+engine = vt.Analytics(
+    data=df,
+    target="converted",
+    id_column="customer_id",
+    positive_label=1,            # inferred when omitted
+    value_column="cart_value",   # pre-outcome value; leaked revenue is not used
+    date_column="signup_date",
+    treatment_column=None,       # set this to run propensity matching
+    min_segment_size=None,       # default max(50, 2% of rows)
+    max_combination_depth=2,     # 1, 2, or 3
+    random_state=42,
+    test_size=0.30,
+    cv_folds=5,
+    n_bootstrap=200,
+    enable_shap=True,            # skipped with a clear message if shap is absent
+    model_names=("logreg", "random_forest"),
+    spark_sample_limit=100_000,
+    llm_narrative=False,         # True requires an llm_fn you supply
+)
+```
+
+`llm_narrative=True` calls your function with the computed insights. The library never contacts an LLM API on its own. `results.ask()` answers from the computed tables by keyword. Pass `use_llm=True` only when `llm_fn` is set.
+
+## Notebooks
+
+- `examples/01_quickstart.ipynb`
+- `examples/02_segmentation.ipynb`
+- `examples/03_shap.ipynb`
+- `examples/04_databricks.ipynb`
+- `examples/05_telco_churn.ipynb` — IBM Telco churn check. Findings are in [docs/telco_churn.md](https://github.com/thechinmayanand/vistaar/blob/main/docs/telco_churn.md). The CSV is downloaded, not vendored.
+- `examples/VISTAAR_end_to_end.ipynb` — the 0.2 tour: deciles, segments inside the cut, profit, calibration, monitoring, champion/challenger, and Hillstrom uplift.
+
+## Development
+
+```bash
+pip install -e ".[dev,shap]"
+pytest
+```
+
+The wheel build:
+
+```bash
+python -m build
+pip install dist/vistaar-*.whl
+```