Merge pull request #52 from CausalityInMotion/dev

Refactor installation guide and documentation references for clarity

Author: bmusangu

gpfa/__init__.py blockinvgpfa/__init__.pygpfa/__init__.py renamed to blockinvgpfa/__init__.py

@@ -2,10 +2,10 @@
 :copyright: Copyright 2021 Brooks M. Musangu and Jan Drugowitsch.
 :license: Modified BSD, see LICENSE.txt for details.
 """
-from .gpfa import GPFA
+from .blockinvgpfa import BlockInvGPFA
 from .preprocessing import EventTimesToCounts
 
 __all__ = [
-    "GPFA",
+    "BlockInvGPFA",
     "EventTimesToCounts"
 ]

gpfa/gpfa.py blockinvgpfa/blockinvgpfa.pygpfa/gpfa.py renamed to blockinvgpfa/blockinvgpfa.py

@@ -25,17 +25,18 @@
 from tqdm import trange
 
 __all__ = [
-    "GPFA"
+    "BlockInvGPFA"
 ]
 
 
-class GPFA(sklearn.base.BaseEstimator):
-    """Gaussian Process Factor Analysis (GPFA) is a probabilistic
-    dimensionality reduction technique that extracts smooth latent
-    trajectories from noisy, high-dimensional time series data.
-    It combines Factor Analysis (FA) for dimensionality reduction with Gaussian
-    Processes (GPs) to model the time courses of the latent factors in a
-    unified, probabilistic framework.
+class BlockInvGPFA(sklearn.base.BaseEstimator):
+    """BlockInvGPFA is a high-performance implementation of Gaussian
+    Process Factor Analysis (GPFA) is a probabilistic dimensionality
+    reduction technique that extracts smooth latent trajectories from
+    noisy, high-dimensional time series data. GPFA combines Factor
+    Analysis (FA) for dimensionality reduction with Gaussian Processes
+    (GPs) to model the time courses of the latent factors in a unified,
+    probabilistic framework.
 
     GPFA operates on a set of time-series data, where each time series is
     given by an ``x_dim`` x ``bins`` matrix. ``x_dim`` needs to be the same
@@ -47,6 +48,16 @@ class GPFA(sklearn.base.BaseEstimator):
     Please consult the :ref:`main page <gpfa_prob_model>` for more details on
     the underlying probabilistic model.
 
+    This implementation, BlockInvGPFA, builds on the core model described
+    in [Yu et al., 2009] and is adapted from the Elephant's toolkit, with
+    substantial algorithmic enhancements:
+
+    1. It uses block-matrix identities and Schur complement updates to
+       efficiently share kernel inversion computations across 
+       variable-length trials.
+    2. It introduces a new variance-explained metric to evaluate BlockInvGPFA 
+       model fits
+
     Parameters
     ----------
     bin_size : float, optional, default=0.02
@@ -194,45 +205,45 @@ class GPFA(sklearn.base.BaseEstimator):
     Examples
     --------
     >>> import numpy as np
-    >>> from gpfa import GPFA
+    >>> from blockinvgpfa import BlockInvGPFA
 
     >>> X = np.array([[
     ...     [3, 1, 0, 4, 1, 2, 1, 3, 4, 2, 2, 1, 2, 0, 0, 2, 2, 5, 1, 3],
     ...     [1, 0, 2, 0, 2, 1, 4, 2, 0, 1, 4, 4, 1, 2, 8, 3, 2, 1, 3, 1],
     ...     [2, 2, 1, 1, 3, 2, 3, 2, 2, 0, 3, 4, 1, 2, 3, 1, 4, 1, 0, 1]
     ... ]])
     >>> 
-    >>> gpfa_model = GPFA(z_dim=1)
+    >>> blockinv_gpfa = BlockInvGPFA(z_dim=1)
 
     >>> # Fit the model
-    >>> gpfa_model.fit(X)
+    >>> blockinv_gpfa.fit(X)
     Initializing parameters using factor analysis...
-    Fitting GPFA model...
+    Fitting GP parameters by EM...
 
     >>> # Infere latent variable time-courses for the same data
-    >>> Zs, _ = gpfa_model.predict()
+    >>> Zs, _ = blockinv_gpfa.predict()
     >>> print(Zs)
     [array([[-1.18405633, -2.00878   , -0.01470251, -2.3143544 ,  0.03651376,
              -1.06948736,  2.05355342, -0.16920794, -2.26437342, -1.21934552,
               1.98656088,  2.13305066, -1.14113106,  0.11319858,  6.14998095,
               0.89241818,  0.03509708, -1.3936327 ,  0.84781358, -1.2281484 ]])]
 
     >>> # Display the loading matrix (C_) and observation mean (d_) parameters
-    >>> print(gpfa_model.C_)
+    >>> print(blockinv_gpfa.C_)
     [[-0.78376501]
     [ 1.77773876]
     [ 0.51134474]]
 
-    >>> print(gpfa_model.d_)
+    >>> print(blockinv_gpfa.d_)
     [1.95470037 2.08933859 1.89693338]
 
     >>> # Obtaining log-likelihood scores
-    >>> llhs = gpfa_model.score()
+    >>> llhs = blockinv_gpfa.score()
     >>> print(llhs)
     [-117.54588379661148, -107.17193271370158, ..., -100.13200154180569]
 
     >>> # Evaluate the total explained variance regression score
-    >>> print(gpfa_model.variance_explained())
+    >>> print(blockinv_gpfa.variance_explained())
     (0.6581475357501596, array([0.65814754]))
 
 
@@ -761,7 +772,7 @@ def _em(self, X):
 
         if np.any(np.diag(self.R_) == var_floor):
             warnings.warn('Private variance floor used for one or more '
-                          'observed dimensions in GPFA.')
+                          'observed dimensions in BlockInvGPFA.')
 
         self.fit_info_ = {'iteration_time': iter_time, 'log_likelihoods': lls}
 
@@ -1188,7 +1199,7 @@ def _fill_p_auto_sum(self, Seqs, precomp):
             on the caller (which should be :func:`_learn_gp_params()`) to make
             sure this is called correctly.
 
-        Finally, see the notes in the GPFA README.
+        Finally, see the notes in the BlockInvGPFA README.
         """
         ############################################################
         # Fill out PautoSum

