feedback from steph

paper.md

@@ -125,7 +125,7 @@ bibliography: paper.bib
 
 # Summary
 
-HNN-core is a library for circuit and cellular level interpretation of non-invasive human magneto-/electro-encephalography (MEG/EEG) data. It is based on the Human Neocortical Neurosolver (HNN) software [@neymotin2020human], a modeling tool designed to simulate multiscale neural mechanisms generating current dipoles in a localized patch of neocortex. HNN’s foundation is a biophysically detailed neural network representing a canonical neocortical column containing populations of pyramidal and inhibitory neurons together with layer-specific exogenous synaptic drive. In addition to simulating network-level interactions, HNN produces the intracellular currents in the long apical dendrites of pyramidal cells across the cortical layers known to be responsible for macroscopic current dipole generation.
+HNN-core is a library for circuit and cellular level interpretation of non-invasive human magneto-/electro-encephalography (MEG/EEG) data. It is based on the Human Neocortical Neurosolver (HNN, <hnn.brown.edu>) software [@neymotin2020human], a modeling tool designed to simulate multiscale neural mechanisms generating current dipoles in a localized patch of neocortex. HNN’s foundation is a biophysically detailed neural network representing a canonical neocortical column containing populations of pyramidal and inhibitory neurons together with layer-specific exogenous synaptic drive. In addition to simulating network-level interactions, HNN produces the intracellular currents in the long apical dendrites of pyramidal cells across the cortical layers known to be responsible for macroscopic current dipole generation.
 
 HNN-core reproduces the workflows and tutorials provided in the original HNN software to generate commonly observed MEG/EEG signals including evoked response potentials (ERPs) and alpha (8-10 Hz), beta (15-30 Hz), and gamma (30-80 Hz) rhythms. HNN-core enables simultaneous calculation and visualization of macro- to micro-scale dynamics including MEG/EEG current dipoles, local field potential, laminar current-source density, and cell spiking and intrinsic dynamics. Importantly, HNN-core adopts modern open source development standards including a simplified installation procedure, unit tests, automatic documentation builds, code coverage, continuous integration, and contributing guidelines, supporting community development and long-term sustainability.
 
@@ -135,7 +135,7 @@ HNN-core addresses a key need in the fields of computational and experimental ne
 
 # HNN-core implements a biophysically detailed model to interpret MEG/EEG primary current sources
 
