StepMix

https://stepmix.readthedocs.io/en/latest/
Admin
StepMix is a Python package for stepwise estimation of mixture models with support for latent class...
Tokens:83,369
Snippets:522
Trust Score:9.6
Update:4 months ago
Show doc for...
Tokens:
Raw
### Import StepMix and Data

Source: https://stepmix.readthedocs.io/en/latest/api.html

Imports the StepMix model and a sample dataset. This is a common starting point for using the library.

```python
from stepmix.datasets import data_bakk_response
from stepmix.stepmix import StepMix
```

--------------------------------

### Install Stepmix Python Package

Source: https://stepmix.readthedocs.io/en/latest/_sources/installation.rst.txt

Install the Stepmix Python package using pip. It is recommended to perform this installation within a virtual environment.

```bash
pip install stepmix
```

--------------------------------

### StepMix Initialization with Default Parameters

Source: https://stepmix.readthedocs.io/en/latest/_modules/stepmix/stepmix.html

Initializes the StepMix model with the default number of components (2) and estimation steps (1). This is a basic setup for latent mixture modeling.

```python
from stepmix.stepmix import StepMix

# Initialize StepMix with default parameters
sm = StepMix()

```

--------------------------------

### Get Bootstrap Statistics

Source: https://stepmix.readthedocs.io/en/latest/api.html

Provides bootstrapped parameters and statistics (mean, standard deviation) for the model. Omits covariate-related keys if a covariate model is used.

```python
model.bootstrap_stats(_X_ , _Y =None_, _n_repetitions =1000_, _sample_weight =None_, _parametric =False_, _progress_bar =True_)
```

--------------------------------

### Initialize StepMix Parameters with KMeans

Source: https://stepmix.readthedocs.io/en/latest/_modules/stepmix/stepmix.html

Initializes responsibilities for the StepMix model using KMeans clustering. This method is suitable when you want to start with distinct clusters identified by KMeans.

```python
        if self.init_params == "kmeans":
            resp = np.zeros((n_samples, self.n_components))
            label = (
                KMeans(
                    n_clusters=self.n_components, n_init=1, random_state=random_state
                )
                .fit(X)
                .labels_
            )
            resp[np.arange(n_samples), label] = 1

```

--------------------------------

### initialize

Source: https://stepmix.readthedocs.io/en/latest/api.html

Initializes the Gaussian model parameters by performing the m-step on the current responsibilities.

```APIDOC
## initialize(_X_ , _resp_ , _random_state =None_)

### Description
Initialize parameters. Simply performs the m-step on the current responsibilities to initialize parameters.

### Parameters
* **X** (_ndarray_ _of_ _shape_ _(__n_samples_ _,__n_features_ _)_) – Input data for this emission model.
* **resp** (_ndarray_ _of_ _shape_ _(__n_samples_ _,__n_components_ _)_) – Responsibilities, i.e., posterior probabilities over the latent classes.
* **random_state** (_int_ _,__RandomState instance_ _or_ _None_ _,__default=None_) – Controls the random seed given to the method chosen to initialize the parameters. Pass an int for reproducible output across multiple function calls.
```

--------------------------------

### get_default_feature_names

Source: https://stepmix.readthedocs.io/en/latest/api.html

Gets default feature names for the GaussianSpherical model.

```APIDOC
## get_default_feature_names(_n_features_)

### Description
Get default feature names.
```

--------------------------------

### GaussianUnit.initialize

Source: https://stepmix.readthedocs.io/en/latest/api.html

Initializes the GaussianUnit emission model parameters by performing the M-step on the current responsibilities.

```APIDOC
## GaussianUnit.initialize

### Description
Initialize parameters. Simply performs the m-step on the current responsibilities to initialize parameters.

### Parameters
* **X** (ndarray of shape (n_samples, n_features)) – Input data for this emission model.
* **resp** (ndarray of shape (n_samples, n_components)) – Responsibilities, i.e., posterior probabilities over the latent classes.
* **random_state** (int, RandomState instance or None, default=None) – Controls the random seed given to the method chosen to initialize the parameters. Pass an int for reproducible output across multiple function calls.
```

--------------------------------

### MultinoulliNan - get_n_features

Source: https://stepmix.readthedocs.io/en/latest/api.html

Gets the number of features for the MultinoulliNan emission model.

```APIDOC
## get_n_features

### Description
Gets the number of features for the MultinoulliNan emission model.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
None

#### Response Example
None
```

--------------------------------

### Gaussian.initialize

Source: https://stepmix.readthedocs.io/en/latest/api.html

Initializes the Gaussian emission model parameters by performing the m-step on the current responsibilities.

```APIDOC
## Gaussian.initialize

### Description
Initializes parameters by performing the m-step on the current responsibilities.

### Method
initialize(_X_ , _resp_ , _random_state =None_)

### Parameters
* **X** (_ndarray_ _of_ _shape_ _(__n_samples_ _,__n_features_ _)_) – Input data for this emission model.
* **resp** (_ndarray_ _of_ _shape_ _(__n_samples_ _,__n_components_ _)_) – Responsibilities, i.e., posterior probabilities over the latent classes.
* **random_state** (_int_ _,__RandomState instance_ _or_ _None_ _,__default=None_) – Controls the random seed for parameter initialization.
```

--------------------------------

### Gaussian.initialize

Source: https://stepmix.readthedocs.io/en/latest/api.html

Initializes the Gaussian emission model parameters by performing the m-step on the current responsibilities.

```APIDOC
## Gaussian.initialize

### Description
Initializes parameters by performing the m-step on the current responsibilities.

### Method
initialize(X, resp, random_state=None)

### Parameters
* **X** (ndarray of shape (n_samples, n_features)) – Input data for this emission model.
* **resp** (ndarray of shape (n_samples, n_components)) – Responsibilities, i.e., posterior probabilities over the latent classes.
* **random_state** (int, RandomState instance or None, default=None) – Controls the random seed for parameter initialization.
```