gpfa/preprocessing.py blockinvgpfa/preprocessing.pygpfa/preprocessing.py renamed to blockinvgpfa/preprocessing.py

@@ -0,0 +1,7 @@
+==================
+BlockInvGPFA Class
+==================
+
+.. currentmodule:: blockinvgpfa
+.. autoclass:: BlockInvGPFA
+   :members:

docs/_static/log-likelihoods.png

@@ -7,7 +7,7 @@
 import os
 from datetime import date
 
-# include root path to allow autodoc to find gpfa module
+# include root path to allow autodoc to find blockgpfa module
 sys.path.insert(0, os.path.abspath('../'))
 
 # Path to the source directory (where your .rst files are)
@@ -22,7 +22,7 @@
 
 # -- General configuration -----------------------------------------------
 
-project = 'GPFA Documentation'
+project = 'BlockInvGPFA Documentation'
 authors = 'Brooks M. Musangu and Jan Drugowitsch'
 copyright = "2021-{this_year}, {authors}".format(
     this_year=date.today().year, authors=authors)

docs/_static/reach_trajectories_48.gif

@@ -4,7 +4,7 @@
 Contribution
 ==============
 
-We welcome contributions to the GPFA package, whether they involve enhancements, bug fixes,
+We welcome contributions to the BlockInvGPFA package, whether they involve enhancements, bug fixes,
 or documentation improvements. To ensure the codebase's quality and maintainability, please
 follow this guide carefully.
 
@@ -33,9 +33,9 @@ include tests for any module, class, or function you contribute.
 
 **Version Control Workflow**
 
-When contributing to the GPFA package, please follow these steps:
+When contributing to the BlockInvGPFA package, please follow these steps:
 
-1. Fork the GPFA repository on GitHub.
+1. Fork the BlockInvGPFA repository on GitHub.
 
 2. Clone your forked repository to your local machine.
 
@@ -50,12 +50,12 @@ When contributing to the GPFA package, please follow these steps:
 
 7. Push your branch to your GitHub fork.
 
-8. Create a pull request (PR) from your branch to the GPFA main repository. Provide a
+8. Create a pull request (PR) from your branch to the BlockInvGPFA main repository. Provide a
    detailed description of your changes in the PR.
 
 9. We will review your PR, and if necessary, provide feedback or request changes.
 
-10. Once your PR is approved, it will be merged into the main GPFA repository.
+10. Once your PR is approved, it will be merged into the main BlockInvGPFA repository.
 
-Thank you for your contribution to the GPFA package. Your efforts help improve
+Thank you for your contribution to the BlockInvGPFA package. Your efforts help improve
 and maintain this valuable resource for the community.