Merge branch 'GriffithsLab:main' into ex_varying_b_param

.github/workflows/docs.yml

@@ -22,7 +22,6 @@ jobs:
     - name: Build docs
       run: |
         cd doc
-        mkdir _static
         make html
     - name: Deploy Docs
       uses: peaceiris/actions-gh-pages@v3

README.rst

@@ -1,36 +1,28 @@
-WhoBPyT - Whole-Brain Modelling in PyTorch
-=================
-(`Or There and Back Again <https://en.wikipedia.org/wiki/The_Hobbit>`_)
+.. image:: https://github.com/griffithslab/whobpyt/raw/main/doc/_static/whobpyt_logo_shire.png
+   :target: https://github.io/griffithslab/whobpyt/examples/index.html
+   :alt: whobpyt
+   :align: center
 
+*WhoBPyT* is a PyTorch-based Python library for mathematical modelling of large-scale brain network dynamics, obtuse literary allusion, and model-based analysis of neuroimaging and neurophysiology data.
 
-Summary
--------
+It is developed primarily by researchers in the `Whole-Brain Modelling Group`_
+at the `CAMH Krembil Centre for Neuroinformatics`_ & University of Toronto. 
 
-``whobpyt`` (pronounce as 'hobbit') is a Python library for PyTorch-based whole-brain modeling in Python.
+.. _Whole-Brain Modelling Group: www.grifflab.com
 
-Please note that the code here is still very preliminary, under active
-development, and subject to substantial change.
+.. _CAMH Krembil Centre for Neuroinformatics: www.krembilneuroinformatics.ca
 
 
-Rationale
----------
+Note that this project is relatively new and under active development, so the contents of this repo are subject to substantial change. If you are interested in using WhoBPyT in your research (and especially if you are interested in contributing to the code base development), please get in touch by emailing john dot griffiths at utoronto dot ca, or just introduce yourself via an issue.
 
-As open source and open science advocates, we have elected to pursue a
-‘fully open’ and public development approach here. A chief motivation
-behind this is to bring in contributors and collaborators who are
-interested in working together to move things forward more quickly that
-any of us would be able to individually. So, if you are interested in
-getting involved, don’t hesitate to reach out to John ( j dot
-davidgriffiths at gmail dot com ), or just introduce yourself via an
-issue.
 
 Structure
 ---------
 
 There are three main components to the code base:
 
-
 |  ``doc`` folder - Documentation pages text and organization
 |  ``whobpyt`` folder - The importable python library
-|  ``examples`` folder - Example usage scripts that become the gallery
-  items in the CI-managed sphinx gallery site
+|  ``examples`` folder - Example usage scripts that become the gallery items in the CI-managed sphinx gallery site
+
+

doc/API/datatypes.rst

@@ -1,17 +1,17 @@
 Data Types
 ===================================
 
-.. autoclass:: whobpyt.datatypes.Recording
+.. autoclass:: whobpyt.datatypes.timeseries.Timeseries
    :members:
    :undoc-members:
    :special-members: __init__
 
-.. autoclass:: whobpyt.datatypes.par
+.. autoclass:: whobpyt.datatypes.parameter.Parameter
    :members:
    :undoc-members:
    :special-members: __init__
 
-.. autoclass:: whobpyt.datatypes.TrainingStats
+.. autoclass:: whobpyt.datatypes.outputs.TrainingStats
    :members:
    :undoc-members:
-   :special-members: __init__
+   :special-members: __init__

doc/API/models.rst

@@ -1,27 +1,8 @@
 Models
 ===================================
 
-.. autoclass:: whobpyt.models.JansenRit.RNNJANSEN
-   :members: info, createIC, createDelayIC, setModelParameters, forward
+.. autoclass:: whobpyt.models.jansen_rit.jansen_rit.JansenRitModel
+   :members: info, createIC, createDelayIC, setModelParameters, setModelSCParameters,forward
    :undoc-members:
    :special-members: __init__
 
-.. autoclass:: whobpyt.models.RWW.RNNRWW
-   :members: info, createIC, setModelParameters, forward
-   :undoc-members:
-   :special-members: __init__
-
-.. autoclass:: whobpyt.models.RWWEI2.RWWEI2
-   :members: info, createIC, setModelParameters, forward
-   :undoc-members:
-   :special-members: __init__
-
-.. autoclass:: whobpyt.models.BOLD.BOLD_Layer
-   :members: info, createIC, setModelParameters, forward
-   :undoc-members:
-   :special-members: __init__
-
-.. autoclass:: whobpyt.models.EEG.EEG_Layer
-   :members: info, createIC, setModelParameters, forward
-   :undoc-members:
-   :special-members: __init__

doc/API/run.rst

@@ -1,17 +1,8 @@
 Run
 ===================================
 
-.. autoclass:: whobpyt.run.Model_fitting
+.. autoclass:: whobpyt.run.model_fitting.ModelFitting
    :members: train, evaluate, save
    :undoc-members:
    :special-members: __init__
 
-.. autoclass:: whobpyt.run.Fitting_Batch
-   :members: train
-   :undoc-members:
-   :special-members: __init__
-
-.. autoclass:: whobpyt.run.Fitting_FNGFPG
-   :members: train
-   :undoc-members:
-   :special-members: __init__

doc/_static/cards.css

@@ -0,0 +1,7 @@
+.pyvista-card-title {
+  color: #459db9;
+  font-style: normal;
+  font-weight: 500 !important;
+  font-size: 20px;
+  text-align: center;
+}

