# cgmm
[](https://pypi.org/project/cgmm/)
[](https://cgmm.readthedocs.io/en/latest/?badge=latest)
[](https://codecov.io/gh/sitmo/cgmm)
**cgmm** provides **Conditional Gaussian Mixture Models** that are fully compatible with scikit-learn.
It lets you fit a standard `GaussianMixture` on your data, then **condition** on a subset of variables
to obtain the posterior distribution of the remaining ones.
Typical applications:
- Multimodal regression (`E[y | X=x]` and predictive bands)
- Scenario simulation and stochastic forecasting
- Imputation of missing values
- Inverse problems (e.g. kinematics, finance, volatility)
---
## Features
- `GMMConditioner` — take a fitted `GaussianMixture`, choose conditioning indices, and get a new mixture over the target block.
- `ConditionalGMMRegressor` — sklearn-style regressor wrapper, exposes `.predict` and `.predict_cov`.
- Compatible with scikit-learn pipelines & tools.
- Support for multi-modal posteriors (mixtures, not just means).
- Well-tested, BSD-3 licensed.
---
## Installation
```bash
pip install cgmm
```
---
## Quick Start
```python
import numpy as np
from sklearn.mixture import GaussianMixture
from cgmm import GMMConditioner, ConditionalGMMRegressor
# Example data
rng = np.random.default_rng(0)
X = rng.normal(size=(1000, 3))
# Fit a scikit-learn GMM on all features
gmm = GaussianMixture(n_components=3, covariance_type="full", random_state=0).fit(X)
# Condition on the first coordinate (X), predict the rest (y)
cond = GMMConditioner(gmm, cond_idx=[0]).precompute()
gmmy = cond.condition([0.5]) # returns a GaussianMixture over y
samples = gmmy.sample(5)[0] # sample from p(y | X=0.5)
# Regressor interface for posterior mean
reg = ConditionalGMMRegressor(gmm, cond_idx=[0]).fit(X=np.zeros((1, 1)))
y_mean = reg.predict([[0.5]]) # E[y | X=0.5]
```
---
## Examples
- 2D conditional demo: scatter + contours + conditional slice.
https://cgmm.readthedocs.io/en/latest/examples/conditional_2d_gmm.html
- VIX scenario generation: model daily log-VIX changes and simulate stochastic futures.
https://cgmm.readthedocs.io/en/latest/examples/vix_predictor.html
See the documentation for full tutorials: https://cgmm.readthedocs.io/
---
## Documentation
Full documentation is hosted on Read the Docs: https://cgmm.readthedocs.io/
Includes:
- API reference
- Tutorials and examples
- Background on conditional GMMs
---
## Contributing
Contributions are welcome! Typical workflow:
```bash
git clone https://github.com/your-org/cgmm.git
cd cgmm
poetry install -E docs --with dev
pre-commit install
```
- Format & lint: `make precommit`
- Build docs locally: `make docs`
- Bump version: `make bump-patch` (or minor/major)
- Push tags → GitHub Actions → PyPI release
Please open issues or pull requests on GitHub.
---
## License
BSD-3-Clause License © 2025 Thijs van den Berg
Raw data
{
"_id": null,
"home_page": null,
"name": "cgmm",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.13,>=3.9",
"maintainer_email": null,
"keywords": "gaussian mixture, scikit-learn, conditional",
"author": "Thijs van den Berg",
"author_email": "thijs@sitmo.com",
"download_url": "https://files.pythonhosted.org/packages/03/ac/037c7abb62e46549f357045823c4adb8893eaa73865cc2c5efe6f33e9dc4/cgmm-0.3.2.tar.gz",
"platform": null,
"description": "# cgmm\n\n[](https://pypi.org/project/cgmm/)\n[](https://cgmm.readthedocs.io/en/latest/?badge=latest)\n\n[](https://codecov.io/gh/sitmo/cgmm)\n\n\n**cgmm** provides **Conditional Gaussian Mixture Models** that are fully compatible with scikit-learn.\nIt lets you fit a standard `GaussianMixture` on your data, then **condition** on a subset of variables\nto obtain the posterior distribution of the remaining ones.\n\nTypical applications:\n- Multimodal regression (`E[y | X=x]` and predictive bands)\n- Scenario simulation and stochastic forecasting\n- Imputation of missing values\n- Inverse problems (e.g. kinematics, finance, volatility)\n\n---\n\n## Features\n\n- `GMMConditioner` \u2014 take a fitted `GaussianMixture`, choose conditioning indices, and get a new mixture over the target block.\n- `ConditionalGMMRegressor` \u2014 sklearn-style regressor wrapper, exposes `.predict` and `.predict_cov`.\n- Compatible with scikit-learn pipelines & tools.\n- Support for multi-modal posteriors (mixtures, not just means).\n- Well-tested, BSD-3 licensed.\n\n---\n\n## Installation\n\n```bash\npip install cgmm\n```\n\n---\n\n## Quick Start\n\n```python\nimport numpy as np\nfrom sklearn.mixture import GaussianMixture\nfrom cgmm import GMMConditioner, ConditionalGMMRegressor\n\n# Example data\nrng = np.random.default_rng(0)\nX = rng.normal(size=(1000, 3))\n\n# Fit a scikit-learn GMM on all features\ngmm = GaussianMixture(n_components=3, covariance_type=\"full\", random_state=0).fit(X)\n\n# Condition on the first coordinate (X), predict the rest (y)\ncond = GMMConditioner(gmm, cond_idx=[0]).precompute()\ngmmy = cond.condition([0.5]) # returns a GaussianMixture over y\n\nsamples = gmmy.sample(5)[0] # sample from p(y | X=0.5)\n\n# Regressor interface for posterior mean\nreg = ConditionalGMMRegressor(gmm, cond_idx=[0]).fit(X=np.zeros((1, 1)))\ny_mean = reg.predict([[0.5]]) # E[y | X=0.5]\n```\n\n---\n\n## Examples\n\n- 2D conditional demo: scatter + contours + conditional slice. \n https://cgmm.readthedocs.io/en/latest/examples/conditional_2d_gmm.html\n- VIX scenario generation: model daily log-VIX changes and simulate stochastic futures. \n https://cgmm.readthedocs.io/en/latest/examples/vix_predictor.html\n\nSee the documentation for full tutorials: https://cgmm.readthedocs.io/\n\n---\n\n## Documentation\n\nFull documentation is hosted on Read the Docs: https://cgmm.readthedocs.io/\n\nIncludes:\n- API reference\n- Tutorials and examples\n- Background on conditional GMMs\n\n---\n\n## Contributing\n\nContributions are welcome! Typical workflow:\n\n```bash\ngit clone https://github.com/your-org/cgmm.git\ncd cgmm\npoetry install -E docs --with dev\npre-commit install\n```\n\n- Format & lint: `make precommit`\n- Build docs locally: `make docs`\n- Bump version: `make bump-patch` (or minor/major)\n- Push tags \u2192 GitHub Actions \u2192 PyPI release\n\nPlease open issues or pull requests on GitHub.\n\n---\n\n## License\n\nBSD-3-Clause License \u00a9 2025 Thijs van den Berg\n\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "Conditional Gaussian Mixture Models compatible with scikit-learn",
"version": "0.3.2",
"project_urls": {
"Homepage": "https://github.com/sitmo/cgmm",
"Repository": "https://github.com/sitmo/cgmm"
},
"split_keywords": [
"gaussian mixture",
" scikit-learn",
" conditional"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "09a66896c6e0bcccf03054d08467ad02debde00dc618d0d77b49e85719dd69e2",
"md5": "8195f9216ffe242bae2cb63a2a846645",
"sha256": "df7a487050d63035d41ddae0328b2e59e385cd475d1c9b6e59564c14835ec85f"
},
"downloads": -1,
"filename": "cgmm-0.3.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8195f9216ffe242bae2cb63a2a846645",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.13,>=3.9",
"size": 9359,
"upload_time": "2025-09-01T20:59:20",
"upload_time_iso_8601": "2025-09-01T20:59:20.982410Z",
"url": "https://files.pythonhosted.org/packages/09/a6/6896c6e0bcccf03054d08467ad02debde00dc618d0d77b49e85719dd69e2/cgmm-0.3.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "03ac037c7abb62e46549f357045823c4adb8893eaa73865cc2c5efe6f33e9dc4",
"md5": "e2596f7c741403cc690e06686e0c9bfe",
"sha256": "de6e5f3c3bd88bf75d55461f77cc93663cdf1afbe1c4bbb41a1dba8f8013f951"
},
"downloads": -1,
"filename": "cgmm-0.3.2.tar.gz",
"has_sig": false,
"md5_digest": "e2596f7c741403cc690e06686e0c9bfe",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.13,>=3.9",
"size": 8450,
"upload_time": "2025-09-01T20:59:22",
"upload_time_iso_8601": "2025-09-01T20:59:22.725490Z",
"url": "https://files.pythonhosted.org/packages/03/ac/037c7abb62e46549f357045823c4adb8893eaa73865cc2c5efe6f33e9dc4/cgmm-0.3.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-01 20:59:22",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sitmo",
"github_project": "cgmm",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "cgmm"
}
JSON