--------------------------------

### MultinoulliNan - get_parameters

Source: https://stepmix.readthedocs.io/en/latest/api.html

Gets a copy of the model parameters for the MultinoulliNan emission model.

```APIDOC
## get_parameters

### Description
Gets a copy of the model parameters for the MultinoulliNan emission model.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
* **parameters** (_dict_) – Copy of model parameters.

#### Response Example
None
```

--------------------------------

### Gaussian.initialize

Source: https://stepmix.readthedocs.io/en/latest/api.html

Initializes the Gaussian emission model parameters by performing the M-step on the current responsibilities.

```APIDOC
## Gaussian.initialize

### Description
Initializes parameters by performing the m-step on the current responsibilities.

### Parameters
* **X** (ndarray of shape (n_samples, n_features)) – Input data for this emission model.
* **resp** (ndarray of shape (n_samples, n_components)) – Responsibilities, i.e., posterior probabilities over the latent classes.
* **random_state** (int, RandomState instance or None, default=None) – Controls the random seed given to the method chosen to initialize the parameters. Pass an int for reproducible output across multiple function calls.
```

--------------------------------

### MultinoulliNan - get_default_feature_names

Source: https://stepmix.readthedocs.io/en/latest/api.html

Gets the default feature names for the MultinoulliNan emission model.

```APIDOC
## get_default_feature_names

### Description
Gets the default feature names for the MultinoulliNan emission model.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* **n_features** (_int_) – The number of features.

### Request Example
None

### Response
#### Success Response (200)
None

#### Response Example
None
```

--------------------------------

### MultinoulliNan - initialize

Source: https://stepmix.readthedocs.io/en/latest/api.html

Initializes parameters for the MultinoulliNan emission model using the current responsibilities. This method performs the m-step to initialize parameters.

```APIDOC
## initialize

### Description
Initializes parameters for the MultinoulliNan emission model using the current responsibilities. This method performs the m-step to initialize parameters.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* **X** (_ndarray_ _of_ _shape_ _(__n_samples_ _,__n_features_ _)_) – Input data for this emission model.
* **resp** (_ndarray_ _of_ _shape_ _(__n_samples_ _,__n_components_ _)_) – Responsibilities, i.e., posterior probabilities over the latent classes.
* **random_state** (_int_ _,__RandomState instance_ _or_ _None_ _,__default=None_) – Controls the random seed given to the method chosen to initialize the parameters. Pass an int for reproducible output across multiple function calls.

### Request Example
None

### Response
#### Success Response (200)
None

#### Response Example
None
```

--------------------------------

### Datasets

Source: https://stepmix.readthedocs.io/en/latest/api.html

Utility functions for loading and generating datasets used in StepMix examples and testing.

```APIDOC
## Datasets

### Description
Functions for loading and generating datasets.

### Functions
- `bakk_measurements()`
- `data_bakk_complete()`
- `data_bakk_complex()`
- `data_bakk_covariate()`
- `data_bakk_response()`
- `data_gaussian_binary()`
- `data_gaussian_categorical()`
- `data_gaussian_diag()`
- `data_generation_gaussian()`
- `random_nan()`
```

--------------------------------

### Get Number of Features

Source: https://stepmix.readthedocs.io/en/latest/_modules/stepmix/emission/categorical.html

Calculates and returns the number of features based on the shape of the 'pis' parameters and 'max_n_outcomes'.

```python
n_features_x_max_n_outcomes = self.parameters["pis"].shape[1]
        n_features = int(
            n_features_x_max_n_outcomes / self.parameters["max_n_outcomes"]
        )
        return n_features
```

--------------------------------

### GaussianUnitNan.initialize

Source: https://stepmix.readthedocs.io/en/latest/api.html

Initializes the parameters of the GaussianUnitNan model by performing an m-step on the current responsibilities.

```APIDOC
## initialize

### Description
Initialize parameters. Simply performs the m-step on the current responsibilities to initialize parameters.

### Method
initialize

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* **X** (ndarray of shape (n_samples, n_features)) - Input data for this emission model.
* **resp** (ndarray of shape (n_samples, n_components)) - Responsibilities, i.e., posterior probabilities over the latent classes of each point in X.
* **random_state** (int, RandomState instance or None, default=None) - Controls the random seed given to the method chosen to initialize the parameters. Pass an int for reproducible output across multiple function calls.

### Request Example
None

### Response
#### Success Response (200)
None

### Response Example
None
```

--------------------------------

### initialize()

Source: https://stepmix.readthedocs.io/en/latest/api.html

Initializes the model parameters using the m-step on the current responsibilities.

```APIDOC
## initialize(_X_ , _resp_ , _random_state =None_)

### Description
Initializes the model parameters using the m-step on the current responsibilities.

### Parameters
* **X** (ndarray of shape (n_samples, n_features)) - Input data for this emission model.
* **resp** (ndarray of shape (n_samples, n_components)) - Responsibilities, i.e., posterior probabilities over the latent classes.
* **random_state** (int, RandomState, or None, optional) - Controls the random seed for parameter initialization.
```

--------------------------------

### MultinoulliNan Get Parameters

Source: https://stepmix.readthedocs.io/en/latest/api.html

Retrieves a copy of the current model parameters. The returned dictionary should have the same format as expected by the set_parameters method.

```python
get_parameters()
    
    Get a copy of model parameters. 

    Returns:
        
    parameters – Copy of model parameters.

    Return type:
        
    dict
```

--------------------------------