-MEG/EEG are the two electrophysiological methods to non-invasively study the human brain. They have been used in developing biomarkers for healthy and pathological brain processes. Yet, the underlying cellular and circuit level generators of MEG/EEG signals have been difficult to infer. This detailed understanding is critical to develop theories of information processing based on these signals, or to use these techniques to develop new therapeutics. Computational neural modeling is a powerful technique to hypothesize the neural origin of these signals and several modeling frameworks have been developed. Since MEG/EEG recordings are dominated by neocortical sources, all models developed so far simulate neocortical activity, but with different levels of biophysical details. One class of models known as neural mass models (NMMs) uses simplified representations to simulate net population dynamics, where hypothesized connectivity among neural “nodes” can be inferred from recordings. The Virtual Brain Project [@sanz2013virtual] and Dynamic Causal Modeling from the SPM software [@friston2003dynamic; @litvak2011eeg] are prominent examples of software that implement NMMs. While NMMs are computationally tractable and advantageous for studying brain-wide interactions, they do not provide detailed interpretation of cell and circuit level phenomena underlying MEG/EEG. The primary electrical currents that create MEG/EEG sensor signals are known to be oriented along the long and spatially aligned cortical pyramidal neuron dendrites, and their direction corresponds to that of the intracellular current flow [@hamalainen1993magnetoencephalography]. For a detailed discussion see @neymotin2020human. Further, source localization methods such as minimum-norm estimate (MNE) calculate the primary currents (assuming constraints defined by the technique [@gramfort2013meg]). As such, models created to study the cell and circuit origin of these signals are designed with detailed pyramidal neuron morphology and physiology, and are often embedded in a full neocortical column model. HNN is one such detailed neocortical column model [@neymotin2020human], and other examples have been employed using the software LFPy [@linden2014lfpy]. A unique feature of HNN is its workflows for interacting with the template neocortical model through layer-specific activations to study ERPs and low frequency brain rhythms. HNN also enables direct comparison between simulation output and the waveforms of estimated sources in the same units of measure and supports parameter inference. HNN-core was created to maintain all of the functionality of the original HNN software with additional utility (described below) and a well-defined, well-tested and documented API. Its adoption of open source development standards, including a simplified installation procedure, unit tests, automatic documentation builds, code coverage, and continuous integration, enables community development and long-term sustainability.
+MEG/EEG are the two electrophysiological methods to non-invasively study the human brain. They have been used in developing biomarkers for healthy and pathological brain processes. Yet, the underlying cellular and circuit level generators of MEG/EEG signals have been difficult to infer. This detailed understanding is critical to develop theories of information processing based on these signals, or to use these techniques to develop new therapeutics. Computational neural modeling is a powerful technique to hypothesize the neural origin of these signals and several modeling frameworks have been developed. Since MEG/EEG recordings are dominated by neocortical sources, all models developed so far simulate neocortical activity, but they are developed with different levels of biophysical detail and correspondingly different use cases. The level of detail in HNN’s pre-tuned network models and the workflows developed to study ERPs and low frequency oscillations are unique within the field of MEG/EEG modeling. One class of models known as neural mass models (NMMs) uses simplified representations to simulate net population dynamics, where hypothesized connectivity among neural “nodes” can be inferred from recordings. The Virtual Brain Project [@sanz2013virtual] and Dynamic Causal Modeling from the SPM software [@friston2003dynamic; @litvak2011eeg] are prominent examples of software that implement NMMs. While NMMs are computationally tractable and advantageous for studying brain-wide interactions, they do not provide detailed interpretation of cell and circuit level phenomena underlying MEG/EEG. The primary electrical currents that create MEG/EEG sensor signals are known to be oriented along the long and spatially aligned cortical pyramidal neuron dendrites, and their direction corresponds to that of the intracellular current flow [@hamalainen1993magnetoencephalography]. For a detailed discussion see @neymotin2020human. Further, source localization methods such as minimum-norm estimate (MNE) calculate the primary currents (assuming constraints defined by the technique [@gramfort2013meg]). As such, models created to study the cell and circuit origin of these signals are designed with detailed pyramidal neuron morphology and physiology, and are often embedded in a full neocortical column model. HNN is one such detailed neocortical column model [@neymotin2020human], and other examples have been employed using the software LFPy [@linden2014lfpy]. LFPy simulates fields and currents from detailed models of pyramidal neurons and networks [@linden2014lfpy]. LFPy does not support a specific neocortical model or workflows/parameter inference to study particular signals of interest. Rather, it provides multi-use Python scripts that can be integrated into any NEURON based neural model containing  multi-compartment pyramidal neurons. A unique feature of HNN is its workflows for interacting with the template neocortical model through layer-specific activations to study ERPs and low frequency brain rhythms. HNN also enables direct comparison between simulation output and the waveforms of estimated sources in the same units of measure and supports parameter inference. HNN-core was created to maintain all of the functionality of the original HNN software with additional utility (described below) and a well-defined, well-tested and documented API. Its adoption of open source development standards, including a simplified installation procedure, unit tests, automatic documentation builds, code coverage, and continuous integration, enables community development and long-term sustainability.
 
 # HNN-core facilitates reproducibility and computationally expensive workflows
 
@@ -157,7 +157,11 @@ HNN-core code has also enabled the creation of a new and improved web-based GUI
 
 All of the code associated with HNN-core has been extensively documented at multiple levels,  including an API describing basic functions/parameters and examples of  use for hypothesis generation and/or testing. Specifically, we distribute tutorials that mimic the original GUI tutorial workflows for simulating ERPs and low frequency rhythms using HNN-core functions, with commentary on the known biophysical mechanisms of these signals. We also provide short and targeted “How to” examples that describe how to use specific functionality, such as plotting firing rates, or recording extracellular LFPs. 
 
