Merge pull request #672 from suny-downstate-medical-center/development

PR from development to master - VERSION 1.0.2

CHANGES.md

@@ -1,3 +1,17 @@
+# Version 1.0.2
+
+**New features**
+
+- Added back the syncLines argument to plotRaster()
+
+- Updated conversion to/from NeuroML 2
+
+- Added RxD-based spreading depression example model
+
+**Bug fixes**
+
+- Avoid exception in plotSpikeHist() and plotSpikeFreq() when pop has no spikes
+
 # Version 1.0.1
 
 **New features**

doc/source/about.rst

@@ -199,7 +199,7 @@ Cite NetPyNE
 
 - Gast, R., Rose, D., Salomon, C., Möller, H.E., Weiskopf, N. and Knösche, T.R.. **PyRates—A Python framework for rate-based neural simulations.** PLoS ONE, 14(12), *2019*. doi: `<https://doi.org/10.1371/journal.pone.0225900>`_.
 
-- Tejada J, Roque AC, **Conductance-based models and the fragmentation problem: A case study based on hippocampal CA1 pyramidal cell models and epilepsy** `Epilepsy & Behavior, 106841, *2019*. doi: `<https://doi.org/10.1016/j.yebeh.2019.106841>`_.
+- Tejada J, Roque AC, **Conductance-based models and the fragmentation problem: A case study based on hippocampal CA1 pyramidal cell models and epilepsy** Epilepsy & Behavior, 106841, *2019*. doi: `<https://doi.org/10.1016/j.yebeh.2019.106841>`_.
 
 - Kuhl E, Alber M, Tepole BA, Cannon WR, De S, Dura-Bernal S, Garikipati K, Karniadakis GE, Lytton WW, Perdikaris P, Petzold L. **Multiscale modeling meets machine learning: What can we learn?** arXiv:1911.11958. doi: `<https://doi.org/10.1007/s11831-020-09405-5>`_. [Preprint]. *Under review in Computer Methods in Applied Mechanics and Engineering. 2019*
 

doc/source/conf.py

@@ -65,9 +65,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '1.0.1'
+version = '1.0.2'
 # The full version, including alpha/beta/rc tags.
-release = '1.0.1'
+release = '1.0.2'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

doc/source/reference.rst

@@ -908,7 +908,7 @@ Related to recording:
 * **recordTraces** - Dict of traces to record (default: {} ; example: {'V_soma':{'sec':'soma','loc':0.5,'var':'v'}})
 * **recordSpikesGids** - List of cells to record spike times from  (-1 to record from all). Can include cell gids (e.g. 5), population labels (e.g. 'S' to record from one cell of the 'S' population), or 'all', to record from all cells. (default: -1)
 * **recordStim** - Record spikes of cell stims (default: False)
-* **recordLFP** - 3D locations of local field potential (LFP) electrodes, e.g. [[50, 100, 50], [50, 200, 50]] (note the y coordinate represents depth, so will be represented as a negative value when plotted). The LFP signal in 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 |sigma| = 0.3 mS/mm. Stored in ``sim.allSimData['LFP']``. (default: False).
+* **recordLFP** - 3D locations of local field potential (LFP) electrodes, e.g. [[50, 100, 50], [50, 200, 50]] (note the y coordinate represents depth, so will be represented as a negative value when plotted). The LFP signal in 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 sigma = 0.3 mS/mm. Stored in ``sim.allSimData['LFP']``. (default: False).
 * **saveLFPCells** - Store LFP generated individually by each cell in ``sim.allSimData['LFPCells']``; can select a subset of cells to save e.g. [3, 'PYR', ('PV2', 5)] 
 * **recordStep** - Step size in ms for data recording (default: 0.1)
 
@@ -1287,6 +1287,163 @@ A representation of the instantiated network structure generated by NetPyNE is s
 	:align: center
 
 