### Gaussian Emission Model - Get Parameters

Source: https://stepmix.readthedocs.io/en/latest/_modules/stepmix/emission/gaussian.html

Retrieves the current parameters (means, covariances, precisions_cholesky) of the Gaussian emission model.

```python
    def get_parameters(self):
        return dict(
            means=self.means_.copy(),
            covariances=self.covariances_.copy(),
            precisions_cholesky=self.precisions_cholesky_.copy(),
        )
```

--------------------------------

### Gaussian Emission Model with NaN Support Initialization

Source: https://stepmix.readthedocs.io/en/latest/_modules/stepmix/emission/gaussian.html

Initializes the Gaussian emission model that supports missing values (NaNs) using the Full Information Maximum Likelihood approach. Assumes a diagonal covariance structure.

```python
def __init__(self, debug_likelihood=False, **kwargs):
    super().__init__(**kwargs)
    self.debug_likelihood = debug_likelihood
```

--------------------------------

### Get Structural Model Parameters

Source: https://stepmix.readthedocs.io/en/latest/_modules/stepmix/stepmix.html

Retrieves structural model parameters as a DataFrame. This method requires that a structural model has already been fitted.

```python
def get_sm_df(self, x_names=None, y_names=None):
    """Get structural model parameters as DataFrame with classes as columns.

    Parameters
    ----------
    x_names : List of str
        Column names of X.
    y_names : List of str
        Column names of Y.

    Returns
    -------
    params: pd.DataFrame
    """
    if not hasattr(self, "_sm"):
        raise ValueError("No structural model fitted.")
    df = self.get_parameters_df(x_names, y_names).loc["structural"]
    return self._pivot_param(df, aggfunc="mean")  # Mean of one value if okay
```

--------------------------------

### MultinoulliNan Get Number of Features

Source: https://stepmix.readthedocs.io/en/latest/api.html

Returns the number of features the emission model is configured to handle. This can be used to ensure compatibility with input data.

```python
get_n_features()
     
```

--------------------------------

### MultinoulliNan Parameter Initialization

Source: https://stepmix.readthedocs.io/en/latest/api.html

Initializes the model parameters using the current responsibilities. This method performs the m-step to set initial parameters based on the provided data and responsibilities.

```python
initialize(_X_ , _resp_ , _random_state =None_)
    
    Initialize parameters.
    Simply performs the m-step on the current responsibilities to initialize parameters. 

    Parameters:
        
      * **X** (_ndarray_ _of_ _shape_ _(__n_samples_ _,__n_features_ _)_) – Input data for this emission model.
      * **resp** (_ndarray_ _of_ _shape_ _(__n_samples_ _,__n_components_ _)_) – Responsibilities, i.e., posterior probabilities over the latent classes. 
      * **random_state** (_int_ _,__RandomState instance_ _or_ _None_ _,__default=None_) – Controls the random seed given to the method chosen to initialize the parameters. Pass an int for reproducible output across multiple function calls.
    
```

--------------------------------

### Gaussian Initialization using _initialize

Source: https://stepmix.readthedocs.io/en/latest/_modules/stepmix/emission/gaussian.html

Initializes the Gaussian model parameters (means, covariances, precisions) using scikit-learn's internal _initialize method. This method also performs the M-step.

```python
def initialize(self, X, resp, random_state=None):
        self.check_parameters()

        # Required to get the initial means, covariances and precisions right
        # Already performs the M-step
        GaussianMixture._initialize(self, X, resp)
```

--------------------------------

### Get Measurement Model Parameters

Source: https://stepmix.readthedocs.io/en/latest/_modules/stepmix/stepmix.html

Retrieves measurement model parameters as a DataFrame. Useful for inspecting the learned parameters of the measurement component of the model.

```python
def get_mm_df(self, x_names=None, y_names=None):
    """Get measurement model parameters as DataFrame with classes as columns.

    Parameters
    ----------
    x_names : List of str
        Column names of X.
    y_names : List of str
        Column names of Y.

    Returns
    -------
    params: pd.DataFrame
    """
    df = (
        self.get_parameters_df(x_names, y_names)
        .loc["measurement"]
        .drop("class_weights", level=0, errors="ignore")
    )
    return self._pivot_param(df, aggfunc="mean")  # Mean of one value is okay
```

--------------------------------

### Get Class Weights DataFrame

Source: https://stepmix.readthedocs.io/en/latest/_modules/stepmix/stepmix.html

Retrieves class weights as a DataFrame with classes as columns. This method is only available when not using the conditional likelihood perspective.

```python
if self._conditional_likelihood:
    raise ValueError(
        "Class weights are not defined when using the conditional likelihood perspective (covariates)."
    )
df = self.get_parameters_df(x_names, y_names).loc[
        "measurement", "class_weights"
    ]
return self._pivot_cw(df, aggfunc="mean")
```

--------------------------------

### GaussianFull Emission Model - Initialization

Source: https://stepmix.readthedocs.io/en/latest/_modules/stepmix/emission/gaussian.html

Initializes the GaussianFull emission model, setting the covariance type to 'full'.

```python
class GaussianFull(Gaussian):
    def __init__(self, **kwargs):
        # Make sure no other covariance_type is specified
        kwargs.pop("covariance_type", None)
        super().__init__(covariance_type="full", **kwargs)
        self.model_str = "gaussian_full"
```

--------------------------------

### StepMix EM Algorithm Initialization and Iterations

Source: https://stepmix.readthedocs.io/en/latest/_modules/stepmix/stepmix.html

This code snippet illustrates the initialization and main loop of the Expectation-Maximization (EM) algorithm within the StepMix library. It handles multiple restarts, E-step, M-step, and convergence checks.

