Removed redundant example but added existing splitting example to examples.rst (#3)

* updated some docstrings

* example documentation updates

---------

Co-authored-by: Keith LeGrand <keithalegrand@gmail.com>

Author: amyloid8

docs/examples.rst

@@ -1,7 +1,15 @@
 Examples
 ========
 
-This section provides examples of using pyest for various applications.
+This section provides examples of using PyEst for various applications.
+
+Splitting and Plotting PyEst Gaussian Mixtures
+---------------------------------------------------------------------
+
+This example demonstrates using PyEst to split a mixand in a Gaussian mixture, and how to plot the resulting Gaussian mixture:
+
+.. literalinclude:: ../examples/example_gm_2d_split.py
+   :language: python
 
 Gaussian Mixture Splitting for Field-of-View and Negative Information
 ---------------------------------------------------------------------
@@ -23,7 +31,13 @@ Cislunar Space Object Uncertainty Propagation
 ---------------------------------------------
 
 This example shows how to use pyest for propagating uncertainty in the circular restricted three-body problem
-(CR3BP):
+(CR3BP).
+
+.. note::
+    This example utilizes a cache of precomputed Monte Carlo samples to evaluate various performance measures.
+    If the cache is not available, this example will generate new samples and store them in a cache for future use.
+    On first run, this may take a few minutes to build the cache. These samples are only for performance evaluation
+    and not required for any of the adaptive Gaussian splitting operations.
 
 .. literalinclude:: ../examples/example_splitting_cislunar.py
    :language: python

pyest/gm/gm.py

@@ -188,6 +188,7 @@ def equal_weights(L):
     ----------
     L : int
         number of weights
+
     Returns
     -------
     ndarray
@@ -200,8 +201,8 @@ def eval_gmpdf(x, w, m, P):
     """
     evaluates Gaussian mixture at points x
 
-    Required
-    --------
+    Parameters
+    ----------
     x : array_like
         (n_samp, vect_length) points at which to evaluate the GM
     w : array_like
@@ -229,8 +230,8 @@ def eval_gmpdfchol(x, w, m, S):
     """
     evaluates Gaussian mixture at points x
 
-    Required
-    --------
+    Parameters
+    ----------
     x : array_like
         (n_samp, vect_length) points at which to evaluate the GM
     w : array_like
@@ -258,8 +259,8 @@ def optimized_eval_gmpdf(x, w, m, Schol, log_pdet):
     """
     Evaluates Gaussian mixture at points x
 
-    Required
-    --------
+    Parameters
+    ----------
     x : array_like
         (n_samp, vect_length) points at which to evaluate the GM
     w : array_like
@@ -416,8 +417,8 @@ def eig_sqrt_factor(P):
 def integral_gauss_product_chol(m1, S1, m2, S2):
     ''' compute integral of product of two Gaussians
 
-    Required
-    --------
+    Parameters
+    ----------
     m1: np.ndarray
         mean of Gaussian 1
     S1: np.ndarray
@@ -442,8 +443,8 @@ def integral_gauss_product_chol(m1, S1, m2, S2):
 def integral_gauss_product(m1, P1, m2, P2, allow_singular=False):
     ''' compute integral of product of two Gaussians
 
-    Required
-    --------
+    Parameters
+    ----------
     m1: np.ndarray
         mean of Gaussian 1
     P1: np.ndarray
@@ -498,8 +499,8 @@ def print_3d_mat(A):
 def gm_pdf_2d(w, m, P, dimensions=(0, 1), res=100, xbnd=None, ybnd=None):
     """ evaluate GM pdf in two dimensions
 
-    Required
-    --------
+    Parameters
+    ----------
     w: ndarray
         (nC,) weights
     m: ndarray
@@ -595,9 +596,22 @@ class GaussianMixture(object):
 
     def __init__(self, w, m, cov, cov_type='full', Seig=None):
         """
-        w is a 1d array
-        m is a 2d array (nC,nx)
-        cov is a 3d array (nC,nx,nx)
+        Parameters
+        ----------
+        w: array_like
+          (nC,) array of mixand weights
+        m: array_like
+          (nC,nx) array of mixand means
+        cov: array_like
+          (nC,nx,nx) array of covariances. Covariances can be specified in
+          different ways, as specified by the optional cov_type argument
+
+        Optional
+        --------
+        cov_type: str
+            type of covariance matrix. Defaults to 'full'.
+        Seig: 3d array
+            eigenvalues and eigenvectors of the covariance matrix. Defaults to None.
         """
         self.set_w(w)
         self.set_m(m)
@@ -658,24 +672,42 @@ def _compute_eig_sqrt_factors(self):
         return np.array([eig_sqrt_factor(cov.covariance) for cov in self._cov])
 
     def get_size(self):
+        """
+        Returns the number of components in the Gaussian mixture model.
+        """
         return len(self.w)
 
     # def _set_size(self):
     #    self._size = len(self._w)
 
     def get_w(self):
+        """
+        Returns the weights (1d array) of the Gaussian mixture model.
+        """
         return self._w
 
     def set_w(self, w):
+        """
+        Sets the weights (1d array) of the Gaussian mixture model.
+        """
         self._w = np.atleast_1d(w)
 
     def get_m(self):
+        """
+        Returns the means (2d array (nC,nx)) of the Gaussian mixture model.
+        """
         return self._m
 
     def set_m(self, m):
+        """
+        Sets the means (2d array (nC,nx)) of the Gaussian mixture model.
+        """
         self._m = np.atleast_2d(m)
 
     def get_P(self, ind=None):
+        """
+        Returns the covariance matrices (3d array (nC,nx,nx)) of the Gaussian mixture model.
+        """
         if ind is not None:
             if np.isscalar(ind):
                 return self._cov[ind].covariance
@@ -684,6 +716,9 @@ def get_P(self, ind=None):
         return np.array([P.covariance for P in self._cov])
 
     def set_P(self, P):
+        """
+        Sets the covariance matrices (3d array (nC,nx,nx)) of the Gaussian mixture model.
+        """
         self._set_cov(P, 'full')
 
     def _set_cov(self, cov, cov_type):
@@ -713,6 +748,9 @@ def _set_cov(self, cov, cov_type):
             raise ValueError('cov_type must be one of "full", "cholesky", or "eigendecomposition"')
 
     def set_Seig(self, S):
+        """
+        Sets the covariance matrix eigenvalues and eigenvectors.
+        """
         S = np.atleast_2d(S)
         if S.ndim == 2:
             self._Seig = S[np.newaxis, :, :]
@@ -804,11 +842,23 @@ def eval(self, x):
         return _squeeze_output(optimized_eval_gmpdf(x, self.w, self.m, self.Schol, self.log_pdet))
 
     def mean(self):
-        """ return the mean of the Gaussian mixture """
+        """ return the mean of the distribution
+
+        Returns
+        -------
+        ndarray
+          (nx,) distribution mean
+        """
         return np.sum(self.w[:, np.newaxis] * self.m, axis=0)
 
     def cov(self):
-        """ return the conditional covariance """
+        """ return covariance of the distribution
+
+        Returns
+        -------
+        ndarray
+          (nx,nx) full covariance matrix of distribution
+        """
         wsum = np.sum(self.w)
         mean = self.mean()
         return np.sum([
@@ -860,7 +910,19 @@ def pdf_2d(self,  dimensions=(0, 1), res=100, xbnd=None, ybnd=None):
         return gm_pdf_2d(self.w, self.m, self.P, dimensions, res, xbnd, ybnd)
 
     def pop(self, idx):
-        """ remove and return component by index """
+        """
+        remove and return component by index
+
+        Required
+        --------
+        idx: int
+            index of component to remove
+
+        Returns
+        -------
+        tuple
+            (weight, mean, covariance) of removed component
+        """
         w, m, P = self[idx]
         self._w = np.delete(self._w, idx, 0)
         self._m = np.delete(self._m, idx, 0)