cleaned up density structure, use parent mixture class to organize model variations

Author: Alexander Ororbia

docs/source/ngclearn.utils.density.rst

@@ -20,6 +20,14 @@ ngclearn.utils.density.gmm module
    :undoc-members:
    :show-inheritance:
 
+ngclearn.utils.density.mixture module
+-------------------------------------
+
+.. automodule:: ngclearn.utils.density.mixture
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 Module contents
 ---------------
 

ngclearn/utils/density/__init__.py

@@ -1,4 +1,5 @@
+from .mixture import Mixture ## general mixture template parent class
 ## point to supported density estimator models
-from .gmm import GMM ## Gaussian mixture 
-from .bmm import BMM ## Bernoulli mixture
+from .gmm import GMM ## Gaussian mixture model 
+from .bmm import BMM ## Bernoulli mixture model
 

ngclearn/utils/density/bmm.py

@@ -3,6 +3,8 @@
 import time, sys
 import numpy as np
 
+from ngclearn.utils.density.mixture import Mixture
+
 ########################################################################################################################
 ## internal routines for mixture model
 ########################################################################################################################
@@ -58,7 +60,7 @@ def _sample_component(dkey, n_samples, mu): ## samples a component (of mixture)
 
 ########################################################################################################################
 
-class BMM: ## Bernoulli mixture model (mixture-of-Bernoullis)
+class BMM(Mixture): ## Bernoulli mixture model (mixture-of-Bernoullis)
     """
     Implements a Bernoulli mixture model (BMM) -- or mixture of Bernoullis (MoB).
     Adaptation of parameters is conducted via the Expectation-Maximization (EM)
@@ -74,7 +76,8 @@ class BMM: ## Bernoulli mixture model (mixture-of-Bernoullis)
         init_kmeans: <Unsupported>
     """
 
-    def __init__(self, K, max_iter=50, init_kmeans=False, key=None):
+    def __init__(self, K, max_iter=50, init_kmeans=False, key=None, **kwargs):
+        super().__init__(K, max_iter, **kwargs)
         self.K = K
         self.max_iter = int(max_iter)
         self.init_kmeans = init_kmeans ## Unsupported currently
@@ -204,3 +207,4 @@ def sample(self, n_samples, mode_j=-1):
                 Xs.append(x_s)
             Xs = jnp.concat(Xs, axis=0)
         return Xs
+

ngclearn/utils/density/gmm.py

@@ -3,6 +3,8 @@
 import time, sys
 import numpy as np
 
+from ngclearn.utils.density.mixture import Mixture
+
 ########################################################################################################################
 ## internal routines for mixture model
 ########################################################################################################################
@@ -99,7 +101,7 @@ def _sample_component(dkey, n_samples, mu, Sigma, assume_diag_cov=False): ## sam
 
 ########################################################################################################################
 
-class GMM: ## Gaussian mixture model (mixture-of-Gaussians)
+class GMM(Mixture): ## Gaussian mixture model (mixture-of-Gaussians)
     """
     Implements a Gaussian mixture model (GMM) -- or mixture of Gaussians (MoG).
     Adaptation of parameters is conducted via the Expectation-Maximization (EM)
@@ -119,7 +121,8 @@ class GMM: ## Gaussian mixture model (mixture-of-Gaussians)
     # init_kmeans: if True, first learn use the K-Means algorithm to initialize
     #              the component Gaussians of this GMM (Default = False)
 
-    def __init__(self, K, max_iter=50, assume_diag_cov=False, init_kmeans=False, key=None):
+    def __init__(self, K, max_iter=50, assume_diag_cov=False, init_kmeans=False, key=None, **kwargs):
+        super().__init__(K, max_iter, **kwargs) 
         self.K = K
         self.max_iter = int(max_iter)
         self.assume_diag_cov = assume_diag_cov
@@ -265,3 +268,4 @@ def sample(self, n_samples, mode_j=-1):
                 Xs.append(x_s)
             Xs = jnp.concat(Xs, axis=0)
         return Xs
+

ngclearn/utils/density/mixture.py

@@ -0,0 +1,33 @@
+
+
+class Mixture: ## General mixture structure
+    """
+    Implements a general mixture model template/structure. Effectively, this is the parent 
+    class/template for mixtures of distributions. 
+
+    Args:
+        K: the number of components/latent variables within this mixture model
+
+        max_iter: the maximum number of iterations to fit parameters to data (Default = 50)
+
+    """
+
+    def __init__(self, K, max_iter=50, **kwargs): 
+        self.K = K
+        self.max_iter = max_iter
+
+    def init(self, X): ## model data-dependent initialization function
+        pass 
+
+    def calc_log_likelihood(self, X): ## log-likelihood calculation routine
+        pass
+
+    def fit(self, X, tol=1e-3, verbose=False): ## outer fitting process
+        pass 
+
+    def update(self, X): ## inner/iterative adjustment/update step
+        pass 
+
+    def sample(self, n_samples, mode_j=-1): ## model sampling routine
+        pass
+