Abstract
Biophysical modeling of neuronal networks helps to integrate and interpret rapidly growing and disparate experimental datasets at multiple scales. The widely used NEURON tool enables simulation ranging from the molecular to the network level. However, building data-driven large-scale network models and running parallel simulations using NEURON remains a technically difficult task. Additionally, the lack of standardization makes it hard to understand, reproduce and reuse many existing models. Here we present NetPyNE, a tool that provides both a programmatic and graphical interface to facilitate the definition, parallel simulation and analysis of data-driven multiscale network models in NEURON. Users can provide specifications at a high level via a standardized declarative language, e.g. a connectivity rule, instead of millions of explicit cell-to-cell connections. NetPyNE clearly separates model parameters from implementation code. With a single command, NetPyNE can then generate the NEURON network model and run efficiently parallelized simulations. The user can select from a variety of built-in functions to visualize and analyze the results, including connectivity matrices, voltage traces, raster plots, local field potentials or information transfer measures. NetPyNE also includes a graphical user interface, which allows users to intuitively access all key functionality, including interactive visualizations of the 3D network. NetPyNE models and results can be saved and loaded using common file formats, and imported/exported to the NeuroML standardized language, facilitating model sharing and simulator interoperability. NetPyNE automates parameter exploration via batch simulations and provides pre-defined, configurable setups to submit jobs in supercomputers. The tool’s website (www.netpyne.org) includes comprehensive documentation, tutorials and Q&A forums. NetPyNE is currently being used to develop models of different brain regions – including thalamus, cortex, claustrum, hippocampus and basal ganglia – and phenomena – including dendritic computations, oscillations, epilepsy, and transcranial magnetic stimulation. It is also employed by the Open Source Brain portal to run parallel simulation of NeuroML-based models, and by the Human Neocortical Solver (hnn.brown.edu) tool to flexibly build cortical models. NetPyNE enables both expert and inexperienced modelers to tackle challenging problems in neuroscience.
1 Introduction
The worldwide upsurge of neuroscience research through the BRAIN Initiative, Human Brain Project, and other efforts is yielding unprecedented levels of experimental findings from many different species, brain regions, scales and techniques. As highlighted in the BRAIN Initiative 2025 report,1 these initiatives require computational tools to consolidate and interpret the data, and translate isolated findings into an understanding of brain function. Biophysically-detailed multiscale modeling (MSM) provides a unique method for integrating, organizing and bridging these many types of data. For example, data coming from brain slices must be compared and consolidated with in vivo data. These data domains cannot be compared directly, but can be compared through simulations that permit one to switch readily back-and-forth between slice-simulation and in vivo simulation. Furthermore, these multiscale models permit one to develop hypotheses about how biological mechanisms underlie brain function. The MSM approach is essential to understand how subcellular, cellular and circuit-level components of complex neural systems interact to yield neural function and behavior.2–4 It also provides the bridge to more compact theoretical domains, such as low-dimensional dynamics, analytic modeling and information theory.5–7
NEURON is the leading simulator in the domain of multiscale neuronal modeling. It has 648 models available via ModelDB (modeldb.yale.edu), and 1,929 NEURON-based publications.8 However, building data-driven large-scale networks and running parallel simulations in NEURON is technically challenging,9 requiring integration of custom frameworks needed to build and organize complex model components across multiple scales. Other key elements of the modeling workflow such as ensuring replicability, optimizing parameters and analyzing results also need to be implemented separately by each user.10,11 Lack of model standardization makes it hard to understand, reproduce and reuse many existing models and simulation results.
We introduce a new software tool, NetPyNE†. NetPyNE addresses these issues and relieves the user from much of the time-consuming coding previously needed for these ancillary modeling tasks, by adding a number of automated functionalities previously unavailable for NEURON. NetPyNE enables users to consolidate complex experimental data with prior models and other external data sources at different scales into a unified computational model. Users can then simulate and analyze the model in the NetPyNE framework in order to better understand brain structure, brain dynamics and ultimately brain structure-function relationships. The NetPyNE framework combines: 1. flexible, rule-based, high-level standardized specifications covering scales from molecule to cell to network; 2. efficient parallel simulation both on stand-alone computers and in high-performance computing (HPC) clusters; 3. automated data analysis and visualization (e.g., connectivity, neural activity, information theoretic analysis); 4. standardized input/output formats, importing of existing NEURON cell models, and conversion to/from NeuroML;12,13 5. automated parameter tuning (molecular to network levels) using grid search and evolutionary algorithms. All tool features are available programmatically or via an integrated graphical user interface (GUI). This centralized organization gives the user the ability to interact readily with the various components (for building, simulating, optimizing and analyzing networks), without requiring additional installation, setup, training and format conversion across multiple tools.
NetPyNE’s high-level specifications are implemented as a declarative language designed to facilitate the definition of data-driven multiscale network models by accommodating many of the intricacies of experimental data, such as complex subcellular mechanisms, the distribution of synapses across fully-detailed dendrites, and time-varying stimulation. Contrasting with the obscurity of raw-code descriptions used in many existing models,14 NetPyNE’s standardized language provides transparent and manageable descriptions. Model specifications are then translated into the necessary NEURON components via built-in algorithms. This approach cleanly separates model specifications from the underlying technical implementation. Users avoid complex low-level coding, preventing implementation errors, inefficiencies and flawed results that are common during the development of complex multiscale models. Crucially, users retain control of the model design choices, including the conceptual model, level of biological detail, scales to include, and biological parameter values. The NetPyNE tool allows users to shift their time, effort and focus from low-level coding to designing a model that matches the biological details at the chosen scales.
NetPyNE is one of several tools that facilitate network modeling with NEURON: neuroConstruct,15 PyNN,16 Topographica,17 ARACHNE18 and BioNet.19 NetPyNE differs from these in terms of its scale and breadth, from molecular up to large networks and extracellular space simulation – it is the only tool that supports NEURON’s Reaction-Diffusion (RxD) module20,21 and which provides complex, experimentally-derived rules to distribute synapses across dendrites. NetPyNE is also unique in integrating a standardized declarative language, automated parameter optimization and a GUI designed to work across all these scales.
NetPyNE therefore streamlines the modeling workflow, consequently accelerating the iteration between modeling and experiment. By reducing programming challenges, our tool also makes multiscale modeling highly accessible to a wide range of users in the neuroscience community. NetPyNE is publicly available from www.netpyne.org, which includes installation instructions, documentation, tutorials, example models and Q&A forums. The tool has already been used by over 40 researchers in different labs to train students and to model a variety of brain regions and phenomena (see www.netpyne.org/models).22–25 Additionally, it has also been integrated with other tools in the neuroscience community: the Human Neocortical Neurosolver (https://hnn.brown.edu/), Open Source Brain26 (www.opensourcebrain.org),13 and the Neuroscience Gateway27 (www.nsgportal.org).
2 Results
2.1 Tool overview and workflow
NetPyNE’s workflow consists of four main stages: 1. high-level specification, 2. network instantiation, 3. simulation and 4. analysis and saving (Fig. 1). The first stage involves defining all the parameters required to build the network – from population sizes to cell properties to connectivity rules – and the simulation options – duration, integration step, variables to record etc. This is the main step requiring input from the user, who can provide these inputs either programmatically with NetPyNE’s declarative language, or by using the GUI. NetPyNE also enables importing of existing cell models so they can be readily used in the network.
The next stages can be accomplished with a single function call – or mouse click if using the GUI. The network instantiation step consists of creating all the cells, connections and stimuli based on the high-level parameters and rules provided by the user. The instantiated network is represented as a Python hierarchical structure that includes all the NEURON objects required to run a parallel simulation. This is followed by the simulation stage, where NetPyNE takes care of distributing the cells and connections across the available nodes, running the parallelized simulation, and gathering the data back in the master node. Here, NetPyNE is using NEURON as its back-end simulator, but all the technical complexities of parallel NEURON are hidden to the user. In the final stage, the user can plot a wide variety of figures to analyze the network and simulation output. The model and simulation output can be saved to common file formats and exported to NeuroML, a standard description for neural models.13 This enables exploring the data using other tools (e.g. Matlab) or importing and running the model using other simulators (e.g. NEST).
An additional overarching component enables users to automate these steps to run batches of simulations to explore model parameters. The user can define the range of values to explore for each parameter and customize one of the pre-defined configuration templates to automatically submit all the simulation jobs on multi-processor machines or supercomputers.
Each of these stages is implemented in modular fashion to make it possible to follow different workflows such as saving an instantiated network and then loading and running simulations at a later time. The following sections provide additional details about each simulation stage.
2.2 High-level specifications
A major challenge in building models is combining the data from many scales. In this respect, NetPyNE offers a substantial advantage by employing a human-readable, clean, rule-based shareable declarative language to specify networks and simulation configuration. These standardized high-level specifications employ a compact JSON-compatible format consisting of Python lists and dictionaries (Fig. 2). The objective of the high-level declarative language is to allow users to accurately describe the particulars and patterns observed at each biological scale, while hiding all the complex technical aspects required to implement them in NEURON. For example, one can define a probabilistic connectivity rule between two populations, instead of creating potentially millions of cell-to-cell connections directly in NEURON. The high-level language enables structured specification of all the model parameters: populations, cell properties, connectivity, input stimulation and simulation configuration.
2.2.1 Population and cell parameters
Users can define network populations, including their cell type, number of cells or density (in cells/mm3), and their spatial distribution (Fig. 2A, top 2 boxes). Morphological and biophysical properties can then be applied to subsets of cells using custom rules. This enables, for example, setting properties for all cells in a population with a certain “cell type” attribute or within a spatial region (e.g. cortical depth between 200 and 400µm) (Fig. 2A, 3rd box). The flexibility of this rule-based method allows the heterogeneity of cell populations observed experimentally to be captured. Cell parameters can be entered directly or extracted from existing cell model files, including hoc templates, Python classes or NeuroML templates (Fig. 2A, 4th box). Thus, any cell model available online can be downloaded and used as part of a network model. The rule-based definition also enables having different implementations for the same cell type – e.g., Hodgkin-Huxley multicompartment vs. Izhikevich point neuron models – and easily alternating between them or combining both in the same network model.
NetPyNE’s declarative language also supports NEURON’s reaction-diffusion (RxD)20,21 specifications (Regions, Species and Reactions). RxD enables defining the intracellular and extracellular dynamics of subcellular processes. During instantiation, these specifications are translated into RxD components integrated within the NetPyNE-defined network. This facilitates exploration of multiscale interactions, e.g., calcium regulation of HCN channels promoting persistent network activity.28,29
2.2.2 Connectivity and stimulation parameters
A strong emphasis was placed on making the connectivity rules flexible and broad enough to account for myriad experimental observations. The subset of pre-and post-synaptic cells can be selected based on a combination of attributes such as cell type or spatial location. The user can also select the target synaptic mechanisms (e.g. AMPA or GABAA), for which parameters will have been previously defined, and a list of cell sections (compartments) along which synapses will be distributed. Multiple connectivity functions are available, including all-to-all, probabilistic, convergent and divergent. A user-defined cell-to-cell connection matrix can also be provided, enabling any arbitrary connectivity pattern. Additionally, connectivity parameters (e.g., weight, probability or delay) can be specified as a function of pre-and post-synaptic spatial properties. This enables implementation of complex biological patterns, such as delays or connection probabilities that depend on distance between cells, or weights that depend on the post-synaptic neuron’s cortical depth (Fig. 2A, bottom two boxes). Electrical gap junctions and learning mechanisms – spike-timing dependent plasticity and reinforcement learning – can be readily incorporated.
NetPyNE also supports detailed specification of the subcellular distribution of synapses along the dendrites. This enables directly incorporating subcellular synaptic density maps obtained, for example, via optogenetic techniques such as subcellular Channelrhodopsin-2-Assisted Circuit Mapping (sCRACM)30,31 (Fig. 3A left). NetPyNE enables defining synapse distributions based on 1. categorical information on dendritic subsets (e.g., obliques, spiny sections); 2. path distance from a particular cell point (typically from the soma); and 3. location as a function of underlying 1D, 2D, or 3D tissue coordinates, e.g., normalized cortical depth (NCD) – from pia to white matter. These rules and the corresponding synapse locations will be automatically adapted to morphologies of different cell types and models, which could range from simple 5-compartment cells to full reconstructions with thousands of compartments (Fig. 3A, right). This enables users to more closely match neuronal synaptic densities – which can be visualized via NetPyNE (Fig. 3A, right) – to the complex subcellular synaptic location patterns observed experimentally.30–33
Network models typically employ artificial stimulation to reproduce the effect of afferent inputs that are not explicitly modeled, e.g. inputs from thalamus and V2 targeting a model of V1. NetPyNE supports a variety of stimulation sources, including current clamps and artificial spike generators (using the NEURON NetStim object). These can be placed on target cells using the same flexible, customizable rules previously described for connections. Additionally, NetPyNE supports the generation of biological stimulation patterns, including random white-noise activity and oscillations in particular bands or with a particular spectrum. Users can also employ experimentally recorded input patterns.
2.2.3 Simulation configuration
Up to now we have described how to define the network parameters. In a separate data structure, generally provided in a separate file, the user configures the parameters related to a simulation run. These include the simulation duration, time-step, parallelization options, output verbosity, cell variables to record (e.g., voltage or calcium concentration) and cells to record from, LFP recording options, what to save to file and in what format, graphs to plot and graphing options, and others. All options have default values so only those being customized are required. These options give the user precise control over the simulation configuration.
2.3 Network instantiation
NetPyNE generates a readily simulatable NEURON model containing all the elements and properties described by the user in the rule-based high-level specifications. These elements include molecular processes, cells, connections, stimulators and simulation options. This prevents the errors and flawed results that are common when creating these elements directly via procedural coding (in Python/NEURON), due to the layered complexities of these multiscale models.
Traditionally, it has been up to the user to provide an easy way to access the components of a NEURON network model, e.g., the connections or stimulators targeting a cell, the sections in a cell, or the properties and mechanisms in each section. This feature is absent in many existing models. Hence, inspecting these models requires calling multiple, and sometimes obscure, NEURON functions (e.g., h.MechanismStandard()). Other models include some form of indexing for the elements at some scales, but, given this is not enforced, their structure and naming can vary significantly across models.
In contrast, all networks generated by NetPyNE are consistently represented as a nested Python structure: the root network object contains a list of populations and cells; each cell contains lists or dictionaries with its properties, sections, connections and stimulators; each section contains dictionaries with its morphology and mechanisms;etc (see Fig. 4). This standardized hierarchical organization enables the user to easily access any element or parameter of the network. For example, |net.cells[5].secs.soma.mechs.hh.gbar— provides access to the maximum sodium conductance in the soma of cell number 5. The NEURON objects (Sections, NetStims, IClamps, etc) required to run the simulation are embedded within this Python structure, so they can also be accessed intuitively.
2.4 Parallel simulation
Computational needs for running much larger and more complex neural simulations are constantly increasing as researchers attempt to reproduce fast-growing experimental datasets.2,4,22,34 Fortunately, parallelization methods and high performance computing (HPC, supercomputing) resources are becoming increasingly available to the average user.27,27,35–40
The NEURON simulator provides the ParallelContext module, which enables parallelizing the simulation computations across different nodes. However, this is an elaborate process that involves distributing computations across nodes in a balanced manner, gathering and reassembling simulation results for post-processing, and ensuring simulation results are replicable and independent of the number of processors used. Therefore, appropriate and efficient parallelization of network simulations requires design, implementation and deployment of a variety of techniques, some complex, many obscure, and generally not accessible to the average user.41
NetPyNE handles all these burdensome tasks so the user can run efficiently parallelized simulations with a single function call or mouse click. All model elements (cells, connections, stimulators, etc) are distributed across processors using a round-robin algorithm, which generally results in balanced computation load on each processor.41,42 After the simulation run is complete, NetPyNE gathers in the master all the network metadata (cells, connections, etc) and simulation results (spike times, voltage traces, LFP signal, etc) so it can be analyzed. As models scale up, it becomes unfeasible to store the simulation results on a single centralized master node. NetPyNE offers distributed data saving methods that reduce both the runtime memory required and the gathering time. Distributed data saving means multiple compute nodes can write information in parallel, either at intervals during simulation runtime, or once the simulation is completed. The output files are later merged for analysis. Random number generators (RNGs) are used to generate cell locations, connectivity properties and the spike times of inputs. To ensure simulation replicability across different numbers of cores, RNGs are initialized based on pre-and post-synaptic cell global identifiers (gids), a seed value associated to the RNG purpose (e.g., connectivity or locations) and a global seed. The purpose and global seeds can be modified to run statistically independent, but otherwise identical simulations. Using previously tested and debugged implementations reduces the chances of replicability issues and inefficiencies.
We performed parallelization performance analyses that demonstrated run time scales appropriately as a function of number of cells (tested up to 100,000) and compute nodes (tested up to 512).43 Simulations were developed and executed using NetPyNE and NEURON on the XSEDE Comet supercomputer via the Neuroscience Gateway27 (www.nsgportal.org). The Neuroscience Gateway, which provides neuroscientists with free and easy access to supercomputers, includes NetPyNE as one of the tools available via their web portal. Large-scale models – including one with 10k multicompartment neurons and 30 million synapses22 and one with over 80k point neurons and 300 million synapses23 – have been simulated in both the XSEDE Comet supercomputer and Google Cloud supercomputers.
2.5 Analysis of network and simulation output
To extract conclusions from neural simulations it is necessary to adequately visualize and analyze the raw data generated. NetPyNE includes built-in implementations of a wide range of visualization and analysis functions commonly used in neuroscience (Fig. 6). All analysis functions include options to customize the desired output. Functions available after instantiation to visualize and analyze the network structure include: 1. intracellular and extracellular RxD species concentration in a 2D region; 2. matrix or stacked bar plot of connectivity; 3. 2D representation of cell locations and connections; and 4. 3D cell morphology with color-coded variable (e.g. number of synapses per segment). Functions available after a simulation run to visualize and analyze the simulation output include: 1. time-resolved traces of any recorded cell variable (e.g., voltage, synaptic current or ion concentration); 2. relative and absolute amplitudes of post-synaptic potentials; 3. spiking statistics (boxplot) of rate, the interspike interval coefficient of variation (ISI CV) and synchrony;44 4. power spectral density of firing rates; and 5. information theory measures, including normalized transfer entropy and Granger causality.
A major feature of our tool is the ability to place extracellular electrodes to record LFPs at any arbitrary 3D locations within the network, similar to the approach offered by the LFPy45 and LFPsim46 add-ons to NEURON. The LFP signal at each electrode is obtained by summing the extracellular potential contributed by each neuronal segment, calculated using the “line source approximation” and assuming an Ohmic medium with conductivity.46,47 The user can then plot the location of each electrode, together with the recorded LFP signal and its power spectral density and spectrogram (Fig. 7). The ability to record and analyze LFPs facilitates reproducing experimental datasets that include this commonly used measure.47
2.6 Data saving and exporting
NetPyNE permits saving and loading of all model components and results separately or in combination: high-level specifications, network instance, simulation configuration, simulation data, and simulation analysis results. Saving network instances enables loading a specific saved network with all explicit cells and connections, without the need to re-generate these from the high-level connectivity rules. NetPyNE supports several standard file formats: pickle, JSON, MAT, and HDF5. The use of common file formats allows network structure and simulation results to be easily analyzed using other tools such as Matlab or Python Pandas.
Network instances can also be exported to or imported from NeuroML,13 a standard declarative format for neural models, and SONATA (https://github.com/AllenInstitute/sonata), a format standard for neural models proposed by the Blue Brain Project and Allen Institute for Brain Science. These formats are also supported by other simulation tools, so that models developed using NetPyNE can be exported, explored and simulated in other tools Brian,48 MOOSE,49,50 PyNN,16 Bionet19 or Open Source Brain.26 Similarly simulations from these other tools can be imported into NetPyNE. This feature also enables any NetPyNE model to be visualized via the Open Source Brain portal, and permits a NeuroML model hosted on the portal to be parallelized across multiple cores (e.g., on HPC) using NetPyNE.
2.7 Parameter optimization and exploration via batch simulations
Parameter optimization involves finding sets of parameters that lead to a desired output in a model. This process is required since biological models are never fully constrained by experimental data. Single neuron and network models typically include many not-fully constrained parameters that can be modified within a known biological range of values. These may be highly sensitive, small variations leading to large differences in output, and thus require fine tuning within complex multidimensional spaces to match experimental data. A related concept is that of parameter exploration. Once a model is tuned to reproduce certain biological features, it is common to explore other parameters to understand their relation to certain model features, e.g., how synaptic weights affect network oscillations,51 or the effect of different pharmacological treatments on pathological symptoms.25,52
Many different approaches exist to perform parameter optimization and exploration. Manual tuning approaches usually require a great deal of time and expertise.53,54 NetPyNE provides built-in support for several automated methods that have been successfully applied to both single cell and network optimization: grid-search and evolutionary algorithms.2,55–60 Grid search refers to evaluating all combinations of a fixed set of values for each parameter, resulting in a grid-like sampling of the multidimensional parameter space. Evolutionary algorithms (EAs) employ principles derived from evolution – selection, reproduction and mutation – to iteratively improve the model solutions. They are computationally efficient when handling complex, non-smooth and high-dimensional parameter spaces.54 Evolutionary algorithms effectively follow the principles of biological evolution: here a population of models evolves by changing parameters in a way that emulates crossover events and mutation over generations until individuals reach a desired fitness level.
NetPyNE provides an automated parameter optimization and exploration framework specifically tailored to multiscale bio-physically detailed models. Our tool facilitates the multiple steps required: 1. parameterizing the model and selecting appropriate value ranges; 2. providing a fitness function if using EA; 3. customizing the optimization/exploration algorithm options; 4. running the batch simulations; and 5. managing and analyzing batch simulation parameters and outputs. To facilitate parameter selection, all of the network specifications are readily available to the user via NetPyNE’s standardized, declarative data structure – from molecular concentrations and ionic channel conductances to long-range input firing rates.
Both parameter optimization and exploration involve running many instances of the network with different parameter values, and thus typically require parallelization. For these purposes, NetPyNE parallelization is implemented at two levels: 1. NEURON simulation level – cell computations distributed across nodes; and 2. batch level – many NEURON simulations with different parameters executed in parallel.55 NetPyNE includes predefined execution setups to automatically run parallelized batch simulations on different environments: 1. multiprocessor local machines or servers via standard message passing interface (MPI) support; 2. the Neuroscience Gateway (NSG) online portal, which includes compressing the files and uploading a zip file via RESTful services; 3. HPC systems (supercomputers) that employ job queuing systems such as PBS Torque or SLURM (e.g. Google Cloud Computing HPCs). Users will be able to select the most suitable environment setup and customize options if necessary, including any optimization algorithm metaparameters such as population size, mutation rate, etc. A simple high-level command will then take care of launching the batch simulations to optimize or to explore the model.
2.8 Graphical User Interface (GUI)
The GUI enables users to more intuitively access NetPyNE functionalities. It divides the workflow into two tabs: network definition and network exploration, simulation and analysis. From the first tab it is possible to define – or import from various formats – the high-level network parameters/rules and simulation configuration (Fig. 2B). Parameter specification is greatly facilitated by having clearly structured and labeled sets of parameters, graphics to represent different components, drop-down lists, autocomplete forms and automated suggestions. The GUI also includes an interactive Python console and full bidirectional synchronization with the underlying Python-based model – parameters changed via the Python console will be reflected in the GUI, and vice versa. In the second tab the user can interactively visualize the instantiated network in 3D, run parallel simulations and display all the available plots to analyze the network and simulation results. An example of a multiscale model visualized, simulated and analyzed using the GUI is shown in Fig. 8. The code and further details of this example are available at https://github.com/Neurosim-lab/netpyne/tree/development/examples/rxdnet.
The GUI is particularly useful for beginners, students or non-computational researchers who can rapidly build networks without knowledge of coding and without learning NetPyNE’s declarative syntax. From there, they can simulate and explore multiscale subcellular, cellular and network models with varying degrees of complexity, from integrate-and-fire up to large-scale simulations that require HPCs. The GUI is also useful for modelers, who can easily prototype new models graphically and later extend the model programmatically using automatically generated Python scripts. Finally, the GUI is useful – independently of expertise level – to explore and visualize existing models developed by oneself, developed by other users programmatically, or imported from other simulators. Understanding unfamiliar models is easier if users can navigate through all the high-level parameters in a structured manner and visualize the instantiated network structure, instead of just looking at the model definition code.61
2.9 Using the tool for training
In addition to the tool itself, we have developed detailed online documentation, step-by-step tutorials (www.netpyne.org), and example models. The code has been released as open source (https://github.com/Neurosim-lab/netpyne). Ongoing support is provided via a mailing list (with 50 subscribed users) and active Q&A forums (150 posts and over 5,000 views in the first year): www.netpyne.org/mailing, www.netpyne.org/forum and netpyne.org/neuron-forum. Users have been able to quickly learn to build, simulate and explore models that illustrate fundamental neuroscience concepts, making NetPyNE a useful tool to train students. To disseminate the tool we have also provided NetPyNE training at conference workshops and tutorials, summer schools and university courses. Several labs are beginning to use NetPyNE to train students and postdocs, as well as for research purposes.
2.10 Using the tool for research
Models being developed in NetPyNE cover a wide range of regions and phenomena, including, among others, thalamus, sensory and motor cortices,22,25 claustrum,24 striatum, cerebellum, hippocampus, schizophrenia, epilepsy, transcranial magnetic stimulation (TMS), and electro-and magneto-encephalography (EEG/MEG) signals.62 Several models published in other languages have been converted into NetPyNE. These include models of cortex exploring EEG/MEG signals (https://hnn.brown.edu/), thalamocortical networks23,63,64 (Fig. 9A), CA1 microcircuits65,66 (Fig. 9B) and a dentate gyrus network67,68 (Fig. 9). Currently, NetPyNE is being used in over 40 models – the full list is available at www.netpyne.org/models.
Our recent model of primary motor cortex (M1) microcircuits22,25,56 constitutes an illustrative example where NetPyNE enabled the integration of complex experimental data at multiple scales: it simulates over 10,000 biophysically detailed neurons and 30 million synaptic connections. Neuron densities, classes, morphology and biophysics, and connectivity at the long-range, local and dendritic scale were derived from published experimental data.31–33,69,70,70–76 Results yielded insights into circuit information pathways, oscillatory coding mechanisms and the role of HCN in modulating corticospinal output.22 A scaled down version (180 neurons) of the M1 model is illustrated Fig. 10.
3 Discussion
NetPyNE is a high-level Python interface to the NEURON simulator that facilitates the definition, parallel simulation, optimization and analysis of data-driven brain circuits models. NetPyNE provides a systematic, standardized approach to biologically-detailed multiscale modeling. This broad scope offers users the option to look at the neuronal network simulation in the context of extracellular space, or to focus on cellular level models in the context of the neuronal network, or to do detailed spine and dendrite modeling in the context of the whole cell and the network, to give a few examples. Swapping focus back-and-forth across scales allows the investigator to understand scale integration in a way that cannot be done in the experimental preparation. In this way, multiscale modeling complements experimentation by combining and making interpretable previously incommensurable datasets.In silico models developed with NetPyNE can serve as testbeds that can be probed extensively and precisely in ways that parallel experimentation to make testable predictions. Simulation can also go beyond the capabilities of physical experimentation to build comprehension and develop novel theoretical constructs.2,4,34,77
By providing support for NEURON’s intracellular and extracellular reaction-diffusion module (RxD),20,21 NetPyNE helps to couple molecular-level chemophysiology – historically neglected in computational neuroscience – to the classical electrophysiology at subcellular, cellular and network scales. RxD allows the user to specify and simulate the diffusion of molecules (e.g., calcium, potassium or IP3) intracellularly, subcellularly (by including organelles such as endoplasmic reticulum and mitochondria), and extracellularly in the context of signaling and enzymatic processing –e.g., metabolism, phosphorylation, buffering, second messenger cascades. This relates the scale of molecular interactions with that of cells and networks.
NetPyNE rules allow users to not only define connections at the cell-to-cell level, but also to compactly express highly specific patterns of the subcellular distribution of synapses, e.g., depending on the neurite cortical depth or path distance from soma. Such distinct innervation patterns have been shown to depend on brain region, cell type and location and are likely to subserve important information processing functions and have effects at multiple scales.30,32,78,79 Although some simulation tools (Genesis,49 MOOSE, PyNN,16 BioNet19 and neuroConstruct15) include basic dendritic level connectivity, they do not provide high-level declarations to describe complex subcellular synaptic location patterns extracted from experimental data.
NetPyNE’s high-level language has advantages over procedural description in that it provides a human-readable, declarative format, accompanied by a parallel graphical representation, making models easier to read, modify, share and reuse. Other simulation tools such as PyNN, NEST, Brian or BioNet include high-level specifications in the context of the underlying procedural language used for all aspects of model instantiation, running and initial analysis. Procedural languages require ordering by the logic of execution rather than the logic of the conceptual model. Since the NetPyNE declarative format is order free, it can be cleanly organized by scale, by cell type, or by region at the discretion of the user. This declarative description can then be stored in standardized formats that can be readily translated into shareable data formats for use with other simulators. The trade-off is that users of a declarative language are constrained to express inputs according to the standardized formats provided, offering somewhat less flexibility compared to a procedural language. However, NetPyNE has been designed so that many fields are agglutinative, allowing multiple descriptors to be provided together to hone in on particular subsets of cells, subcells or subnetworks.
Developers of several applications and languages, including NeuroML, PyNN, SONATA and NetPyNE, are working together to ensure interoperability between their different formats. NeuroML13 is a widely-used model specification language for computational neuroscience which can store instantiated networks through an explicit list of populations of cells and their connections, without higher level specification rules. We are collaborating with the NeuroML developers to incorporate high-level specifications similar to those used in NetPyNE, e.g., compact connectivity rules (see https://github.com/NeuroML/NeuroMLlite). The hope is that these compact network descriptions become a standard in the field so that they can be used to produce identical network instances across different simulators. To further promote standardization and interoperability, we and other groups working on large-scale networks founded the INCF Special Interest Group on “Standardized Representations of Network Structures” (https://www.incf.org/activities/standards-and-best-practices/incf-special-interest-groups/incf-sig-on-standardised).
To ensure accessibility to a wide range of researchers, including modelers, students and experimentalists, NetPyNE combines many of the modeling workflow features under a single framework with both a programmatic and graphical interface. The GUI provides an intuitive way to learn to use the tool and explore all the different components and features interactively. Exporting the generated network to a Python script enables more advanced users to extend the model programmatically.
A major difficulty in building complex models is optimizing its many parameters within biological constrains to reproduce experimental results.53,54 Multiple tools are available to fit detailed single cell models to electrophysiological data: BluePyOpt,80 Optimizer,81 Pypet82 or NeuroTune.83 However, these optimizers work within a single scale rather than optimizing across scales to study complex cells in complex circuits. NetPyNE provides a parameter optimization framework designed specifically to tackle this problem, thus enabling and encouraging the exploration of interactions across scales. It also closely integrates with the simulator rather than being a standalone optimizer, which would require expertise to interface properly. NetPyNE offers multiple optimization methods, including evolutionary algorithms, which are computationally efficient for handling the non-smooth high-dimensional parameter spaces found in this domain.53,54,84
Tools such as NetPyNE that provide insights into multiscale interactions are particularly important for the understanding of brain disorders, which always involve interactions across spatial and temporal scale domains.85 Development of novel biomarkers, increased segregation of disease subtypes, new treatments, and personalized treatments, all require that details of molecular, anatomical, functional, and dynamic organization that have been demonstrated in isolation be related to one another. Simulations and analyses developed in NetPyNE provide a way to link these scales, from the molecular processes of pharmacology, to cell biophysics, electrophysiology, neural dynamics, population oscillations, EEG/MEG signals and behavioral measures.
4 Methods
4.1 Overview of tool components and workflow
NetPyNE is implemented as a Python package that acts as a high-level interface to the NEURON simulator. The package is divided into several subpackages, which roughly match the components depicted in the workflow diagram in Fig. 1. The specs subpackage contains modules related to definition of high-level specifications. The sim subpackage contains modules related to running the simulation. It also serves as a shared container that encapsulates and provides easy access to the remaining subpackages, including methods to build the network or analyze the output, and the actual instantiated network and cell objects, etc. From the user perspective, the basic modeling workflow is divided into three steps: defining the network parameters (populations, cell rules, connectivity rules, etc) inside an object of the class specs.NetParams; setting the simulation configuration options (run time, integration interval, recording option, etc) inside an object of the class specs.SimConfig; and passing these two objects to a wrapper function (sim.createSimulateAnalyze()) that takes care of creating the network, running the simulation and analyzing the output.
4.2 Network instantiation
The following standard sequence of events are executed internally to instantiate a network from the high-level specifications in the netParams object: 1. create a Network object and add to it a set of Population and Cell objects based on parameters; 2. set cell properties (morphology and biophysics) based on cellParams parameters (checking which cells match the conditions of each rule); 3. create molecular-level RxD objects based on rxdParams parameters; 4. add stimulation (IClamps, NetStims, etc) to the cells based on stimSourceParams and stimTargetParams parameters; and 5. create a set of connections based on connParams and subConnParams parameters (checking which presynpatic and postsynaptic cells match the conn rule conditions), with the synaptic parameters specified in synMechParams. After this process is completed all the resulting NEURON objects will be contained and easily accessible within a hierarchical Python structure (object sim.net of the class Network) as depicted in Fig. 4.
The network building task is further complicated by the need to implement parallel NEURON simulations in an efficient and replicable manner, independent of the number of processors employed. Random number generators (RNGs) are used in several steps of the building process, including cell locations, connectivity properties and the spike times of input stimuli (e.g., Netstims). To ensure random independent streams that can be replicated deterministically when running on different number of cores we employed NEURON’s Random123 RNG from the h.Random class. This versatile cryptographic quality RNG is initialized using three seed values, which, in our case, will include a global seed value and two other values related to unique properties of the cells involved, e.g., for probabilistic connections, the gids of the pre-and post-synaptic cells.
To run NEURON parallel simulations NetPyNE employs a pc object of the class h.ParallelContext(), which is created when the sim object is first initialized. During the creation of the network, the cells are registered via the pc methods to enable exchange and recording of spikes across compute nodes. Prior to running the simulation, global variables, such as temperature or initial voltages are initialized, and the recording of any traces (e.g., cell voltages) and LFP is set up by creating the appropriate containers (e.g., h.Vectors()) and calling the recording methods. After running the parallel simulation via pc.solve(), data (cells, connections, spike times, recorded traces, LFPs, etc) is gathered into the master node from all compute nodes using the pc.py alltoall() method. Alternatively, distributed saving enables writing the output of each node to file and combining these files after the simulation has ended. After gathering, the built-in analysis functions have direct access to all the network and simulation output data via sim.net.allCells and sim.allSimData.
4.3 Importing and exporting
NetPyNE enables importing existing cells in hoc or Python, including both templates/classes and instantiated cells. To do this NetPyNE internally runs the hoc or Python cell model, extracts all the relevant cell parameters (morphology, mechanisms, point processes, synapses, etc) and stores them in the NetPyNE JSON-like format used for high-level specifications. The hoc or Python cell model is then completely removed from memory so later simulations are not affected.
Importing and exporting to other formats such as NeuroML or SONATA requires mapping the different model components across formats. To ensure validity of the conversion we have compared simulation outputs from each tool, or converted back to the original format and compared to the original model. Tests on mappings between NetPyNE and NeuroML can be found at https://github.com/OpenSourceBrain/NetPyNEShowcase.
4.4 Batch simulations
Exploring or fitting model parameters typically involves running many simulations with small variations in some parameters. NetPyNE facilitates this process by automatically modifying these parameters and running all the simulations based on a set of high-level instructions provided by the user. Although two different approaches are available – grid search and evolutionary algorithms – both require a similar set up. The user creates a Batch object that specifies the range of parameters values to be explored and the run configuration (e.g., use 48 cores on a cluster with SLURM workload manager). For evolutionary algorithms, the user also needs to provide a Python function that acts as the algorithm fitness function, which can include variables from the network and simulation output data (e.g., number of cells or firing rate of a population.) The tool website includes documentation and examples on how to run the different types of batch simulations.
Once the batch configuration is completed, the user can call the Batch.run() method to trigger the execution of the batch simulations. NetPyNE will internally iterate over the different parameter combinations. For each one, NetPyNE will 1. set the varying parameters in the simulation configuration (SimConfig object) and save it to file, 2. launch a job to run the NEURON simulation based on the run options provided by the user (e.g., submit a SLURM job), 3. store the simulation output with a unique filename, and 4. repeat for the next parameter set, or if using evolutionary algorithms, calculate the fitness values and the next generation of individuals (parameter sets).
To implement the evolutionary algorithm optimization we made use of the Inspyred Python package (https://pythonhosted.org/inspyred/). Although we make use of Inspyred subroutines for each of the algorithms, these are particularized to our problem, using parameters and fitness values obtained from NetPyNE data structures, and running parallel simulations under the NEURON environment either in multiprocessor machines via MPI or supercomputers via workload managers.
4.5 Graphical User Interface
The NetPyNE GUI is implemented on top of Geppetto,86 an open-source platform that provides the infrastructure for building tools for visualizing neuroscience models and data and managing simulations in a highly accessible way. The GUI is defined using Javascript, React and HTML5. This offers a flexible and intuitive way to create advanced layouts while still enabling each of the elements of the interface to be synchronized with the Python model. The interactive Python backend is implemented as a Jupyter Notebook extension which provides direct communication with the Python kernel. This makes it possible to synchronize the data model underlying the GUI with a custom Python-based NetPyNE model. This functionality is at the heart of the GUI and means any change made to the NetPyNE model in Python kernel is immediately reflected in the GUI and vice versa. The tool’s GUI is available at https://github.com/MetaCell/NetPyNE-UI and is under active development.
5 Acknowledgements
This work was funded by the following grants: NIH grant U01EB017695, DOH01-C32250GG-3450000, NIH R01EB022903, NIH R01MH086638, and NIH 2R01DC012947-06A1. PG was funded by the Wellcome Trust (101445). We are thankful to all the contributors that have collaborated in the development of this open source tool via GitHub (https://github.com/Neurosim-lab/netpyne).
Footnotes
↵† NetPyNE: Network specification, simulation and analysis using Python and NEURON.