```python
        random_state = check_random_state(self.random_state)
        max_lower_bound = -np.inf
        self.converged_ = False

        # Run multiple restarts
        if self.progress_bar:
            print("Fitting StepMix...")
        if self.progress_bar == 2:
            print(
                "The Iteration bar may update too quickly to be visualized depending on dataset size and StepMix settings.\n"
            )
        tqdm_init = tqdm.trange(
            self.n_init, disable=not self.progress_bar, desc="Initializations (n_init) "
        )
        for init in tqdm_init:
            if not freeze_measurement:
                self._initialize_parameters(X, random_state)  # Measurement model

            if Y is not None:
                self._initialize_parameters_structural(
                    Y, random_state
                )  # Structural Model

            lower_bound = -np.inf

            # EM iterations
            tqdm_iter = tqdm.tqdm(
                range(1, self.max_iter + 1),
                disable=self.progress_bar < 2,
                desc="Iterations (max_iter)    ",
                leave=False,
            )
            for n_iter in tqdm_iter:
                prev_lower_bound = lower_bound

                # E-step
                log_prob_norm, log_resp = self._e_step(
                    X, Y=Y, sample_weight=sample_weight, log_emission_pm=log_emission_pm
                )

                # M-step
                self._m_step(
                    X,
                    np.exp(log_resp),
                    Y,
                    sample_weight=sample_weight,
                    freeze_measurement=freeze_measurement,
                )

                # Likelihood & stopping criterion
                lower_bound = log_prob_norm
                change = lower_bound - prev_lower_bound
                rel_change = change / lower_bound

                # if both an absolute and a relative tolerance threshold are given, the EM algorithm stops
                # as soon as one of them is respected
                if abs(change) < self.abs_tol or abs(rel_change) < self.rel_tol:
                    self.converged_ = True
                    break

                # Ask tqdm to display current max lower bound
                ll = (
                    lower_bound * np.sum(sample_weight)
                    if sample_weight is not None
                    else lower_bound * n_samples
                )
                tqdm_iter.set_postfix(avg_LL=lower_bound, LL=ll)

            # Update buffers
            current_parameters = self.get_parameters()

            if (
                lower_bound > max_lower_bound
                or max_lower_bound == -np.inf
                or np.isnan(max_lower_bound)
            ):
                max_lower_bound = lower_bound
                best_params = current_parameters
                best_n_iter = n_iter

            if self.save_param_init:
                self.param_buffer_.append(copy.deepcopy(current_parameters))

            # Save lower bound
            ll, _ = self._e_step(
                X, Y=Y, sample_weight=sample_weight, log_emission_pm=log_emission_pm
            )
            self.lower_bound_buffer_.append(ll)

            # Ask tqdm to display current max lower bound
            max_ll = (
                max_lower_bound * np.sum(sample_weight)
                if sample_weight is not None
                else max_lower_bound * n_samples
            )
            tqdm_init.set_postfix(max_avg_LL=max_lower_bound, max_LL=max_ll)

        if not self.converged_:
            warnings.warn(
                "Initializations did not converge. "
                "Try different init parameters, "
                "or increase max_iter, abs_tol, rel_tol "
                "or check for degenerate data.",
                ConvergenceWarning,
            )

        self.set_parameters(best_params)
        self.n_iter_ = best_n_iter
        self.lower_bound_ = max_lower_bound

```

--------------------------------

### GaussianDiag Emission Model - Get Parameters DataFrame

Source: https://stepmix.readthedocs.io/en/latest/_modules/stepmix/emission/gaussian.html

Retrieves the parameters of the GaussianDiag emission model as a pandas DataFrame, including means and covariances.

```python
    def get_parameters_df(self, feature_names=None):
        params = self.get_parameters()
        return self._to_df(
            param_dict=params,
            keys=["means", "covariances"],
            feature_names=feature_names,
        )
```

--------------------------------

### GaussianFull Emission Model - Get Parameters DataFrame

Source: https://stepmix.readthedocs.io/en/latest/_modules/stepmix/emission/gaussian.html

Retrieves the parameters of the GaussianFull emission model as a pandas DataFrame, including means and covariances.

```python
    def get_parameters_df(self, feature_names=None):
        """Return self.parameters into a long dataframe.

        Call self._to_df or implement custom method."""
        if feature_names is None:
            n_features = self.parameters["means"].shape[1]
            feature_names = self.get_default_feature_names(n_features)

        means = self._to_df(
            param_dict=self.parameters, keys=["means"], feature_names=feature_names
        )
        cov = cov_np_to_df(
            self.parameters["covariances"], feature_names, self.model_str
        )

        return pd.concat([means, cov])
```

--------------------------------

### GaussianFull Emission Model - Print Parameters

Source: https://stepmix.readthedocs.io/en/latest/_modules/stepmix/emission/gaussian.html

Prints the parameters of the GaussianFull emission model, with a specific format for full covariances.

```python
    def print_parameters(
        self,
        indent=1,
        feature_names=None,
        index=["class_no", "param"],
        columns=["model_name", "variable"],
    ):
        """Flipping class_no and variable is nicer for full covariances."""
        super().print_parameters(
            indent=indent, feature_names=feature_names, index=index, columns=columns
        )
```

--------------------------------

### Covariate Model Initialization

Source: https://stepmix.readthedocs.io/en/latest/_modules/stepmix/emission/covariate.html

Initializes the Covariate emission model with specified parameters like tolerance, max iterations, learning rate, and optimization method. It also sets up the model string and checks parameter validity.