+NetPyNE data model: Structure of instantiated network
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The model is instantiated in **sim.net** as a **Network** object. This object has a number of intrisic attributes, and others may or may not be present depending on particular implementations. The two basic elements composing "sim.net" are:
+
+* **pops** - An ordered dictionary describing all populations implemented in the network. Its entries are a key labeling the population (as defined in ``netParams.popParams``) and a value referencing the **Pop** object. This object has a number of attributes:
+
+	* **tags**: Dictionary describing different attributes of the population, related to the declaration rule that defines it. For example:
+
+		``sim.net.pops['Exc_L4'].tags = {'cellType': 'PYR', 'numCells': 100, 'pop': 'Exc_L4'}``
+
+	* **cellGids**: List of neuron identifiers (global ids) composing the population. For example:
+
+		``sim.net.pops['Exc_L4'].cellGids = [0, 1, 2, 3, 4]``
+
+	* **cellModelClass**: Type describing which particular cell model class was implemented (e.g. ``compartCell`` or ``pointCell``).
+
+* **cells** - A list of cells instantiated **locally** (this disctinction is important when implementing parallel computing). Each element in the list is a **Cell** object (among different cell model classes). As a Cell object, there are a number of intrinsic attributes:
+
+	* **gid**: cell global identification number
+
+	* **tags**: Dictionary describing different attributes of the cell, which may include some tags from the population it belongs to (tags list in ``netParams.popTagsCopiedToCells``, for example 'cellType'). These attributes are:
+
+		* **pop**: Label of the population it belongs to. For example:
+
+			``sim.net.cells[0].tags['pop'] = 'Exc_L4'``
+
+		* **x**, **y**, **z**: Cell's x-, y-, z-coordinates. For example:
+
+			``sim.net.cells[0].tags['x'] = -2.3535``
+
+		* **xnorm**, **ynorm**, **znorm**: Cell's x-, y-, z-normalized coordinates.
+
+		* Other tags depending on particular situations (for example, declaring populations in ``netParams.popParams`` with a ``cellsList``, including ``params``).
+
+	* **conns**: List of connections (this cell at the post-synaptic side). Each element in this list (a particular connection) is a dictionary with the following entries:
+
+		* **preGid**: Identity of the presynaptic cell (Gid). In the case this connection arises from a stimulation that requires a connection, the value will correspond to 'NetStim'. 
+
+		* **weight**: Weight of the connection.
+
+		* **delay**: Delay of the connection.
+
+		* **synMech**: Label of the synaptic mechanism governing this connection.
+
+		* Depending on different scenarios, other entries will appear:
+
+			* If the cell model class is NOT a point process, there will be a section/location where the synapse is put on. Then, these entries will appear:
+				* **sec**: Section hosting the synapse. 
+
+				* **loc**: Location within this section where the synapse is displayed.
+
+			* If the connection is specified as a gap junction (``netParams.connParams['rule']['gapJunction']= True``, only available for 'compartCell' cell model class), entries associated to this kind of connections will appear:
+ 
+				* **gapJunction**: Connection side ('pre' or 'post'), as specified by the rule.
+
+				* **preLoc**: Gap junction location at pre-synaptic side, as specified by the rule (for cells at 'post').
+
+				* **gapId**: Id of the cell at its connection side.
+
+				* **preGapId**: Id of the cell at other connection side.
+
+			* **shape**, **plast**, **weightIndex**: Entries used for implementing specific connectivity patterns or processes.
+
+		* **hObj**: Except for the case of gap junctions, all other connections are implemented via NEURON ``NetCon`` objects. The object itself is the value correspoding to this 'hObj' key. So, the NEURON object can be accessed (and modified) with, for example,
+
+			``sim.net.cells[0].conns[0]['hObj']``
+
+		In particular, methods corresponding to these objects can be called from command line (once the network has been instantiated). For example: 
+
+			``sim.net.cells[0].conns[0]['hObj'].syn()``.
+
+	* **stims**: List of stimuli incoming to the cell. Each element in this list is a dictionary with the following entries:
+
+		* **label**: Label of the rule specifying target parameters
+
+		* **source**: Label of the source rule that defines the incoming stimulus.
+
+		* **type**: Type of stimulus. For example:
+
+			``sim.net.cells[0].stims[0]['type'] = 'NetStim'`` or ``sim.net.cells[0].stims[0]['type'] = 'IClamp'``
+
+		* **sec**: Section where the stimulus is targeting.
+
+		* **loc**: Location within the section where the stimulus is impinging on.
+
+		* Properties defining the incoming stimuli. For example, 'rate', 'noise', 'start', and 'number' for **NetStim** (plus 'seed' to initialize the random generator).
+
+		* **hObj**: NEURON object associated to the stimuli. For example:
+
+			``sim.net.cells[0].stims[0]['hObj']``
+
+		Methods associated to the NEURON object are readily available. For example, if the object is an 'IClamp', then we can change its duration via ``sim.net.cells[0].stims[0]['hObj'].dur``
+
+
+	* Depending on the cell model class, other entries are available. In particular, for the **'compartCell'** cell model class, the following one:
+
+		* **secs**: Dictionary with the sections composing the cell. Within this dictionary, the following entries:
+
+			* **geom**: Dictionary with the geometrical properties of the cylinder composing the section. For example,
+
+				``sim.net.cells[0].secs['soma']['geom'] = {diam: 18.8, L: 18.8, Ra: 123.0}``
+	
+			* **topol**: Dictionary with the specifications of the topology (how is it connected to other sections).
+
+			* **mechs**: Dictionary with distributed mechanisms. For example,
+
+ 				``sim.net.cells[0].secs['soma']['mechs']['hh'] = {gnabar: 0.12, gkbar: 0.036, gl: 0.003, el: -70}``
+
+			* **ions**: Dictionary specyfing ionic mechanisms included in the section.
+
+			* **synMechs**: List of all synapses located at this section. Each element in this list is a dictionary with all the information related to it:
+
+				* **label**: Label describing the rule that specifies the synaptic dynamics.
+
+				* **loc**: Location within the section where the synapse is displayed
+
+				* properties associated to the definition of the synaptic model. For example, 'tau1', 'e', etcetera.
+
+				* **hObj**: NEURON object associated to the synapse. For example 
+
+					``sim.net.cells[0].secs['soma']['synMechs'][0]['hObj'] = Exp2Syn[0]``
+
+			* **pointps**: Dictionary specifying a point process governing the voltage dynamics of the section, including the name of the 'mod' where the nonlinear mechanism is defined and all neccessary parameters. 
+
+			* Other scalar properties: **spikeGenLoc**, **vinit**, etcetera.
+
+			* **hObj**: NEURON object associated to the section. For example,
+
+				``type(sim.net.cells[0].secs['soma']['hObj']) = nrn.Section``
+
+
+* Beyond these two elements ('pops' and 'cells'), there are a number of elements also defining and composing "sim.net":
+
+	* **allPops**: Dictionary with all populations composing the network. Each key correspond to a defined population, and its value is a dictionary with information about it ('tags', 'cellGids', etc).
+
+	* **allCells**: List with information about all cells (global). Each element/cell is a dictionary with all the information defining this cell.
+
+
+	* **params**: netParams specifying the network.
+
+	* **rxd**: Dictionary with all the specifications of a Reaction-Diffusion model (same format as in ``netParams.rxdParams``) PLUS the associated NEURON objects.
+
+	* **recXElectrode**: Object associated to recording LFP (if any).
+
+	* **compartCells** and **popForEachGid**: Object cells and a dictionary, {'gid': 'pop'}, for use during LFP and dipole recording.
+
+	* **cells_dpls** and **cells_dpl**: Dictionary with vectors of dipoles for each cell, over time and at one time, for use during LFP and dipole recording.
+
+	* **gid2lid**: Dictionary mapping global to local ids, {'gid': 'lid'}.
+
+	* **lastGid**: Last cell's Gid defined. Useful during development of the network.
+
+	* **lastGapId**: Last gap junction defined. Useful during development of the network.
+
+	* **preGapJunctions**: List storing information about presynaptic side, according to the direction written in the connectivity rule, for gap junctions.
+
+
 .. _dicts_dotnotation:
 
 Accessing dictionaries using dot notation: Dict and ODict classes 
