machine_learning.gaussian_mixture_model
=======================================

.. py:module:: machine_learning.gaussian_mixture_model

.. autoapi-nested-parse::

   README, Author - Md Ruman Islam (mailto:ruman23.github.io)
   Requirements:
     - numpy
     - matplotlib
   Python:
     - 3.8+
   Inputs:
     - data : a 2D numpy array of features.
     - n_components : number of Gaussian distributions (clusters) to fit.
     - max_iter : maximum number of EM iterations.
     - tol : convergence tolerance.
   Usage:
     1. define 'n_components' value and 'data' features array
     2. initialize model:
           gmm = GaussianMixture(n_components=3, max_iter=100)
     3. fit model to data:
           gmm.fit(data)
     4. get cluster predictions:
           labels = gmm.predict(data)
     5. visualize results:
           gmm.plot_results(data)



Attributes
----------

.. autoapisummary::

   machine_learning.gaussian_mixture_model.TAG
   machine_learning.gaussian_mixture_model.gmm


Classes
-------

.. autoapisummary::

   machine_learning.gaussian_mixture_model.GaussianMixture


Module Contents
---------------

.. py:class:: GaussianMixture(n_components: int = 2, max_iter: int = 100, tol: float = 0.0001, seed: int | None = None)

   Gaussian Mixture Model implemented using the Expectation-Maximization algorithm.


   .. py:method:: _compute_log_likelihood(data: numpy.typing.NDArray[numpy.float64]) -> float

      Compute total log-likelihood of the model.

      Note: assumes the model parameters are already initialized.

      Examples
      --------
      >>> sample = np.array(
      ...     [[0.0, 0.5], [1.0, 1.5], [2.0, 2.5], [3.0, 3.5]]
      ... )
      >>> model = GaussianMixture(n_components=2, seed=0)
      >>> model._initialize_parameters(sample)
      >>> bool(np.isfinite(model._compute_log_likelihood(sample)))
      True



   .. py:method:: _e_step(data: numpy.typing.NDArray[numpy.float64]) -> numpy.typing.NDArray[numpy.float64]

      Compute responsibilities (posterior probabilities).

      Examples
      --------
      >>> sample = np.array(
      ...     [[0.0, 0.5], [1.0, 1.5], [2.0, 2.5], [3.0, 3.5]]
      ... )
      >>> model = GaussianMixture(n_components=2, seed=0)
      >>> model._initialize_parameters(sample)
      >>> resp = model._e_step(sample)
      >>> resp.shape
      (4, 2)
      >>> bool(np.allclose(resp.sum(axis=1), 1.0))
      True



   .. py:method:: _initialize_parameters(data: numpy.typing.NDArray[numpy.float64]) -> None

      Randomly initialize means, covariances, and mixture weights.

      Examples
      --------
      >>> sample = np.array(
      ...     [[0.0, 0.5], [1.0, 1.5], [2.0, 2.5], [3.0, 3.5]]
      ... )
      >>> model = GaussianMixture(n_components=2, seed=0)
      >>> model._initialize_parameters(sample)
      >>> model.means_.shape
      (2, 2)
      >>> bool(np.isclose(model.weights_.sum(), 1.0))
      True



   .. py:method:: _m_step(data: numpy.typing.NDArray[numpy.float64], responsibilities: numpy.typing.NDArray[numpy.float64]) -> None

      Update weights, means, and covariances.

      Note: assumes the model parameters are already initialized.

      Examples
      --------
      >>> sample = np.array(
      ...     [[0.0, 0.5], [1.0, 1.5], [2.0, 2.5], [3.0, 3.5]]
      ... )
      >>> model = GaussianMixture(n_components=2, seed=0)
      >>> model._initialize_parameters(sample)
      >>> resp = model._e_step(sample)
      >>> model._m_step(sample, resp)
      >>> bool(np.isclose(model.weights_.sum(), 1.0))
      True



   .. py:method:: fit(data: numpy.typing.NDArray[numpy.float64]) -> None

      Fit the Gaussian Mixture Model to data using the EM algorithm.

      Examples
      --------
      >>> sample = np.array(
      ...     [[0.0, 0.5], [1.0, 1.5], [2.0, 2.5], [3.0, 3.5]]
      ... )
      >>> model = GaussianMixture(n_components=2, max_iter=5, tol=1e-3, seed=0)
      >>> model.fit(sample)  # doctest: +ELLIPSIS
      GAUSSIAN-MIXTURE/ ...
      >>> len(model.log_likelihoods_) > 0
      True



   .. py:method:: plot_results(data: numpy.typing.NDArray[numpy.float64]) -> None

      Visualize GMM clustering results (2D only).

      Note: This method assumes self.means_ is initialized.

      Examples
      --------
      >>> sample = np.ones((3, 3))
      >>> model = GaussianMixture()
      >>> model.plot_results(sample)
      GAUSSIAN-MIXTURE/ Plotting only supported for 2D data.



   .. py:method:: predict(data: numpy.typing.NDArray[numpy.float64]) -> numpy.typing.NDArray[numpy.int_]

      Predict cluster assignment for each data point.

      Note: assumes the model parameters are already initialized.

      Examples
      --------
      >>> sample = np.array(
      ...     [[0.0, 0.5], [1.0, 1.5], [2.0, 2.5], [3.0, 3.5]]
      ... )
      >>> model = GaussianMixture(n_components=2, max_iter=5, tol=1e-3, seed=0)
      >>> model.fit(sample)  # doctest: +ELLIPSIS
      GAUSSIAN-MIXTURE/ ...
      >>> labels = model.predict(sample)
      >>> labels.shape
      (4,)



   .. py:attribute:: covariances_
      :type:  numpy.typing.NDArray[numpy.float64] | None
      :value: None



   .. py:attribute:: log_likelihoods_
      :type:  list[float]
      :value: []



   .. py:attribute:: max_iter
      :type:  int
      :value: 100



   .. py:attribute:: means_
      :type:  numpy.typing.NDArray[numpy.float64] | None
      :value: None



   .. py:attribute:: n_components
      :type:  int
      :value: 2



   .. py:attribute:: seed
      :type:  int | None
      :value: None



   .. py:attribute:: tol
      :type:  float
      :value: 0.0001



   .. py:attribute:: weights_
      :type:  numpy.typing.NDArray[numpy.float64] | None
      :value: None



.. py:data:: TAG
   :value: 'GAUSSIAN-MIXTURE/ '


.. py:data:: gmm