BOLD readme file

doc/getting_started/how_to_contribute.md

@@ -0,0 +1,47 @@
+# Contributing to WhoBPyT Codebase
+Authors: Andrew Clappison, Kevin Kadak, John Griffiths
+
+The below instuctions outline how to properly adhere to version control for contributing to the WhoBPyT repo.
+
+## Setting Up (Done Once):
+
+- **Downloading your Fork**
+  - Must have already configured an authentication key and have forked the repository on github.com; ensure your fork is up-to-date with the whobpyt/dev branch from which your new branch will be created.
+  - Open terminal and go to the desired directory.
+  - `git clone git@github.com:<<your_github_account>>/whobpyt.git`
+
+- **Adding Upstream**
+  - `cd whobpyt`
+  - `git remote add upstream https://github.com/GriffithsLab/whobpyt.git`
+  - `git fetch upstream`
+
+## Coding Cycle (Done for each new feature or group of features):
+
+- **Creating a New Branch**
+  - `git fetch upstream`
+  - `git checkout --track upstream/dev`
+  - `git push origin dev`
+  - `git checkout -b <<new_branch_name>>`
+
+- **Editing Code**
+  - Add/Delete/Edit code
+
+- **Testing (WhoBPyT Sphinx Examples should run successfully on Linux, but may fail to run on Windows)**
+  - Optionally: Rename sphinx examples ending in “r” to “x” if it is not relevant to the code changes done (for quicker debugging). Example: “eg001r...” to “eg001x...”.
+  - `cd doc`
+  - `make clean`
+  - `make html`
+  - Open and inspect in a web browser: whobpyt/doc/_build/html/html.txt
+  - Additional other testing may also be advised.
+
+- **Committing Code**
+  - `git status`
+  - `git add <<edited_file_names>>`
+  - `git commit -m “<<commit_message>>”`
+
+- **Pushing Code**
+  - `git push --set-upstream origin <<new_branch_name>>`
+
+- **Creating a pull request**
+  - On github.com do a pull request from the new branch on your fork to the main repo’s dev branch. If there is a merging conflict, it will have to be addressed before proceeding.
+

requirements.txt

@@ -12,13 +12,12 @@ mne
 
 
 # Docs requirements
-sphinx
-#sphinx==3.1.1
-sphinx-gallery==0.8.1
-sphinx_rtd_theme==0.5.0
-sphinx-tabs==1.3.0
-sphinx-copybutton==0.3.1
-sphinxcontrib-httpdomain==1.7.0
+sphinx==5.0.0
+sphinx-gallery==0.15.0
+sphinx_rtd_theme==2.0.0
+sphinx-tabs==3.4.4
+sphinx-copybutton==0.5.2
+sphinxcontrib-httpdomain==1.8.1
 numpydoc==1.1.0
 recommonmark==0.6.0
 versioneer==0.19
@@ -28,7 +27,7 @@ nbsphinx
 jupyter
 ipykernel
 jupyter-alabaster-theme
-gdown
+gdown==4.6
 jinja2<3.1
 
 

whobpyt/models/BOLD/README.md

@@ -0,0 +1,30 @@
+# Balloon Windkessel Model (Friston et al., 2003)
+
+## Description:
+
+The Balloon Windkessel model (as described in Friston et al., 2003) is a computational model used to simulate the hemodynamic response associated with neural activity in functional Magnetic Resonance Imaging (fMRI) studies. This model captures the changes in cerebral blood flow, blood volume, and oxygenation levels that occur in response to neuronal activity. The metaphorical "balloon" in the model represents the compliance of blood vessels, while the "Windkessel" refers to a simplified model of the arterial system. The model assumes that an increase in neural activity leads to a transient increase in blood flow, causing the balloon to inflate. As a result, blood volume and oxygenation levels rise, mimicking the hemodynamic response observed in fMRI experiments. The Balloon Windkessel model provides a computationally efficient way to link neural activity to the observed fMRI signal, facilitating the interpretation of functional brain imaging data.
+
+
+## Utility
+
+Hemodynamic Response Simulation: The Balloon Windkessel model is designed to simulate the hemodynamic response associated with neural activity in fMRI studies.
+
+Linking Neural Activity to fMRI Signal: It provides a computational framework to link changes in neural activity to observed fMRI signals, aiding in the interpretation of functional brain imaging data.
+
+Efficient Representation: The model efficiently represents the dynamics of blood flow, blood volume, and oxygenation levels in response to neural stimuli, capturing key aspects of the hemodynamic response.
+
+Parameter Adjustability: Parameters such as τ1,τ2,η,ρ,α,β,υ can be adjusted to fit experimental data, accommodating individual variability and specific research needs.
+
+Insights into Neurovascular Coupling: By simulating the interplay between neural and vascular responses, the model contributes to a deeper understanding of neurovascular coupling, which is essential for interpreting fMRI signals.
+
+Predictive and Exploratory Tool: It serves as a predictive tool for experimental outcomes and an exploratory tool for understanding the impact of various physiological parameters on the observed hemodynamic response.
+
+Integration with Experimental Data: The model facilitates integration with experimental data, allowing researchers to validate and refine theoretical concepts about the relationship between neural activity and the resulting hemodynamic changes.
+
+Educational Tool: The model provides a simplified yet instructive educational resource, aiding students and researchers in comprehending the complex dynamics involved in the hemodynamic response.
+
+
+
+## Equations & Biological Variables From:
+
+Friston KJ, Harrison L, Penny W. Dynamic causal modelling. Neuroimage. 2003 Aug 1;19(4):1273-302.