Refactor/documentation

.github/workflows/deploy-gh-pages.yaml

@@ -0,0 +1,41 @@
+name: Deploy Github Pages
+
+on:
+  workflow_dispatch
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repo
+        uses: actions/checkout@v3
+
+      - name: Install Pandoc
+        run: sudo apt-get install -y pandoc
+
+      - name: Setup Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.10'
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: 16
+
+      - name: Install Requirements
+        run: |
+          pip install -r doc_requirements.txt
+          pip install .
+
+      - name: Build Documentation
+        run: |
+          cd docs/autodocs
+          make html
+
+      - name: Deploy to Github Pages
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          clean: true
+          branch: gh-pages
+          folder: ./docs/autodocs/build/html

.gitignore

@@ -38,3 +38,4 @@ benchmarks/.asv
 .conda/conda-bld/**/*
 **/*.code-workspace
 **/.coverage
+**/.DS_Store

doc_requirements.txt

@@ -0,0 +1,7 @@
+sphinx
+numpydoc
+jupyterlab
+nbsphinx
+sphinx-design
+pydata-sphinx-theme
+neuron

docs/autodocs/source/ad_tutorials.rst

@@ -1,8 +1,15 @@
 Additional Tutorials
 ====================
 
-These tutorials cover in more detail advanced or specialized topics that may be of interest to users.  
-
-
+.. toctree::
+    :hidden:
+    :maxdepth: 2
+
+    Cell placement: Functions for spatially distributing units <tutorial_cell_placement>
+    Accessing synapse models in NEST to model dynamic synapses <tutorial_dynamic_synapses>
+    Creating spike trains with refractory periods <tutorial_spike_trains_refractory>
+    Replaying disconnected simulations in BioNet <tutorial_bionet_disconnected_sims>
+
 
+These tutorials cover in more detail advanced or specialized topics that may be of interest to users.  
 

docs/autodocs/source/contact_us.rst

@@ -1,3 +1,12 @@
 ##########
 Contact Us
-##########
+##########
+
+Primary Investigator: Anton Arkhipov <antona at alleninstitute dot org>
+Lead Developer: Kael Dai <kaeld at alleninstitute dot org>
+
+For issues, questions, and feature requests for BMTK and associated software please feel free to 
+open up an issue on github: https://github.com/AllenInstitute/bmtk/issues.
+
+**Users are encouraged to register** `here <https://secure2.convio.net/allins/site/SPageServer/?pagename=modeling_tools>`_ 
+**to receive updates and other communications, but registration is not required to use the package.** 

docs/autodocs/source/developers_guide.rst

@@ -1,3 +1,9 @@
 ##############
 For Developers
-##############
+##############
+
+.. toctree::
+    :maxdepth: 4
+
+    bmtk/modules
+    contributors

docs/autodocs/source/how_to_cite.rst

@@ -1,3 +1,5 @@
+:orphan:
+
 How to Cite
 ===========
 
@@ -30,10 +32,9 @@ The BioNet module of BMTK was described in an earlier paper. If using BioNet, pl
 
 |
 |
+
 **How to cite the V1 models:**
 
 Development of BMTK and SONATA was driven to a large degree by our efforts to model cortical circuits. Models of the mouse primary visual cortex (area V1) are `publicly available here <https://portal.brain-map.org/explore/models/mv1-all-layers>`_ and should be cited as follows:
 
 [1] Billeh, Y. N., Cai, B., Gratiy, S. L., Dai, K., Iyer, R., Gouwens, N. W., Abbasi-Asl, R., Jia, X., Siegle, J. H., Olsen, S. R., Koch, C., Mihalas, S., & Arkhipov, A. (2020). Systematic Integration of Structural and Functional Data into Multi-scale Models of Mouse Primary Visual Cortex. Neuron, 106(3), 388-403.e18. https://doi.org/10.1016/j.neuron.2020.01.040 
-
-

docs/autodocs/source/index.rst

@@ -9,7 +9,6 @@ Welcome to the Brain Modeling Toolkit (BMTK)
    About BMTK <self>
 
 .. toctree::
-   :maxdepth: 1
    :hidden:
 
    About BMTK <index.rst>
@@ -21,37 +20,78 @@ Welcome to the Brain Modeling Toolkit (BMTK)
    developers_guide
 
 
-
-.. card:: News and Events
-   :img-background: _static/images/blue_banner.jpg
-   :class-card: sd-text-black
-
-   **Come and See us at SFN** : 
-
-   Find us at `here <https://kingcounty.gov/en/dept/dja/courts-jails-legal-system/case-records/records-access>`_
-
-
-
-#######################################
 About the Brain Modeling Toolkit (BMTK)