-# Quick example code of running a simulation
+# Use cases and quick example code of running a simulation
+
+As summarized above, HNN-core reproduces the workflows and tutorials provided in the original GUI driven HNN software designed to investigate the origin of commonly observed MEG/EEG signals. The HNN-core [tutorials](https://jonescompneurolab.github.io/hnn-core/stable/auto_examples/index.html) include examples of how to study [alpha](https://jonescompneurolab.github.io/hnn-core/stable/auto_examples/workflows/plot_simulate_alpha.html#sphx-glr-auto-examples-workflows-plot-simulate-alpha-py) (8-10 Hz), [beta](https://jonescompneurolab.github.io/hnn-core/stable/auto_examples/workflows/plot_simulate_alpha.html#sphx-glr-auto-examples-workflows-plot-simulate-alpha-py) (15-30 Hz), and [gamma](https://jonescompneurolab.github.io/hnn-core/stable/auto_examples/workflows/plot_simulate_gamma.html#sphx-glr-auto-examples-workflows-plot-simulate-gamma-py) (30-0 Hz) brain rhythms. The tutorials also include an example of directly comparing simulations to real data, i.e. the [median nerve evoked responses](https://jonescompneurolab.github.io/hnn-core/stable/auto_examples/workflows/plot_simulate_somato.html#sphx-glr-auto-examples-workflows-plot-simulate-somato-py).
+
+In practice, users learn how to study the multi-scale origin of ERPs and low frequency oscillations by first following the tutorials in the HNN-GUI, and then recapitulating these tutorials in HNN-core. The tutorials provide an interactive investigation that gives intuition on how exogenous drives and other parameters in the model impact the outputs of the simulations. From there, users can test hypotheses about what parameters or sets of parameters need to be adjusted to account for their recorded data by directly comparing simulation output to data. Automated parameter inference can be performed to optimize parameters to produce a close fit (i.e., small root mean squared error) to current source ERPs, and more advanced parameter inference methods are in development.
 
 HNN-core has minimal dependencies which allows for effortless installation using the pip Python installer. In addition to NumPy [@harris2020array], SciPy [@virtanen2020scipy], and Matplotlib [@hunter2007matplotlib] common in most libraries in the scientific Python stack, HNN-core uses NEURON [@hines1997neuron] for the cell and circuit modeling. Here, we demonstrate how the HNN-core interface can be used to quickly simulate and plot the net cortical dipole response to a brief exogenously evoked drive representing “feedforward” thalamocortical input. This input  (referred to as ‘evprox1’) effectively targets the proximal dendrites of the pyramidal neurons in L2/3 and L5, using the template neocortical model as in @jones2009quantitative. Note that this simulation is not addressing a specific scientific question, and is simply an educational example.
 
@@ -181,10 +185,6 @@ dpl = simulate_dipole(net, tstop=100.0)
 ```
 ![**Left**: Reduced schematic of HNN model detailing the cell types, layer-specific synaptic connectivity structure, and locations of proximal drive synapses. The default size of the full network is a grid of 100 pyramidal neurons, and 35 inhibitory neurons, synaptically connected in each layer. Figure adapted from @neymotin2020human. **Right**: Plots of the network and simulated results can be generated using the HNN-core visualization API. The drive input histogram with `net.cell_response.plot_spikes_hist()`, the net current dipole with `plot_dipole(dpl)`, and the spike raster with `net.cell_response.plot_spikes_raster()`.\label{fig:fig1}](joss_figure.pdf)
 
-Given a well-structured hypothesis, HNN-core can be used to make inferences on a variety of neocortical circuit mechanisms by observing a mechanism’s effect (through simulation) on resting state and evoked response current dipoles, LFPs, and spiking activity. Such mechanisms include, but are not limited to, the timing, location, and synaptic strength of external inputs, as well as biophysical and morphological properties of key neuron types and their connectivity within a neocortical column network.
-
-The HNN-core tutorials include examples of directly comparing simulations to real data such as human SI MEG [tactile](https://jonescompneurolab.github.io/hnn-core/stable/auto_examples/workflows/plot_simulate_evoked.html#sphx-glr-auto-examples-workflows-plot-simulate-evoked-py) and [median nerve](https://jonescompneurolab.github.io/hnn-core/stable/auto_examples/workflows/plot_simulate_somato.html#sphx-glr-auto-examples-workflows-plot-simulate-somato-py) evoked responses. The tutorials also include examples of recreating [alpha/beta](https://jonescompneurolab.github.io/hnn-core/stable/auto_examples/workflows/plot_simulate_alpha.html#sphx-glr-auto-examples-workflows-plot-simulate-alpha-py) and [gamma](https://jonescompneurolab.github.io/hnn-core/stable/auto_examples/workflows/plot_simulate_gamma.html#sphx-glr-auto-examples-workflows-plot-simulate-gamma-py) brain rhythms.
-
 # Ongoing research using HNN-core
 
 The scripted interface of HNN-core has enabled the development of advanced parameter inference techniques [@tolley2023methods] using Simulation-Based Inference [@tejero-cantero2020sbi]. It has been used in @thorpe2021distinct to propose new mechanisms of innocuous versus noxious sensory processing in the primary somatosensory neocortex. @Lankinen2023.06.16.545371 have used HNN-core to study crossmodal interactions between auditory and visual cortices. They performed group analysis on multiple subjects along with optimization and nonparametric statistical testing. Additionally, @szul2022diverse used it for understanding features of beta bursts in motor cortex and @fernandez2023laminar to study auditory perception.