doc/conf.py

@@ -58,11 +58,11 @@ def is_development_build():
     'sphinx': ('http://www.sphinx-doc.org/en/stable/', None),
 }
 
-html_theme = 'sphinx_rtd_theme'
-#html_theme_options = {
-#    'logo_only': False,#True,
-#    'navigation_depth': 5,
-#}
+html_theme = 'pydata_sphinx_theme'
+html_theme_options = {
+    'logo_only': False,#True,
+    'navigation_depth': 5,
+}
 html_context = {}
 
 if not 'READTHEDOCS' in os.environ:
@@ -255,7 +255,7 @@ def setup(app):
 
 # Configurations for sphinx gallery
 
-sphinx_gallery_conf = {'filename_pattern': '(?=.*r__)(?=.*.py)', 
+sphinx_gallery_conf = {'filename_pattern': '(?=.*eg__)(?=.*.py)', 
                        'examples_dirs': ['../examples'],
                        'gallery_dirs': ['auto_examples'],
                        'within_subsection_order': FileNameSortKey, #'default_thumb_file': 'img/whobpyt_logo.png',

doc/index.rst

@@ -1,8 +1,8 @@
+.. include:: ../README.rst
+
 Welcome to WhoBPyT documentation!
 ===================================
 
-.. include:: ../README.md
-
 .. toctree::
    :maxdepth: 1
    :caption: About WhoBPyT
@@ -37,5 +37,5 @@ Welcome to WhoBPyT documentation!
    :caption: Examples
    :glob:
 
-   auto_examples/eg__replicate_Momi2023
+   auto_examples/eg__tmseeg
 

examples/eg__replicate_Momi2023.py → examples/eg__tmseeg.py

@@ -1,11 +1,11 @@
 """
-.. _ex-momi2023-rep:
+.. _ex-tmseeg:
 
 ========================================================
-Replicating Momi et al. (2023): TMS-evoked Responses
+Modelling TMS-EEG evoked responses
 ========================================================
 
-This script replicates the findings of the paper :footcite:`MomiEtAl2023`:
+This example runs a minimal example based on the analysis in the paaper :footcite:`MomiEtAl2023`:
 
 Momi, D., Wang, Z., Griffiths, J.D. (2023).
  "TMS-evoked responses are driven by recurrent large-scale network dynamics."
@@ -56,9 +56,10 @@
 # %%
 # Download and load necessary data for the example
 download_data = True 
-url = 'https://drive.google.com/drive/folders/1dpyyfJl9wjTrWVo5lqOmB8HRhD3irjNj?usp=drive_link'
+url = 'https://drive.google.com/drive/folders/1DTdF_xR78DxB6kzxqY3SVYBAcdU9IkAB?usp=drive_link'
+
 if download_data: gdown.download_folder(url, quiet=True)
-data_dir = os.path.abspath('eg__replicate_Momi2023_data')
+data_dir = os.path.abspath('eg__tmseeg_data')
 
 # %%
 # Load EEG data from a file
@@ -113,7 +114,7 @@
 output_size = eeg_data.shape[0]
 batch_size = 20
 step_size = 0.0001
-num_epochs = 20 #2 # num_epochs = 20
+num_epochs = 2 # num_epochs = 20
 tr = 0.001
 state_size = 6
 base_batch_num = 20

requirements.txt

@@ -28,6 +28,7 @@ nbsphinx
 jupyter
 ipykernel
 jupyter-alabaster-theme
+pydata-sphinx-theme
 gdown
 jinja2<3.1
 

whobpyt/datatypes/abstract_neural_model.py

@@ -6,6 +6,18 @@
 from .parameter import Parameter as par
 from torch.nn.parameter import Parameter as ptParameter
 from torch.nn import Module as ptModule
+import subprocess
+
+def get_git_commit_hash():
+    try:
+        # Run the Git command to get the current commit hash
+        commit_hash = subprocess.check_output(['git', 'rev-parse', 'HEAD']).strip().decode('utf-8')
+        return commit_hash
+    except subprocess.CalledProcessError:
+        # Handle the case where the git command fails, for example, if not in a git repository
+        return None
+
+
 
 class AbstractNeuralModel(ptModule):
     # This is the abstract class for the models (typically neural mass models) that are being trained. 
@@ -17,14 +29,16 @@ def __init__(self, params):
         self.state_names = ["None"] # The names of the state variables of the model
         self.output_names = ["None"] # The variable to be used as output from the NMM, for purposes such as the input to an objective function
         self.track_params = [] # Which NMM Parameters to track over training
+        self.commit_hash = get_git_commit_hash()
 
 
     def info(self):
         # Information about the model, which may be used by other classes to know which variables to use. 
 
         return {"state_names": self.state_names, 
                 "output_names": self.output_names,
-                "track_params": self.track_params}
+                "track_params": self.track_params,
+                "commit_hash": self.commit_hash}
 
     def setModelParameters(self):
         # Setting the parameters that will be optimized as either model parameters or 2ndLevel/hyper

whobpyt/functions/arg_type_check.py

@@ -4,7 +4,7 @@
 
 def method_arg_type_check(method_obj, exclude = []):
     """
-    Takes the method object of a given function (e.g. RNNJANSEN) and checks that the passed arguments abide by their 
+    Takes the method object of a given function (e.g. JansenRitModel) and checks that the passed arguments abide by their 
     expected data types.  If there is a discrepency, raises a ValueError.
     
     Optional argument: exclude