Metadata-Version: 2.4
Name: gmm-membership
Version: 0.3.0
Summary: Membership functions derived from one-dimensional Gaussian mixture posteriors
Author-email: Aleksandra Suwalska <Aleksandra.Suwalska@polsl.pl>
License-Expression: MIT
Project-URL: Publication, https://doi.org/10.3390/ijms241814033
Keywords: gaussian-mixture-model,membership-functions,posterior-probabilities,rare-cell-subtypes,mass-cytometry
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<3,>=1.24
Requires-Dist: scipy<2,>=1.10
Requires-Dist: matplotlib<4,>=3.7
Requires-Dist: seaborn<1,>=0.13
Provides-Extra: dev
Requires-Dist: pytest<9,>=8; extra == "dev"
Requires-Dist: ruff<1,>=0.6; extra == "dev"
Dynamic: license-file

# GMM Membership

`gmm-membership` converts posterior probabilities from one-dimensional Gaussian mixture models into ordered membership functions. It corrects tail-dominance reversals caused by components with unequal standard deviations and returns the intersections of adjacent corrected curves as cluster thresholds.

## Installation

Recommended, from pip:

```bash
python -m pip install gmm-membership
```

Directly from GitHub:

```bash
python -m pip install git+https://github.com/YOUR_GITHUB_USERNAME/gmm-membership.git
```

## Example

```python
import numpy as np

from gmm_membership import build_membership_functions

parameters = np.array([
    [-2.50, 0.22, 0.08],
    [-1.60, 1.10, 0.22],
    [0.50, 0.35, 0.12],
    [2.40, 0.95, 0.22],
    [4.00, 1.20, 0.26],
    [4.80, 0.25, 0.10],
])

result = build_membership_functions(
    parameters,
    grid_min=-6.0,
    grid_max=8.8,
)

membership = result.membership_functions
thresholds = result.thresholds
new_values = result.transform(np.array([-2.6, -1.4, 0.4, 4.9]))
```

## Main functions

`build_membership_functions` runs the complete correction pipeline. `compute_posterior_probabilities` computes smoothed GMM posterior probabilities. `compute_membership_thresholds` locates intersections of adjacent corrected curves. `evaluate_membership_functions` evaluates corrected functions for new observations. `identify_active_components` identifies components that dominate within their local regions. `plot_gmm_density`, `plot_posterior_probabilities`, and `plot_membership_functions` provide publication-oriented visualizations.

## Main parameters

`parameters` is an array with columns `mean`, `standard_deviation`, and `weight`. `grid_min` and `grid_max` define the evaluation interval. `settings` accepts a `CorrectionSettings` object controlling grid resolution, smoothing, search offsets, and interpolation anchors. Plotting functions accept `cmap`, `save_path`, and an optional existing Matplotlib `Axes` object. `plot_membership_functions` accepts `show_thresholds=True` to display cluster boundaries.

## Citation

Suwalska A, Polanska J. GMM-Based Expanded Feature Space as a Way to Extract Useful Information for Rare Cell Subtypes Identification in Single-Cell Mass Cytometry. *International Journal of Molecular Sciences*. 2023;24(18):14033. https://doi.org/10.3390/ijms241814033
