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:

python -m pip install gmm-membership

Directly from GitHub:

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

Example

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