probviz 1.0.1__tar.gz

probviz-1.0.1/CHANGELOG.md

@@ -0,0 +1,78 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.1] — 2026-09-11
+
+### Changed
+
+- Renamed the project and distribution to **`probviz`** (GitHub repo
+  `sanskarpan/probviz`, PyPI `probviz`, docs at
+  <https://sanskarpan.github.io/probviz/>). All URLs, badges, packaging
+  metadata, Docker labels, and citations updated; `docs/archive/` historical
+  notes intentionally left untouched.
+
+## [1.0.0] — 2026-09-07
+
+### Added
+
+- `LICENSE` (MIT) and `CITATION.cff`.
+- `src/cli.py` with the `probviz` command (`app`, `test`, `version`); fixed the
+  packaging entry point (`web.app:main` → `src.cli:main`) and added
+  `web/__init__.py` / `src/__init__.py` (`__version__`).
+- `tests/conftest.py` centralizing the `src`-layout path setup.
+- `requirements-dev.txt` / `requirements-docs.txt` splitting dev and docs tooling.
+- `src/visualizers` public facade (`plot_pdf`, `plot_cdf`, `plot_comparison`)
+  re-exporting `src.utils.plotting`, resolving the previously empty package.
+- Missing `src.utils` re-exports (`validate_integer`,
+  `validate_covariance_matrix`, `validate_correlation_matrix`, `log_transform`,
+  `box_cox_transform`, `plot_probability_bands`) and abstract-base exports
+  (`Copula`, `MultivariateDistribution`).
+- MkDocs Material site (`mkdocs.yml`, `docs/`) with GitHub Pages deploy workflow.
+- Production repo files: `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`,
+  `SECURITY.md`, issue/PR templates, `CODEOWNERS`, `.editorconfig`,
+  `.gitattributes`, `MANIFEST.in`, `.github/workflows/docs.yml`,
+  `.github/workflows/publish.yml`.
+
+### Fixed
+
+- `MixtureDistribution.fit_em`: convergence is now checked **after** the M-step
+  so returned weights/components/responsibilities are never one iteration stale;
+  added guards for empty data, `n_components > n`, zero row-likelihoods, zero
+  component counts, and zero variances.
+- Replaced global `np.random.seed` mutation with local
+  `np.random.default_rng(random_state)` in mixture, multivariate-t, and all
+  copula samplers (reproducibility preserved per-call).
+- Fixed dead `np.atleast_2d` + `ndim == 1` branches in GMM wrappers via a
+  `_as_2d` helper that correctly maps 1-D input to `(n, 1)`.
+- `plot_bivariate_normal`: builds the 2-D + 3-D panels directly instead of
+  orphaning a subplot axis.
+- `GaussianCopula.pdf`: clips uniform inputs to avoid `ppf(0/1) → ±inf → nan`.
+- `GumbelCopula.rvs`: no longer silently substitutes `0.5` on solver failure;
+  degenerate brackets raise `ValueError`, converged roots are kept.
+- `fit_copula_to_data`: validates Kendall's τ ranges for Clayton/Gumbel and
+  documents the Student-t `df=4` simplification.
+- `StudentTCopula`: validates correlation diagonals/positive-definiteness and
+  now documents `cdf`/`pdf` as intentionally unimplemented (Monte Carlo via
+  `rvs` instead of inheriting a bare `NotImplementedError`).
+- `Clayton`/`Gumbel` bivariate-only guards now state the limitation explicitly.
+- Removed dead imports (`ProcessPoolExecutor`, unused `warnings`/`optimize`/
+  `gammaln`/`Axes3D`) and the redundant inner `Lognormal` numpy import path.
+
+### Changed
+
+- `pyproject.toml` is now the single source of packaging truth (aligned
+  runtime deps incl. scikit-learn/statsmodels/joblib, `requires-python >=3.10`,
+  ruff config, project URLs); `setup.py` is a thin shim; `requirements.txt`
+  mirrors runtime deps.
+- Root historical notes moved to `docs/archive/` with a staleness disclaimer.
+- `README.md` rewritten for accuracy (16 univariate + advanced modules, real
+  tree, correct repo URLs, honest test counts, documented limitations).
+
+### Verification
+
+- `pytest tests/ -q`: **688 passed**.
+- `flake8 src/ tests/ --select=E9,F63,F7,F82`, `mypy src/`, Docker build.

probviz-1.0.1/CITATION.cff

@@ -0,0 +1,19 @@
+cff-version: 1.2.0
+title: Probability Distribution Visualizer
+message: If you use this software, please cite it as below.
+type: software
+authors:
+  - given-names: Sanskar
+    family-names: Pan
+    email: sanskarpandey2004@gmail.com
+repository-code: https://github.com/sanskarpan/probviz
+url: https://sanskarpan.github.io/probviz/
+license: MIT
+version: 1.0.1
+date-released: "2026-09-11"
+keywords:
+  - statistics
+  - probability-distributions
+  - visualization
+  - streamlit
+  - monte-carlo

probviz-1.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 Sanskar Pan and 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.

probviz-1.0.1/MANIFEST.in

@@ -0,0 +1,5 @@
+include README.md QUICKSTART.md CHANGELOG.md LICENSE CITATION.cff
+include requirements*.txt
+recursive-include examples *.py
+recursive-include docs *.md *.yml
+global-exclude __pycache__ *.py[cod]

probviz-1.0.1/PKG-INFO

@@ -0,0 +1,219 @@
+Metadata-Version: 2.4
+Name: probviz
+Version: 1.0.1
+Summary: Interactive probability distribution visualizer: 16 univariate + multivariate, copulas, mixtures, fitting, Monte Carlo, and statistical tests
+Author: Sanskar Pan and contributors
+Maintainer-email: Sanskar Pan <sanskarpandey2004@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/sanskarpan/probviz
+Project-URL: Documentation, https://sanskarpan.github.io/probviz/
+Project-URL: Repository, https://github.com/sanskarpan/probviz
+Project-URL: Issues, https://github.com/sanskarpan/probviz/issues
+Project-URL: Changelog, https://github.com/sanskarpan/probviz/blob/main/CHANGELOG.md
+Keywords: statistics,probability,distributions,visualization,streamlit,monte-carlo
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: scipy>=1.11.0
+Requires-Dist: pandas>=2.1.0
+Requires-Dist: matplotlib>=3.8.0
+Requires-Dist: seaborn>=0.13.0
+Requires-Dist: plotly>=5.18.0
+Requires-Dist: streamlit>=1.29.0
+Requires-Dist: scikit-learn>=1.7.2
+Requires-Dist: statsmodels>=0.15.0
+Requires-Dist: joblib>=1.6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: mypy>=1.7.0; extra == "dev"
+Requires-Dist: black>=23.12.0; extra == "dev"
+Requires-Dist: flake8>=6.1.0; extra == "dev"
+Requires-Dist: isort>=5.13.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: pre-commit>=3.0.0; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.6.0; extra == "docs"
+Requires-Dist: mkdocs-material>=9.0.0; extra == "docs"
+Requires-Dist: mkdocstrings[python]>=0.24.0; extra == "docs"
+Provides-Extra: test
+Requires-Dist: pytest>=7.4.0; extra == "test"
+Requires-Dist: pytest-cov>=4.1.0; extra == "test"
+Dynamic: license-file
+
+# Probability Distribution Visualizer
+
+An interactive probability distribution visualizer with a Streamlit web interface,
+a typed Python API, and toolkits for fitting, Monte Carlo simulation, and
+statistical testing.
+
+<p align="center">
+  <a href="https://github.com/sanskarpan/probviz/actions/workflows/ci.yml"><img src="https://github.com/sanskarpan/probviz/actions/workflows/ci.yml/badge.svg" alt="CI Status"></a>
+  <a href="https://github.com/sanskarpan/probviz/actions/workflows/ci.yml"><img src="https://img.shields.io/badge/tests-688%20passed-brightgreen" alt="Tests"></a>
+  <a href="https://sanskarpan.github.io/probviz/"><img src="https://img.shields.io/badge/docs-GitHub%20Pages-blue" alt="Docs"></a>
+  <a href="https://github.com/sanskarpan/probviz/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="License"></a>
+  <br>
+  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue?logo=python" alt="Python"></a>
+  <a href="https://streamlit.io/"><img src="https://img.shields.io/badge/Streamlit-1.29+-FF4B4B?logo=streamlit" alt="Streamlit"></a>
+  <a href="https://github.com/sanskarpan/probviz/pkgs/container/probviz"><img src="https://img.shields.io/badge/docker-ghcr.io-2496ED?logo=docker" alt="Docker"></a>
+  <a href="https://github.com/sanskarpan/probviz/pulls"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen" alt="PRs Welcome"></a>
+</p>
+
+- **Docs (GitHub Pages):** <https://sanskarpan.github.io/probviz/>
+- **16 univariate distributions** (10 continuous + 6 discrete) with PDF/PMF, CDF,
+  quantiles, sampling, and full statistics — in the web app and the API.
+- **Advanced modules** (Python API): multivariate distributions, copulas,
+  mixtures/GMM, distribution fitting, Monte Carlo, and statistical tests.
+- **Production-ready:** 688-test suite, typed packaging (`pyproject.toml`),
+  `probviz` CLI, Docker/Compose, CI with coverage gate, docs + PyPI + Docker
+  release pipelines. See [`CHANGELOG.md`](CHANGELOG.md).
+
+## Gallery
+
+<p align="center">
+  <img src="docs/assets/normal_sigma_morph.gif" width="250" alt="Normal PDF morphing with sigma">
+  <img src="docs/assets/clt_convergence.gif" width="250" alt="Central Limit Theorem convergence">
+  <img src="docs/assets/copula_dependence.gif" width="210" alt="Gaussian copula dependence sweep">
+  <br>
+  <img src="docs/assets/beta_shape_morph.gif" width="250" alt="Beta PDF shape morph">
+  <img src="docs/assets/mixture_separation.gif" width="250" alt="Gaussian mixture separation">
+</p>
+
+*Top: Normal σ sweep · CLT convergence · Gaussian-copula ρ sweep. Bottom: Beta shape sweep · mixture separation. Regenerate with `python examples/generate_media.py`.*
+
+## Quick start
+
+```bash
+pip install probviz
+probviz app
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/sanskarpan/probviz.git
+cd probviz
+pip install -r requirements.txt
+streamlit run web/app.py
+```
+
+Open `http://localhost:8501`. Full guide: [`QUICKSTART.md`](QUICKSTART.md) ·
+[docs quickstart](https://sanskarpan.github.io/probviz/quickstart/).
+
+### Install as a package
+
+```bash
+pip install -e .
+probviz app        # launch the UI
+probviz test       # run tests
+probviz version    # print version
+```
+
+### Docker
+
+```bash
+docker build -t probviz .
+docker run -p 8501:8501 probviz
+# or
+docker compose up --build
+```
+
+## What's inside
+
+| Area | Contents |
+|---|---|
+| Univariate | Normal, Exponential, Uniform, Beta, Gamma, Chi-Square, Student-t, Weibull, Lognormal, Cauchy · Binomial, Poisson, Geometric, Negative Binomial, Hypergeometric, Discrete Uniform |
+| Multivariate | Multivariate Normal, Dirichlet, Multivariate Student-t, Wishart |
+| Copulas | Gaussian, Clayton, Gumbel, Student-t + `fit_copula_to_data` |
+| Mixtures | `MixtureDistribution` (1-D EM), `GaussianMixtureModel`, `BayesianGMM`, BIC selection |
+| Fitting | `DistributionFitter`, `BayesianEstimator`, `GoodnessOfFit` |
+| Monte Carlo | `MonteCarloSimulator`, `VarianceReduction`, `QuasiMonteCarloSimulator` |
+| Tests | hypothesis / nonparametric / descriptive dict-returning helpers |
+| Utils | validation, preprocessing, plotting, structured logging; `src.visualizers` facade |
+
+Project layout and conventions: [`docs/architecture.md`](docs/architecture.md).
+API reference: [`docs/api.md`](docs/api.md) (rendered on the docs site).
+
+## Python API
+
+```python
+import numpy as np
+from src.distributions import NormalDistribution, BinomialDistribution
+
+normal = NormalDistribution(mu=0, sigma=1)
+x = np.linspace(-4, 4, 200)
+pdf, cdf = normal.pdf(x), normal.cdf(x)
+samples = normal.rvs(size=1000, random_state=42)
+print(normal.get_statistics())
+print(normal.interval(0.95), normal.ppf(0.975))
+
+binomial = BinomialDistribution(n=10, p=0.3)
+print(binomial.pdf(np.arange(0, 11)))
+```
+
+```python
+from src.fitting import DistributionFitter
+from src.monte_carlo import MonteCarloSimulator
+
+fitter = DistributionFitter(samples)
+print(fitter.fit_all())
+
+rng = np.random.default_rng(42)
+sim = MonteCarloSimulator(random_seed=42)
+res = sim.estimate_probability(lambda: rng.normal(0, 1) > 1.0, num_samples=100_000)
+print(res["probability"], res["confidence_interval"])
+```
+
+## Known limitations (by design)
+
+- The Streamlit app covers the **16 univariate distributions only**; advanced
+  modules are Python-API only.
+- `Clayton`/`Gumbel` copula `pdf`/`rvs` are **bivariate-only** (explicit error otherwise).
+- `StudentTCopula` has **no closed-form `cdf`/`pdf`**; use Monte Carlo via `rvs`.
+- `MixtureDistribution` EM assumes **1-D** components; use the sklearn GMM wrappers
+  for multivariate mixtures.
+- Cauchy moments are undefined — the API surfaces `nan` instead of masking it.
+
+## Testing
+
+```bash
+pip install -r requirements-dev.txt
+pytest tests/ -q                                  # 688 tests
+pytest tests/ -q --cov=src --cov-report=term      # with coverage (gate: 80%)
+flake8 src/ tests/ --count --select=E9,F63,F7,F82 --statistics
+mypy --config-file=pyproject.toml src/
+```
+
+## Contributing
+
+See [`CONTRIBUTING.md`](CONTRIBUTING.md) (setup, style, tests, PR checklist),
+[`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md), and [`SECURITY.md`](SECURITY.md).
+
+## License
+
+MIT — see [`LICENSE`](LICENSE). If you use this in research or teaching:
+
+```bibtex
+@software{probability_distribution_visualizer,
+  title  = {Probability Distribution Visualizer},
+  author = {sanskarpan},
+  year   = {2026},
+  url    = {https://github.com/sanskarpan/probviz}
+}
+```
+
+Also see [`CITATION.cff`](CITATION.cff).

probviz-1.0.1/QUICKSTART.md

@@ -0,0 +1,56 @@
+# Quickstart
+
+Get from zero to interactive plots in under five minutes.
+
+## 1. Install
+
+```bash
+git clone https://github.com/sanskarpan/probviz.git
+cd probviz
+python -m venv .venv && source .venv/bin/activate
+pip install -r requirements.txt
+```
+
+## 2. Launch the web app
+
+```bash
+streamlit run web/app.py
+# or, after `pip install -e .`:
+probviz app
+```
+
+Open `http://localhost:8501`.
+
+## 3. Explore
+
+1. Pick **Continuous** or **Discrete** in the sidebar.
+2. Choose one of the **16 univariate distributions**.
+3. Move the parameter sliders (bounds come from `get_parameter_bounds()`).
+4. Read the PDF/PMF + CDF charts, sample overlay, statistics table, and quantiles.
+
+## 4. Try the Python API
+
+```python
+import numpy as np
+from src.distributions import NormalDistribution
+
+normal = NormalDistribution(mu=0, sigma=1)
+x = np.linspace(-4, 4, 200)
+pdf, cdf = normal.pdf(x), normal.cdf(x)
+samples = normal.rvs(size=1000, random_state=42)
+print(normal.get_statistics())
+```
+
+## 5. Go further
+
+- `docs/` (GitHub Pages): fitting, Monte Carlo, copulas, mixtures, API reference.
+- `examples/basic_usage.py`: `python examples/basic_usage.py`.
+- `pytest tests/ -q`: run the 688-test suite.
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| `streamlit: command not found` | Activate the venv / `pip install -r requirements.txt` |
+| Port 8501 busy | `streamlit run web/app.py --server.port 8502` |
+| Import errors in snippets | Run from the repo root or `pip install -e .`; imports are `from src....` |

probviz-1.0.1/README.md

@@ -0,0 +1,162 @@
+# Probability Distribution Visualizer
+
+An interactive probability distribution visualizer with a Streamlit web interface,
+a typed Python API, and toolkits for fitting, Monte Carlo simulation, and
+statistical testing.
+
+<p align="center">
+  <a href="https://github.com/sanskarpan/probviz/actions/workflows/ci.yml"><img src="https://github.com/sanskarpan/probviz/actions/workflows/ci.yml/badge.svg" alt="CI Status"></a>
+  <a href="https://github.com/sanskarpan/probviz/actions/workflows/ci.yml"><img src="https://img.shields.io/badge/tests-688%20passed-brightgreen" alt="Tests"></a>
+  <a href="https://sanskarpan.github.io/probviz/"><img src="https://img.shields.io/badge/docs-GitHub%20Pages-blue" alt="Docs"></a>
+  <a href="https://github.com/sanskarpan/probviz/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="License"></a>
+  <br>
+  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue?logo=python" alt="Python"></a>
+  <a href="https://streamlit.io/"><img src="https://img.shields.io/badge/Streamlit-1.29+-FF4B4B?logo=streamlit" alt="Streamlit"></a>
+  <a href="https://github.com/sanskarpan/probviz/pkgs/container/probviz"><img src="https://img.shields.io/badge/docker-ghcr.io-2496ED?logo=docker" alt="Docker"></a>
+  <a href="https://github.com/sanskarpan/probviz/pulls"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen" alt="PRs Welcome"></a>
+</p>
+
+- **Docs (GitHub Pages):** <https://sanskarpan.github.io/probviz/>
+- **16 univariate distributions** (10 continuous + 6 discrete) with PDF/PMF, CDF,
+  quantiles, sampling, and full statistics — in the web app and the API.
+- **Advanced modules** (Python API): multivariate distributions, copulas,
+  mixtures/GMM, distribution fitting, Monte Carlo, and statistical tests.
+- **Production-ready:** 688-test suite, typed packaging (`pyproject.toml`),
+  `probviz` CLI, Docker/Compose, CI with coverage gate, docs + PyPI + Docker
+  release pipelines. See [`CHANGELOG.md`](CHANGELOG.md).
+
+## Gallery
+
+<p align="center">
+  <img src="docs/assets/normal_sigma_morph.gif" width="250" alt="Normal PDF morphing with sigma">
+  <img src="docs/assets/clt_convergence.gif" width="250" alt="Central Limit Theorem convergence">
+  <img src="docs/assets/copula_dependence.gif" width="210" alt="Gaussian copula dependence sweep">
+  <br>
+  <img src="docs/assets/beta_shape_morph.gif" width="250" alt="Beta PDF shape morph">
+  <img src="docs/assets/mixture_separation.gif" width="250" alt="Gaussian mixture separation">
+</p>
+
+*Top: Normal σ sweep · CLT convergence · Gaussian-copula ρ sweep. Bottom: Beta shape sweep · mixture separation. Regenerate with `python examples/generate_media.py`.*
+
+## Quick start
+
+```bash
+pip install probviz
+probviz app
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/sanskarpan/probviz.git
+cd probviz
+pip install -r requirements.txt
+streamlit run web/app.py
+```
+
+Open `http://localhost:8501`. Full guide: [`QUICKSTART.md`](QUICKSTART.md) ·
+[docs quickstart](https://sanskarpan.github.io/probviz/quickstart/).
+
+### Install as a package
+
+```bash
+pip install -e .
+probviz app        # launch the UI
+probviz test       # run tests
+probviz version    # print version
+```
+
+### Docker
+
+```bash
+docker build -t probviz .
+docker run -p 8501:8501 probviz
+# or
+docker compose up --build
+```
+
+## What's inside
+
+| Area | Contents |
+|---|---|
+| Univariate | Normal, Exponential, Uniform, Beta, Gamma, Chi-Square, Student-t, Weibull, Lognormal, Cauchy · Binomial, Poisson, Geometric, Negative Binomial, Hypergeometric, Discrete Uniform |
+| Multivariate | Multivariate Normal, Dirichlet, Multivariate Student-t, Wishart |
+| Copulas | Gaussian, Clayton, Gumbel, Student-t + `fit_copula_to_data` |
+| Mixtures | `MixtureDistribution` (1-D EM), `GaussianMixtureModel`, `BayesianGMM`, BIC selection |
+| Fitting | `DistributionFitter`, `BayesianEstimator`, `GoodnessOfFit` |
+| Monte Carlo | `MonteCarloSimulator`, `VarianceReduction`, `QuasiMonteCarloSimulator` |
+| Tests | hypothesis / nonparametric / descriptive dict-returning helpers |
+| Utils | validation, preprocessing, plotting, structured logging; `src.visualizers` facade |
+
+Project layout and conventions: [`docs/architecture.md`](docs/architecture.md).
+API reference: [`docs/api.md`](docs/api.md) (rendered on the docs site).
+
+## Python API
+
+```python
+import numpy as np
+from src.distributions import NormalDistribution, BinomialDistribution
+
+normal = NormalDistribution(mu=0, sigma=1)
+x = np.linspace(-4, 4, 200)
+pdf, cdf = normal.pdf(x), normal.cdf(x)
+samples = normal.rvs(size=1000, random_state=42)
+print(normal.get_statistics())
+print(normal.interval(0.95), normal.ppf(0.975))
+
+binomial = BinomialDistribution(n=10, p=0.3)
+print(binomial.pdf(np.arange(0, 11)))
+```
+
+```python
+from src.fitting import DistributionFitter
+from src.monte_carlo import MonteCarloSimulator
+
+fitter = DistributionFitter(samples)
+print(fitter.fit_all())
+
+rng = np.random.default_rng(42)
+sim = MonteCarloSimulator(random_seed=42)
+res = sim.estimate_probability(lambda: rng.normal(0, 1) > 1.0, num_samples=100_000)
+print(res["probability"], res["confidence_interval"])
+```
+
+## Known limitations (by design)
+
+- The Streamlit app covers the **16 univariate distributions only**; advanced
+  modules are Python-API only.
+- `Clayton`/`Gumbel` copula `pdf`/`rvs` are **bivariate-only** (explicit error otherwise).
+- `StudentTCopula` has **no closed-form `cdf`/`pdf`**; use Monte Carlo via `rvs`.
+- `MixtureDistribution` EM assumes **1-D** components; use the sklearn GMM wrappers
+  for multivariate mixtures.
+- Cauchy moments are undefined — the API surfaces `nan` instead of masking it.
+
+## Testing
+
+```bash
+pip install -r requirements-dev.txt
+pytest tests/ -q                                  # 688 tests
+pytest tests/ -q --cov=src --cov-report=term      # with coverage (gate: 80%)
+flake8 src/ tests/ --count --select=E9,F63,F7,F82 --statistics
+mypy --config-file=pyproject.toml src/
+```
+
+## Contributing
+
+See [`CONTRIBUTING.md`](CONTRIBUTING.md) (setup, style, tests, PR checklist),
+[`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md), and [`SECURITY.md`](SECURITY.md).
+
+## License
+
+MIT — see [`LICENSE`](LICENSE). If you use this in research or teaching:
+
+```bibtex
+@software{probability_distribution_visualizer,
+  title  = {Probability Distribution Visualizer},
+  author = {sanskarpan},
+  year   = {2026},
+  url    = {https://github.com/sanskarpan/probviz}
+}
+```
+
+Also see [`CITATION.cff`](CITATION.cff).

probviz-1.0.1/docs/advanced.md

@@ -0,0 +1,47 @@
+# Multivariate, Copulas & Mixtures
+
+## Multivariate (`src.distributions.multivariate`)
+
+- `MultivariateNormalDistribution(mean, cov)` — full pdf/logpdf/rvs/mean/cov;
+  `plot_bivariate_normal(dist)` gives contour + 3-D surface for d=2.
+- `DirichletDistribution(alpha)` — simplex sampling; `plot_dirichlet_simplex`
+  for d=3.
+- `MultivariateStudentT(df, loc, shape)` — pdf via the closed-form density,
+  sampling via the normal/χ² representation with a local `default_rng`.
+- `WishartDistribution(df, scale)` — distribution over PSD matrices with
+  mean/mode/pdf/logpdf/rvs.
+
+## Copulas (`src.distributions.copulas`)
+
+| Copula | Status |
+|---|---|
+| Gaussian | cdf/pdf/rvs/kendall_tau (any dimension) |
+| Clayton | cdf (any d); **pdf/rvs currently bivariate-only** |
+| Gumbel | cdf (any d); **pdf/rvs currently bivariate-only** |
+| Student-t | rvs/kendall_tau; **cdf/pdf intentionally not implemented** (requires multivariate-t integration — use Monte Carlo via `rvs`) |
+
+`fit_copula_to_data(data, copula_type, method)` fits Gaussian/Clayton/Gumbel/t
+from pseudo-observations. It validates Kendall's τ ranges and documents the
+`t` degrees-of-freedom simplification (`df=4`).
+
+```python
+from src.distributions import GaussianCopula
+import numpy as np
+
+cop = GaussianCopula(np.array([[1.0, 0.6], [0.6, 1.0]]))
+u = cop.rvs(size=1000, random_state=42)   # uniform margins with Gaussian dependence
+```
+
+## Mixtures (`src.distributions.mixtures`)
+
+- `MixtureDistribution(components, weights)` — pdf/cdf/rvs/mean/var + `fit_em`
+  (EM for 1-D Gaussian mixtures; guards empty data, `n_components > n`, zero
+  responsibilities, and zero variances; convergence is checked **after** the
+  M-step so returned parameters are never stale).
+- `GaussianMixtureModel` / `BayesianGMM` — sklearn-backed fitting, predict,
+  BIC/AIC, active-component counts.
+- `select_optimal_components(data, max_components)` — BIC sweep.
+
+!!! warning "Scope"
+    `MixtureDistribution` assumes 1-D components. Multivariate mixtures should
+    use `GaussianMixtureModel`/`BayesianGMM`.

probviz-1.0.1/docs/api.md

@@ -0,0 +1,61 @@
+# API Reference
+
+::: src.distributions
+    options:
+      show_root_heading: true
+
+::: src.distributions.continuous
+    options:
+      show_root_heading: true
+
+::: src.distributions.discrete
+    options:
+      show_root_heading: true
+
+::: src.distributions.multivariate
+    options:
+      show_root_heading: true
+
+::: src.distributions.copulas
+    options:
+      show_root_heading: true
+
+::: src.distributions.mixtures
+    options:
+      show_root_heading: true
+
+::: src.fitting.distribution_fitter
+    options:
+      show_root_heading: true
+
+::: src.monte_carlo.simulator
+    options:
+      show_root_heading: true
+
+::: src.statistical_tests
+    options:
+      show_root_heading: true
+
+::: src.utils.validation
+    options:
+      show_root_heading: true
+
+::: src.utils.data_preprocessing
+    options:
+      show_root_heading: true
+
+::: src.utils.plotting
+    options:
+      show_root_heading: true
+
+::: src.utils.logger
+    options:
+      show_root_heading: true
+
+::: src.visualizers
+    options:
+      show_root_heading: true
+
+::: src.cli
+    options:
+      show_root_heading: true