```python
class Covariate(Emission):
    """Covariate model with descent update.


    Parameters
    ----------
    tol : float, default=1e-4
        Absolute tolerance applied to each component of the gradient.
    max_iter : int, default=100
        The maximum number of steps to take per M-step.
    lr : float, default=1e-3
        Learning rate.
    intercept : bool, default=True
        If an intercept parameter should be fitted.
    method: {"gradient", "newton-raphson"}, default="gradient"
        Optimization method.
    """

    def __init__(
        self,
        tol=1e-4,
        max_iter=1,
        lr=1e-3,
        intercept=True,
        method="newton-raphson",
        **kwargs,
    ):
        super().__init__(**kwargs)
        self.tol = tol
        self.max_iter = max_iter
        self.lr = lr
        self.intercept = intercept
        self.method = method
        self.model_str = "covariate"
```

--------------------------------

### Get Parameters DataFrame for Nested Models

Source: https://stepmix.readthedocs.io/en/latest/_modules/stepmix/emission/nested.html

Retrieves a DataFrame containing parameters for all nested models. It handles feature name mapping for submodels.

```python
import pandas as pd

# Assuming 'self.models' is a dictionary of models and 'self.columns_per_model' is a list of column counts per model
def get_parameters_df(self, feature_names=None):
    df_list = list()
    if feature_names is None:
        n_columns = sum(self.columns_per_model)
        feature_names = self.get_default_feature_names(n_columns)

    i = 0
    for name, m, range_ in zip(
        self.models.keys(), self.models.values(), self.columns_per_model
    ):
        # Slice parameter names to get the right column names for this submodel
        f_i = feature_names[i : i + range_]
        df_i = m.get_parameters_df(f_i)
        df_i["model_name"] = name
        df_list.append(df_i)
        i += range_

    return pd.concat(df_list)
```

--------------------------------

### stepmix.datasets.data_bakk_complex

Source: https://stepmix.readthedocs.io/en/latest/api.html

Builds a simulated example with mixed data and missing values, suitable for complex Bakk 2018 simulations. Returns data as a dataframe.

```APIDOC
## stepmix.datasets.data_bakk_complex(_n_samples_ , _sep_level_ , _random_state =None_, _nan_ratio =0.0_)

### Description
Build a simulated example with mixed data and missing values. Measurements: 3 binary variables + 1 continuous variable. Structural: 3 binary response variables + 1 continuous response variable + 1 covariate. Missing values everywhere except in the covariate. Return data as a dataframe.
```

--------------------------------

### sample

Source: https://stepmix.readthedocs.io/en/latest/_modules/stepmix/stepmix.html

Sample method for fitted StepMix model. Adapted from the sklearn BaseMixture sample method.

```APIDOC
## sample(n_samples, labels=None)

### Description
Sample method for fitted StepMix model. Adapted from the sklearn BaseMixture sample method.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **n_samples** (int) - Required - Number of samples.
- **labels** (ndarray of shape (n_samples,)) - Optional - Predetermined class labels. Will ignore class weights if provided.

### Returns
- **X** (array-like of shape (n_samples, n_columns)) - Measurement samples.
- **Y** (array-like of shape (n_samples, n_columns_structural)) - Structural samples.
- **labels** (ndarray of shape (n_samples,)) - Ground truth class membership.

### Request Example
None

### Response
#### Success Response (200)
- **X** (array-like of shape (n_samples, n_columns)) - Measurement samples.
- **Y** (array-like of shape (n_samples, n_columns_structural)) - Structural samples.
- **labels** (ndarray of shape (n_samples,)) - Ground truth class membership.

#### Response Example
None
```

--------------------------------

### Build and Initialize Measurement Model

Source: https://stepmix.readthedocs.io/en/latest/_modules/stepmix/stepmix.html

Constructs and initializes the measurement model for StepMix. It uses the `build_emission` function and then calls the `initialize` method on the created measurement model.

```python
        if not hasattr(self, "_mm"):
            mm_params = (
                self.measurement_params
                if self.measurement_params is not None
                else dict()
            )
            self._mm = build_emission(
                self.measurement,
                n_components=self.n_components,
                random_state=random_state,
                **mm_params,
            )
        if init_emission:
            self._mm.initialize(X, np.exp(self.log_resp_), random_state)

```

--------------------------------

### StepMix Initialization with Custom Parameters

Source: https://stepmix.readthedocs.io/en/latest/_modules/stepmix/stepmix.html

Initializes the StepMix model with a specified number of latent classes (e.g., 3) and a 3-step estimation process. This configuration is suitable for more complex analyses requiring sequential fitting and bias correction.

```python
from stepmix.stepmix import StepMix

# Initialize StepMix with 3 components and 3 steps
sm = StepMix(n_components=3, n_steps=3)

```

--------------------------------

### GaussianSpherical Emission Model - Get Parameters DataFrame

Source: https://stepmix.readthedocs.io/en/latest/_modules/stepmix/emission/gaussian.html

Retrieves the parameters of the GaussianSpherical emission model as a pandas DataFrame. Adjusts covariances for the DataFrame format.

```python
    def get_parameters_df(self, feature_names=None):
        params = self.get_parameters()
        n_features = params["means"].shape[1]
        params["covariances"] = np.tile(params["covariances"], (n_features, 1)).T
        return self._to_df(
            param_dict=params,
            keys=["means", "covariances"],
            feature_names=feature_names,
        )
```

--------------------------------

### Permute Latent Classes

Source: https://stepmix.readthedocs.io/en/latest/_modules/stepmix/stepmix.html

Permutes the latent classes and their associated parameters. This is useful for remapping classes, for example, after model fitting to ensure consistent ordering.

