Merge branch 'main' into dev

Author: OmidS

.github/workflows/publish-to-pypi.yml

@@ -0,0 +1,118 @@
+name: Publish Python 🐍 distribution 📦 to PyPI and TestPyPI
+
+on: push
+
+jobs:
+  build:
+    name: Build distribution 📦
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: "3.x"
+    - name: Install pypa/build
+      run: >-
+        python3 -m
+        pip install
+        build
+        --user
+    - name: Build a binary wheel and a source tarball
+      run: python3 -m build
+    - name: Store the distribution packages
+      uses: actions/upload-artifact@v4
+      with:
+        name: python-package-distributions
+        path: dist/
+
+  publish-to-pypi:
+    name: >-
+      Publish Python 🐍 distribution 📦 to PyPI
+    if: startsWith(github.ref, 'refs/tags/')  # only publish to PyPI on tag pushes
+    needs:
+    - build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/PSID  # Replace <package-name> with your PyPI project name
+    permissions:
+      id-token: write  # IMPORTANT: mandatory for trusted publishing
+
+    steps:
+    - name: Download all the dists
+      uses: actions/download-artifact@v4
+      with:
+        name: python-package-distributions
+        path: dist/
+    - name: Publish distribution 📦 to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: >-
+      Sign the Python 🐍 distribution 📦 with Sigstore
+      and upload them to GitHub Release
+    needs:
+    - publish-to-pypi
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write  # IMPORTANT: mandatory for making GitHub Releases
+      id-token: write  # IMPORTANT: mandatory for sigstore
+
+    steps:
+    - name: Download all the dists
+      uses: actions/download-artifact@v4
+      with:
+        name: python-package-distributions
+        path: dist/
+    - name: Sign the dists with Sigstore
+      uses: sigstore/gh-action-sigstore-python@v3.0.0
+      with:
+        inputs: >-
+          ./dist/*.tar.gz
+          ./dist/*.whl
+    - name: Create GitHub Release
+      env:
+        GITHUB_TOKEN: ${{ github.token }}
+      run: >-
+        gh release create
+        '${{ github.ref_name }}'
+        --repo '${{ github.repository }}'
+        --notes ""
+    - name: Upload artifact signatures to GitHub Release
+      env:
+        GITHUB_TOKEN: ${{ github.token }}
+      # Upload to GitHub Release using the `gh` CLI.
+      # `dist/` contains the built packages, and the
+      # sigstore-produced signatures and certificates.
+      run: >-
+        gh release upload
+        '${{ github.ref_name }}' dist/**
+        --repo '${{ github.repository }}'
+
+  publish-to-testpypi:
+    name: Publish Python 🐍 distribution 📦 to TestPyPI
+    needs:
+    - build
+    runs-on: ubuntu-latest
+    if: false
+
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/PSID
+
+    permissions:
+      id-token: write  # IMPORTANT: mandatory for trusted publishing
+
+    steps:
+    - name: Download all the dists
+      uses: actions/download-artifact@v4
+      with:
+        name: python-package-distributions
+        path: dist/
+    - name: Publish distribution 📦 to TestPyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        repository-url: https://test.pypi.org/legacy/

ChangeLog.md

@@ -1,8 +1,14 @@
 # Changes 
 Versioning follows [semver](https://semver.org/).
 
-- v1.2.0:
+- v1.3.0:
   - Add support for using different horizons for neural/behavior data. 
+- v1.2.6:
+  - Fixes minor error in variable init for trial-based ISID.
+- v1.2.5:
+  - Fixes minor `numpy.eye` error that was thrown for unstable learned models.
+- v1.2.0:
+  - Adds version with support for external input (i.e., IPSID).
 - v1.1.0:
   - Automatically does the necessary mean-removal preprocessing for input neural/behavior data. Automatically adds back the learned means to predicted signals. 
 - v1.0.6:

README.md

@@ -1,5 +1,7 @@
-- [PSID: Preferential subspace identification <br/> [Python implementation]](#psid-preferential-subspace-identification--python-implementation)
-- [Publication](#publication)
+- [(I)PSID: (Input) Preferential subspace identification  \[Python implementation\]](#ipsid-input-preferential-subspace-identification--python-implementation)
+- [Publications](#publications)
+  - [PSID](#psid)
+  - [IPSID](#ipsid)
 - [Usage guide](#usage-guide)
   - [Installation](#installation)
   - [Initialization](#initialization)
@@ -10,16 +12,21 @@
     - [How to pick the state dimensions nx and n1?](#how-to-pick-the-state-dimensions-nx-and-n1)
     - [How to pick the horizon `i`?](#how-to-pick-the-horizon-i)
 - [Usage examples](#usage-examples)
+  - [PSID](#psid-1)
+  - [IPSID](#ipsid-1)
 - [Change Log](#change-log)
 - [Licence](#licence)
 
-# PSID: Preferential subspace identification <br/> [Python implementation]
+# (I)PSID: (Input) Preferential subspace identification <br/> [Python implementation]
 
 For MATLAB implementation see http://github.com/ShanechiLab/PSID
 
 Given signals y_t (e.g. neural signals) and z_t (e.g behavior), PSID learns a dynamic model for y_t while prioritizing the dynamics that are relevant to z_t. 
 
-# Publication
+IPSID is an extension of PSID that also supports taking a third signal u_t (e.g., task instructions) that is simultaneously measured with y_t. In the learned dynamical model, u_t plays the role of input to the latent states. 
+
+# Publications
+## PSID
 For the derivation of PSID and results in real neural data see the paper below.
 
 Omid G. Sani, Hamidreza Abbaspourazad, Yan T. Wong, Bijan Pesaran, Maryam M. Shanechi. *Modeling behaviorally relevant neural dynamics enabled by preferential subspace identification*. Nature Neuroscience, 24, 140–149 (2021). https://doi.org/10.1038/s41593-020-00733-0
@@ -31,6 +38,11 @@ Original preprint: https://doi.org/10.1101/808154
 You can also find a summary of the paper in the following Twitter thread:
 https://twitter.com/MaryamShanechi/status/1325835609345122304
 
+## IPSID 
+For the derivation of IPSID and results in real neural data see the paper below.
+
+Parsa Vahidi*, Omid G. Sani*, Maryam M. Shanechi. *Modeling and dissociation of intrinsic and input-driven neural population dynamics underlying behavior*. PNAS (2024). https://doi.org/10.1073/pnas.2212887121
+
 
 # Usage guide
 ## Installation
@@ -47,12 +59,19 @@ import PSID
 ```
 
 ## Main learning function
-The main function for the Python implementation is [source/PSID/PSID.py](https://github.com/ShanechiLab/PyPSID/blob/main/source/PSID/PSID.py) -> function PSID. A complete usage guide is available in the function. The following shows an example case:
+The main functions for the Python implementation are the follwing:
+- For PSID: [source/PSID/PSID.py](https://github.com/ShanechiLab/PyPSID/blob/main/source/PSID/PSID.py) -> the function called PSID
+- For IPSID [source/PSID/IPSID.py](https://github.com/ShanechiLab/PyPSID/blob/main/source/PSID/IPSID.py) -> the function called IPSID
+
+A complete usage guide is available in as comments in each function. The following shows example use cases:
 ```
-idSys = PSID.PSID(y, z, nx, n1, i);
+idSys = PSID.PSID(y, z, nx, n1, i)
+# Or, if modeling effect of input u is also of interest
+idSys = PSID.IPSID(y, z, u, nx, n1, i)
 ```
 Inputs:
 - y and z are time x dimension matrices with neural (e.g. LFP signal powers or spike counts) and behavioral data (e.g. joint angles, hand position, etc), respectively. 
+- IPSID also takes u as an input, which is a time x dimension matrix, containing the measured input data. 
 - nx is the total number of latent states to be identified.
 - n1 is the number of states that are going to be dedicated to behaviorally relevant dynamics.
 - i is the subspace horizon used for modeling. 
@@ -61,30 +80,34 @@ Output:
 - idSys: an LSSM object containing all model parameters (A, Cy, Cz, etc). For a full list see the code.
 
 ## Extracting latent states using learned model
-Once a model is learned using PSID, you can apply the model to new data (i.e. run the associated Kalman filter) as follows:
+Once a model is learned using (I)PSID, you can apply the model to new data (i.e. run the associated Kalman filter) as follows:
 ```
 zPred, yPred, xPred = idSys.predict(y)
+# Or, for IPSID:
+zPred, yPred, xPred = idSys.predict(y, u)
 ```
 Input:
 - y: neural activity time series (time x dimension)
+- [For IPSID] u: input time series (time x dimension)
 
 Outputs:
 - zPred: one-step ahead prediction of behavior (if any)
 - yPred: one-step ahead prediction of neural activity
 - xPred: Extracted latent state
 
 ## Required preprocessing
-A required preprocessing when using PSID is to remove the mean of neural/behavior signals and if needed, add them back to predictions after learning the model. Starting from version 1.1.0, Python and MATLAB PSID libraries automatically do this by default so that users won't need to worry about it. Please update to the latest version if you are using an older version.
+- Repeated data dimensions (e.g., two identical neurons) can cause issues for the learning. Remove repeated data dimensions as a preprocessing and repeat predictions as needed to reproduce prediction of repeated data dimensions. 
+- A required preprocessing when using (I)PSID is to remove the mean of neural/behavior/input signals and if needed, add them back to neural/behavior predictions after learning the model. Starting from version 1.1.0, Python (I)PSID and MATLAB PSID libraries automatically do this by default so that users won't need to worry about it. Please update to the latest version if you are using an older version.
 
 ## Choosing the hyperparameters
 ### How to pick the state dimensions nx and n1?
-nx determines the total dimension of the latent state and n1 determines how many of those dimensions will be prioritizing the inclusion of behaviorally relevant neural dynamics (i.e. will be extracted using stage 1 of PSID). So the values that you would select for these hyperparameters depend on the goal of modeling and on the data. Some examples use cases are:
+nx determines the total dimension of the latent state and n1 determines how many of those dimensions will be prioritizing the inclusion of behaviorally relevant neural dynamics (i.e. will be extracted using stage 1 of (I)PSID). So the values that you would select for these hyperparameters depend on the goal of modeling and on the data. Some examples use cases are:
 
 If you want to perform dimension reduction, nx will be your desired target dimension. For example, to reduce dimension to 2 to plot low-dimensional visualizations of neural activity, you would use nx=2. Now if you want to reduce dimension while preserving as much behaviorally relevant neural dynamics as possible, you would use n1=nx.
 If you want to find the best fit to data overall, you can perform a grid search over values of nx and n1 and pick the value that achieves the best performance metric in the training data. For example, you could pick the nx and n1 pair that achieves the best cross-validated behavior decoding in an inner-cross-validation within the training data.
 
 ### How to pick the horizon `i`?
-The horizon `i` does not affect the model structure and only affects the intermediate linear algebra operations that PSID performs during the learning of the model. Nevertheless, different values of `i` may have different model learning performance. `i` needs to be at least 2, but also also determines the maximum n1 and nx that can be used per:
+The horizon `i` does not affect the model structure and only affects the intermediate linear algebra operations that (I)PSID performs during the learning of the model. Nevertheless, different values of `i` may have different model learning performance. `i` needs to be at least 2, but also also determines the maximum n1 and nx that can be used per:
 
 ```
 n1 <= nz * i
@@ -96,18 +119,27 @@ So if you have a low dimensional y_k or z_k (small ny or nz), you typically woul
 For more information, see the notebook(s) referenced in the next section. 
 
 # Usage examples
+## PSID
 Example code for running PSID is provided in 
 [source/example/PSID_example.py](https://github.com/ShanechiLab/PyPSID/blob/main/source/PSID/example/PSID_example.py)
-This script performs PSID model identification and visualizes the learned eigenvalues similar to in Supplementary Fig 1.
+This script performs PSID model identification and visualizes the learned eigenvalues similar to in Supplementary Fig 1 in (Sani et al, 2021).
 
 The following notebook also contains some examples along with more descriptions:
 [source/example/PSID_tutorial.ipynb](https://github.com/ShanechiLab/PyPSID/blob/main/source/PSID/example/PSID_tutorial.ipynb)
 
+## IPSID
+Example code for running IPSID is provided in 
+[source/example/IPSID_example.py](https://github.com/ShanechiLab/PyPSID/blob/main/source/PSID/example/IPSID_example.py)
+This script performs IPSID model identification and visualizes the learned eigenvalues similar to in Fig. 2A in (Vahidi, Sani, et al, 2024).
+
+The following notebook also contains some examples along with more descriptions:
+[source/example/IPSID_tutorial.ipynb](https://github.com/ShanechiLab/PyPSID/blob/main/source/PSID/example/IPSID_tutorial.ipynb)
+
 # Change Log
-You can see the change log in in [ChangeLog.md](https://github.com/ShanechiLab/PyPSID/blob/main/ChangeLog.md)  
+You can see the change log in [ChangeLog.md](https://github.com/ShanechiLab/PyPSID/blob/main/ChangeLog.md)  
 
 # Licence
 Copyright (c) 2020 University of Southern California  
 See full notice in [LICENSE.md](https://github.com/ShanechiLab/PyPSID/blob/main/LICENSE.md)  
-Omid G. Sani and Maryam M. Shanechi  
+Omid G. Sani, Parsa Vahidi and Maryam M. Shanechi  
 Shanechi Lab, University of Southern California

pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "PSID"
+version = "1.2.6"
+authors = [
+    {name = "Omid Sani", email = "omidsani@gmail.com"},
+]
+description = "Python implementation for preferential subspace identification (PSID)"
+requires-python = ">=3.10"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "numpy",
+    "scipy",
+    "scikit-learn",
+    "matplotlib",
+    "h5py"
+]
+dynamic = ["readme"]
+
+[tool.setuptools.dynamic]
+readme = {file = ["README.md"], content-type = "text/markdown"}
+
+[tool.setuptools.packages.find]
+where = ["source"]  # list of folders that contain the packages (["."] by default)

requirements.txt

@@ -1,6 +1,8 @@
 numpy
 scipy
+scikit-learn # sklearn
 matplotlib
+h5py
 
 # Dev tools
 scikit-learn  # Used for tests

setup.py

@@ -0,0 +1,46 @@
+# Release tutorial:
+# https://packaging.python.org/tutorials/packaging-projects/
+# Old version:
+# pip install setuptools wheel twine
+# python setup.py sdist bdist_wheel
+# New version:
+# python -m build
+# Then run the following to upload to PyPI
+# python -m twine upload --repository testpypi dist/*
+# pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple PSID --upgrade
+# python -m twine upload --repository pypi dist/*
+
+
+import setuptools, os
+
+# Get the directory of the setup.py file
+dir_path = os.path.dirname(os.path.realpath(__file__))
+base_dir = os.path.join(dir_path)
+
+# requirements_file_path = os.path.join(base_dir, 'requirements.txt')
+# with open(requirements_file_path, "r", encoding="utf-8") as fh:
+#     requirements = fh.read().split('\n')
+
+readme_file_path = os.path.join(base_dir, "README.md")
+with open(readme_file_path, "r", encoding="utf-8") as fh:
+    long_description = fh.read()
+
+setuptools.setup(
+    name="PSID",
+    version="1.2.5",
+    author="Omid Sani",
+    author_email="omidsani@gmail.com",
+    description="Python implementation for preferential subspace identification (PSID)",
+    long_description=long_description,
+    long_description_content_type="text/markdown",
+    url="https://github.com/ShanechiLab/PyPSID",
+    packages=setuptools.find_packages(where="source"),
+    package_dir={"": "source"},
+    package_data={"PSID": ["*.mat"]},
+    classifiers=[
+        "Programming Language :: Python :: 3",
+        "Operating System :: OS Independent",
+    ],
+    python_requires=">=3.6",
+    # install_requires=requirements,
+)