-#######################################
+=======================================
 
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi est metus, blandit et metus eu, porttitor rutrum enim. Ut vel maximus massa, ac blandit purus. Duis lacus tellus, congue in velit in, tincidunt ornare ante. Proin aliquet aliquam dui nec gravida. Cras pellentesque elit in gravida fringilla. Donec eleifend dapibus faucibus. Cras posuere dapibus nibh, vitae ornare libero tincidunt nec.
+The Brain Modeling Toolkit (BMTK) is a python-based software package for building, simulating and analyzing large-scale
+neural network models. It supports the building and simulation of models of varying levels-of-resolution; from
+multi-compartment biophysically detailed networks, to point-neuron models, to filter-based models, and even
+population-level firing rate models.
 
 .. figure:: _static/images/levels_of_resolution_noml.png
    :scale: 70%
 
-Sed finibus arcu mi. Vestibulum tincidunt volutpat ligula imperdiet vulputate. Nam quis gravida neque. Quisque fringilla dui et orci aliquet, nec finibus velit egestas. In interdum ligula massa, quis suscipit tortor cursus id. Suspendisse tempus risus id massa dapibus, vel viverra dolor lobortis. Donec porttitor ex mauris, sit amet sodales ex fringilla ac. Vestibulum congue vel risus sit amet eleifend.
+The BMTK is not itself a simulator and will utilize existing simulators, like NEURON and NEST, to run different types of
+models. What BMTK does provide:
 
 .. figure:: _static/images/bmtk_architecture.jpg
    :scale: 45%
 
-Nulla auctor, nibh id accumsan vehicula, leo nisl vestibulum ex, eget dapibus neque lacus sit amet nibh. Mauris rutrum lectus ex, a interdum erat molestie sit amet. Donec ornare cursus tortor molestie gravida. Quisque vitae nisl a eros convallis imperdiet porta eu nulla. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum non pharetra tellus, id hendrerit mauris. Aenean eget ipsum semper magna posuere lacinia nec ut urna. Curabitur auctor, erat at vehicula luctus, lectus lacus pharetra urna, id interdum elit enim ut nisi. Pellentesque nulla risus, sagittis ut leo ac, pellentesque ullamcorper ante.
+The BMTK Workflow and architecture
+----------------------------------
+BMTK can readily scale to run models of single neurons, and even single compartments, and for all different types of
+neuronal networks. However BMTK was designed for very-large, highly optimized mammalian cortical network models.
+Generating the connectivity matrix could take hours or even days to complete. Plus once we had the base-line model we
+wanted to run against a large variety of conditions and stimuli, so that we could directly compare with existing in-vivo
+recordings (see Allen Brain Observatory).
 
+.. figure:: _static/images/bmtk_workflow.jpg
+   :scale: 100%
 
-################
-Acknowledgements
-################
-We wish to thank the Allen Institute for Brain Science founder, Paul G. Allen, for their vision, encouragement, and support.
+Unlike other simulators, BMTK separates the process of building, simulating, and analyzing the results. First a fully
+instantiated base-line version of the model is built and saved to a file so each time a simulation is ran it takes only
+a small fraction of the time to instantiate the simulation. Results are also automatically saved to a disk. BMTK and
+the format it uses (SONATA, see below) makes it easy to dynamically adjust cell and synaptic parameters so that multiple
+iterations of a simulation be done as fast as possible
+
+As such BMTK can be broken into three major components:
+
+* The Network Builder [:py:mod:`bmtk.builder`] - Used to build network models
+* The Simulation Engines [:py:mod:`bmtk.simulator`] - Interfaces for simulating the network
+* Analysis and Visualization Tools [:py:mod:`bmtk.analyzer`] - Python functions for analyzing and visualizing the
+   network and simulation results
+
+.. figure:: _static/images/bmtk_architecture.jpg
+   :scale: 45%
+
+The components can be as one workflow or separately by themselves. BMTK utilizes the SONATA Data format (see next section)
+to allow sharing of large-scale network data. As such, it is possible to use the Network Builder to build the model but
+another tool to run the model. Or if another model has been built by someone else and saved in SONATA format BMTK will
+be able to simulate it.
 
-Grant Number
+
+SONATA
+------
+SONATA is a multi-institutional developed standardized, cross-platform data format for storing large scale networks and
+simulation results. The BMTK utilizes SONATA when building and simulating networks, so much of what is being described
+in the documentation and tutorials will be based on SONATA. For more information see the
+`SONATA github page <https://github.com/AllenInstitute/sonata>`_.
+
+
+VND
+---
+`Visual Neuronal Dynamics <https://www.ks.uiuc.edu/Research/vnd/>`_ is a software package for 3D visualization of neuronal network models. VND can be used to check and inspect models, such as those created by BMTK, as well as to visualize the activity output. Images and movies made in VND can also be used to showcase or schematize models for presentations and publications. VND is developed in a collaboration between researchers at the University of Illinois at Urbana-Champaign and Allen Institute.  
+
+
+References
+----------
+See the paper about BMTK: `link <https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1008386>`_.
+
+For information on how to cite BMTK, please see: `link <how_to_cite.html>`_.
+
+
+
+
+Acknowledgements
+----------------
+We wish to thank the Allen Institute for Brain Science founder, Paul G. Allen, for their vision, encouragement, and support.