```python
def permute_classes(self, perm):
    """Permute the latent class and associated parameters of this estimator.

    Effectively remaps latent classes.

    Parameters
    ----------
    perm : ndarray of shape  (n_classes,)
        Integer array representing the target permutation. Should be a permutation of np.arange(n_classes).
    """
    check_is_fitted(self)
    self.weights_ = self.weights_[perm]

    # Permute classes of measurement model
    self._mm.permute_classes(perm)

    # Permute classes of structural model (if any)
    if hasattr(self, "_sm"):
        self._sm.permute_classes(perm)
```

--------------------------------

### StepMix Initialization with Missing Data Support

Source: https://stepmix.readthedocs.io/en/latest/_modules/stepmix/stepmix.html

Initializes the StepMix model using a 'gaussian_diag_nan' measurement model, which supports missing values in continuous data. This is crucial for datasets with incomplete observations, enabling robust analysis without imputation.

```python
from stepmix.stepmix import StepMix

# Initialize StepMix with a Gaussian diagonal measurement model that supports NaNs
sm = StepMix(measurement='gaussian_diag_nan')

```

--------------------------------

### Build and Initialize Structural Model

Source: https://stepmix.readthedocs.io/en/latest/_modules/stepmix/stepmix.html

Constructs and initializes the structural model for StepMix. Similar to the measurement model, it uses `build_emission` and then calls `initialize`.

```python
        if not hasattr(self, "_sm"):
            sm_params = (
                self.structural_params if self.structural_params is not None else dict()
            )
            self._sm = build_emission(
                self.structural,
                n_components=self.n_components,
                random_state=random_state,
                **sm_params,
            )
        if init_emission:
            self._sm.initialize(Y, np.exp(self.log_resp_), random_state)

```

--------------------------------

### MultinoulliNan Get Default Feature Names

Source: https://stepmix.readthedocs.io/en/latest/api.html

Generates default feature names based on the specified number of features. This is useful when explicit feature names are not provided.

```python
get_default_feature_names(_n_features_)
     
```

--------------------------------

### StepMix Initialization

Source: https://stepmix.readthedocs.io/en/latest/_modules/stepmix/stepmix.html

Initializes the StepMix model with various parameters to control the estimation process, model structure, and convergence criteria.

```APIDOC
## StepMix Class

### Description

Initializes the StepMix model. This class allows for mixture modeling with a step-wise estimation approach, supporting different measurement and structural models, and various initialization and assignment strategies.

### Parameters

- **n_components** (int) - Optional - The number of mixture components (default: 2).
- **n_steps** (int) - Optional - The number of steps for estimation (1, 2, or 3) (default: 1).
- **measurement** (str) - Optional - The type of measurement model (e.g., 'bernoulli', 'gaussian_unit') (default: 'bernoulli').
- **structural** (str) - Optional - The type of structural model (e.g., 'gaussian_unit') (default: 'gaussian_unit').
- **assignment** (str) - Optional - The assignment strategy ('modal' or 'soft') (default: 'modal').
- **correction** (str or None) - Optional - Correction method ('BCH' or 'ML') (default: None).
- **abs_tol** (float) - Optional - Absolute tolerance for convergence (default: 1e-10).
- **rel_tol** (float) - Optional - Relative tolerance for convergence (default: 0.00).
- **max_iter** (int) - Optional - Maximum number of iterations for the EM algorithm (default: 1000).
- **n_init** (int) - Optional - Number of initializations to perform (default: 1).
- **save_param_init** (bool) - Optional - Whether to save parameters from initializations (default: False).
- **init_params** (str) - Optional - Initialization method ('kmeans' or 'random') (default: 'random').
- **random_state** (int or None) - Optional - Seed for random number generation (default: None).
- **verbose** (int) - Optional - Verbosity level (default: 0).
- **progress_bar** (int) - Optional - Whether to display a progress bar (0 or 1) (default: 1).
- **measurement_params** (dict or None) - Optional - Additional parameters for the measurement model (default: None).
- **structural_params** (dict or None) - Optional - Additional parameters for the structural model (default: None).

### Examples

```python
from stepmix.datasets import data_bakk_response
from stepmix.stepmix import StepMix

# Soft 3-step estimation
X, Y, _ = data_bakk_response(n_samples=1000, sep_level=.7, random_state=42)
model = StepMix(n_components=3, n_steps=3, measurement='bernoulli', structural='gaussian_unit', random_state=42, assignment='soft')
model.fit(X, Y)
print(model.score(X, Y))  # Average log-likelihood

# Individual step execution
model = StepMix(n_components=3, measurement='bernoulli', structural='gaussian_unit', random_state=42)
model.em(X) # Step 1: EM algorithm
probs = model.predict_proba(X) # Step 2: Predict probabilities
model.m_step_structural(probs, Y) # Step 3: Structural model step
print(model.score(X, Y))  # Average log-likelihood
```
```

--------------------------------

### Get Model Parameters

Source: https://stepmix.readthedocs.io/en/latest/_modules/stepmix/stepmix.html

Retrieves the current model parameters as a nested dictionary. This includes weights, measurement parameters, structural parameters (if applicable), and input dimensions.

```python
check_is_fitted(self)
params = dict(
    weights=self.weights_,
    measurement=self._mm.get_parameters(),
    measurement_in=self.measurement_in_,
)
if hasattr(self, "_sm"):
    params["structural"] = self._sm.get_parameters()
    params["structural_in"] = self.structural_in_
return params
```

--------------------------------

### StepMix Soft 3-Step Estimation

Source: https://stepmix.readthedocs.io/en/latest/_modules/stepmix/stepmix.html

Demonstrates fitting a soft 3-step StepMix model using Bernoulli measurement and Gaussian structural models. This snippet shows the direct fitting approach.

```python
from stepmix.datasets import data_bakk_response
from stepmix.stepmix import StepMix
# Soft 3-step
X, Y, _ = data_bakk_response(n_samples=1000, sep_level=.7, random_state=42)
model = StepMix(n_components=3, n_steps=3, measurement='bernoulli', structural='gaussian_unit', random_state=42, assignment='soft')
model.fit(X, Y)
model.score(X, Y)  # Average log-likelihood
```

