diff --git a/README.md b/README.md new file mode 100644 index 000000000..5791078e9 --- /dev/null +++ b/README.md @@ -0,0 +1,201 @@ +# hnn-core + +[![tests](https://github.com/jonescompneurolab/hnn-core/actions/workflows/unix_unit_tests.yml/badge.svg?branch=master)](https://github.com/jonescompneurolab/hnn-core/actions/?query=branch:master+event:push) +[![CircleCI](https://circleci.com/gh/jonescompneurolab/hnn-core.svg?style=svg)](https://circleci.com/gh/jonescompneurolab/hnn-core) +[![Codecov](https://codecov.io/gh/jonescompneurolab/hnn-core/branch/master/graph/badge.svg)](https://codecov.io/gh/jonescompneurolab/hnn-core) +[![PyPI](https://img.shields.io/pypi/dm/hnn-core.svg?label=PyPI%20downloads)](https://pypi.org/project/hnn-core/) +[![Gitter](https://badges.gitter.im/jonescompneurolab/hnn_core.svg)](https://gitter.im/jonescompneurolab/hnn-core?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge) +[![JOSS](https://joss.theoj.org/papers/10.21105/joss.05848/status.svg)](https://doi.org/10.21105/joss.05848) + +![HNN-GUI](https://raw.githubusercontent.com/jonescompneurolab/hnn-core/acbcc4a598610dc3be5d4b0b7c59f98251ea7690/.github/images/hnn_gui.png) + +## About + +This is a leaner and cleaner version of the code based off the [HNN +repository](https://github.com/jonescompneurolab/hnn). + +The **Human Neocortical Neurosolver (HNN)** is an open-source neural modeling +tool designed to help researchers/clinicians interpret human brain imaging +data. Based off the original [HNN +repository](https://github.com/jonescompneurolab/hnn), **HNN-core** provides a +convenient way to run simulations of an anatomically and biophysically detailed +dynamical system model of human thalamocortical brain circuits with only a few +lines of code. Given its modular, object-oriented design, HNN-core makes it +easy to generate and evaluate hypotheses on the mechanistic origin of signals +measured with magnetoencephalography (MEG), electroencephalography (EEG), or +intracranial electrocorticography (ECoG). A unique feature of the HNN model is +that it accounts for the biophysics generating the primary electric currents +underlying such data, so simulation results are directly comparable to source +localized data (current dipoles in units of nano-Ampere-meters); this enables +precise tuning of model parameters to match characteristics of recorded +signals. Multimodal neurophysiology data such as local field potential (LFP), +current-source density (CSD), and spiking dynamics can also be simulated +simultaneously with current dipoles. + +While the HNN-core API is designed to be flexible and serve users with varying +levels of coding expertise, the HNN-core GUI is designed to be useful to +researchers with no formal computational neural modeling or coding experience. + +For more information visit . There, we describe the use +of HNN in studying the circuit-level origin of some of the most commonly +measured MEG/EEG and ECoG signals: event related potentials (ERPs) and low +frequency rhythms (alpha/beta/gamma). + +Contributors are very welcome. Please read our [contributing +guide][] if you are interested. + +## Dependencies + +hnn-core requires Python (>=3.8) and the following packages: + +- numpy +- scipy +- matplotlib +- Neuron (>=7.7) + +## Optional dependencies + +### GUI + +- ipywidgets +- voila +- ipympl +- ipykernel + +*Note*: Please follow the **GUI installation** section to install the +correct GUI dependency versions automatically. + +### Optimization + +- scikit-learn + +### Parallel processing + +- joblib (for simulating trials simultaneously) +- mpi4py (for simulating the cells in parallel for a single trial). + Also depends on: + - openmpi or other mpi platform installed on system + - psutil + +# Installation + +We recommend the [Anaconda Python +distribution](https://www.anaconda.com/products/individual). To install +`hnn-core`, simply do: + + $ pip install hnn_core + +and it will install `hnn-core` along with the dependencies which are not +already installed. + +Note that if you installed Neuron using the traditional installer +package, it is recommended to remove it first and unset `PYTHONPATH` and +`PYTHONHOME` if they were set. This is because the pip installer works +better with virtual environments such as the ones provided by `conda`. + +If you want to track the latest developments of `hnn-core`, you can +install the current version of the code (nightly) with: + + $ pip install --upgrade https://api.github.com/repos/jonescompneurolab/hnn-core/zipball/master + +To check if everything worked fine, you can do: + + $ python -c 'import hnn_core' + +and it should not give any error messages. + +**Installing optimization dependencies** + +If you are using bayesian optimization, then scikit-learn is required. +Install hnn-core with scikit-learn using the following command: + + $ pip install hnn_core[opt] + +**GUI installation** + +To install the GUI dependencies along with `hnn-core`, a simple tweak to +the above command is needed: + + $ pip install hnn_core[gui] + +Note if you are zsh in macOS the command is: + + $ pip install hnn_core'[gui]' + +To start the GUI, please do: + + $ hnn-gui + +**Parallel backends** + +For further instructions on installation and usage of parallel backends +for using more than one CPU core, refer to our [parallel backend +guide](https://jonescompneurolab.github.io/hnn-core/stable/parallel.html). + +**Note for Windows users** + +Install Neuron using the [precompiled +installers](https://nrn.readthedocs.io/en/latest/) **before** installing +`hnn-core`. Make sure that: + + $ python -c 'import neuron;' + +does not throw any errors before running the install command. If you +encounter errors, please get help from [NEURON +forum](https://www.neuron.yale.edu/phpbb/). Finally, do: + + $ pip install hnn_core[gui] + +# Documentation and examples + +Once you have tested that `hnn_core` and its dependencies were +installed, we recommend downloading and executing the [example +scripts](https://jonescompneurolab.github.io/hnn-core/stable/auto_examples/index.html) +provided on the [documentation +pages](https://jonescompneurolab.github.io/hnn-core/) (as well as in the +[GitHub repository](https://github.com/jonescompneurolab/hnn-core)). + +Note that `python` plots are by default non-interactive (blocking): each +plot must thus be closed before the code execution continues. We +recommend using and 'interactive' python interpreter such as +`ipython`: + + $ ipython --matplotlib + +and executing the scripts using the `%run`-magic: + + %run plot_simulate_evoked.py + +When executed in this manner, the scripts will execute entirely, after +which all plots will be shown. For an even more interactive experience, +in which you execute code and interrogate plots in sequential blocks, we +recommend editors such as [VS Code](https://code.visualstudio.com) and +[Spyder](https://docs.spyder-ide.org/current/index.html). + +# Bug reports + +Use the [github issue +tracker](https://github.com/jonescompneurolab/hnn-core/issues) to report +bugs. For user questions and scientific discussions, please see our +[GitHub Discussions +page](https://github.com/jonescompneurolab/hnn-core/discussions). + +# Interested in Contributing? + +Read our [contributing guide][]. + +# Governance Structure + +Read our [governance +structure](https://jonescompneurolab.github.io/hnn-core/stable/governance.html). + +# Citing + +If you use HNN-core in your work, please cite our [publication in +JOSS](https://doi.org/10.21105/joss.05848): + +> Jas et al., (2023). HNN-core: A Python software for cellular and +> circuit-level interpretation of human MEG/EEG. *Journal of Open Source +> Software*, 8(92), 5848, + +[contributing guide]: https://jonescompneurolab.github.io/hnn-core/stable/contributing.html diff --git a/README.rst b/README.rst deleted file mode 100644 index d326a50b0..000000000 --- a/README.rst +++ /dev/null @@ -1,216 +0,0 @@ -hnn-core -======== - -|tests| |CircleCI| |Codecov| |PyPI| |Gitter| |JOSS| - -|HNN-GUI| - -About ------ -This is a leaner and cleaner version of the code based off the -`HNN repository `_. - -The **Human Neocortical Neurosolver (HNN)** is an open-source neural modeling -tool designed to help researchers/clinicians interpret human brain imaging -data. Based off the original -`HNN repository `_, **HNN-core** -provides a convenient way to run simulations of an anatomically -and biophysically detailed dynamical system model of human thalamocortical -brain circuits with only a few lines of code. Given its modular, -object-oriented design, HNN-core makes it easy to generate and evaluate -hypotheses on the mechanistic origin of signals measured with -magnetoencephalography (MEG), electroencephalography (EEG), or -intracranial electrocorticography (ECoG). A unique feature of the HNN model is -that it accounts for the biophysics generating the primary electric currents -underlying such data, so simulation results are directly comparable to source -localized data (current dipoles in units of nano-Ampere-meters); this enables -precise tuning of model parameters to match characteristics of recorded -signals. Multimodal neurophysiology data such as local field potential (LFP), -current-source density (CSD), and spiking dynamics can also be simulated -simultaneously with current dipoles. - -While the HNN-core API is designed to be flexible and serve users with varying -levels of coding expertise, the HNN-core GUI is designed to be useful -to researchers with no formal computational neural modeling or coding -experience. - -For more information visit `https://hnn.brown.edu `_. -There, we describe the use of HNN in studying the circuit-level origin of some -of the most commonly measured MEG/EEG and ECoG signals: event related -potentials (ERPs) and low frequency rhythms (alpha/beta/gamma). - -Contributors are very welcome. Please read our -`contributing guide`_ if you are interested. - -Dependencies ------------- -hnn-core requires Python (>=3.8) and the following packages: - -* numpy -* scipy -* matplotlib -* Neuron (>=7.7) - -Optional dependencies ---------------------- - -GUI -~~~ - -* ipywidgets -* voila -* ipympl -* ipykernel - -*Note*: Please follow the **GUI installation** section to install the correct -GUI dependency versions automatically. - -Optimization -~~~~~~~~~~~~ - -* scikit-learn - -Parallel processing -~~~~~~~~~~~~~~~~~~~ - -* joblib (for simulating trials simultaneously) -* mpi4py (for simulating the cells in parallel for a single trial). Also depends on: - - * openmpi or other mpi platform installed on system - * psutil - -Installation -============ - -We recommend the `Anaconda Python distribution `_. -To install ``hnn-core``, simply do:: - - $ pip install hnn_core - -and it will install ``hnn-core`` along with the dependencies which are not already installed. - -Note that if you installed Neuron using the traditional installer package, it is recommended -to remove it first and unset ``PYTHONPATH`` and ``PYTHONHOME`` if they were set. This is -because the pip installer works better with virtual environments such as the ones provided by ``conda``. - -If you want to track the latest developments of ``hnn-core``, you can install the current version of the code (nightly) with:: - - $ pip install --upgrade https://api.github.com/repos/jonescompneurolab/hnn-core/zipball/master - -To check if everything worked fine, you can do:: - - $ python -c 'import hnn_core' - -and it should not give any error messages. - -**Installing optimization dependencies** - -If you are using bayesian optimization, then scikit-learn is required. Install -hnn-core with scikit-learn using the following command:: - - $ pip install hnn_core[opt] - -**GUI installation** - -To install the GUI dependencies along with ``hnn-core``, a simple tweak to the above command is needed:: - - $ pip install hnn_core[gui] - -Note if you are zsh in macOS the command is:: - - $ pip install hnn_core'[gui]' - -To start the GUI, please do:: - - $ hnn-gui - -**Parallel backends** - -For further instructions on installation and usage of parallel backends for using more -than one CPU core, refer to our `parallel backend guide`_. - -**Note for Windows users** - -Install Neuron using the `precompiled installers`_ **before** installing -``hnn-core``. Make sure that:: - - $ python -c 'import neuron;' - -does not throw any errors before running the install command. -If you encounter errors, please get help from `NEURON forum`_. -Finally, do:: - - $ pip install hnn_core[gui] - - -Documentation and examples -========================== - -Once you have tested that ``hnn_core`` and its dependencies were installed, -we recommend downloading and executing the -`example scripts `_ -provided on the `documentation pages `_ -(as well as in the `GitHub repository `_). - -Note that ``python`` plots are by default non-interactive (blocking): each plot must thus be closed before the code execution continues. We recommend using and 'interactive' python interpreter such as ``ipython``:: - - $ ipython --matplotlib - -and executing the scripts using the ``%run``-magic:: - - %run plot_simulate_evoked.py - -When executed in this manner, the scripts will execute entirely, after which all plots will be shown. For an even more interactive experience, in which you execute code and interrogate plots in sequential blocks, we recommend editors such as `VS Code `_ and `Spyder `_. - -Bug reports -=========== - -Use the `github issue tracker `_ to -report bugs. For user questions and scientific discussions, please see our -`GitHub Discussions page `_. - -Interested in Contributing? -=========================== - -Read our `contributing guide`_. - -Governance Structure -==================== - -Read our `governance structure`_. - -Citing -====== - -If you use HNN-core in your work, please cite our -`publication in JOSS `_: - - Jas et al., (2023). HNN-core: A Python software for cellular and - circuit-level interpretation of human MEG/EEG. *Journal of Open Source - Software*, 8(92), 5848, https://doi.org/10.21105/joss.05848 - -.. _precompiled installers: https://nrn.readthedocs.io/en/latest/ -.. _NEURON forum: https://www.neuron.yale.edu/phpbb/ -.. _contributing guide: https://jonescompneurolab.github.io/hnn-core/stable/contributing.html -.. _governance structure: https://jonescompneurolab.github.io/hnn-core/stable/governance.html -.. _parallel backend guide: https://jonescompneurolab.github.io/hnn-core/stable/parallel.html - -.. |tests| image:: https://github.com/jonescompneurolab/hnn-core/actions/workflows/unix_unit_tests.yml/badge.svg?branch=master - :target: https://github.com/jonescompneurolab/hnn-core/actions/?query=branch:master+event:push - -.. |CircleCI| image:: https://circleci.com/gh/jonescompneurolab/hnn-core.svg?style=svg - :target: https://circleci.com/gh/jonescompneurolab/hnn-core - -.. |Codecov| image:: https://codecov.io/gh/jonescompneurolab/hnn-core/branch/master/graph/badge.svg - :target: https://codecov.io/gh/jonescompneurolab/hnn-core - -.. |PyPI| image:: https://img.shields.io/pypi/dm/hnn-core.svg?label=PyPI%20downloads - :target: https://pypi.org/project/hnn-core/ - -.. |HNN-GUI| image:: https://raw.githubusercontent.com/jonescompneurolab/hnn-core/acbcc4a598610dc3be5d4b0b7c59f98251ea7690/.github/images/hnn_gui.png - -.. |Gitter| image:: https://badges.gitter.im/jonescompneurolab/hnn_core.svg - :target: https://gitter.im/jonescompneurolab/hnn-core?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge - -.. |JOSS| image:: https://joss.theoj.org/papers/10.21105/joss.05848/status.svg - :target: https://doi.org/10.21105/joss.05848 diff --git a/doc/api.rst b/doc/api.rst index 66cdd0bed..89ed7c19e 100644 --- a/doc/api.rst +++ b/doc/api.rst @@ -1,5 +1,10 @@ :orphan: +.. + This document is kept in RST instead of Markdown format due to its + importance, accessibility, and the potential for mistaken configuration in + adapting it to the MyST Markdown parser. + .. _api_documentation: ================= diff --git a/doc/conf.py b/doc/conf.py index ec461fffa..61a746791 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -50,14 +50,15 @@ # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ + 'gh_substitutions', # custom extension, see ./sphinxext/gh_substitutions.py + 'myst_parser', + 'numpydoc', 'sphinx_gallery.gen_gallery', 'sphinx.ext.viewcode', 'sphinx.ext.autosummary', 'sphinx.ext.autodoc', 'sphinx.ext.intersphinx', - 'numpydoc', 'sphinx_copybutton', - 'gh_substitutions' # custom extension, see ./sphinxext/gh_substitutions.py ] # generate autosummary even if no references @@ -75,10 +76,12 @@ templates_path = ['_templates'] # The suffix(es) of source filenames. -# You can specify multiple suffix as a list of string: -# -# source_suffix = ['.rst', '.md'] -source_suffix = '.rst' +# You can specify multiple suffix as a dict: +source_suffix = { + '.rst': 'restructuredtext', + '.md': 'markdown', +} + # The master toctree document. master_doc = 'index' diff --git a/doc/contributing.md b/doc/contributing.md new file mode 100644 index 000000000..7dbe0b90e --- /dev/null +++ b/doc/contributing.md @@ -0,0 +1,284 @@ +(contributing)= +# Contributions + +Please read the contribution guide **until the end** before beginning +contributions. + +Contributions are welcome in the form of pull requests. + +Once the implementation of a piece of functionality is considered to be +bug free and properly documented (both API docs and an example script), +it can be incorporated into the master branch. + +To help developing `hnn-core`, you will need a few adjustments to your +installation as shown below. + +If your contributions will make use of parallel backends for using more +than one core, please see the additional installation steps in our {doc}`parallel backend guide `. + +## Setting up your local development environment + +### Configuring git + +Instructions for how to configure git can be found on the git book +[configuration](https://git-scm.com/book/en/v2/Customizing-Git-Git-Configuration) +page. + +## Making your first pull request + +Changes to hnn-core are typically made by "forking" the hnn-core +repository, making changes to your fork (usually by "cloning" it to +your personal computer, making the changes locally, and then "pushing" +the local changes up to your fork on GitHub), and finally creating a +"pull request" to incorporate your changes back into the shared +"upstream" version of the codebase. + +In general you'll be working with three different copies of the +hnn-core codebase: the official remote copy at + (usually called +`upstream`), your remote fork of the upstream repository (similar URL, +but with your username in place of `hnn-core`, and usually called +`origin`), and the local copy of the codebase on your computer. The +typical contribution process is to + +1. Make a fork of the + [hnn-core](https://github.com/jonescompneurolab/hnn-core) repository + to your own account on github. Look for the Fork button in the top + right corner + +2. On the terminal of your local computer clone the fork: + + $ git clone https://github.com//hnn-core + +3. On the terminal of your local computer set up the remotes: + + $ cd hnn-core + $ git remote add upstream https://github.com/jonescompneurolab/hnn-core + +4. Check that the remotes have been correctly added: + + $ git remote -v + + You should see: + + origin https://github.com//hnn-core (fetch) + origin https://github.com//hnn-core (push) + upstream https://github.com/jonescompneurolab/hnn-core (fetch) + upstream https://github.com/jonescompneurolab/hnn-core (push) + +5. To start a new feature branch, we will copy the existing `master` + branch from the `upstream` remote and give it a specific name: + + $ git fetch upstream master:cool_feature + $ git checkout cool_feature + +6. Make your changes relevant to the pull request + +7. To make a commit, you first have to add the files you have changed + to the staging area: + + $ git add -u + + ensure they have been added correctly: + + $ git status + + make a commit: + + $ git commit -m "your commit message" + + and finally check that the commit has been added: + + $ git log + + Note: see the [numpy contributing + guide](https://numpy.org/doc/stable/dev/development_workflow.html#writing-the-commit-message) + for tips on informative commit messages. + +8. Now push the feature branch to your fork: + + $ git push origin cool_feature + +9. Go to to + open the pull request by selecting your feature branch. You should + also see this link on the terminal when you make the push. + +10. After your pull request is reviewed, repeat steps 6-8 to update the + pull request. + +11. Once the pull request is ready to be merged, add the prefix [MRG] + to the title. + +See the [git book](https://git-scm.com/book/en/v2) for a more general +guide on using git. + +## Installing editable hnn-core + +For making changes to hnn-core, you will need to install an editable +version of hnn-core. For that you need to have the git cloned `hnn-core` +repository and use pip with the editable (`-e`) flag: + + $ git clone https://github.com/jonescompneurolab/hnn-core + $ cd hnn-core + $ pip install -e '.[dev]' + $ python setup.py build_mod + +The `pip install -e '.[dev]'` step will install all extra packages used +by developers to access all features and to perform testing and building +of documentation. + +The last step builds `mod` files which specifies the dynamics of +specific cellular mechanisms. These are converted to C, and hence +require a compilation step. In the normal course of development, you +will not have to edit these files. However, if you do have to update +them, they will need to be rebuilt using the command: + + $ python setup.py build_mod + +## Running tests + +Once you have the editable hnn-core, you should install the requirements +for running the tests. Tests help ensure integrity of the package after +your change has been made. We recommend developers to run tests locally +on their computers after making changes. + +We use the `pytest` testing framework. + +To run the tests simply type into your terminal: + + $ make test + +MPI tests are skipped if the `mpi4py` module is not installed. We highly +encourage contributors to follow the +`parallel backend guide `{.interpreted-text role="doc"} to +install `mpi4py` so that they can run the entire test suite locally on +their computer. + +## Updating documentation + +When you update the documentation, it is recommended to build it locally +to check whether the documentation renders correctly in HTML. + +Certain documentation files require explicit updates by the contributor +of a given change (i.e., you). These are: + +- `doc/api.rst` if you added a new function. +- `doc/whats_new.rst` to document the fix or change so you can be + credited on the next release. + +Please update these documents once your pull request is ready to merge +to avoid rebase conflicts with other pull requests. + +### Building the documentation + +The documentation can be built using sphinx. + +You can build the documentation locally using the command: + + $ cd doc/ + $ make html + +If you want to build the documentation locally without running all the +examples, use the command: + + $ make html-noplot + +Finally, to view the documentation, do: + + $ make view + +### Writing the documentation + +You are welcome to write documentation pages using +[reStructuredText](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#rst-primer) (RST). However, +you are also welcome to write using Sphinx's support for [MyST +Markdown](https://www.sphinx-doc.org/en/master/usage/markdown.html#markdown), which employs +[`myst-parser`](https://myst-parser.readthedocs.io/en/latest/). This gives you the power of RST with +the readability of Markdown. + +If you want to take advantage of [Roles and Directives inside your Markdown files](https://myst-parser.readthedocs.io/en/latest/syntax/roles-and-directives.html#roles-directives), it is fairly straightforward to use them via ["MyST Markdown" syntax](https://myst-parser.readthedocs.io/en/latest/syntax/roles-and-directives.html#roles-directives). For example: + +- If you want to refer to another local document like this: {doc}`Parallel Backend Guide `, then: + - In RST, write: + ``` + :doc:`Parallel Backend Guide ` + ``` + - In Markdown, write: + ``` + {doc}`Parallel Backend Guide ` + ``` +- If you want to refer to a part of the HNN-Core API like this: {func}`~hnn_core.Network.add_electrode_array`, then: + - In RST, write: + ``` + :func:`~hnn_core.Network.add_electrode_array` + ``` + - In Markdown, write: + ``` + {func}`~hnn_core.Network.add_electrode_array` + ``` +- For convenience, to quickly insert a link to any specific GitHub issue at , like this: {gh}`705`, then: + - In RST, write: + ``` + :gh:`705` + ``` + - In Markdown, write: + ``` + {gh}`705` + ``` + +## How to rebase + +Commits in hnn-core follow a linear history, therefore we use a +"rebase" workflow instead of "merge" to resolve commits. See [this +article](https://www.atlassian.com/git/tutorials/merging-vs-rebasing) +for more details on the differences between these workflows. + +To rebase, we do the following: + +1. Checkout the feature branch: + + $ git checkout cool_feature + +2. Delete the `master` branch and fetch a new copy: + + $ git branch -D master + $ git fetch upstream master:master + +3. Start the rebase: + + $ git rebase master + +4. If there are conflicts, the easiest approach is to resolve them in + an editor like VS code. See [this + guide](https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging) + for more general information on resolve merge conflicts + +5. Once the conflicts have been resolved, add the resolved files to the + staging area: + + $ git add -u + $ git rebase --continue + +In general it is best to rebase frequently if you are aware of pull +requests being merged into the `master` base. + +If you face a lot of difficulting resolving merge conflicts, it may be +easier to +[squash](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History) +before rebasing. + +## Continuous Integration + +The repository is tested via continuous integration with GitHub Actions +and Circle. The automated tests run on GitHub Actions while the +documentation is built on Circle. + +To speed up the documentation-building process on CircleCI, we enabled +versioned [caching](https://circleci.com/docs/caching/). + +Usually, you don't need to worry about it. But in case a complete +rebuild is necessary for a new version of the doc, you can modify the +content in `.circleci/build_cache`, as CircleCI uses the MD5 of that +file as the key for previously cached content. For consistency, we +recommend you to monotonically increase the version number in that file, +e.g., from "v2"->"v3". diff --git a/doc/contributing.rst b/doc/contributing.rst deleted file mode 100644 index b2c10155b..000000000 --- a/doc/contributing.rst +++ /dev/null @@ -1,239 +0,0 @@ -.. _contributing: - -Contributions -------------- - -Please read the contribution guide **until the end** before beginning -contributions. - -Contributions are welcome in the form of pull requests. - -Once the implementation of a piece of functionality is considered to be bug -free and properly documented (both API docs and an example script), -it can be incorporated into the master branch. - -To help developing ``hnn-core``, you will need a few adjustments to your -installation as shown below. - -If your contributions will make use of parallel backends for using more than -one core, please see the additional installation steps in our -:doc:`parallel backend guide `. - -Setting up your local development environment -============================================= - -Configuring git -~~~~~~~~~~~~~~~ - -Instructions for how to configure git can be found on -the git book `configuration `_ page. - -Making your first pull request -============================== -Changes to hnn-core are typically made by "forking" the hnn-core -repository, making changes to your fork (usually by "cloning" it to your -personal computer, making the changes locally, and then "pushing" the local -changes up to your fork on GitHub), and finally creating a "pull request" to incorporate -your changes back into the shared "upstream" version of the codebase. - -In general you'll be working with three different copies of the hnn-core -codebase: the official remote copy at https://github.com/jonescompneurolab/hnn-core -(usually called ``upstream``), your remote fork of the upstream repository -(similar URL, but with your username in place of ``hnn-core``, and usually -called ``origin``), and the local copy of the codebase on your computer. The -typical contribution process is to - -1. Make a fork of the `hnn-core `_ - repository to your own account on github. Look for the Fork button in the top right corner - -2. On the terminal of your local computer clone the fork:: - - $ git clone https://github.com//hnn-core - -3. On the terminal of your local computer set up the remotes:: - - $ cd hnn-core - $ git remote add upstream https://github.com/jonescompneurolab/hnn-core - -4. Check that the remotes have been correctly added:: - - $ git remote -v - - You should see:: - - origin https://github.com//hnn-core (fetch) - origin https://github.com//hnn-core (push) - upstream https://github.com/jonescompneurolab/hnn-core (fetch) - upstream https://github.com/jonescompneurolab/hnn-core (push) - -5. To start a new feature branch, we will copy the existing ``master`` branch from - the ``upstream`` remote and give it a specific name:: - - $ git fetch upstream master:cool_feature - $ git checkout cool_feature - -6. Make your changes relevant to the pull request - -7. To make a commit, you first have to add the files you have changed to the staging area:: - - $ git add -u - - ensure they have been added correctly:: - - $ git status - - make a commit:: - - $ git commit -m "your commit message" - - and finally check that the commit has been added:: - - $ git log - - Note: see the `numpy contributing guide `_ - for tips on informative commit messages. - -8. Now push the feature branch to your fork:: - - $ git push origin cool_feature - -9. Go to https://github.com/jonescompneurolab/hnn-core/compare to open the pull request by selecting your feature branch. - You should also see this link on the terminal when you make the push. - -11. After your pull request is reviewed, repeat steps 6-8 to update the pull request. - -12. Once the pull request is ready to be merged, add the prefix [MRG] to the title. - -See the `git book `_ for a more general guide on using git. - -Installing editable hnn-core -============================ - -For making changes to hnn-core, you will need to install an editable -version of hnn-core. For that you need to have the git cloned ``hnn-core`` -repository and use pip with the editable (``-e``) flag:: - - $ git clone https://github.com/jonescompneurolab/hnn-core - $ cd hnn-core - $ pip install -e '.[dev]' - $ python setup.py build_mod - -The ``pip install -e '.[dev]'`` step will install all extra packages used by -developers to access all features and to perform testing and building of -documentation. - -The last step builds ``mod`` files which specifies the dynamics of specific -cellular mechanisms. These are converted to C, and hence require a compilation -step. In the normal course of development, you will not have to edit these -files. However, if you do have to update them, they will need to be rebuilt -using the command:: - - $ python setup.py build_mod - -Running tests -============= - -Once you have the editable hnn-core, you should install the requirements -for running the tests. Tests help ensure integrity of the package after -your change has been made. We recommend developers to run tests locally -on their computers after making changes. - -We use the ``pytest`` testing framework. - -To run the tests simply type into your terminal:: - - $ make test - -MPI tests are skipped if the ``mpi4py`` module is not installed. We highly -encourage contributors to follow the :doc:`parallel backend guide ` -to install ``mpi4py`` so that they can run the entire test suite locally -on their computer. - -Updating documentation -====================== - -When you update the documentation, it is recommended to build it locally to -check whether the documentation renders correctly in HTML. - -Certain documentation files require explicit updates by the contributor of a given change (i.e., you). These are: - -* ``doc/api.rst`` if you added a new function. -* ``doc/whats_new.rst`` to document the fix or change so you can be credited on the next release. - -Please update these documents once your pull request is ready to merge to avoid rebase conflicts with other -pull requests. - -Building the documentation -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The documentation can be built using sphinx. - -You can build the documentation locally using the command:: - -$ cd doc/ -$ make html - -If you want to build the documentation locally without running all the examples, -use the command:: - - $ make html-noplot - -Finally, to view the documentation, do:: - - $ make view - -How to rebase -============= - -Commits in hnn-core follow a linear history, therefore we use a "rebase" workflow -instead of "merge" to resolve commits. -See `this article `_ for more details -on the differences between these workflows. - -To rebase, we do the following: - -1. Checkout the feature branch:: - - $ git checkout cool_feature - -2. Delete the ``master`` branch and fetch a new copy:: - - $ git branch -D master - $ git fetch upstream master:master - -3. Start the rebase:: - - $ git rebase master - -4. If there are conflicts, the easiest approach is to resolve them in an editor - like VS code. - See `this guide `_ - for more general information on resolve merge conflicts - -5. Once the conflicts have been resolved, add the resolved files to the staging area:: - - $ git add -u - $ git rebase --continue - -In general it is best to rebase frequently if you are aware of pull requests being merged -into the ``master`` base. - -If you face a lot of difficulting resolving merge conflicts, -it may be easier to `squash `_ -before rebasing. - -Continuous Integration -====================== - -The repository is tested via continuous integration with GitHub Actions and -Circle. The automated tests run on GitHub Actions while the documentation is -built on Circle. - -To speed up the documentation-building process on CircleCI, we enabled versioned -`caching `_. - -Usually, you don't need to worry about it. But in case a complete rebuild is necessary -for a new version of the doc, you can modify the content in ``.circleci/build_cache``, as -CircleCI uses the MD5 of that file as the key for previously cached content. -For consistency, we recommend you to monotonically increase the version number -in that file, e.g., from "v2"-> "v3". diff --git a/doc/glossary.md b/doc/glossary.md new file mode 100644 index 000000000..2433ebd1e --- /dev/null +++ b/doc/glossary.md @@ -0,0 +1,32 @@ +(glossary)= +# Glossary + +The Glossary provides short definitions of HNN-specific vocabulary and +general computational neuroscience concepts. If you think a term is +missing, please consider creating a new issue or opening a pull request +to add it. + +```{glossary} +:sorted: + +drive + An exogenous source of excitatory action potentials that perturbs + the cortical column network. + +gid + The "global" cell ID. A gid is assigned to each cell in the + network as well as artificial drive cells. Global refers to the fact + that the cell ID is unique even if the simulation is split across + cores. + +distal + Anatomical location that is further away from the soma. Distal + drives refer to extrinsic connections to the distal dendrites of the + cortical column, which often originate from indirect thalamic + nuclei, as well as other cortical regions. + +proximal + Anatomical location that is closer to the soma. Proximal drives + refer to extrinsic connections to the proximal dendrites of the + cortical column, which often originate from direct thalamic nuclei. +``` diff --git a/doc/glossary.rst b/doc/glossary.rst deleted file mode 100644 index 0be5ff975..000000000 --- a/doc/glossary.rst +++ /dev/null @@ -1,34 +0,0 @@ -Glossary -======== - -.. currentmodule:: hnn_core - -The Glossary provides short definitions of HNN-specific vocabulary and -general computational neuroscience concepts. If you think a term is missing, -please consider creating a new issue or opening a pull request to add it. - -.. glossary:: - :sorted: - - - drive - An exogenous source of excitatory action potentials - that perturbs the cortical column network. - - gid - The "global" cell ID. A gid is assigned to each cell in the - network as well as artificial drive cells. Global refers to - the fact that the cell ID is unique even if the simulation - is split across cores. - - distal - Anatomical location that is further away from the soma. - Distal drives refer to extrinsic connections to the distal dendrites of - the cortical column, which often originate from indirect thalamic - nuclei, as well as other cortical regions. - - proximal - Anatomical location that is closer to the soma. - Proximal drives refer to extrinsic connections to the proximal dendrites - of the cortical column, which often originate from direct thalamic - nuclei. diff --git a/doc/governance.md b/doc/governance.md new file mode 100644 index 000000000..1159f6eae --- /dev/null +++ b/doc/governance.md @@ -0,0 +1,173 @@ +(governance)= +# Project Governance + +The purpose of this document is to formalize the governance process used +by the Human Neocortical Neurosolver (HNN) project and to clarify how +decisions are made and how the various elements of our community +interact. + +## Mission + +HNN is an open source software project. The goal of HNN is to develop a +hypothesis testing tool for researchers, with the software built upon a +biophysically-principled neocortical circuit model with appropriate +physics that allow bridging from macroscale human magneto- and +electro-encephalography (M/EEG) signals to their cellular and circuit +level generators. + +The foundations of the project governance are: + +- Openness and transparency +- Active contribution +- Institutional neutrality + +The HNN project aims to support a collaborative community of developers, +where any individual may contribute to the project and have their +contributions acknowledged and reflected in the project's GitHub +repository. HNN is developed by researchers with diverse skill sets: +scientific, software, MEG, neuro etc. The governance model is made +keeping in mind that contributions from these diverse sub-communities +will be necessary to advance HNN. + +We invite anyone with an interest in the project to join the community, +contribute to the project design, and participate in the decision making +process. In line with this philosophy, we provide a pathway for project +Contributors\* to become project Maintainers\*\*, allowing for a deeper +level of engagement with the development and decision making processes +of the project. We want to encourage a diverse array of backgrounds, +viewpoints, and talents in our team. Towards this end, contributions are +not limited to changes to the codebase, but can involve updates to the +documentation, proposals of biologically relevant features, and +participation in online discussions, among other activities that advance +the mission of the project. + +## Roles and Responsibilities + +We distinguish between Contributors, Maintainers, and the Steering +Council as outlined in the following sections. + +### Contributors* +Contributors are community members who contribute in concrete ways to +the project. Anyone can become a contributor, and contributions can take +many forms, as detailed in HNN's Contributions page in the HNN-core +documentation. Contributors participate in the project by submitting, +reviewing, and discussing GitHub Pull Requests and Issues and by +participating in open discussions on GitHub and via other channels +including but not limited to the weekly project meetings, email, and +hackathon events. Contributors work on behalf of and are responsible to +the larger HNN Community, and we strive to keep the barrier between +Contributors and Users as low as possible. + +### Maintainers** +Maintainers are community members who have shown that they are dedicated +to the continued development of the project through ongoing engagement +with the community. Being a Maintainer allows contributors to more +easily contribute to the project by giving them "commit rights" to the +project repositories. Maintainers are expected to review code +contributions, merge approved pull requests, and to be involved in +deciding major changes to the API. Maintainers are invited to join +weekly Develop Council meetings hosted virtually. + +Maintainers are determined by the Steering Council based on their level +of engagement and their contributions to the project. Contributors who +have produced contributions that are substantial in quality and quantity +may be eligible for Maintainer status. Maintainers will be elected by +consensus among members of the Steering Council. Under extenuating +circumstances, Maintainer status may be revoked by the Steering Council +by consensus. + +Maintainer status is dependent on continued engagement with the project. +If a Maintainer becomes inactive for a period greater than 1 year, +"commit rights" to the project's repository will be revoked. Maintainer +status can be reinstated for any Contributor if they resume engagement +with the project and produce substantial contributions. + +### Developer Council + +The Developer Council is composed of individuals who take on additional +responsibilities to ensure the smooth operation of the project. +Membership in the Developer Council is by nomination from a current +Developer Council member. The Developer Council will include at least 2 +maintainers at all times. A nomination will result in discussion and +then a vote by the Developer Council members. Developer Council +membership votes are subject to a two-third majority. + +The Developer Council and its members are expected to participate in +strategic planning to guide the overall direction of the project. While +the Developer Council is the final authority for guiding the code review +process and merging pull requests, not all Develop Council members need +to contribute code to the project on a regular basis. Members may be +nominated to the Developer Council based on the quality and quantity of +their contributions to any and all aspects of the project, including +their expertise and efforts in advancing the project mission as outlined +above. + +Responsibilities of the Developer Council include: + +- Attend virtual meetings on a regular basis or as deemed appropriate +- Make decisions about the overall scope, vision, and direction of the + project. +- Make decisions about strategic collaborations with other + organizations or individuals. +- Make decisions about specific technical issues, features, bugs, and + pull requests when appropriate +- Make decisions about the services that are run by the project and + manage those services for the benefit of the community +- Update policy documents, such the Project Governance + +If a member becomes inactive in the project for a period of one year, +they will be considered for removal from the Developer Council. Before +removal, the inactive member will be approached to inquire if they plan +to return to active participation. If not, they will be removed upon a +Developer Council vote. If the inactive member plans on returning to +active participation, they can be granted a grace period as determined +by the Developer Council. All former Developer Council Members can be +considered for membership again at any time in the future. Retired +Developer Council Members will be listed on the project website. + +## Decision-Making Process + +Decisions related to the project are made through consensus among the +Maintainers and the Developer Council, with input from the community and +Contributors. Final authority over key decisions related to the overall +scope, vision, and direction of the project lies solely with the +Developer Council. For contributions to the project repositories, HNN +uses a "consensus-seeking" process for making decisions. Any +contributions must follow the processes outlined in the Contributions +page of the HNN-core documentation. + +As outlined in Roles and Responsibilities, the merging of GitHub Pull +Requests is under the purview of Maintainers. For minor changes (i.e., +typo fixes or the addition / correction of sentences in the +Documentation), a single Maintainer may approve a Pull Request if +they're confident others would agree. For any changes that are not minor +(i.e., code changes, major Documentation changes), approval from at +least two Maintainers is needed before a Pull Request is merged. +Contributors work with the maintainers to resolve comments on a Pull +Request. A pull request can be merged when there are no remaining +objections among the Maintainers. In cases where a resolution cannot be +easily reached, the pull request is tabled for further discussion at the +Strategic Planning meeting and a determination is made by consensus +amongst the Council members and maintainers. + +Virtual "Strategic Planning Meetings" are held weekly between the +Steering Council and the Maintainers to facilitate discussion and to +provide guidance on specific decisions related to the project. Any Pull +Requests that do not reach consensus on GitHub are to be raised at the +Strategic Planning meetings so that the Developer Council members can +arrive at a consensus on the direction that should be taken. Strategic +Planning Meetings also provide an opportunity for Maintainers and +Developer Council members to share updates, discuss future directions, +and address logistic matters related to the project. Decisions on any +and all matters raised at the Strategic Planning Meetings follow the +consensus-seeking approach outlined above. + +## Governance Model Changes + +The Project Governance document will be reviewed at least once yearly by +the Developer Council. Changes will be made to the document by majority +vote of the Developer Council. The document may also be revisited and +updated at any time between yearly reviews as deemed necessary by the +Developer Council. Contributors and Maintainers may recommend changes to +the document by opening a Draft Pull Request at any time. Any suggested +changes will be reviewed and voted upon by the Council. diff --git a/doc/governance.rst b/doc/governance.rst deleted file mode 100644 index b0725e6cb..000000000 --- a/doc/governance.rst +++ /dev/null @@ -1,64 +0,0 @@ -.. _governance: - -Project Governance ------------------- -The purpose of this document is to formalize the governance process used by the Human Neocortical Neurosolver (HNN) project and to clarify how decisions are made and how the various elements of our community interact. - -Mission -======= -HNN is an open source software project. The goal of HNN is to develop a hypothesis testing tool for researchers, with the software built upon a biophysically-principled neocortical circuit model with appropriate physics that allow bridging from macroscale human magneto- and electro-encephalography (M/EEG) signals to their cellular and circuit level generators. - -The foundations of the project governance are: - -* Openness and transparency -* Active contribution -* Institutional neutrality - -The HNN project aims to support a collaborative community of developers, where any individual may contribute to the project and have their contributions acknowledged and reflected in the project’s GitHub repository. HNN is developed by researchers with diverse skill sets: scientific, software, MEG, neuro etc. The governance model is made keeping in mind that contributions from these diverse sub-communities will be necessary to advance HNN. - -We invite anyone with an interest in the project to join the community, contribute to the project design, and participate in the decision making process. In line with this philosophy, we provide a pathway for project Contributors* to become project Maintainers**, allowing for a deeper level of engagement with the development and decision making processes of the project. We want to encourage a diverse array of backgrounds, viewpoints, and talents in our team. Towards this end, contributions are not limited to changes to the codebase, but can involve updates to the documentation, proposals of biologically relevant features, and participation in online discussions, among other activities that advance the mission of the project. - -Roles and Responsibilities -========================== -We distinguish between Contributors, Maintainers, and the Steering Council as outlined in the following sections. - -Contributors\ :sup:`*` -~~~~~~~~~~~~ -Contributors are community members who contribute in concrete ways to the project. Anyone can become a contributor, and contributions can take many forms, as detailed in HNN’s Contributions page in the HNN-core documentation. Contributors participate in the project by submitting, reviewing, and discussing GitHub Pull Requests and Issues and by participating in open discussions on GitHub and via other channels including but not limited to the weekly project meetings, email, and hackathon events. Contributors work on behalf of and are responsible to the larger HNN Community, and we strive to keep the barrier between Contributors and Users as low as possible. - -Maintainers\ :sup:`**` -~~~~~~~~~~~ -Maintainers are community members who have shown that they are dedicated to the continued development of the project through ongoing engagement with the community. Being a Maintainer allows contributors to more easily contribute to the project by giving them “commit rights” to the project repositories. Maintainers are expected to review code contributions, merge approved pull requests, and to be involved in deciding major changes to the API. Maintainers are invited to join weekly Develop Council meetings hosted virtually. - -Maintainers are determined by the Steering Council based on their level of engagement and their contributions to the project. Contributors who have produced contributions that are substantial in quality and quantity may be eligible for Maintainer status. Maintainers will be elected by consensus among members of the Steering Council. Under extenuating circumstances, Maintainer status may be revoked by the Steering Council by consensus. - -Maintainer status is dependent on continued engagement with the project. If a Maintainer becomes inactive for a period greater than 1 year, “commit rights” to the project’s repository will be revoked. Maintainer status can be reinstated for any Contributor if they resume engagement with the project and produce substantial contributions. - -Developer Council -~~~~~~~~~~~~~~~~~ -The Developer Council is composed of individuals who take on additional responsibilities to ensure the smooth operation of the project. Membership in the Developer Council is by nomination from a current Developer Council member. The Developer Council will include at least 2 maintainers at all times. A nomination will result in discussion and then a vote by the Developer Council members. Developer Council membership votes are subject to a two-third majority. - -The Developer Council and its members are expected to participate in strategic planning to guide the overall direction of the project. While the Developer Council is the final authority for guiding the code review process and merging pull requests, not all Develop Council members need to contribute code to the project on a regular basis. Members may be nominated to the Developer Council based on the quality and quantity of their contributions to any and all aspects of the project, including their expertise and efforts in advancing the project mission as outlined above. - -Responsibilities of the Developer Council include: - -* Attend virtual meetings on a regular basis or as deemed appropriate -* Make decisions about the overall scope, vision, and direction of the project. -* Make decisions about strategic collaborations with other organizations or individuals. -* Make decisions about specific technical issues, features, bugs, and pull requests when appropriate -* Make decisions about the services that are run by the project and manage those services for the benefit of the community -* Update policy documents, such the Project Governance - -If a member becomes inactive in the project for a period of one year, they will be considered for removal from the Developer Council. Before removal, the inactive member will be approached to inquire if they plan to return to active participation. If not, they will be removed upon a Developer Council vote. If the inactive member plans on returning to active participation, they can be granted a grace period as determined by the Developer Council. All former Developer Council Members can be considered for membership again at any time in the future. Retired Developer Council Members will be listed on the project website. - -Decision-Making Process -======================= -Decisions related to the project are made through consensus among the Maintainers and the Developer Council, with input from the community and Contributors. Final authority over key decisions related to the overall scope, vision, and direction of the project lies solely with the Developer Council. For contributions to the project repositories, HNN uses a “consensus-seeking” process for making decisions. Any contributions must follow the processes outlined in the Contributions page of the HNN-core documentation. - -As outlined in Roles and Responsibilities, the merging of GitHub Pull Requests is under the purview of Maintainers. For minor changes (i.e., typo fixes or the addition / correction of sentences in the Documentation), a single Maintainer may approve a Pull Request if they’re confident others would agree. For any changes that are not minor (i.e., code changes, major Documentation changes), approval from at least two Maintainers is needed before a Pull Request is merged. Contributors work with the maintainers to resolve comments on a Pull Request. A pull request can be merged when there are no remaining objections among the Maintainers. In cases where a resolution cannot be easily reached, the pull request is tabled for further discussion at the Strategic Planning meeting and a determination is made by consensus amongst the Council members and maintainers. - -Virtual “Strategic Planning Meetings” are held weekly between the Steering Council and the Maintainers to facilitate discussion and to provide guidance on specific decisions related to the project. Any Pull Requests that do not reach consensus on GitHub are to be raised at the Strategic Planning meetings so that the Developer Council members can arrive at a consensus on the direction that should be taken. Strategic Planning Meetings also provide an opportunity for Maintainers and Developer Council members to share updates, discuss future directions, and address logistic matters related to the project. Decisions on any and all matters raised at the Strategic Planning Meetings follow the consensus-seeking approach outlined above. - -Governance Model Changes -======================== -The Project Governance document will be reviewed at least once yearly by the Developer Council. Changes will be made to the document by majority vote of the Developer Council. The document may also be revisited and updated at any time between yearly reviews as deemed necessary by the Developer Council. Contributors and Maintainers may recommend changes to the document by opening a Draft Pull Request at any time. Any suggested changes will be reviewed and voted upon by the Council. diff --git a/doc/index.md b/doc/index.md new file mode 100644 index 000000000..07a75561a --- /dev/null +++ b/doc/index.md @@ -0,0 +1,15 @@ + + +```{toctree} +:hidden: + +Examples +API +glossary +whats_new +Contributing +``` + +```{include} ../README.md + +``` diff --git a/doc/index.rst b/doc/index.rst deleted file mode 100644 index 72a335581..000000000 --- a/doc/index.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../README.rst diff --git a/doc/parallel.md b/doc/parallel.md new file mode 100644 index 000000000..d594b5e6d --- /dev/null +++ b/doc/parallel.md @@ -0,0 +1,138 @@ +(parallel)= +# Parallel backends + +Two options are available for making use of multiple CPU cores. The +first runs multiple trials in parallel with joblib. Alternatively, you +can run each trial across multiple cores to reduce the runtime. + +## Joblib + +This is the default backend and will execute multiple trials at the same +time, with each trial running on a separate core in "embarrassingly +parallel" execution. Note that with only 1 trial, there will be no +parallelism. + +**Dependencies**: + + $ pip install joblib + +**Usage**: + +``` +from hnn_core import JoblibBackend + +# set n_jobs to the number of trials to run in parallel with Joblib (up to number of cores on system) +with JoblibBackend(n_jobs=2): + dpls = simulate_dipole(net, n_trials=2) +``` + +## MPI + +This backend will use MPI (Message Passing Interface) on the system to +split neurons across CPU cores (processors) and reduce the simulation +time as more cores are used. + +**Linux Dependencies**: + + $ sudo apt-get install libopenmpi-dev openmpi-bin + $ pip install mpi4py psutil + +**MacOS Dependencies**: + + $ conda install -y openmpi mpi4py + $ pip install psutil + +**MacOS Environment**: + + $ export DYLD_FALLBACK_LIBRARY_PATH=${CONDA_PREFIX}/lib + +Altpernatively, run the commands below will avoid needing to run the +export command every time a new shell is opened: + + $ cd ${CONDA_PREFIX} + $ mkdir -p etc/conda/activate.d etc/conda/deactivate.d + $ echo "export OLD_DYLD_FALLBACK_LIBRARY_PATH=\$DYLD_FALLBACK_LIBRARY_PATH" >> etc/conda/activate.d/env_vars.sh + $ echo "export DYLD_FALLBACK_LIBRARY_PATH=\$DYLD_FALLBACK_LIBRARY_PATH:\${CONDA_PREFIX}/lib" >> etc/conda/activate.d/env_vars.sh + $ echo "export DYLD_FALLBACK_LIBRARY_PATH=\$OLD_DYLD_FALLBACK_LIBRARY_PATH" >> etc/conda/deactivate.d/env_vars.sh + $ echo "unset OLD_DYLD_FALLBACK_LIBRARY_PATH" >> etc/conda/deactivate.d/env_vars.sh + +**Test MPI**: + + $ mpiexec -np 2 nrniv -mpi -python -c 'from neuron import h; from mpi4py import MPI; \ + print(f"Hello from proc {MPI.COMM_WORLD.Get_rank()}"); \ + h.quit()' + numprocs=2 + NEURON -- VERSION 7.7.2 7.7 (2b7985ba) 2019-06-20 + Duke, Yale, and the BlueBrain Project -- Copyright 1984-2018 + See http://neuron.yale.edu/neuron/credits + + Hello from proc 0 + Hello from proc 1 + + +Verifies that MPI, NEURON, and Python are all working together. + +**Usage**: + +``` +from hnn_core import MPIBackend + +# Set n_procs to the number of processors MPI can use (up to number of cores on system) +# A different launch command can be specified for MPI distributions other than openmpi +with MPIBackend(n_procs=2, mpi_cmd='mpiexec'): + dpls = simulate_dipole(net, n_trials=1) +``` + +**Notes for contributors**: + +MPI parallelization with NEURON requires that the simulation be launched +with the `nrniv` binary from the command-line. The `mpiexec` command is +used to launch multiple `nrniv` processes which communicate via MPI. +This is done using `subprocess.Popen()` in `MPIBackend.simulate()` to +launch parallel child processes (`MPISimulation`) to carry out the +simulation. The communication sequence between `MPIBackend` and +`MPISimulation` is outlined below. + +1. In order to pass the network to simulate from `MPIBackend`, the + child `MPISimulation` processes' `stdin` is used. The ready-to-use + {class}`~hnn_core.Network` object is base64 encoded and pickled before + being written to the child processes' `stdin` by way of a Queue in + a non-blocking way. See how it is [used in MNE-Python][]. + The data is marked by start and end signals that are used to extract + the pickled net object. After being unpickled, the parallel + simulation begins. +2. Output from the simulation (either to `stdout` or `stderr`) is + communicated back to `MPIBackend`, where it will be printed to the + console. Typical output at this point would be simulation progress + messages as well as any MPI warnings/errors during the simulation. +3. Once the simulation has completed, the rank 0 of the child process + sends back the simulation data by base64 encoding and and pickling + the data object. It also adds markings for the start and end of the + encoded data, including the expected length of data (in bytes) in + the end of data marking. Finally rank 0 writes the whole string with + markings and encoded data to `stderr`. +4. `MPIBackend` will look for these markings to know that data is being + sent (and will not print this). It will verify the length of data it + receives, printing a `UserWarning` if the data length received + doesn't match the length part of the marking. +5. To signal that the child process should terminate, `MPIBackend` + sends a signal to the child proccesses' `stdin`. After sending the + simulation data, rank 0 waits for this completion signal before + continuing and letting all ranks of the MPI process exit + successfully. +6. At this point, `MPIBackend.simulate()` decodes and unpickles the + data, populates the network's CellResponse object, and returns the + simulation dipoles to the caller. + +It is important that `flush()` is used whenever data is written to stdin +or stderr to ensure that the signal will immediately be available for +reading by the other side. + +Tests for parallel backends utilize a special `@pytest.mark.incremental` +decorator (defined in `conftest.py`) that causes a test failure to skip +subsequent tests in the incremental block. For example, if a test +running a simple MPI simulation fails, subsequent tests that compare +simulation output between different backends will be skipped. These +types of failures will be marked as a failure in CI. + +[used in MNE-Python]: https://github.com/mne-tools/mne-python/blob/148de1661d5e43cc88d62e27731ce44e78892951/mne/utils/misc.py#L124-L132 diff --git a/doc/parallel.rst b/doc/parallel.rst deleted file mode 100644 index 32034225f..000000000 --- a/doc/parallel.rst +++ /dev/null @@ -1,111 +0,0 @@ -.. _parallel: - -Parallel backends -================= - -Two options are available for making use of multiple CPU cores. The first runs multiple trials in parallel with joblib. Alternatively, you can run each trial across multiple cores to reduce the runtime. - -Joblib ------- - -This is the default backend and will execute multiple trials at the same time, with each trial running on a separate core in "embarrassingly parallel" execution. Note that with only 1 trial, there will be no parallelism. - -**Dependencies**:: - - $ pip install joblib - -**Usage**:: - - from hnn_core import JoblibBackend - - # set n_jobs to the number of trials to run in parallel with Joblib (up to number of cores on system) - with JoblibBackend(n_jobs=2): - dpls = simulate_dipole(net, n_trials=2) - -MPI ---- - -This backend will use MPI (Message Passing Interface) on the system to split neurons across CPU cores (processors) and reduce the simulation time as more cores are used. - -**Linux Dependencies**:: - - $ sudo apt-get install libopenmpi-dev openmpi-bin - $ pip install mpi4py psutil - -**MacOS Dependencies**:: - - $ conda install -y openmpi mpi4py - $ pip install psutil - -**MacOS Environment**:: - - $ export DYLD_FALLBACK_LIBRARY_PATH=${CONDA_PREFIX}/lib - -Alternatively, run the commands below will avoid needing to run the export command every time a new shell is opened:: - - $ cd ${CONDA_PREFIX} - $ mkdir -p etc/conda/activate.d etc/conda/deactivate.d - $ echo "export OLD_DYLD_FALLBACK_LIBRARY_PATH=\$DYLD_FALLBACK_LIBRARY_PATH" >> etc/conda/activate.d/env_vars.sh - $ echo "export DYLD_FALLBACK_LIBRARY_PATH=\$DYLD_FALLBACK_LIBRARY_PATH:\${CONDA_PREFIX}/lib" >> etc/conda/activate.d/env_vars.sh - $ echo "export DYLD_FALLBACK_LIBRARY_PATH=\$OLD_DYLD_FALLBACK_LIBRARY_PATH" >> etc/conda/deactivate.d/env_vars.sh - $ echo "unset OLD_DYLD_FALLBACK_LIBRARY_PATH" >> etc/conda/deactivate.d/env_vars.sh - -**Test MPI**:: - - $ mpiexec -np 2 nrniv -mpi -python -c 'from neuron import h; from mpi4py import MPI; \ - print(f"Hello from proc {MPI.COMM_WORLD.Get_rank()}"); \ - h.quit()' - numprocs=2 - NEURON -- VERSION 7.7.2 7.7 (2b7985ba) 2019-06-20 - Duke, Yale, and the BlueBrain Project -- Copyright 1984-2018 - See http://neuron.yale.edu/neuron/credits - - Hello from proc 0 - Hello from proc 1 - -Verifies that MPI, NEURON, and Python are all working together. - -**Usage**:: - - from hnn_core import MPIBackend - - # Set n_procs to the number of processors MPI can use (up to number of cores on system) - # A different launch command can be specified for MPI distributions other than openmpi - with MPIBackend(n_procs=2, mpi_cmd='mpiexec'): - dpls = simulate_dipole(net, n_trials=1) - -**Notes for contributors**: - -MPI parallelization with NEURON requires that the simulation be launched with the ``nrniv`` binary -from the command-line. The ``mpiexec`` command is used to launch multiple ``nrniv`` processes which -communicate via MPI. This is done using ``subprocess.Popen()`` in ``MPIBackend.simulate()`` to -launch parallel child processes (``MPISimulation``) to carry out the simulation. -The communication sequence between ``MPIBackend`` and ``MPISimulation`` is outlined below. - -#. In order to pass the network to simulate from ``MPIBackend``, the child ``MPISimulation`` - processes' ``stdin`` is used. The ready-to-use `Network` object is base64 encoded and pickled - before being written to the child processes' ``stdin`` by way of a Queue in a non-blocking way. - See how it is `used in MNE-Python`_. The data is marked by start and end signals that are used - to extract the pickled net object. After being unpickled, the parallel simulation begins. -#. Output from the simulation (either to ``stdout`` or ``stderr``) is communicated back - to ``MPIBackend``, where it will be printed to the console. Typical output at this point - would be simulation progress messages as well as any MPI warnings/errors during the simulation. -#. Once the simulation has completed, the rank 0 of the child process sends back the simulation data - by base64 encoding and and pickling the data object. It also adds markings for the start and end - of the encoded data, including the expected length of data (in bytes) in the end of data marking. - Finally rank 0 writes the whole string with markings and encoded data to ``stderr``. -#. ``MPIBackend`` will look for these markings to know that data is being sent (and will not - print this). It will verify the length of data it receives, printing a - ``UserWarning`` if the data length received doesn't match the length part of the marking. -#. To signal that the child process should terminate, ``MPIBackend`` sends a signal to the child - proccesses' ``stdin``. After sending the simulation data, rank 0 waits for this completion signal - before continuing and letting all ranks of the MPI process exit successfully. -#. At this point, ``MPIBackend.simulate()`` decodes and unpickles the data, populates the network's - CellResponse object, and returns the simulation dipoles to the caller. - - -It is important that ``flush()`` is used whenever data is written to stdin or stderr to ensure that the signal will immediately be available for reading by the other side. - -Tests for parallel backends utilize a special ``@pytest.mark.incremental`` decorator (defined in ``conftest.py``) that causes a test failure to skip subsequent tests in the incremental block. For example, if a test running a simple MPI simulation fails, subsequent tests that compare simulation output between different backends will be skipped. These types of failures will be marked as a failure in CI. - -.. _used in MNE-Python: https://github.com/mne-tools/mne-python/blob/148de1661d5e43cc88d62e27731ce44e78892951/mne/utils/misc.py#L124-L132 diff --git a/doc/roadmap.md b/doc/roadmap.md new file mode 100644 index 000000000..f50c229c3 --- /dev/null +++ b/doc/roadmap.md @@ -0,0 +1,279 @@ +(roadmap)= +# The HNN Roadmap + +## Project Vision + +HNN was created as a resource for the MEG/EEG community to develop and +test hypotheses on the neural origin of their human data. The foundation +of HNN is a detailed cortical column model containing generalizable +features of cortical circuitry, including layer specific synaptic drive +from exogenous thalamic and cortical sources, that simulates a primary +current dipole from a single localized brain area. In addition to +calculating the primary current source in units that are directly +comparable to source localized data (Ampere-meters, Am), the details in +HNN enable interpretation of multi-scale activity including layer +specific and individual cell activity. HNN was designed based on +workflows to simulate the most commonly measured signals, including ERPs +and low frequency brain rhythms based on [prior studies][]. + +A main goal of HNN is to create a user-friendly interactive interface +and tutorials to teach to the MEG/EEG community how to interact with the +model to study the neural origin of these signals, without needing to +access the underlying complex neural modeling code. To this end, HNN was +constructed with a graphical user interface (GUI) and corresponding +tutorials of use for commonly measured signals, which are distributed on +the HNN website (). Our philosophy is that the +interactive GUI is essential for all new users of HNN to develop an +intuition on how to interact with the large-scale computational model to +study the multi-scale neural dynamics underlying their MEG/EEG data. +Once this intuition is gained, users who chose to can dive into the +computational neural modeling code, where further command line utily can +be developed. As such, an equal goal is to enable the neural modeling +and coding community to participate in HNN development. We are +prioritizing best practices in open-source software design and the +development of a documented API for interoperability and to facilitate +integration with other relevant open-source platforms (e.g. MNE-Python, +NetPyNE). Our vision is to create a unique transformational software +specific to interpreting the neural origin of MEG/EEG. + +## Timeline Overview + +This roadmap timeline outlines the major short-term and longer-term +goals for HNNs. The short term goals will entail a substantial +reorganization of the HNN code and creation of an API to facilitate HNN +expansions, community contribution, and integration with other relevant +open-source platforms (e.g. MNE-Python, NetPyNE). To this end, in March +2021, we released the first version of the HNN-core repository. HNN-core +contains improved versions of HNN's non-GUI components following best +practices in open-source software design, with unit testing and +continuous integration, along with initial API and documentation for +command-line coding. We will adopt similar best practices to develop a +new HNN-GUI and several new HNN features, including the ability to +simulate and visualize LFP/CSD and to use improved parameter estimation +procedures. Our process will be to develop all new features in HNN-core, +with API and examples of use followed, when applicable, by integration +into the HNN-GUI with corresponding GUI-based tutorials on our website. +Longer-term goals include integration with the related modeling software +MNE-Python and NetPyNe, the development of a web-based interface with +ability for simultaneous GUI and Command Line Interface (CLI), and +extension to multi-area simulations. + +## Short-Term Goals + +## Modularize HNN code to simplify installation, development and maintenance + +We are working on cleaning up and re-organizing the underlying code that +defines the current distribution of HNN to facilitate expansion and +community engagement in its use and development. To minimize the +dependencies that are required to install before contributing to HNN +development and maintenance, all of the non-GUI components of HNN's code +are being organized into a new repository HNN-core (initial release +March 2021). This reorganization will entail continued improvements +within the HNN-core repository, along with API development and examples +of use, in the following steps: + +- Following best practices in open-source software design, including + continuous integration testing, to develop HNN-core. HNN-core will + contain clean and reorganized code, and separate all components that + interact directly with the NEURON simulator (e.g. cell and network + instantiation, external drives, etc..), from those that pertain to + post-processing data analysis and plotting functions (e.g. spectra + lanalysis). **COMPLETED FEB 2021** +- Convert installation procedures to PIP. **COMPLETED FEB 2021** +- Parallelization of the simulations in HNN-core via MPI or Joblib. + **COMPLETED SEP 2020** +- Reorganization of the Network class within HNN-core module to + separate cortical column model from exogenous drive, and + optimization routines. See {gh}`104`, {gh}`124`, and {gh}`129` + for related discussions. **COMPLETED FEB 2021** +- Reorganization of the Network class within HNN-core module to + separate cortical column model from exogenous drive, and + optimization routines. See + {gh}`104`, {gh}`124`, and {gh}`129` + for related discussions. **COMPLETED FEB 2021** +- Develop initial HNN-core documentation and example simulations + following those detailed in the HNN-GUI tutorials + . + **COMPLETED MARCH 2021** +- First release of HNN-Core 0.1 to the community **COMPLETED MARCH + 2021** +- Make HNN-Core compatible for windows including installation, testing + and continuous integration. +- Reorganization of Param.py file within HNN-core to multiple files + that contain smaller dictionaries of parameters related to different + modules of the code. See {gh}`104` for related discussions. +- Expand details in HNN-core examples to follow HNN-GUI based + tutorials. + +## Develop a New HNN GUI + +A new HNN-GUI will be developed following similar best-practices in open +source software design, as employed in HNN-core. The first step will be +to ensure all of the functionality of the current GUI distribution is +developed in HNN-Core, followed by integration into a new HNN-GUI, with +corresponding GUI-based tutorials on the HNN website. Once complete, the +current HNN-GUI repository will be deprecated. + +- Development of optimization routines in HNN-core that have the + current functionality in HNN-GUI. +- Develop a new HNN-GUI using ipywidgets in HNN-core that has all of + the functionality of the current HNN-GUI. +- Rename HNN to HNN-GUI and release updated version to the community + and deprecate original HNN repository. + +## LFP/CSD Simulation, Visualization and Data Comparison + +Essential to testing circuit-level predictions developed in HNN is the +ability to test the predictions with invasive recordings in animals or +humans. The most fundamental domain over which the predictions will be +tested is local field potential (LFP) recordings across the cortical +layers and the associated current source density (CSD) profiles. We will +develop a method to simulate and visualize LFP/CSD across the cortical +layers and to statistically compare model simulations to recorded data. +These components will be developed in HNN-core, with corresponding API +and examples of use, followed by integration into the HNN-GUI, with +corresponding GUI based tutorials on the HNN website, in the following +steps: + +- Develop code in HNN-core to simulate and visualize LFP/CSD from + cellular membrane potentials. +- Develop code in HNN-core to statistically compare and visualize + model LFP/CSD to invasive animal data. +- Develop functions in HNN-GUI to enable simulation, visualization and + data comparison in the GUI. + +## Parameter Estimation Expansion + +Parameter estimation is an inherent difficulty in neural model +simulation. HNN currently enables some parameter estimation, focussing +on parameters relevant to an ERP. New methods have been recently +developed that apply a machine learning approach to parameter +estimation, namely Sequential Neural Parameter Estimation (SNPE) +(Gonçalves et al Elife 2020: DOI: 10.7554/eLife.56261). We will adapt +this method for parameter estimation to work with HNN-core, enabling +estimation of a distribution of parameters that could account for +empirical data, and then integrate it into the HNN-GUI, with GUI-based +tutorials, in the following steps: + +- Extending HNN-core to run batch simulations that enable parameter + sweeps. +- Development of functions in HNN-GUI to enable parameter sweeps via + the GUI. +- Develop code for SNPE parameter estimation and visualization in + HNN-core. +- Develop functions in HNN-GUI to enable SNPE estimation in the GUI. + +## Different Cortical Model Template Choices + +HNN is distributed with a cortical column model template that represents +generalizable features of cortical circuitry based on [prior studies][]. +Updates to this model are being made by the HNN team, including a model +with alternate pyramidal neuron calcium dynamics, and an updated +inhibitory connectivity architecture. We will expand HNN-core to enable +a choice of template models, beginning with those developed by the HNN +team and ultimately expanding to model development in other platforms +(e.g. NetPyNE), see Longer-Term goals. These models will first be +developed in HNN-core, with corresponding API and examples of use, +followed by integration into HNN-GUI, with GUI-based tutorials. + +- Develop new cortical column template models with pyramidal neuron + calcium dynamics, in HNN-core. +- Create flexibility to change local connectivity and to visualize + connectivity in HNN-core. +- Create flexibility to change exogenous connectivity and to visualize + connectivity in HHN-core. +- Develop functionality in HNN-GUI to chose amng different template + models. +- Develop function in HNN-GUI to choose among different template + models in the GUI. + +See {gh}`111` for more discussions. + +## API and Tutorial development + +The ability to interpret the neural origin of macroscale MEG/EEG signals +in a complex high-dimensional non-linear computational neural model is +challenging. A primary goal of HNN is to facilitate this interpretation +with a clear API and examples of use in HNN-core, and interactive +GUI-based tutorials for all HNN-GUI functionality on our HNN website. +Following the process for creating new features in HNN, the process for +documenting new features will be to first develop them with API and +examples of use in HNN-core, followed by integration into the HNN-GUI, +with corresponding GUI-based tutorials on the HNN-website. Developmental +goals are only complete once the corresponding documentation is +available. + +## Longer-Term Goals + +**Develop a framework to import cortical column models developed in +NetPyNE or other modeling platforms into HNN:** The core of HNN is a +cortical column model that simulates macroscale current dipoles. +Currently, HNN is distributed with a template cortical column model +based on generalizable features of cortical circuitry and as applied in +[prior studies][]. +Essential to future expansion of HNN is the ability to use other +cortical column models that include different cell types and or +different network features. We have begun creation of a framework where +models built in NetPyNE can be adapted to the HNN workflows of use. As a +test bed, this currently entails integration of the HNN cortical column +model and exogenous drives into the full NetPyNE platform +(). See also +update from **MARCH 2021** + . + +To limit the scope of this effort to HNN-specific goals, i.e. neural +modeling designed for interpretation of human EEG/MEG signals, we will +work with NetPyNE team to develop clean modularized framework for +integrating NetPyNe developed cortical models that have laminar +structure and multicompartment pyramidal neurons into HNN design and +workflows of use to simulate ERPs and low frequency brain rhythms work. + +**Integrate HNN and MNE-Python tools:** We will work to create a +framework where source localization using MNE-Python is seamlessly +integrated with HNN for circuit-level interpretation of the signal. We +will develop workflows that enable users starting with sensor level +signals to perform both source localization using MNE-Python and circuit +interpretation using HNN-core. We begin with use open-source median +nerve datasets and develop examples using three different inverse +methods (Dipole, MNE, Beamformer). + +- Develop test-case example using open-source median nerve data of how + to go from sensor space data to source localized signal using + MNE-Python, and then simulate the neural mechanisms of the source + signal using HNN-core. + + **COMPLETED MARCH 2021 - note still needs documentation** + +**Convert HNN to web-based platform with dual GUI and Command Line +Interface (CLI):** We have begun working with MetaCell (metacell.org) to +convert HNN to a web-based interactive GUI with updated graphics +(). This conversion will eliminate +the installation process and enhance computational efficiency. +Additionally, MetaCell is facilitating the transformation to a dual GUI +and CLI interface enabled through Jupyter notebooks. There are +advantages to both GUI and CLI in adapting HNN to user goals. GUIs +provide a framework for teaching the community the workflow to use such +models to study the biophysical origin of MEG/EEG signals, like ERPs and +brain rhythms. Once a meaningful parameter set is identified to account +for the data of one subject, CLI scripts can be useful to investigate +how well this parameter set accounts for the data from multiple subjects +or how parameter changes impact the signal. CLIs can be used to generate +sequences of processing steps that can then be applied to multiple data +sets, ensuring rigor and reproducibility. Further, simultaneous viewing +of GUI and CLI can help advanced users quickly adapt the code with +scripting, and ultimately help create a community of HNN software +developers. This framework will also facilitate the integration with +other open-source platforms, including MNE-Python and NetPyNE. + +**Expand HNN to include study of multi-area interactions:** HNN is +designed for detailed multi-scale interpretation of the neural origin of +macroscale current dipoles signals from a single brain area. A long term +vision is to create a framework where multi-area interactions can be +studied. We will begin with simulations of the interactions between +sensory and motor cortices during median nerve stimulation. + +**Footnotes** + +[^1]: We do not claim all the neural mechanisms of these signals are completely understood, rather that there is a baseline of knowledge to build from and that HNN provides a framework for further investigation. + +[prior studies]: https://hnn.brown.edu/index.php/publications/ diff --git a/doc/roadmap.rst b/doc/roadmap.rst deleted file mode 100644 index f3146c825..000000000 --- a/doc/roadmap.rst +++ /dev/null @@ -1,235 +0,0 @@ -The HNN Roadmap -=============== - -Project Vision --------------- -HNN was created as a resource for the MEG/EEG community to develop and -test hypotheses on the neural origin of their human data. The foundation of -HNN is a detailed cortical column model containing generalizable features of -cortical circuitry, including layer specific synaptic drive from exogenous thalamic -and cortical sources, that simulates a primary current dipole from a single -localized brain area. In addition to calculating the primary current source in -units that are directly comparable to source localized data (Ampere-meters, Am), -the details in -HNN enable interpretation of multi-scale activity including layer specific and -individual cell activity. HNN was designed based on workflows to simulate the most -commonly measured signals, including ERPs and low frequency brain rhythms based on -`prior studies`_. - -A main goal of HNN is to create a user-friendly interactive interface and -tutorials to teach to the MEG/EEG community how to interact with the model to -study the neural origin of these signals, without needing to access the -underlying complex neural modeling code. To this end, HNN was constructed with a -graphical user interface (GUI) and corresponding tutorials of use for commonly measured signals, -which are distributed on the HNN website (https://hnn.brown.edu). -Our philosophy is that the interactive GUI is essential for all new users of HNN to develop an intuition -on how to interact with the large-scale computational model to study the multi-scale neural dynamics underlying -their MEG/EEG data. Once this intuition is gained, users who chose to can dive into the computational neural -modeling code, where further command line utily can be developed. As such, an equal goal is to enable the neural -modeling and coding community to participate in HNN development. We are prioritizing -best practices in open-source software design and the development of a documented API -for interoperability and to facilitate integration with other relevant open-source -platforms (e.g. MNE-Python, NetPyNE). Our vision is to create a unique -transformational software specific to interpreting the neural origin of MEG/EEG. - -Timeline Overview ------------------ -This roadmap timeline outlines the major short-term and longer-term -goals for HNNs. The short term goals will entail a substantial reorganization of the -HNN code and creation of an API to facilitate HNN expansions, community contribution, -and integration with other relevant open-source platforms (e.g. MNE-Python, NetPyNE). To this end, in March 2021, we released the first version of the HNN-core repository. HNN-core contains improved versions of HNN’s non-GUI components following best practices in open-source software design, with unit testing and continuous integration, along with initial API and documentation for command-line coding. We will adopt similar best practices to develop a new HNN-GUI and several new HNN features, including the ability to simulate and visualize LFP/CSD and to use improved parameter estimation procedures. Our process will be to develop all new features in HNN-core, with API and examples of use followed, when applicable, by integration into the HNN-GUI with corresponding GUI-based tutorials on our website. Longer-term goals include integration with the related modeling software MNE-Python and NetPyNe, the development of a web-based interface with ability for simultaneous GUI and Command Line Interface (CLI), and extension to multi-area simulations. - -Short-Term Goals --------------------------- - -Modularize HNN code to simplify installation, development and maintenance -------------------------------------------------------------------------- - -We are working on cleaning up and re-organizing the -underlying code that defines the current distribution of HNN to facilitate -expansion and community engagement in its use and development. To minimize the -dependencies that are required to install before contributing to HNN development -and maintenance, all of the non-GUI components of HNN’s code are being organized into a new repository HNN-core (initial release March 2021). -This reorganization will entail continued improvements within the HNN-core repository, along with API development and examples of use, in the following steps: - -- Following best practices in open-source software design, including continuous integration testing, - to develop HNN-core. HNN-core will contain clean and reorganized code, and separate all components that - interact directly with the NEURON simulator (e.g. cell and network instantiation, external drives, etc..), - from those that pertain to post-processing data analysis and plotting functions (e.g. spectra lanalysis). - **COMPLETED FEB 2021** -- Convert installation procedures to PIP. **COMPLETED FEB 2021** -- Parallelization of the simulations in HNN-core via MPI or Joblib. **COMPLETED SEP 2020** -- Reorganization of the Network class within HNN-core module - to separate cortical column model from exogenous drive, and optimization routines. - See `gh-104`_, `gh-124`_, and `gh-129`_ for related discussions. - **COMPLETED FEB 2021** -- Develop initial HNN-core documentation and example simulations following those - detailed in the HNN-GUI tutorials https://jonescompneurolab.github.io/hnn-core/stable/index.html. - **COMPLETED MARCH 2021** -- First release of HNN-Core 0.1 to the community **COMPLETED MARCH 2021** -- Make HNN-Core compatible for windows including installation, testing and - continuous integration. -- Reorganization of Param.py file within HNN-core to multiple files that - contain smaller dictionaries of parameters related to different modules of the code. - See `gh-104`_ for related discussions. -- Expand details in HNN-core examples to follow HNN-GUI based tutorials. - - -Develop a New HNN GUI -------------------------------------------------------------------------- -A new HNN-GUI will be developed following similar best-practices in open source software design, as employed in HNN-core. -The first step will be to ensure all of the functionality of the current GUI distribution is developed in HNN-Core, followed by -integration into a new HNN-GUI, with corresponding GUI-based tutorials on the HNN website. Once complete, the current HNN-GUI repository will be deprecated. - -- Development of optimization routines in HNN-core that have the current functionality - in HNN-GUI. -- Develop a new HNN-GUI using ipywidgets in HNN-core that has all of the functionality - of the current HNN-GUI. -- Rename HNN to HNN-GUI and release updated version to the community and deprecate - original HNN repository. - - -LFP/CSD Simulation, Visualization and Data Comparison ------------------------------------------------------ - -Essential to testing circuit-level predictions developed in HNN is the ability to -test the predictions with invasive recordings in animals or humans. The most fundamental -domain over which the predictions will be tested is local field potential (LFP) recordings -across the cortical layers and the associated current source density (CSD) profiles. -We will develop a method to simulate and visualize LFP/CSD across the cortical layers -and to statistically compare model simulations to recorded data. These components will -be developed in HNN-core, with corresponding API and examples of use, followed by integration -into the HNN-GUI, with corresponding GUI based tutorials on the HNN website, in the following steps: - -- Develop code in HNN-core to simulate and visualize LFP/CSD from cellular - membrane potentials. -- Develop code in HNN-core to statistically compare and visualize model - LFP/CSD to invasive animal data. -- Develop functions in HNN-GUI to enable simulation, visualization and data comparison - in the GUI. - -Parameter Estimation Expansion ------------------------------- -Parameter estimation is an inherent difficulty in neural model simulation. -HNN currently enables some parameter estimation, focussing on parameters relevant -to an ERP. New methods have been recently developed that apply a machine learning -approach to parameter estimation, namely Sequential Neural Parameter Estimation (SNPE) -(Gonçalves et al Elife 2020: DOI: 10.7554/eLife.56261). We will adapt this method for parameter -estimation to work with HNN-core, enabling estimation of a distribution of parameters -that could account for empirical data, and then integrate it into the HNN-GUI, with -GUI-based tutorials, in the following steps: - -- Extending HNN-core to run batch simulations that enable parameter sweeps. -- Development of functions in HNN-GUI to enable parameter sweeps via the GUI. -- Develop code for SNPE parameter estimation and visualization in HNN-core. -- Develop functions in HNN-GUI to enable SNPE estimation in the GUI. - -Different Cortical Model Template Choices ------------------------------------------ -HNN is distributed with a cortical column model template that represents -generalizable features of cortical circuitry based on prior studies. Updates to -this model are being made by the HNN team, including a model with alternate pyramidal -neuron calcium dynamics, and an updated inhibitory connectivity architecture. We will -expand HNN-core to enable a choice of template models, beginning -with those developed by the HNN team and ultimately expanding to model development -in other platforms (e.g. NetPyNE), see Longer-Term goals. These models will first be -developed in HNN-core, with corresponding API and examples of use, followed by integration -into HNN-GUI, with GUI-based tutorials. - -- Develop new cortical column template models with pyramidal neuron - calcium dynamics, in HNN-core. -- Create flexibility to change local connectivity and to visualize connectivity in HNN-core. -- Create flexibility to change exogenous connectivity and to visualize connectivity in HHN-core. -- Develop functionality in HNN-GUI to chose amng different template models. -- Develop function in HNN-GUI to choose among different template models in the GUI. - -See `gh-111`_ for more discussions. - -API and Tutorial development ----------------------------- -The ability to interpret the neural origin of macroscale MEG/EEG signals in a -complex high-dimensional non-linear computational neural model is challenging. -A primary goal of HNN is to facilitate this interpretation with a clear API and examples -of use in HNN-core, and interactive GUI-based tutorials for all HNN-GUI functionality on our HNN website. -Following the process for creating new features in HNN, the process for documenting -new features will be to first develop them with API and examples of use in HNN-core, followed -by integration into the HNN-GUI, with corresponding GUI-based tutorials on the HNN-website. -Developmental goals are only complete once the corresponding documentation is available. - - -Longer-Term Goals ----------------------- - -**Develop a framework to import cortical column models developed in NetPyNE or -other modeling platforms into HNN:** -The core of HNN is a cortical column model -that simulates macroscale current dipoles. Currently, HNN is distributed with -a template cortical column model based on generalizable features of cortical -circuitry and as applied in `prior studies`_. -Essential to future expansion of HNN is the ability to use other cortical column -models that include different cell types and or different network features. -We have begun creation of a framework where models built in NetPyNE can be adapted -to the HNN workflows of use. As a test bed, this currently entails integration of -the HNN cortical column model and exogenous drives into the full NetPyNE -platform (https://github.com/jonescompneurolab/hnn/tree/netpyne). -See also update from **MARCH 2021** https://github.com/jonescompneurolab/hnn/tree/hnn2 . - -To limit the scope of this effort to HNN-specific goals, i.e. neural modeling -designed for interpretation of human EEG/MEG signals, we will work with NetPyNE team -to develop clean modularized framework for integrating NetPyNe developed cortical models -that have laminar structure and multicompartment pyramidal neurons into HNN design and workflows -of use to simulate ERPs and low frequency brain rhythms work. - -**Integrate HNN and MNE-Python tools:** We will work to create a framework where -source localization using MNE-Python is seamlessly integrated with HNN for -circuit-level interpretation of the signal. We will develop workflows that enable users -starting with sensor level signals to perform both source localization using MNE-Python -and circuit interpretation using HNN-core. We begin with use open-source median nerve -datasets and develop examples using three different inverse methods (Dipole, MNE, Beamformer). - -- Develop test-case example using open-source median nerve data of how to go from - sensor space data to source localized signal using MNE-Python, and then - simulate the neural mechanisms of the source signal using HNN-core. - https://jonescompneurolab.github.io/hnn-core/stable/auto_examples/index.html - **COMPLETED MARCH 2021 - note still needs documentation** - -**Convert HNN to web-based platform with dual GUI and Command Line Interface (CLI):** -We have begun working with MetaCell (metacell.org) to convert HNN to a web-based -interactive GUI with updated graphics (https://github.com/MetaCell/HNN-UI). -This conversion will eliminate the installation process and enhance computational -efficiency. Additionally, MetaCell is facilitating the transformation to a dual -GUI and CLI interface enabled through Jupyter notebooks. There are advantages to -both GUI and CLI in adapting HNN to user goals. GUIs provide a framework for -teaching the community the workflow to use such models to study the biophysical -origin of MEG/EEG signals, like ERPs and brain rhythms. Once a meaningful -parameter set is identified to account for the data of one subject, CLI scripts -can be useful to investigate how well this parameter set accounts for the data -from multiple subjects or how parameter changes impact the signal. CLIs can -be used to generate sequences of processing steps that can then be applied -to multiple data sets, ensuring rigor and reproducibility. Further, -simultaneous viewing of GUI and CLI can help advanced users quickly adapt the -code with scripting, and ultimately help create a community of HNN software -developers. This framework will also facilitate the integration with other -open-source platforms, including MNE-Python and NetPyNE. - -**Expand HNN to include study of multi-area interactions:** -HNN is designed for detailed multi-scale interpretation of the neural origin -of macroscale current dipoles signals from a single brain area. A long term vision -is to create a framework where multi-area interactions can be studied. We will -begin with simulations of the interactions between sensory and motor cortices -during median nerve stimulation. - -.. _prior studies: https://hnn.brown.edu/index.php/publications/ -.. _HNN-core: https://github.com/jonescompneurolab/hnn-core -.. _HNN: https://github.com/jonescompneurolab/hnn -.. _GUI tutorials: https://hnn.brown.edu/index.php/tutorials/ -.. _gh-104: https://github.com/jonescompneurolab/hnn-core/issues/104 -.. _gh-111: https://github.com/jonescompneurolab/hnn-core/issues/111 -.. _gh-124: https://github.com/jonescompneurolab/hnn-core/issues/129 -.. _gh-129: https://github.com/jonescompneurolab/hnn-core/issues/124 - -.. rubric:: Footnotes - -.. [#f1] We do not claim all the neural mechanisms of these signals are completely understood, - rather that there is a baseline of knowledge to build from and that HNN provides a - framework for further investigation. diff --git a/doc/whats_new.md b/doc/whats_new.md new file mode 100644 index 000000000..e40b4e7ce --- /dev/null +++ b/doc/whats_new.md @@ -0,0 +1,624 @@ +--- +orphan: true +--- + +(whats_new)= +# What's new? + +## Current + +### Changelog + +- Add button to delete a single drive on GUI drive windows, by + [George Dang][] in {gh}`890` + +- Add minimum spectral frequency widget to GUI for adjusting spectrogram + frequency axis, by [George Dang][] in {gh}`894` + +- Add method to {class}`~hnn_core.Network` to modify synaptic gains, by + [Nick Tolley][] and [George Dang][] in {gh}`897` + +- Update GUI to display "L2/3", by [Austin Soplata][] in {gh}`904` + +- Add argument to change colors of `plot_spikes_raster`, shortened line lengths + to prevent overlap, and added an argument for custom cell types, by + [George Dang][] in {gh}`895` + +### Bug + +- Fix GUI over-plotting of loaded data where the app stalled and did not plot + RMSE, by [George Dang][] in {gh}`869` + +- Fix scaling and smoothing of loaded data dipoles to the GUI, by [George Dang][] + in {gh}`892` + +### API + +- Add {func}`~hnn_core.CellResponse.spike_times_by_type` to get cell spiking times + organized by cell type, by [Mainak Jas][] in {gh}`916`. + +- Add option to apply a tonic bias to any compartment of the cell, and option to + add multiple biases per simulation and cell {func}`hnn_core.network.add_tonic_bias`, + by [Katharina Duecker][] in {gh}`922`. + +## 0.4 + +### Changelog + +- Fix bug in {func}`~hnn_core.Network.add_poisson_drive` where an error is + thrown when passing an int for rate_constant when ``cell_specific=True``, + by [Dylan Daniels][] in {gh}`818` + +- Fix bug in {func}`~hnn_core.Network.add_poisson_drive` where an error is + thrown when passing a float for rate_constant when ``cell_specific=False``, + by [Dylan Daniels][] in {gh}`814` + +- Add ability to customize plot colors for each cell section in + {func}`~hnn_core.Cell.plot_morphology`, by [Nick Tolley][] in {gh}`646` + +- Add ability to manually define colors in spike histogram plots, + by [Nick Tolley][] in {gh}`640` + +- Update minimum supported version of Python to 3.8, by [Ryan Thorpe][] in + {gh}`678`. + +- Update GUI to use ipywidgets v8.0.0+ API, by [George Dang][] in + {gh}`696`. + +- Add dependency groups to setup.py and update CI workflows to reference + dependency groups, by [George Dang][] in {gh}`703`. + +- Add ability to specify number of cells in {class}`~hnn_core.Network`, + by [Nick Tolley][] in {gh}`705` + +- Fixed figure annotation overlap in multiple sub-plots, + by [Camilo Diaz][] in {gh}`741` + +- Fix bug in {func}`~hnn_core.network.pick_connection` where connections are + returned for cases when there should be no valid matches, by [George Dang][] + in {gh}`739` + +- Added check for invalid Axes object in {func}`~hnn_core.viz.plot_cells` + function, by [Abdul Samad Siddiqui][] in {gh}`744`. + +- Added kwargs options to `plot_spikes_hist` for adjusting the histogram plots + of spiking activity, by [Abdul Samad Siddiqui][] in {gh}`732`. + +- Added pre defined plot sets for simulated data, + by [Camilo Diaz][] in {gh}`746` + +- Added gui widget to enable/disable synchronous input in simulations, + by [Camilo Diaz][] in {gh}`750` + +- Added gui widgets to save simulation as csv and updated the file upload to support csv data, + by [Camilo Diaz][] in {gh}`753` + +- Added feature to read/write {class}`~hnn_core.Network` configurations to + json, by [George Dang][] and [Rajat Partani][] in {gh}`757` + +- Added {class}`~hnn_core.viz.NetworkPlotter` to visualize and animate network simulations, + by [Nick Tolley][] in {gh}`649`. + +- Added GUI feature to include Tonic input drives in simulations, + by [Camilo Diaz][] {gh}`773` + +- {func}`~plot_lfp`, {func}`~plot_dipole`, {func}`~plot_spikes_hist`, + and {func}`~plot_spikes_raster` now plotted from 0 to tstop. Inputs tmin and tmax are deprecated, + by [Katharina Duecker][] in {gh}`769` + +- Add function {func}`~hnn_core.params.convert_to_json` to convert legacy param + and json files to new json format, by [George Dang][] in {gh}`772` + +- Add {class}`~hnn_core.BatchSimulate` for batch simulation capability, + by [Abdul Samad Siddiqui][] in {gh}`782`. + +- Updated `plot_spikes_raster` logic to include all neurons in network model. + Removed GUI exclusion from build, by [Abdul Samad Siddiqui][] in {gh}`754`. + +- Added GUI feature to read and modify cell parameters, + by [Camilo Diaz][] in {gh}`806`. + +- Add ability to optimize parameters associated with rhythmic drives, + by [Carolina Fernandez Pujol][] in {gh}`673`. + +- Added features to {func}`~plot_csd`: to set color of sinks and sources, range of the colormap, + and interpolation method to smoothen CSD plot, + by [Katharina Duecker][] in {gh}`815` + +- Cleaned up internal logic in {class}`~hnn_core.CellResponse`, + by [Nick Tolley][] in {gh}`647`. + +- Changed the configuration/parameter file format support of the GUI. Loading + of connectivity and drives use a new multi-level json structure that mirrors + the structure of the Network object. Flat parameter and json configuration + files are no longer supported by the GUI, by [George Dang][] in {gh}`837` + +- Updated the GUI load drive widget to be able to load tonic biases from a + network configuration file. [George Dang][] in {gh}`852` + +- Added "No. Drive Cells" input widget to the GUI and changed the "Synchronous + Input" checkbox to "Cell-Specific" to align with the API [George Dang][] in {gh}`861` + +### Bug + +- Fix inconsistent connection mapping from drive gids to cell gids, by + [Ryan Thorpe][] in {gh}`642`. + +- Objective function called by {func}`~hnn_core.optimization.optimize_evoked` + now returns a scalar instead of tuple, by [Ryan Thorpe][] in {gh}`670`. + +- Fix GUI plotting bug due to deprecation of matplotlib color cycling method, + by [George Dang][] in {gh}`695`. + +- Fix loading of drives in the GUI: drives are now overwritten instead of updated, + by [Mainak Jas][] in {gh}`795`. + +- Use `np.isin()` in place of `np.in1d()` to address numpy deprecation, + by [Nick Tolley][] in {gh}`799. + +- Fix drive seeding so that event times are unique across multiple trials, + by [Nick Tolley][] in {gh}`810`. + +- Fix bug in {func}`~hnn_core.network.clear_drives` where network object are not + accurately updated, by [Nick Tolley][] in {gh}`812`. + +### API + +- {func}`~hnn_core.CellResponse.write` and {func}`~hnn_core.Cell_response.read_spikes` + now support hdf5 format for read/write Cell response object, by + [Rajat Partani][] in {gh}`644` + +- Connection `'src_gids'` and `'target_gids'` are now stored as set objects + instead of lists, by [Ryan Thorpe][] in {gh}`642`. + +- {func}`~hnn_core.Dipole.write` and {func}`~hnn_core.Dipole.read_dipoles` + now support hdf5 format for read/write Dipole object, by + [Rajat Partani][] in {gh}`648` + +- Add ability to optimize parameters associated with evoked drives and plot + convergence. User can constrain parameter ranges and specify solver, + by [Carolina Fernandez Pujol][] in {gh}`652` + +- {func}`network.add_tonic_bias` cell-specific tonic bias can now be provided using the argument + amplitude in {func}`network.add_tonic_bias`, by [Camilo Diaz][] in {gh}`766` + +### People who contributed to this release (in alphabetical order): + +- [Huzi Cheng][] +- [Tianqi Cheng][] +- [Dylan Daniels][] +- [George Dang][] +- [Camilo Diaz][] +- [Katharina Duecker][] +- [Carolina Fernandez Pujol][] +- [Yaroslav Halchenko][] +- [Mainak Jas][] +- [Nick Tolley][] +- [Orsolya Beatrix Kolozsvari][] +- [Rajat Partani][] +- [Abdul Samad Siddiqui][] +- [Ryan Thorpe][] +- [Stephanie R. Jones][] + +## 0.3 + +### Changelog + +- Add option to select drives using argument 'which_drives' in + {func}`~hnn_core.optimization.optimize_evoked`, by [Mohamed A. Sherif][] in {gh}`478`. + +- Changed ``conn_seed`` default to ``None`` (from ``3``) in {func}`~hnn_core.network.add_connection`, + by [Mattan Pelah][] in {gh}`492`. + +- Add interface to modify attributes of sections in + {func}`~hnn_core.Cell.modify_section`, by [Nick Tolley][] in {gh}`481` + +- Add ability to target specific sections when adding drives or connections, + by [Nick Tolley][] in {gh}`419` + +- Runtime output messages now specify the trial with which each simulation time + checkpoint belongs too, by [Ryan Thorpe][] in {gh}`546`. + +- Add warning if network drives are not loaded, by [Orsolya Beatrix Kolozsvari][] in {gh}`516` + +- Add ability to record voltages and synaptic currents from all sections in {class}`~hnn_core.CellResponse`, + by [Nick Tolley][] in {gh}`502`. + +- Add ability to return unweighted RMSE for each optimization iteration in {func}`~hnn_core.optimization.optimize_evoked`, by [Kaisu Lankinen][] in {gh}`610`. + +### Bug + +- Fix bugs in drives API to enable: rate constant argument as float; evoked drive with + connection probability, by [Nick Tolley][] in {gh}`458` + +- Allow regular strings as filenames in {meth}`~hnn_core.Cell_response.write` by + [Mainak Jas][] in {gh}`456`. + +- Fix to make network output independent of the order in which drives are added to + the network by making the seed of the random process generating spike times in + drives use the offset of the gid with respect to the first gid in the population + by [Mainak Jas][] in {gh}`462`. + +- Negative ``event_seed`` is no longer allowed by [Mainak Jas][] in {gh}`462`. + +- Evoked drive optimization no longer assigns a default timing sigma value to + a drive if it is not already specified, by [Ryan Thorpe][] in {gh}`446`. + +- Subsets of trials can be indexed when using {func}`~hnn_core.viz.plot_spikes_raster` + and {func}`~hnn_core.viz.plot_spikes_hist`, by [Nick Tolley][] in {gh}`472`. + +- Add option to plot the averaged dipole in {func}`~hnn_core.viz.plot_dipole` when `dpl` + is a list of dipoles, by [Huzi Cheng][] in {gh}`475`. + +- Fix bug where {func}`~hnn_core.viz.plot_morphology` did not accurately + reflect the shape of the cell being simulated, by [Nick Tolley][] in {gh}`481` + +- Fix bug where {func}`~hnn_core.network.pick_connection` did not return an + empty list when searching non existing connections, by [Nick Tolley][] in {gh}`515` + +- Fix bug in {class}`~hnn_core.MPIBackend` that caused an MPI runtime error + (``RuntimeError: MPI simulation failed. Return code: 143``), when running a + simulation with an oversubscribed MPI session on a reduced network, by + [Ryan Thorpe][] in {gh}`545`. + +- Fix bug where {func}`~hnn_core.network.pick_connection` failed when searching + for connections with a list of cell types, by [Nick Tolley][] in {gh}`559` + +- Fix bug where {func}`~hnn_core.network.add_evoked_drive` failed when adding + a drive with just NMDA weights, by [Nick Tolley][] in {gh}`611` + +- Fix bug where {func}`~hnn_core.params.read_params` failed to create a network when + legacy mode is False, by [Nick Tolley][] in {gh}`614` + +- Fix bug where {func}`~hnn_core.viz.plot_dipole` failed to check the instance + type of Dipole, by [Rajat Partani][] in {gh}`606` + +### API + +- Optimization of the evoked drives can be conducted on any {class}`~hnn_core.Network` + template model by passing a {class}`~hnn_core.Network` instance directly into + {func}`~hnn_core.optimization.optimize_evoked`. Simulations run during + optimization can now consist of multiple trials over which the simulated + dipole is averaged, by [Ryan Thorpe][] in {gh}`446`. + +- {func}`~hnn_core.viz.plot_dipole` now supports separate visualizations of different layers, by [Huzi + Cheng][] in {gh}`479`. + +- Current source density (CSD) can now be calculated with + {func}`~hnn_core.extracellular.calculate_csd2d` and plotted with + {meth}`~hnn_core.extracellular.ExtracellularArray.plot_csd`. The method for plotting local field + potential (LFP) is now found at {meth}`~hnn_core.extracellular.ExtracellularArray.plot_lfp`, by + [Steven Brandt][] and [Ryan Thorpe][] in {gh}`517`. + +- Recorded voltages/currents from the soma, as well as all sections, are enabled by setting either + `record_vsec` or `record_isec` to `'all'` or `'soma'` in + {func}`~hnn_core.simulate_dipole`. Recordings are now accessed through + {class}`~hnn_core.CellResponse.vsec` and {class}`~hnn_core.CellResponse.isec`, by [Nick Tolley][] + in {gh}`502`. + +- legacy_mode is now set to False by default in all for all {class}`~hnn_core.Network` objects, by + [Nick Tolley][] and [Ryan Thorpe][] in {gh}`619`. + +- Recorded calcium conncetration from the soma, as well as all sections, are enabled by setting + `record_ca` to `soma` or `all` in {func}`~hnn_core.simulate_dipole`. Recordings are accessed + through {class}`~hnn_core.CellResponse.ca`, by [Katharina Duecker][] in {gh}`804` + +### People who contributed to this release (in alphabetical order): + +- [Christopher Bailey][] +- [Huzi Cheng][] +- [Kaisu Lankinen][] +- [Mainak Jas][] +- [Mattan Pelah][] +- [Mohamed A. Sherif][] +- [Mostafa Khalil][] +- [Nick Tolley][] +- [Orsolya Beatrix Kolozsvari][] +- [Rajat Partani][] +- [Ryan Thorpe][] +- [Stephanie R. Jones][] +- [Steven Brandt][] + +## 0.2 + +## Notable Changes + +- Local field potentials can now be recorded during simulations {ref}`[Example] + ` + +- Ability to optimize parameters to reproduce event related potentials from real data + {ref}`[Example] ` + +- Published models using HNN were added and can be loaded via dedicated functions + +- Several improvements enabling easy modification of connectivity and cell properties + {ref}`[Example] ` + +- Improved visualization including spectral analysis, connectivity, and cell morphology + +### Changelog + +- Store all connectivity information under {attr}`~hnn_core.Network.connectivity` before building + the network, by [Nick Tolley][] in {gh}`276` + +- Add new function {func}`~hnn_core.viz.plot_cell_morphology` to visualize cell morphology, by + [Mainak Jas][] in {gh}`319` + +- Compute dipole component in z-direction automatically from cell morphology instead of hard coding, + by [Mainak Jas][] in {gh}`327` + +- Store {class}`~hnn_core.Cell` instances in {class}`~hnn_core.Network`'s + {attr}`~/hnn_core.Network.cells` attribute by [Ryan Thorpe][] in {gh}`321` + +- Add probability argument to {func}`~hnn_core.Network.add_connection`. Connectivity patterns can + also be visualized with {func}`~hnn_core.viz.plot_connectivity_matrix`, by [Nick Tolley][] in + {gh}`318` + +- Add function to visualize connections originating from individual cells + {func}`~hnn_core.viz.plot_cell_connectivity`, by [Nick Tolley][] in {gh}`339` + +- Add method for calculating extracellular potentials using electrode arrays + {func}`~hnn_core.Network.add_electrode_array` that are stored under ``net.rec_array`` as a + dictionary of {class}`~hnn_core.extracellular.ExtracellularArray` containers, by [Mainak Jas][], + [Nick Tolley][] and [Christopher Bailey][] in {gh}`329` + +- Add function to visualize extracellular potentials from laminar array simulations, by [Christopher + Bailey][] in {gh}`329` + +- Previously published models can now be loaded via {func}`~hnn_core.law_2021_model()` and + {func}`~hnn_core.jones_2009_model()`, by [Nick Tolley][] in {gh}`348` + +- Add ability to interactivity explore connections in {func}`~hnn_core.viz.plot_cell_connectivity` + by [Mainak Jas][] in {gh}`376` + +- Add {func}`~hnn_core.calcium_model` with a distance dependent calcium channel conductivity, by + [Nick Tolley][] and [Sarah Pugliese][] in {gh}`348` + +- Each drive spike train sampled through an independent process corresponds to a single artificial + drive cell, the number of which users can set when adding drives with ``n_drive_cells`` and + ``cell_specific``, by [Ryan Thorpe][] in {gh}`383` + +- Add {func}`~hnn_core.pick_connection` to query the indices of specific connections in + {attr}`~hnn_core.Network.connectivity`, by [Nick Tolley][] in {gh}`367` + +- Drives in {attr}`~hnn_core.Network.external_drives` no longer contain a `'conn'` key and the + {attr}`~hnn_core.Network.connectivity` list contains more items when adding drives from a param + file or when in legacy mode, by [Ryan Thorpe][], [Mainak Jas][], and [Nick Tolley][] in {gh}`369` + +- Add {func}`~hnn_core.optimization.optimize_evoked` to optimize the timing and weights of driving + inputs for simulating evoked responses, by [Blake Caldwell][] and [Mainak Jas][] in {gh}`77` + +- Add method for setting in-plane cell distances and layer separation in the network + {func}`~hnn_core.Network.set_cell_positions`, by [Christopher Bailey][] in {gh}`370` + +- External drives API now accepts probability argument for targeting subsets of cells, by [Nick + Tolley][] in {gh}`416` + +### Bug + +- Remove rounding error caused by repositioning of NEURON cell sections, by [Mainak Jas][] and [Ryan + Thorpe][] in {gh}`314` + +- Fix issue where common drives use the same parameters for all cell types, by [Nick Tolley][] in + {gh}`350` + +- Fix bug where depth of L5 and L2 cells were swapped, by [Christopher Bailey][] in {gh}`352` + +- Fix bug where {func}`~hnn_core.dipole.average_dipoles` failed when there were less than two + dipoles in the input dipole list, by [Kenneth Loi][] in {gh}`368` + +- Fix bug where {func}`~hnn_core.read_spikes` wasn't returning a {class}`~hnn_core.CellResponse` + instance with updated spike types, by [Ryan Thorpe][] in {gh}`382` + +- {attr}`Dipole.times` and {attr}`Cell_response.times` now reflect the actual integration points + instead of the intended times, by [Mainak Jas][] in {gh}`397` + +- Fix overlapping non-cell-specific drive gid assignment over different ranks in + {class}`~hnn_core.MPIBackend`, by [Ryan Thorpe][] and [Mainak Jas][] in {gh}`399` + +- Allow {func}`~hnn_core.read_dipoles` to read dipole from a file with only two columns (``times`` + and ``data``), by [Mainak Jas][] in {gh}`421` + +### API + +- New API for defining cell-cell connections. Custom connections can be added with + {func}`~hnn_core.Network.add_connection`, by [Nick Tolley][] in {gh}`276` + +- Remove {class}`~hnn_core.L2Pyr`, {class}`~hnn_core.L5Pyr`, {class}`~hnn_core.L2Basket`, and + {class}`~hnn_core.L5Basket` classes in favor of instantiation through functions and a more + consistent {class}`~hnn_core.Cell` class by [Mainak Jas][] in {gh}`322` + +- Remove parameter ``distribution`` in {func}`~hnn_core.Network.add_bursty_drive`. The distribution + is now Gaussian by default, by [Mainak Jas][] in {gh}`330` + +- New API for accessing and modifying {class}`~hnn_core.Cell` attributes (e.g., synapse and + biophysics parameters) as cells are now instantiated from template cells specified in a + {class}`~hnn_core.Network` instance's {attr}`~/hnn_core.Network.cell_types` attribute by [Ryan + Thorpe][] in {gh}`321` + +- New API for network creation. The default network is now created with ``net = + jones_2009_model(params)``, by [Nick Tolley][] in {gh}`318` + +- Replace parameter ``T`` with ``tstop`` in {func}`~hnn_core.Network.add_tonic_bias` and + {func}`~hnn_core.Cell.create_tonic_bias` to be more consistent with other functions and improve + readability, by [Kenneth Loi][] in {gh}`354` + +- Deprecated ``postproc`` argument in {func}`~hnn_core.dipole.simulate_dipole`, whereby user should + explicitly smooth and scale resulting dipoles, by [Christopher Bailey][] in {gh}`372` + +- Number of drive cells and their connectivity can now be specified through the ``n_drive_cells`` + and ``cell_specific`` arguments in ``Network.add_xxx_drive()`` methods, replacing use of + ``repeats`` and ``sync_within_trial``, by [Ryan Thorpe][] in {gh}`383` + +- Simulation end time and integration time have to be specified now with ``tstop`` and ``dt`` in + {func}`~hnn_core.simulate_dipole`, by [Mainak Jas][] in {gh}`397` + +- {meth}`CellResponse.reset` method is not supported any more, by [Mainak Jas][] in {gh}`397` + +- Target cell types and their connections are created for each drive according to the synaptic + weight and delay dictionaries assigned in ``Network.add_xxx_drive()``, by [Ryan Thorpe][] in + {gh}`369` + +- Cell objects can no longer be accessed from {class}`~hnn_core.Network` as the + {attr}`~hnn_core.Network.cells` attribute has been removed, by [Ryan Thorpe][] in {gh}`436` + +### People who contributed to this release (in alphabetical order): + +- [Alex Rockhill][] +- [Blake Caldwell][] +- [Christopher Bailey][] +- [Dylan Daniels][] +- [Kenneth Loi][] +- [Mainak Jas][] +- [Nick Tolley][] +- [Ryan Thorpe][] +- [Sarah Pugliese][] +- [Stephanie R. Jones][] + +## 0.1 + +### Changelog + +- Add ability to simulate multiple trials in parallel using joblibs, by [Mainak Jas][] in {gh}`44` + +- Rhythmic inputs can now be turned off by setting their conductance weights to 0 instead of setting + their start times to exceed the simulation stop time, by [Ryan Thorpe][] in {gh}`105` + +- Reader for parameter files, by [Blake Caldwell][] in {gh}`80` + +- Add plotting of voltage at soma to inspect firing pattern of cells, by [Mainak Jas][] in {gh}`86` + +- Add ability to simulate a single trial in parallel across cores using MPI, by [Blake Caldwell][] + in {gh}`79` + +- Modify {func}`~hnn_core.viz.plot_dipole` to accept both lists and individual instances of Dipole + object, by [Nick Tolley][] in {gh}`145` + +- Update ``plot_hist_input`` to {func}`~hnn_core.viz.plot_spikes_hist` which can plot histogram of + spikes for any cell type, by [Nick Tolley][] in {gh}`157` + +- Add function to compute mean spike rates with user specified calculation type, by [Nick Tolley][] + and [Mainak Jas][] in {gh}`155` + +- Add ability to record somatic voltages from all cells, by [Nick Tolley][] in {gh}`190` + +- Add ability to instantiate external feed event times of a network prior to building it, by + [Christopher Bailey][] in {gh}`191` + +- Add ability to record somatic currents from all cells, by [Nick Tolley][] in {gh}`199` + +- Add option to turn off dipole postprocessing, by [Carmen Kohl][] in {gh}`188` + +- Add ability to add tonic inputs to cell types with {func}`~hnn_core.Network.add_tonic_bias`, by + [Mainak Jas][] in {gh}`209` + +- Modify {func}`~hnn_core.viz.plot_spikes_raster` to display individual cells, by [Nick Tolley][] in + {gh}`231` + +- Add {meth}`~hnn_core.Network.copy` method for cloning a ``Network`` instance, by [Christopher + Bailey][] in {gh}`221` + +- Add methods for creating input drives and biases to network: + {meth}`~hnn_core.Network.add_evoked_drive`, {meth}`~hnn_core.Network.add_poisson_drive`, + {meth}`~hnn_core.Network.add_bursty_drive` and {meth}`~hnn_core.Network.add_tonic_bias`, by + [Christopher Bailey][] in {gh}`221` + +- Add functions for plotting power spectral density ({func}`~hnn_core.viz.plot_psd`) and Morlet + time-frequency representations ({func}`~hnn_core.viz.plot_tfr_morlet`), by [Christopher Bailey][] + in {gh}`264` + +- Add y-label units (nAm) to all visualisation functions involving dipole moments, by [Christopher + Bailey][] in {gh}`264` + +- Add Savitzky-Golay filtering method {meth}`~hnn_core.dipole.Dipole.savgol_filter` to ``Dipole``; + copied from ``mne-python`` {meth}`~mne.Evoked.savgol_filter`, by [Christopher Bailey][] in + {gh}`264` + +### Bug + +- Fix missing autapses in network construction, by [Mainak Jas][] in {gh}`50` + +- Fix rhythmic input feed, by [Ryan Thorpe][] in {gh}`98` + +- Fix bug introduced into rhythmic input feed and add test, by [Christopher Bailey][] in {gh}`102` + +- Fix bug in amplitude of delay (for connection between L2 Basket and Gaussian feed) being passed + incorrectly, by [Mainak Jas][] in {gh}`146` + +- Connections now cannot be removed by setting the weights to 0., by [Mainak Jas][] and [Ryan + Thorpe][] in {gh}`162` + +- MPI and Joblib backends now apply jitter across multiple trials identically, by [Ryan Thorpe][] in + {gh}`171` + +- Fix bug in Poisson input where the first spike was being missed after the start time, by [Mainak + Jas][] in {gh}`204` + +- Fix bug in network to add empty spike when empty file is read in, by [Samika Kanekar][] and [Ryan + Thorpe][] in {gh}`207` + +### API + +- Make a context manager for Network class, by [Mainak Jas][] and [Blake Caldwell][] in {gh}`86` + +- Create Spikes class, add write methods and read functions for Spikes and Dipole classes, by [Ryan + Thorpe][] in {gh}`96` + +- Only specify `n_jobs` when instantiating the JoblibBackend, by [Blake Caldwell][] in {gh}`79` + +- Make a context manager for parallel backends (JoblibBackend, MPIBackend), by [Blake Caldwell][] in + {gh}`79` + +- Add {func}`~hnn_core.dipole.average_dipoles` function, by [Blake Caldwell][] in {gh}`156` + +- New API for defining external drives and biases to network. By default, a + {class}`~hnn_core.Network` is created without drives, which are added using class methods. The + argument ``add_drives_from_params`` controls this behaviour, by [Christopher Bailey][] in + {gh}`221` + +- Examples apply random state seeds that reproduce the output of HNN GUI documentation, by + [Christopher Bailey][] in {gh}`221` + +- Force conversion to nAm (from fAm) for output of {func}`~hnn_core.dipole.simulate_dipole` + regardless of ``postproc``-argument, which now only controls parameter file-based smoothing and + scaling, by [Christopher Bailey][] in {gh}`264` + +### People who contributed to this release (in alphabetical order): + +- [Blake Caldwell][] +- [Christopher Bailey][] +- [Carmen Kohl][] +- [Mainak Jas][] +- [Nick Tolley][] +- [Ryan Thorpe][] +- [Samika Kanekar][] +- [Stephanie R. Jones][] + +[Alex Rockhill]: https://github.com/alexrockhill +[Blake Caldwell]: https://github.com/blakecaldwell +[Christopher Bailey]: https://github.com/cjayb +[Carmen Kohl]: https://github.com/kohl-carmen +[Dylan Daniels]: https://github.com/dylansdaniels +[Huzi Cheng]: https://github.com/chenghuzi +[Kenneth Loi]: https://github.com/kenloi +[Mainak Jas]: http://jasmainak.github.io/ +[Mattan Pelah]: https://github.com/mjpelah +[Mohamed A. Sherif]: https://github.com/mohdsherif/ +[Mostafa Khalil]: https://github.com/mkhalil8 +[Nick Tolley]: https://github.com/ntolley +[Orsolya Beatrix Kolozsvari]: http://github.com/orbekolo/ +[Rajat Partani]: https://github.com/raj1701 +[Ryan Thorpe]: https://github.com/rythorpe +[Samika Kanekar]: https://github.com/samikane +[Sarah Pugliese]: https://bcs.mit.edu/directory/sarah-pugliese +[Stephanie R. Jones]: https://github.com/stephanie-r-jones +[Steven Brandt]: https://github.com/spbrandt +[Kaisu Lankinen]: https://github.com/klankinen +[George Dang]: https://github.com/gtdang +[Camilo Diaz]: https://github.com/kmilo9999 +[Abdul Samad Siddiqui]: https://github.com/samadpls +[Katharina Duecker]: https://github.com/katduecker +[Yaroslav Halchenko]: https://github.com/yarikoptic +[Tianqi Cheng]: https://github.com/tianqi-cheng +[Carolina Fernandez Pujol]: https://github.com/carolinafernandezp +[Austin Soplata]: https://github.com/asoplata diff --git a/doc/whats_new.rst b/doc/whats_new.rst deleted file mode 100644 index ee781b59d..000000000 --- a/doc/whats_new.rst +++ /dev/null @@ -1,616 +0,0 @@ -:orphan: - -.. _whats_new: - -What's new? -=========== - -.. currentmodule:: hnn_core - -Current -------- - -Changelog -~~~~~~~~~ -- Add button to delete a single drive on GUI drive windows, by - `George Dang`_ in :gh:`890` - -- Add minimum spectral frequency widget to GUI for adjusting spectrogram - frequency axis, by `George Dang`_ in :gh:`894` - -- Add method to :class:`~hnn_core.Network` to modify synaptic gains, by - `Nick Tolley`_ and `George Dang`_ in :gh:`897` - -- Update GUI to display "L2/3", by `Austin Soplata`_ in :gh:`904` - -- Add argument to change colors of `plot_spikes_raster`, shortened line lengths - to prevent overlap, and added an argument for custom cell types, by - `George Dang`_ in :gh:`895` - - -Bug -~~~ -- Fix GUI over-plotting of loaded data where the app stalled and did not plot - RMSE, by `George Dang`_ in :gh:`869` - -- Fix scaling and smoothing of loaded data dipoles to the GUI, by `George Dang`_ - in :gh:`892` - -API -~~~ -- Add :func:`~hnn_core.CellResponse.spike_times_by_type` to get cell spiking times - organized by cell type, by `Mainak Jas`_ in :gh:`916`. - -- Add option to apply a tonic bias to any compartment of the cell, and option to - add multiple biases per simulation and cell :func:`hnn_core.network.add_tonic_bias`, - by `Katharina Duecker`_ in :gh:`922`. - -.. _0.4: - -0.4 ---- - -Changelog -~~~~~~~~~ -- Fix bug in :func:`~hnn_core.Network.add_poisson_drive` where an error is - thrown when passing an int for rate_constant when ``cell_specific=True``, - by `Dylan Daniels`_ in :gh:`818` - -- Fix bug in :func:`~hnn_core.Network.add_poisson_drive` where an error is - thrown when passing a float for rate_constant when ``cell_specific=False``, - by `Dylan Daniels`_ in :gh:`814` - -- Add ability to customize plot colors for each cell section in - :func:`~hnn_core.Cell.plot_morphology`, by `Nick Tolley`_ in :gh:`646` - -- Add ability to manually define colors in spike histogram plots, - by `Nick Tolley`_ in :gh:`640` - -- Update minimum supported version of Python to 3.8, by `Ryan Thorpe`_ in - :gh:`678`. - -- Update GUI to use ipywidgets v8.0.0+ API, by `George Dang`_ in - :gh:`696`. - -- Add dependency groups to setup.py and update CI workflows to reference - dependency groups, by `George Dang`_ in :gh:`703`. - -- Add ability to specify number of cells in :class:`~hnn_core.Network`, - by `Nick Tolley`_ in :gh:`705` - -- Fixed figure annotation overlap in multiple sub-plots, - by `Camilo Diaz`_ in :gh:`741` - -- Fix bug in :func:`~hnn_core.network.pick_connection` where connections are - returned for cases when there should be no valid matches, by `George Dang`_ - in :gh:`739` - -- Added check for invalid Axes object in :func:`~hnn_core.viz.plot_cells` - function, by `Abdul Samad Siddiqui`_ in :gh:`744`. - -- Added kwargs options to `plot_spikes_hist` for adjusting the histogram plots - of spiking activity, by `Abdul Samad Siddiqui`_ in :gh:`732`. - -- Added pre defined plot sets for simulated data, - by `Camilo Diaz`_ in :gh:`746` - -- Added gui widget to enable/disable synchronous input in simulations, - by `Camilo Diaz`_ in :gh:`750` - -- Added gui widgets to save simulation as csv and updated the file upload to support csv data, - by `Camilo Diaz`_ in :gh:`753` - -- Added feature to read/write :class:`~hnn_core.Network` configurations to - json, by `George Dang`_ and `Rajat Partani`_ in :gh:`757` - -- Added :class:`~hnn_core.viz.NetworkPlotter` to visualize and animate network simulations, - by `Nick Tolley`_ in :gh:`649`. - -- Added GUI feature to include Tonic input drives in simulations, - by `Camilo Diaz` :gh:`773` - -- :func:`~plot_lfp`, :func:`~plot_dipole`, :func:`~plot_spikes_hist`, - and :func:`~plot_spikes_raster` now plotted from 0 to tstop. Inputs tmin and tmax are deprecated, - by `Katharina Duecker`_ in :gh:`769` - -- Add function :func:`~hnn_core.params.convert_to_json` to convert legacy param - and json files to new json format, by `George Dang`_ in :gh:`772` - -- Add :class:`~hnn_core.BatchSimulate` for batch simulation capability, - by `Abdul Samad Siddiqui`_ in :gh:`782`. - -- Updated `plot_spikes_raster` logic to include all neurons in network model. - Removed GUI exclusion from build, by `Abdul Samad Siddiqui`_ in :gh:`754`. - -- Added GUI feature to read and modify cell parameters, - by `Camilo Diaz`_ in :gh:`806`. - -- Add ability to optimize parameters associated with rhythmic drives, - by `Carolina Fernandez Pujol`_ in :gh:`673`. - -- Added features to :func:`~plot_csd`: to set color of sinks and sources, range of the colormap, - and interpolation method to smoothen CSD plot, - by `Katharina Duecker`_ in :gh:`815` - -- Cleaned up internal logic in :class:`~hnn_core.CellResponse`, - by `Nick Tolley`_ in :gh:`647`. - -- Changed the configuration/parameter file format support of the GUI. Loading - of connectivity and drives use a new multi-level json structure that mirrors - the structure of the Network object. Flat parameter and json configuration - files are no longer supported by the GUI, by `George Dang`_ in :gh:`837` - -- Updated the GUI load drive widget to be able to load tonic biases from a - network configuration file. `George Dang`_ in :gh:`852` - -- Added "No. Drive Cells" input widget to the GUI and changed the "Synchronous - Input" checkbox to "Cell-Specific" to align with the API `George Dang`_ in :gh:`861` - -Bug -~~~ -- Fix inconsistent connection mapping from drive gids to cell gids, by - `Ryan Thorpe`_ in :gh:`642`. - -- Objective function called by :func:`~hnn_core.optimization.optimize_evoked` - now returns a scalar instead of tuple, by `Ryan Thorpe`_ in :gh:`670`. - -- Fix GUI plotting bug due to deprecation of matplotlib color cycling method, - by `George Dang`_ in :gh:`695`. - -- Fix loading of drives in the GUI: drives are now overwritten instead of updated, - by `Mainak Jas`_ in :gh:`795`. - -- Use `np.isin()` in place of `np.in1d()` to address numpy deprecation, - by `Nick Tolley`_ in :gh:`799. - -- Fix drive seeding so that event times are unique across multiple trials, - by `Nick Tolley`_ in :gh:`810`. - -- Fix bug in :func:`~hnn_core.network.clear_drives` where network object are not - accurately updated, by `Nick Tolley`_ in :gh:`812`. - -API -~~~ -- :func:`~hnn_core.CellResponse.write` and :func:`~hnn_core.Cell_response.read_spikes` - now support hdf5 format for read/write Cell response object, by - `Rajat Partani`_ in :gh:`644` - -- Connection `'src_gids'` and `'target_gids'` are now stored as set objects - instead of lists, by `Ryan Thorpe`_ in :gh:`642`. - -- :func:`~hnn_core.Dipole.write` and :func:`~hnn_core.Dipole.read_dipoles` - now support hdf5 format for read/write Dipole object, by - `Rajat Partani`_ in :gh:`648` - -- Add ability to optimize parameters associated with evoked drives and plot - convergence. User can constrain parameter ranges and specify solver, - by `Carolina Fernandez Pujol`_ in :gh:`652` - -- :func:`network.add_tonic_bias` cell-specific tonic bias can now be - provided using the argument amplitude in network.add_tonic_bias`, - by `Camilo Diaz`_ in :gh:`766` - -People who contributed to this release (in alphabetical order): -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- `Huzi Cheng`_ -- `Tianqi Cheng`_ -- `Dylan Daniels`_ -- `George Dang`_ -- `Camilo Diaz`_ -- `Katharina Duecker`_ -- `Carolina Fernandez Pujol`_ -- `Yaroslav Halchenko`_ -- `Mainak Jas`_ -- `Nick Tolley`_ -- `Orsolya Beatrix Kolozsvari`_ -- `Rajat Partani`_ -- `Abdul Samad Siddiqui`_ -- `Ryan Thorpe`_ -- `Stephanie R. Jones`_ - -.. _0.3: - -0.3 ---- - -Changelog -~~~~~~~~~ -- Add option to select drives using argument 'which_drives' in - :func:`~hnn_core.optimization.optimize_evoked`, by `Mohamed A. Sherif`_ in :gh:`478`. - -- Changed ``conn_seed`` default to ``None`` (from ``3``) in :func:`~hnn_core.network.add_connection`, - by `Mattan Pelah`_ in :gh:`492`. - -- Add interface to modify attributes of sections in - :func:`~hnn_core.Cell.modify_section`, by `Nick Tolley`_ in :gh:`481` - -- Add ability to target specific sections when adding drives or connections, - by `Nick Tolley`_ in :gh:`419` - -- Runtime output messages now specify the trial with which each simulation time - checkpoint belongs too, by `Ryan Thorpe`_ in :gh:`546`. - -- Add warning if network drives are not loaded, by `Orsolya Beatrix Kolozsvari`_ in :gh:`516` - -- Add ability to record voltages and synaptic currents from all sections in :class:`~hnn_core.CellResponse`, - by `Nick Tolley`_ in :gh:`502`. - -- Add ability to return unweighted RMSE for each optimization iteration in :func:`~hnn_core.optimization.optimize_evoked`, by `Kaisu Lankinen`_ in :gh:`610`. - -Bug -~~~ -- Fix bugs in drives API to enable: rate constant argument as float; evoked drive with - connection probability, by `Nick Tolley`_ in :gh:`458` - -- Allow regular strings as filenames in :meth:`~hnn_core.Cell_response.write` by - `Mainak Jas`_ in :gh:`456`. - -- Fix to make network output independent of the order in which drives are added to - the network by making the seed of the random process generating spike times in - drives use the offset of the gid with respect to the first gid in the population - by `Mainak Jas`_ in :gh:`462`. - -- Negative ``event_seed`` is no longer allowed by `Mainak Jas`_ in :gh:`462`. - -- Evoked drive optimization no longer assigns a default timing sigma value to - a drive if it is not already specified, by `Ryan Thorpe`_ in :gh:`446`. - -- Subsets of trials can be indexed when using :func:`~hnn_core.viz.plot_spikes_raster` - and :func:`~hnn_core.viz.plot_spikes_hist`, by `Nick Tolley`_ in :gh:`472`. - -- Add option to plot the averaged dipole in `~hnn_core.viz.plot_dipole` when `dpl` - is a list of dipoles, by `Huzi Cheng`_ in :gh:`475`. - -- Fix bug where :func:`~hnn_core.viz.plot_morphology` did not accurately - reflect the shape of the cell being simulated, by `Nick Tolley`_ in :gh:`481` - -- Fix bug where :func:`~hnn_core.network.pick_connection` did not return an - empty list when searching non existing connections, by `Nick Tolley`_ in :gh:`515` - -- Fix bug in :class:`~hnn_core.MPIBackend` that caused an MPI runtime error - (``RuntimeError: MPI simulation failed. Return code: 143``), when running a - simulation with an oversubscribed MPI session on a reduced network, by - `Ryan Thorpe`_ in :gh:`545`. - -- Fix bug where :func:`~hnn_core.network.pick_connection` failed when searching - for connections with a list of cell types, by `Nick Tolley`_ in :gh:`559` - -- Fix bug where :func:`~hnn_core.network.add_evoked_drive` failed when adding - a drive with just NMDA weights, by `Nick Tolley`_ in :gh:`611` - -- Fix bug where :func:`~hnn_core.params.read_params` failed to create a network when - legacy mode is False, by `Nick Tolley`_ in :gh:`614` - -- Fix bug where :func:`~hnn_core.viz.plot_dipole` failed to check the instance - type of Dipole, by `Rajat Partani`_ in :gh:`606` - -API -~~~ -- Optimization of the evoked drives can be conducted on any :class:`~hnn_core.Network` - template model by passing a :class:`~hnn_core.Network` instance directly into - :func:`~hnn_core.optimization.optimize_evoked`. Simulations run during - optimization can now consist of multiple trials over which the simulated - dipole is averaged, by `Ryan Thorpe`_ in :gh:`446`. - -- `~hnn_core.viz.plot_dipole` now supports separate visualizations of different - layers, by `Huzi Cheng`_ in :gh:`479`. - -- Current source density (CSD) can now be calculated with - :func:`~hnn_core.extracellular.calculate_csd2d` and plotted with - :meth:`~hnn_core.extracellular.ExtracellularArray.plot_csd`. The method for - plotting local field potential (LFP) is now found at - :meth:`~hnn_core.extracellular.ExtracellularArray.plot_lfp`, by - `Steven Brandt`_ and `Ryan Thorpe`_ in :gh:`517`. - -- Recorded voltages/currents from the soma, as well as all sections, are enabled by - setting either `record_vsec` or `record_isec` to `'all'` or `'soma'` - in :func:`~hnn_core.simulate_dipole`. Recordings are now accessed through - :class:`~hnn_core.CellResponse.vsec` and :class:`~hnn_core.CellResponse.isec`, - by `Nick Tolley`_ in :gh:`502`. - -- legacy_mode is now set to False by default in all for all - :class:`~hnn_core.Network` objects, - by `Nick Tolley`_ and `Ryan Thorpe`_ in :gh:`619`. - -- Recorded calcium conncetration from the soma, as well as all sections, are enabled - by setting `record_ca` to `soma` or `all` in :func:`~hnn_core.simulate_dipole`. - Recordings are accessed through :class:`~hnn_core.CellResponse.ca`, - by `Katharina Duecker`_ in :gh:`804` - -People who contributed to this release (in alphabetical order): -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- `Christopher Bailey`_ -- `Huzi Cheng`_ -- `Kaisu Lankinen`_ -- `Mainak Jas`_ -- `Mattan Pelah`_ -- `Mohamed A. Sherif`_ -- `Mostafa Khalil`_ -- `Nick Tolley`_ -- `Orsolya Beatrix Kolozsvari`_ -- `Rajat Partani`_ -- `Ryan Thorpe`_ -- `Stephanie R. Jones`_ -- `Steven Brandt`_ - -.. _0.2: - -0.2 ---- - -Notable Changes ---------------- -- Local field potentials can now be recorded during simulations - :ref:`[Example] ` - -- Ability to optimize parameters to reproduce event related potentials from real data - :ref:`[Example] ` - -- Published models using HNN were added and can be loaded via dedicated functions - -- Several improvements enabling easy modification of connectivity and cell properties - :ref:`[Example] ` - -- Improved visualization including spectral analysis, connectivity, and cell morphology - -Changelog -~~~~~~~~~ -- Store all connectivity information under :attr:`~hnn_core.Network.connectivity` before building - the network, by `Nick Tolley`_ in :gh:`276` - -- Add new function :func:`~hnn_core.viz.plot_cell_morphology` to visualize cell morphology, - by `Mainak Jas`_ in :gh:`319` - -- Compute dipole component in z-direction automatically from cell morphology instead of hard coding, - by `Mainak Jas`_ in :gh:`327` - -- Store :class:`~hnn_core.Cell` instances in :class:`~hnn_core.Network`'s :attr:`~/hnn_core.Network.cells` - attribute by `Ryan Thorpe`_ in :gh:`321` - -- Add probability argument to :func:`~hnn_core.Network.add_connection`. Connectivity patterns can also - be visualized with :func:`~hnn_core.viz.plot_connectivity_matrix`, by `Nick Tolley`_ in :gh:`318` - -- Add function to visualize connections originating from individual cells :func:`~hnn_core.viz.plot_cell_connectivity`, - by `Nick Tolley`_ in :gh:`339` - -- Add method for calculating extracellular potentials using electrode arrays - :func:`~hnn_core.Network.add_electrode_array` that are stored under ``net.rec_array`` as a dictionary - of :class:`~hnn_core.extracellular.ExtracellularArray` containers, by `Mainak Jas`_, - `Nick Tolley`_ and `Christopher Bailey`_ in :gh:`329` - -- Add function to visualize extracellular potentials from laminar array simulations, - by `Christopher Bailey`_ in :gh:`329` - -- Previously published models can now be loaded via :func:`~hnn_core.law_2021_model()` - and :func:`~hnn_core.jones_2009_model()`, by `Nick Tolley`_ in :gh:`348` - -- Add ability to interactivity explore connections in :func:`~hnn_core.viz.plot_cell_connectivity` - by `Mainak Jas`_ in :gh:`376` - -- Add :func:`~hnn_core.calcium_model` with a distance dependent calcium channel conductivity, - by `Nick Tolley`_ and `Sarah Pugliese`_ in :gh:`348` - -- Each drive spike train sampled through an independent process corresponds to a single artificial - drive cell, the number of which users can set when adding drives with ``n_drive_cells`` and - ``cell_specific``, by `Ryan Thorpe`_ in :gh:`383` - -- Add :func:`~hnn_core.pick_connection` to query the indices of specific connections in - :attr:`~hnn_core.Network.connectivity`, by `Nick Tolley`_ in :gh:`367` - -- Drives in :attr:`~hnn_core.Network.external_drives` no longer contain a `'conn'` key and the - :attr:`~hnn_core.Network.connectivity` list contains more items when adding drives from a param - file or when in legacy mode, by `Ryan Thorpe`_, `Mainak Jas`_, and `Nick Tolley`_ in :gh:`369` - -- Add :func:`~hnn_core.optimization.optimize_evoked` to optimize the timing and weights of driving - inputs for simulating evoked responses, by `Blake Caldwell`_ and `Mainak Jas`_ in :gh:`77` - -- Add method for setting in-plane cell distances and layer separation in the network :func:`~hnn_core.Network.set_cell_positions`, by `Christopher Bailey`_ in `#370 `_ - -- External drives API now accepts probability argument for targeting subsets of cells, - by `Nick Tolley`_ in :gh:`416` - -Bug -~~~ - -- Remove rounding error caused by repositioning of NEURON cell sections, by `Mainak Jas`_ - and `Ryan Thorpe`_ in :gh:`314` - -- Fix issue where common drives use the same parameters for all cell types, by `Nick Tolley`_ - in :gh:`350` - -- Fix bug where depth of L5 and L2 cells were swapped, by `Christopher Bailey`_ in :gh:`352` - -- Fix bug where :func:`~hnn_core.dipole.average_dipoles` failed when there were less than two dipoles in the - input dipole list, by `Kenneth Loi`_ in :gh:`368` - -- Fix bug where :func:`~hnn_core.read_spikes` wasn't returning a :class:`~hnn_core.CellResponse` instance - with updated spike types, by `Ryan Thorpe`_ in :gh:`382` - -- :attr:`Dipole.times` and :attr:`Cell_response.times` now reflect the actual - integration points instead of the intended times, by `Mainak Jas`_ in :gh:`397` - -- Fix overlapping non-cell-specific drive gid assignment over different ranks in `~hnn_core.MPIBackend`, by `Ryan Thorpe`_ - and `Mainak Jas`_ in :gh:`399` - -- Allow :func:`~hnn_core.read_dipoles` to read dipole from a file with only two columns - (``times`` and ``data``), by `Mainak Jas`_ in :gh:`421` - -API -~~~ -- New API for defining cell-cell connections. Custom connections can be added with - :func:`~hnn_core.Network.add_connection`, by `Nick Tolley`_ in :gh:`276` - -- Remove :class:`~hnn_core.L2Pyr`, :class:`~hnn_core.L5Pyr`, :class:`~hnn_core.L2Basket`, - and :class:`~hnn_core.L5Basket` classes in favor of instantiation through functions and - a more consistent :class:`~hnn_core.Cell` class by `Mainak Jas`_ in :gh:`322` - -- Remove parameter ``distribution`` in :func:`~hnn_core.Network.add_bursty_drive`. - The distribution is now Gaussian by default, by `Mainak Jas`_ in :gh:`330` - -- New API for accessing and modifying :class:`~hnn_core.Cell` attributes (e.g., synapse and biophysics parameters) - as cells are now instantiated from template cells specified in a :class:`~hnn_core.Network` - instance's :attr:`~/hnn_core.Network.cell_types` attribute by `Ryan Thorpe`_ in :gh:`321` - -- New API for network creation. The default network is now created with - ``net = jones_2009_model(params)``, by `Nick Tolley`_ in :gh:`318` - -- Replace parameter ``T`` with ``tstop`` in :func:`~hnn_core.Network.add_tonic_bias` - and :func:`~hnn_core.Cell.create_tonic_bias` to be more consistent with other functions and - improve readability, by `Kenneth Loi`_ in :gh:`354` - -- Deprecated ``postproc`` argument in :func:`~hnn_core.dipole.simulate_dipole`, whereby user should - explicitly smooth and scale resulting dipoles, by `Christopher Bailey`_ in :gh:`372` - -- Number of drive cells and their connectivity can now be specified through the ``n_drive_cells`` - and ``cell_specific`` arguments in ``Network.add_xxx_drive()`` methods, replacing use of ``repeats`` - and ``sync_within_trial``, by `Ryan Thorpe`_ in :gh:`383` - -- Simulation end time and integration time have to be specified now with ``tstop`` and ``dt`` in - :func:`~hnn_core.simulate_dipole`, by `Mainak Jas`_ in :gh:`397` - -- :meth:`CellResponse.reset` method is not supported any more, by `Mainak Jas`_ in :gh:`397` - -- Target cell types and their connections are created for each drive according to the synaptic weight - and delay dictionaries assigned in ``Network.add_xxx_drive()``, by `Ryan Thorpe`_ in :gh:`369` - -- Cell objects can no longer be accessed from :class:`~hnn_core.Network` as the - :attr:`~hnn_core.Network.cells` attribute has been removed, by `Ryan Thorpe`_ in :gh:`436` - -People who contributed to this release (in alphabetical order): -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- `Alex Rockhill`_ -- `Blake Caldwell`_ -- `Christopher Bailey`_ -- `Dylan Daniels`_ -- `Kenneth Loi`_ -- `Mainak Jas`_ -- `Nick Tolley`_ -- `Ryan Thorpe`_ -- `Sarah Pugliese`_ -- `Stephanie R. Jones`_ - -.. _0.1: - -0.1 ---- - -Changelog -~~~~~~~~~ - -- Add ability to simulate multiple trials in parallel using joblibs, by `Mainak Jas`_ in `#44 `_ - -- Rhythmic inputs can now be turned off by setting their conductance weights to 0 instead of setting their start times to exceed the simulation stop time, by `Ryan Thorpe`_ in `#105 `_ - -- Reader for parameter files, by `Blake Caldwell`_ in `#80 `_ - -- Add plotting of voltage at soma to inspect firing pattern of cells, by `Mainak Jas`_ in `#86 `_ - -- Add ability to simulate a single trial in parallel across cores using MPI, by `Blake Caldwell`_ in `#79 `_ - -- Modify :func:`~hnn_core.viz.plot_dipole` to accept both lists and individual instances of Dipole object, by `Nick Tolley`_ in `#145 `_ - -- Update ``plot_hist_input`` to :func:`~hnn_core.viz.plot_spikes_hist` which can plot histogram of spikes for any cell type, by `Nick Tolley`_ in `#157 `_ - -- Add function to compute mean spike rates with user specified calculation type, by `Nick Tolley`_ and `Mainak Jas`_ in `#155 `_ - -- Add ability to record somatic voltages from all cells, by `Nick Tolley`_ in `#190 `_ - -- Add ability to instantiate external feed event times of a network prior to building it, by `Christopher Bailey`_ in `#191 `_ - -- Add ability to record somatic currents from all cells, by `Nick Tolley`_ in `#199 `_ - -- Add option to turn off dipole postprocessing, by `Carmen Kohl`_ in `#188 `_ - -- Add ability to add tonic inputs to cell types with :func:`~hnn_core.Network.add_tonic_bias`, by `Mainak Jas`_ in `#209 `_ - -- Modify :func:`~hnn_core.viz.plot_spikes_raster` to display individual cells, by `Nick Tolley`_ in `#231 `_ - -- Add :meth:`~hnn_core.Network.copy` method for cloning a ``Network`` instance, by `Christopher Bailey`_ in `#221 `_ - -- Add methods for creating input drives and biases to network: :meth:`~hnn_core.Network.add_evoked_drive`, :meth:`~hnn_core.Network.add_poisson_drive`, :meth:`~hnn_core.Network.add_bursty_drive` and :meth:`~hnn_core.Network.add_tonic_bias`, by `Christopher Bailey`_ in `#221 `_ - -- Add functions for plotting power spectral density (:func:`~hnn_core.viz.plot_psd`) and Morlet time-frequency representations (:func:`~hnn_core.viz.plot_tfr_morlet`), by `Christopher Bailey`_ in `#264 `_ - -- Add y-label units (nAm) to all visualisation functions involving dipole moments, by `Christopher Bailey`_ in `#264 `_ - -- Add Savitzky-Golay filtering method :meth:`~hnn_core.dipole.Dipole.savgol_filter` to ``Dipole``; copied from ``mne-python`` :meth:`~mne.Evoked.savgol_filter`, by `Christopher Bailey`_ in `#264 `_ - -Bug -~~~ - -- Fix missing autapses in network construction, by `Mainak Jas`_ in `#50 `_ - -- Fix rhythmic input feed, by `Ryan Thorpe`_ in `#98 `_ - -- Fix bug introduced into rhythmic input feed and add test, by `Christopher Bailey`_ in `#102 `_ - -- Fix bug in amplitude of delay (for connection between L2 Basket and Gaussian feed) being passed incorrectly, by `Mainak Jas`_ in `#146 `_ - -- Connections now cannot be removed by setting the weights to 0., by `Mainak Jas`_ and `Ryan Thorpe`_ in `#162 `_ - -- MPI and Joblib backends now apply jitter across multiple trials identically, by `Ryan Thorpe`_ in `#171 `_ - -- Fix bug in Poisson input where the first spike was being missed after the start time, by `Mainak Jas`_ in `#204 `_ - -- Fix bug in network to add empty spike when empty file is read in, by `Samika Kanekar`_ and `Ryan Thorpe`_ in `#207 `_ - -API -~~~ - -- Make a context manager for Network class, by `Mainak Jas`_ and `Blake Caldwell`_ in `#86 `_ - -- Create Spikes class, add write methods and read functions for Spikes and Dipole classes, by `Ryan Thorpe`_ in `#96 `_ - -- Only specify `n_jobs` when instantiating the JoblibBackend, by `Blake Caldwell`_ in `#79 `_ - -- Make a context manager for parallel backends (JoblibBackend, MPIBackend), by `Blake Caldwell`_ in `#79 `_ - -- Add :func:`~hnn_core.dipole.average_dipoles` function, by `Blake Caldwell`_ in `#156 `_ - -- New API for defining external drives and biases to network. By default, a :class:`~hnn_core.Network` is created without drives, which are added using class methods. The argument ``add_drives_from_params`` controls this behaviour, by `Christopher Bailey`_ in `#221 `_ - -- Examples apply random state seeds that reproduce the output of HNN GUI documentation, by `Christopher Bailey`_ in `#221 `_ - -- Force conversion to nAm (from fAm) for output of :func:`~hnn_core.dipole.simulate_dipole` regardless of ``postproc``-argument, which now only controls parameter file-based smoothing and scaling, by `Christopher Bailey`_ in `#264 `_ - -People who contributed to this release (in alphabetical order): -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- `Blake Caldwell`_ -- `Christopher Bailey`_ -- `Carmen Kohl`_ -- `Mainak Jas`_ -- `Nick Tolley`_ -- `Ryan Thorpe`_ -- `Samika Kanekar`_ -- `Stephanie R. Jones`_ - -.. _Alex Rockhill: https://github.com/alexrockhill -.. _Blake Caldwell: https://github.com/blakecaldwell -.. _Christopher Bailey: https://github.com/cjayb -.. _Carmen Kohl: https://github.com/kohl-carmen -.. _Dylan Daniels: https://github.com/dylansdaniels -.. _Huzi Cheng: https://github.com/chenghuzi -.. _Kenneth Loi: https://github.com/kenloi -.. _Mainak Jas: http://jasmainak.github.io/ -.. _Mattan Pelah: https://github.com/mjpelah -.. _Mohamed A. Sherif: https://github.com/mohdsherif/ -.. _Mostafa Khalil: https://github.com/mkhalil8 -.. _Nick Tolley: https://github.com/ntolley -.. _Orsolya Beatrix Kolozsvari: http://github.com/orbekolo/ -.. _Rajat Partani: https://github.com/raj1701 -.. _Ryan Thorpe: https://github.com/rythorpe -.. _Samika Kanekar: https://github.com/samikane -.. _Sarah Pugliese: https://bcs.mit.edu/directory/sarah-pugliese -.. _Stephanie R. Jones: https://github.com/stephanie-r-jones -.. _Steven Brandt: https://github.com/spbrandt -.. _Kaisu Lankinen: https://github.com/klankinen -.. _George Dang: https://github.com/gtdang -.. _Camilo Diaz: https://github.com/kmilo9999 -.. _Abdul Samad Siddiqui: https://github.com/samadpls -.. _Katharina Duecker: https://github.com/katduecker -.. _Yaroslav Halchenko: https://github.com/yarikoptic -.. _Tianqi Cheng: https://github.com/tianqi-cheng diff --git a/setup.py b/setup.py index 3f1131c33..ed20c581e 100644 --- a/setup.py +++ b/setup.py @@ -79,7 +79,7 @@ def run(self): 'opt': ['scikit-learn'], 'parallel': ['joblib', 'psutil'], 'test': ['pytest', 'pytest-cov', 'pytest-xdist', 'ruff'], - 'docs': ['mne', 'nibabel', 'pooch', 'tdqm', + 'docs': ['mne', 'myst-parser', 'nibabel', 'pooch', 'tdqm', 'sphinx', 'sphinx-gallery', 'sphinx_bootstrap_theme', 'sphinx-copybutton', 'pillow', 'numpydoc', @@ -87,8 +87,7 @@ def run(self): 'gui': ['ipywidgets>=8.0.0', 'ipykernel', 'ipympl', 'voila', ], } extras['dev'] = (extras['opt'] + extras['parallel'] + extras['test'] + - extras['docs'] + extras['gui'] - ) + extras['docs'] + extras['gui']) setup(name=DISTNAME, @@ -99,7 +98,7 @@ def run(self): url=URL, version=version, download_url=DOWNLOAD_URL, - long_description=open('README.rst').read(), + long_description=open('README.md').read(), classifiers=[ 'Intended Audience :: Science/Research', 'Intended Audience :: Developers',