@@ -1442,10 +1599,57 @@ Cell class
 		- 'delay'
 
 
-Simulation output data (spikes, etc)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Simulation output data
+^^^^^^^^^^^^^^^^^^^^^^
+
+The output data of simulation is stored in dictionaries ``sim.simData`` and ``sim.allSimData``. The former should be used in sinlge process environment, while the latter contains data gathered from all nodes from parallel context.
+The contents of simulation output data depend on the settings in ``simConfig``, and may contain the following.
+
+**1. Traces of cells**
+
+Keys of ``simData`` correspond to keys of ``simConfig.recordTraces`` (e.g. 'V_soma'), with the value of each trace containing in turn a dictionary with the list of cells for which this traces was recorded. The recorded traces will be stored as ``h.Vector`` for each cell. For example, for simConfig setting::
+
+	simConfig.recordTraces = {'V_soma':{'sec':'soma','loc':0.5,'var':'v'},
+                          	  'Ina_soma':{'sec':'soma','loc':0.5,'var':'ina'}}
+	simConfig.recordCells = [1, 3]
+	simConfig.recordStep = 0.1
+
+the ``simData`` dictionary will contain (among others)::
+
+	{'V_soma': {'cell_1': <h.Vector>, 'cell_3': <h.Vector>},
+ 	 'Ina_soma': {'cell_1': <h.Vector>, 'cell_3': <h.Vector>}
+
+
+where the length of each Vector depends on ``simConfig.duration``  and ``simConfig.recordStep``
+
+**2. Spikes**
+
+``spkt``, ``spkid`` - ordered lists of spike times and cell gids for each spike. 
+
+The ``simConfig.recordCellsSpikes`` (True, by default) can be used to record only from a subset of cells or turn off spike recordig.
+
+**3. Stimuli to the network**
+
+``stims``. For each population of ``NetStim`` or ``VecStim`` it contains the list of spike times (``h.Vector``) for each target cell. 
+Only available if ``simConfig.recordStim`` is ``True``.
+
+**4. LFP-related data**
+
+``LFP``, ``LFPCells``, ``LFPPops``. Depend on the ``recordLFP``, ``saveLFPCells``, ``saveLFPPops`` options in ``simConfig``.
+
+- ``LFP`` - is an np.array of LFP values of shape ``(num timesteps, num electrodes)``
+- ``LFPCells`` - dictionary of LFP data recorded from each cell (LFP data is in format as above)
+- ``LFPPops`` - dictionary of average LFP data recorded from each population (LFP data is in format as above)
+
+**5. Dipole-related data**
+
+``dipoleSum``, ``dipoleCells``, ``dipolePops``. Depend on the ``recordDipole``, ``saveDipoleCells``, ``saveDipolePops`` options in ``simConfig``
+
+- ``dipoleSum`` - sum of current dipole moments at each timestep ``(num timesteps, 3)``; can be used for EEG/MEG calculation
+- ``dipoleCells`` - dictionary of current dipole moments recorded for each cell (dipoles data is in format as above)
+- ``dipolePops`` - dictionary of average current dipole moments recorded for each population (dipoles data is in format as above)	
+
 
-- sim.allSimData (Dict)
 
 
 Data saved to file
@@ -1454,4 +1658,4 @@ Data saved to file
 * simConfig
 * netParams
 * net
-* simData
+* simData

examples/HHTut/HHTut.py

@@ -78,3 +78,6 @@
 simConfig.analysis['plotRaster'] = {'saveData': 'raster_data.json', 'saveFig': True, 'showFig': True} # Plot raster
 simConfig.analysis['plotTraces'] = {'include': [2], 'saveFig': True, 'showFig': True} # Plot cell traces
 simConfig.analysis['plot2Dnet'] = {'saveFig': True, 'showFig': True} # Plot 2D cells and connections
+
+
+simConfig.validateNetParams=True

examples/HHTut/HHTut_export.py

@@ -21,3 +21,5 @@
 
 from netpyne.conversion import createPythonScript
 createPythonScript('HHTut_regen.py', HHTut.netParams, HHTut.simConfig)
+
+

examples/NeuroMLImport/RS.mod

@@ -3,9 +3,9 @@ TITLE Mod file for component: Component(id=RS type=izhikevich2007Cell)
 COMMENT
 
     This NEURON file has been generated by org.neuroml.export (see https://github.com/NeuroML/org.neuroml.export)
-         org.neuroml.export  v1.8.0
-         org.neuroml.model   v1.8.0
-         jLEMS               v0.10.5
+         org.neuroml.export  v1.8.1
+         org.neuroml.model   v1.8.1
+         jLEMS               v0.10.6
 
 ENDCOMMENT
 

examples/NeuroMLImport/poissonFiringSyn.mod

@@ -3,9 +3,9 @@ TITLE Mod file for component: Component(id=poissonFiringSyn type=poissonFiringSy
 COMMENT
 
     This NEURON file has been generated by org.neuroml.export (see https://github.com/NeuroML/org.neuroml.export)
-         org.neuroml.export  v1.8.0
-         org.neuroml.model   v1.8.0
-         jLEMS               v0.10.5
+         org.neuroml.export  v1.8.1
+         org.neuroml.model   v1.8.1
+         jLEMS               v0.10.6
 
 ENDCOMMENT