--------------------------------

### Get Full Matrix with Intercept

Source: https://stepmix.readthedocs.io/en/latest/_modules/stepmix/emission/covariate.html

Constructs the full design matrix by adding a column of ones for the intercept term if specified. This is used internally for model calculations.

```python
def get_full_matrix(self, X):
        n, _ = X.shape
        if self.intercept:
            return np.concatenate((np.ones((n, 1)), X), axis=1)
        else:
            return X
```

--------------------------------

### GaussianTied.initialize

Source: https://stepmix.readthedocs.io/en/latest/api.html

Initializes parameters for the GaussianTied model.

```APIDOC
## GaussianTied.initialize

### Description
Initialize parameters.

### Method
initialize(X, resp, random_state=None)
```

--------------------------------

### MultinoulliNan Get Parameters DataFrame

Source: https://stepmix.readthedocs.io/en/latest/api.html

Expands feature names for parameters, accommodating cases where each feature might have multiple outcomes. This provides a structured DataFrame view of the parameters.

```python
get_parameters_df(_feature_names =None_)
    
    Expand the feature names since each feature may have up to max_n_outcomes outcomes. 
    
```

--------------------------------

### Fit StepMix Model (Two-Step Estimation - Step 1)

Source: https://stepmix.readthedocs.io/en/latest/_modules/stepmix/stepmix.html

Initiates the two-step estimation process by fitting the measurement model first. This is the first part of the two-step approach when n_steps is set to 2.

```python
def fit(self, X, Y=None, sample_weight=None, y=None):
    """Fit StepMix measurement model and optionally the structural model.

    Setting Y=None will fit the measurement model only. Providing both X and Y will fit the full model following
    the self.n_steps argument.

    Parameters
    ----------
    X : array-like of shape (n_samples, n_features)
        List of n_features-dimensional data points to fit the measurement model. Each row
        corresponds to a single data point. If the data is categorical, by default it should be
        0-indexed and integer encoded (not one-hot encoded).
    Y : array-like of shape (n_samples, n_features_structural), default=None
        List of n_features-dimensional data points to fit the structural model. Each row
        corresponds to a single data point. If the data is categorical, by default it should be
        0-indexed and integer encoded (not one-hot encoded).
    y: array-like of shape (n_samples, n_features), default=None
        Alias for Y. Ignored if Y is provided.
    sample_weight : array-like of shape(n_samples,), default=None
        Array of weights that are assigned to individual samples.
        If not provided, then each sample is given unit weight.

    """
    if y is not None and Y is None:
        Y = y

    if Y is None:
        # No structural data. Simply fit the measurement data
        self.em(X, sample_weight=sample_weight)

    elif self.n_steps == 1:
        # One-step estimation
        # 1) Maximum likelihood with both measurement and structural models
        self.em(X, Y, sample_weight=sample_weight)

    elif self.n_steps == 2:
        # Two-step estimation
        # 1) Fit the measurement model
```

--------------------------------

### Get Model Parameters as DataFrame

Source: https://stepmix.readthedocs.io/en/latest/_modules/stepmix/stepmix.html

Returns model parameters in a long-form DataFrame format. Useful for detailed inspection and analysis of model coefficients across different components.

```python
check_is_fitted(self)

# Dataframe of the measurement model
if x_names is None:
    x_names = self.x_names_
df_mm = self._mm.get_parameters_df(x_names)
df_mm["model"] = "measurement"
list_df = [df_mm]

if not self._conditional_likelihood:
    # No class weights if we are using the conditional perspective
    # Create a dataframe for class weights
    df_class = list()
    for class_no, w in enumerate(self.weights_):
        df_class.append(
            dict(
                model="measurement",
                model_name="class_weights",
                param="class_weights",
                class_no=class_no,
                variable="nan",
                value=w,
            )
        )

    df_class = pd.DataFrame.from_records(df_class)
    list_df.append(df_class)

if hasattr(self, "_sm"):
    if y_names is None:
        y_names = self.y_names_
    df_sm = self._sm.get_parameters_df(y_names)
    df_sm["model"] = "structural"
    list_df.append(df_sm)

df = pd.concat(list_df)

return df.set_index(["model", "model_name", "param", "class_no", "variable"])
```

--------------------------------

### Multinoulli Model Class Permutation

Source: https://stepmix.readthedocs.io/en/latest/api.html

Permutes the latent classes and their associated parameters within the Multinoulli model. This is useful for reordering or aligning components, for example, after model fitting.

```python
import numpy as np
from stepmix.emission import Multinoulli

model = Multinoulli(n_components=3)
# Assume model parameters are already set

# Define a permutation for the 3 classes (e.g., swap class 0 and 2)
perm = np.array([2, 1, 0]) 
model.permute_classes(perm)

# The model's internal parameters will now reflect this permutation.
```

--------------------------------

### GaussianTied Emission Model - Print Parameters

Source: https://stepmix.readthedocs.io/en/latest/_modules/stepmix/emission/gaussian.html

Prints the parameters of the GaussianTied emission model.

```python
    def print_parameters(
        self,
        indent=1,
        feature_names=None,

```

--------------------------------

### StepMix Model Parameters

Source: https://stepmix.readthedocs.io/en/latest/api.html

This section outlines the parameters available when initializing the StepMix model. These parameters control various aspects of the model's estimation process, including convergence criteria, initialization methods, and correction techniques.

```APIDOC
## StepMix Model Initialization Parameters

### Description
Parameters for initializing and configuring the StepMix model.

### Parameters
#### Initialization Parameters
- **modal** (bool) - Assign 1 to the class with max probability, 0 otherwise (one-hot encoding).
- **correction** (str, optional) - Bias correction for 3-step estimation. Must be one of: 'None', 'BCH', 'ML'. Defaults to None.
- **abs_tol** (float, optional) - The convergence threshold for the lower bound average gain. Defaults to 1e-10.
- **rel_tol** (float, optional) - The convergence threshold for the relative lower bound average gain. Defaults to 0.00.
- **max_iter** (int, optional) - The maximum number of EM iterations. Defaults to 1000.
- **n_init** (int, optional) - The number of initializations to perform. Defaults to 1.
- **save_param_init** (bool, optional) - Save the estimated parameters of all initializations. Defaults to False.
- **init_params** (str, optional) - The method used to initialize parameters. Must be one of: 'kmeans', 'random'. Defaults to 'random'.
- **random_state** (int or RandomState instance or None, optional) - Controls the random seed for parameter initialization. Defaults to None.
- **verbose** (int, optional) - Enable verbose output. Defaults to 0.
- **progress_bar** (int, optional) - Display a tqdm progress bar during fitting. 0: No progress bar, 1: Progress bar for initializations, 2: Progress bars for initializations and iterations. Defaults to 1.
- **measurement_params** (dict or None, optional) - Additional parameters passed to the measurement model class. Defaults to None.
- **structural_params** (dict or None, optional) - Additional parameters passed to the structural model class. Defaults to None.

### Attributes
- **weights_** (ndarray) - The weights of each mixture components.
- **_mm** (stepmix.emission.Emission) - Measurement model, including parameters and estimation methods.
- **_sm** (stepmix.emission.Emission) - Structural model, including parameters and estimation methods.
- **log_resp_** (ndarray) - Initial log responsibilities.
- **measurement_in_** (int) - Number of features in the measurement model.
- **structural_in_** (int) - Number of features in the structural model.
- **converged_** (bool) - True when convergence was reached in fit(), False otherwise.
- **n_iter_** (int) - Number of steps used by the best fit of EM to reach convergence.
- **lower_bound_** (float) - Lower bound value on the log-likelihood of the best fit of EM.
- **lower_bound_buffer_** (float) - Lower bound values on the log-likelihood of all EM initializations.
- **param_buffer_** (list) - Final parameters of all initializations. Only updated if save_param_init=True.
- **x_names_** (list) - If input is a DataFrame, column names of X.
- **y_names_** (list) - If input is a DataFrame, column names of Y.
```

--------------------------------

### permute_classes

Source: https://stepmix.readthedocs.io/en/latest/_modules/stepmix/stepmix.html

Permutes the latent classes and their associated parameters within the StepMix estimator. This is useful for remapping latent classes, for example, to align with external labels or to ensure consistent ordering.

```APIDOC
## permute_classes

### Description
Permute the latent class and associated parameters of this estimator.

### Method
`permute_classes(self, perm)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
None (This method modifies the model in-place).

#### Response Example
None

### Parameters
* **perm** (ndarray of shape (n_classes,)) - Required - Integer array representing the target permutation. Should be a permutation of np.arange(n_classes).
```

--------------------------------

### GaussianTied Emission Model - Initialization

Source: https://stepmix.readthedocs.io/en/latest/_modules/stepmix/emission/gaussian.html

Initializes the GaussianTied emission model, setting the covariance type to 'tied'.

```python
class GaussianTied(Gaussian):
    def __init__(self, **kwargs):
        # Make sure no other covariance_type is specified
        kwargs.pop("covariance_type", None)
        super().__init__(covariance_type="tied", **kwargs)
        self.model_str = "gaussian_tied"
```

--------------------------------

### Nested Emission Model Descriptor Example

Source: https://stepmix.readthedocs.io/en/latest/_modules/stepmix/emission/nested.html

Defines the structure for a nested emission model, specifying the type and number of columns for each sub-model. Additional arguments can be passed to the nested models.

```python
descriptor = {
   'model_1': {
           'model': 'gaussian_unit',
           'n_columns':3
    },
   'model_2': {
           'model': 'multinoulli',
           'n_columns': 15,
           'n_outcomes': 5
    },
   'model_3': {
           'model': 'covariate',
           'n_columns': 4,
           'method': "newton-raphson",
           'lr': 1e-3,
    }
}
```

--------------------------------

### Parameter Initialization for Covariate Model

Source: https://stepmix.readthedocs.io/en/latest/_modules/stepmix/emission/covariate.html

Initializes the model parameters (beta coefficients) for the Covariate model based on the input data dimensions and responsibilities. Ensures parameters are close to zero for stable optimization.

```python
def initialize(self, X, resp, random_state=None):
        self.check_parameters()
        self.random_state = check_random_state(random_state)

        n, D = X.shape
        D += self.intercept
        _, K = resp.shape

        # Parameter initialization
        # if self.intercept: beta[0,:]=intercept and beta[1:,:] = coefficients
        # Note: initial coefficients must be close to 0 for NR to be relatively stable
        self.parameters["beta"] = self.random_state.normal(0, 1e-3, size=(K, D))
```

--------------------------------

### GaussianSpherical Emission Model - Initialization

Source: https://stepmix.readthedocs.io/en/latest/_modules/stepmix/emission/gaussian.html

Initializes the GaussianSpherical emission model, setting the covariance type to 'spherical'.

```python
class GaussianSpherical(Gaussian):
    def __init__(self, **kwargs):
        # Make sure no other covariance_type is specified
        kwargs.pop("covariance_type", None)
        super().__init__(covariance_type="spherical", **kwargs)
        self.model_str = "gaussian_spherical"
```
Tokens:
Raw