Debian Codegraph @

docs/autodocs/source/bionet.rst

raw
1 BioNet
2 ======
3
4 .. figure:: _static/images/bmtk_architecture_bionet_highlight.jpg
5 :scale: 40%
6
7 BioNet is a high-level interface to `NEURON <http://neuron.yale.edu/neuron/>`_ that facilitates simulations of
8 large-scale networks of multicompartmental neurons. Some of its main features include:
9
10 * Automatically integrates MPI for parallel simulations without the need for extra coding.
11
12 * Supports models and morphologies from the Allen `Cell-Types Database <http://celltypes.brain-map.org/data>`_, as well
13 as custom hoc and NeuroML2 cell and synapse models.
14
15 * Use spike-trains, synaptic connections, current clamps, or even extracellular stimulation to drive network firing.
16
17 * Can simulate extracellular field recordings.
18
19
20 Inputs
21 --------
22 Inputs can be specified in the “inputs” sections of the `simulation config <./simulators.html#configuration-files>`_,
23 following the rules specified in the `SONATA Data format <https://github.com/AllenInstitute/sonata>`_.
24
25 SONATA Spike-Trains
26 +++++++++++++++++++
27 The modeler may wish to have certain cells in the circuit generate a pre-arranged series of spikes to drive the network.
28 These cells must have ``model_type`` value ``virtual`` and are not actual cell objects (you can’t record from them). You
29 may use either a `SONATA spike file <https://github.com/AllenInstitute/sonata/blob/master/docs/SONATA_DEVELOPER_GUIDE.md#spike-file>`_,
30 an NWB file, or a space-separated CSV file with columns **node_id**, **population**, and **timestamps**. The following
31 shows some examples of how to generate `spike-train files using bmtk <./analyzer.html#creating-spike-trains>`_.
32
33 .. code:: json
34
35 {
36 "LGN_spikes": {
37 "input_type": "spikes",
38 "module": "sonata",
39 "input_file": "./inputs/lgn_spikes.h5",
40 "node_set": {"population": "lgn"}
41 }
42 }
43
44 * module: either sonata, hdf5, CSV, or nwb: depending on the format of the spikes file
45
46 * `node_set <./simulators.html#node-sets>`_: used to filter which cells will receive the inputs
47
48 * input_file: path to file contain spike-trains for one or mode node
49
50
51 `Extracelluar ElectroPhysiology (ECEPhys) Probe Data (NWB 2.0) Spikes <ecephys_probe.html>`_
52 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
53 An increasing number of ECEPhys electrode experimental data is being release to the public in NWB format, such as the
54 `Allen Visual Coding - Neuropixels <https://allensdk.readthedocs.io/en/latest/visual_coding_neuropixels.html>`_ dataset or through
55 `DANDI <https://dandiarchive.org/>`_. While it is possible to manually convert this data into SONATA spike-trains to
56 encorpate into your simulations, the `ecephys_probe` spikes module can do this automatically; fetching spikes from ECEPhys units
57 and converting them to virtual cells for network input into your model.
58
59 For example, using a session NWB downloaded using the AllenSDK, the below example wil randomly l map "LGd" cells from the session onto our
60 "LGN" population, and filter out only spikes that occur between 10.0 and 12.0 seconds
61
62 .. code:: json
63
64 {
65 "inputs": {
66 "LGN_spikes": {
67 "input_type": "spikes",
68 "module": "ecephys_probe",
69 "input_file": "./session_715093703.nwb",
70 "node_set": {"population": "LGN"},
71 "mapping": "sample_with_replacement",
72 "units": {
73 "location": "LGd"
74 },
75 "interval": [10000.0, 12000.0]
76 }
77 }
78 }
79
80 See the `documentation <ecephys_probe.html>`_ for more information and advanced features.
81
82
83 `Current Clamps <current_clamps.html>`_
84 +++++++++++++++++++++++++++++++++++++++
85 May use one step current clamp-on multiple nodes, or have one node receive multiple current injections. Currently ;)
86 only support injections at the soma.
87
88 .. code:: json
89
90 {
91 "current_clamp_1": {
92 "input_type": "current_clamp",
93 "module": "IClamp",
94 "node_set": "biophys_cells",
95 "amp": 0.1500,
96 "delay": 500.0,
97 "duration": 500.0
98 }
99 }
100
101 See `documentation <current_clamps.html>`_ for more details on using current clamp inputs.
102
103
104 Voltage Clamp
105 +++++++++++++
106
107 Extracellular Stimulation
108 +++++++++++++++++++++++++
109 Allows for a set of external electrodes to provide a continuous stimulation in the neuropil. Requires a space-separated CSV file with one row for each electrode:
110
111 .. code:: text
112 :name: xstim_electrode.csv
113
114 ip pos_x pos_y pos_z rotation_x rotation_y rotation_z
115 0 6.1803398874989481 0.0 19.021130325903069 0.0 0.0 0.0
116
117 And in the configuration file
118
119 .. code:: json
120
121 {
122 "extra_stim": {
123 "input_type": "lfp",
124 "module": "xstim",
125 "node_set": "all",
126 "positions_file": "./inputs/xstim_electrode.csv",
127 "resistance": 300.0,
128 "waveform": {
129 "shape": "sin",
130 "del": 1000.0,
131 "amp": 0.100,
132 "dur": 2000.0,
133 "freq": 8.0
134 }
135 }
136 }
137
138 * module: Always xstim
139 * `node_set <./simulators.html#node-sets>`_: used to filter which cells will receive the inputs
140 * positions_file: space separated file containing cartesian coordinates of the electrodes.
141 * resistance: extracellular resistance between electrode and cells in Ohms / cm^3 (default: 300.0)
142 * waveform: form of the input, requires arguments “shape”, “amp” (in pA), “del” (delay in ms) and “dur” (duration in ms). Shape may either be “dc” or “sin” (with optional arguments “freq”, “phase” and “offset”)
143
144
145 Spontaneous Firing
146 ++++++++++++++++++
147
148
149 Outputs
150 -------
151 Spikes
152 ++++++
153 By default, all non-virtual cells in the circuit will have all their spikes at the soma recorded. The “spike_threadhold”
154 the parameter in the “run” block of the simulation config is used to determine what counts as a spike for a conductance model
155 cell.
156
157
158 Membrane and Intracellular Variables
159 ++++++++++++++++++++++++++++++++++++
160 Used to record the time trace of specific cell variables, usually the membrane potential (v). For multi-compartmental
161 cells the report can record from any segment that contains mechanics for the desired variable. See
162 `SONATA docs <https://github.com/AllenInstitute/sonata/blob/master/docs/SONATA_DEVELOPER_GUIDE.md#simulation-output---reports>`_
163 for more information about how multi-segment recordings are represented.
164
165 .. code:: json
166
167 {
168 "calcium_concentration": {
169 "module": "membrane_report",
170 "cells": {"population": "biophysical"},
171 "variable_name": "cai",
172 "sections": "soma",
173 "file_name": "cai_traces.h5"
174 },
175 "membrane_potential": {
176 "module": "membrane_report",
177 "cells": {"node_ids": [0, 1, 2, 3, 4, 5]},
178 "variable_name": "v",
179 "sections": "all",
180 "file_name": "cai_traces.h5"
181 }
182 }
183
184 * variable_name: name of the variable being recorded, will depend on the cell model
185 * cells: a `node_set <./simulators.html#node-sets>`_ to filter out what cells to record.
186 * sections: either “all”, “soma”, “basal” or “apical”
187 * file_name: name of the file where traces will be recorded, under the “output_dir”. If not specified the report title
188 will be used, eg “calcium_concentration.h5” and “membrane_potential.h5”
189
190 .. warning::
191 Disk space can be an issue when recording membrane variables. For large networks recording all segments or all cells, every 1-second simulation, can cause BMTK to try to write output files in the 100s of GB or even TB.
192
193
194
195 Extracellular Potential
196 +++++++++++++++++++++++
197 Will simulate recording from an extracellular electrode placed in the neuropil. See
198 `SONATA documentation <https://github.com/AllenInstitute/sonata/blob/master/docs/SONATA_DEVELOPER_GUIDE.md#extracellular-report>`_.
199 Requires a space-separated CSV file to specify the location of each recording channel:
200
201 .. code:: text
202 :name: ./components/xelectrode/linear_probe.csv
203
204 channel x_pos y_pos z_pos
205 0 10.0 0 5.0
206 1 10.0 -10 5.0
207 2 10.0 -20 5.0
208 3 10.0 -30 5.0
209 4 10.0 -40 5.0
210
211 And in the config
212
213 .. code:: json
214
215 {
216 "ecp": {
217 "cells": "all",
218 "variable_name": "v",
219 "module": "extracellular",
220 "electrode_positions": "components/xelectrode/linear_probe.csv",
221 "file_name": "ecp.h5",
222 "contributions_dir": "ecp_contributions"
223 }
224 }
225
226 * cells: a `node_set <./simulators.html#node-sets>`_ to filter out what cells will contribute to the ECP.
227 * variable_name: name of contributing variable, v for membrane potential
228 * electrode_positions: name of electrode placement file
229 * contributions_dir: The output ECP file will contain the combined contributions from all cells, and not possible to
230 determine the ECP of each cell. But if “contributions_dir” is specified it will also record and save each
231 cells’ ECP.
232
233
234 Synaptic Variables
235 ++++++++++++++++++
236 Similar to recording from membrane potential, by setting ``module`` parameter to ``netcon_report`` you can record the
237 variables from a synapse. The output is similar to a
238 `SONATA membrane report <https://github.com/AllenInstitute/sonata/blob/master/docs/SONATA_DEVELOPER_GUIDE.md#frame-oriented-node-element-recordings>`_,
239 but instead of each column being a segment of a neuron, each column represents a different synapse.
240
241 .. code:: json
242
243 {
244 "syn_report": {
245 "cells": {"model_type": "biophysical"},
246 "variable_name": "tau1",
247 "module": "netcon_report",
248 "sections": "soma",
249 "syn_type": "Exp2Syn"
250 }
251 }
252
253
254
255 Advanced Options
256 ----------------
257
258 Specifying Synapse locations
259 ++++++++++++++++++++++++++++
260 In SONATA the location of each synapse is determined by the
261 `"afferent_section_id" and "afferent_section_pos" attributes <https://github.com/AllenInstitute/sonata/blob/master/docs/SONATA_DEVELOPER_GUIDE.md#edges---required-attributes>`_,
262 which requires modelers to know how NEURON parses the morphology of each cell. If these parameters are specified in the edges file
263 SONATA will use them to place a synapse on the target.
264
265 Alternatively, BMTK supports the optional parameters “distance_range" and “target_sections”, which are present in the edges
266 file, which will direct BMTK to randomly choose a target synapse location under the limitations. Here “target_setions” refers
267 to a neuronal area (somatic, axon, apical, basal), and “"istance_range” is the minimum and maximum arc-length distance
268 (in um) from the soma to place the synapse. For example to specify synapses be created either at the soma or nearby
269 basal dendrites:
270
271
272 .. code:: text
273 :name: edge_type.csv
274
275 edge_type_id distance_range target_sections ...
276 100 "[0.0, 100.0]" "['somatic', 'basal']" ...
277
278 Using parameters “distance_range” and “target_sections” will speed up the instantiation by a bit. And has the benefit
279 that the modeler doesn’t need to know the full details of the target_morphology. It may cause results to vary, but in
280 our experience for large-networks usually don’t change the dynamics.
281
282
283 Replaying recurrent activity without inputs
284 +++++++++++++++++++++++++++++++++++++++++++
285 Most of the times when we are running a simulation of a recurrently-connected network, the network is being stimulated
286 by some non-recurrent source; like a voltage clamp, current clamp, extraceullar pulse, or being syanptically driven
287 by a pre-recorded spike-trains (eg, virtual cells). Thus the firing-times/voltage potentials of our network cells are
288 being driven by two primary sources; external inputs and synaptic/electrical activity from other cells in the network.
289 Being able to separate the contributions of the two type of drivers is often important for analysis of our network.
290
291 Being able to see how our network behaves without recurrent connections is usually trivial to implement using the SONATA
292 configuration file. For example, a network called "internal" might have both internal-to-internal recurrent connections
293 and external-to-internal connections as represented in the "networks" section of the config
294
295 .. code:: json
296
297 {
298 "networks": {
299 "nodes": [
300 {
301 "nodes_file": "$NETWORK_DIR/internal_nodes.h5",
302 "node_types_file": "$NETWORK_DIR/internal_node_types.csv"
303 },
304 {
305 "nodes_file": "$NETWORK_DIR/external_nodes.h5",
306 "node_types_file": "$NETWORK_DIR/external_node_types.csv"
307 }
308 ],
309 "edges": [
310 {
311 "edges_file": "$NETWORK_DIR/internal_internal_edges.h5",
312 "edge_types_file": "$NETWORK_DIR/internal_internal_edge_types.csv"
313 },
314 {
315 "edges_file": "$NETWORK_DIR/external_internal_edges.h5",
316 "edge_types_file": "$NETWORK_DIR/external_internal_edge_types.csv"
317 }
318 ]
319 }
320 }
321
322 To run the simulation without the recurrent internal-to-internal connections we just need to remove the relevant
323 SONATA network files:
324
325 .. code:: json
326
327 {
328 "networks": {
329 "nodes": [
330 {
331 "nodes_file": "$NETWORK_DIR/internal_nodes.h5",
332 "node_types_file": "$NETWORK_DIR/internal_node_types.csv"
333 },
334 {
335 "nodes_file": "$NETWORK_DIR/external_nodes.h5",
336 "node_types_file": "$NETWORK_DIR/external_node_types.csv"
337 }
338 ],
339 "edges": [
340 {
341 "edges_file": "$NETWORK_DIR/external_internal_edges.h5",
342 "edge_types_file": "$NETWORK_DIR/external_internal_edge_types.csv"
343 }
344 ]
345 }
346 }
347
348 Plotting the spikes raster we can see how the network behaves without recurrent connections (right) vs. the normal
349 fully connected simulation (left):
350
351 .. image:: _static/images/disconnected_normal_sims.png
352
353 But what if we want to rerun the full simulation but without the external inputs, how see how only the recurrent
354 activity affects the full simulation? To do so we must use a special **"replay"** input module. In the
355 "inputs" section of the config we add the following:
356
357 .. code:: json
358
359 {
360 "inputs": {
361 "recurrent_replay": {
362 "input_type": "replay_spikes",
363 "module": "replay",
364 "spikes_file": "$PREV_RESULTS_DIR/spikes.h5",
365 "edges": {
366 "edges_file": "$NETWORK_DIR/internal_internal_edges.h5",
367 "edge_types_file": "$NETWORK_DIR/internal_internal_edge_types.csv"
368 }
369 }
370 }
371 }
372
373 Here we have
374 * "*recurrent_replay*" is the name of this specific input and can be changed to whatever we like.
375 * **input_type** and **module** are always set to *replay_spikes* and *replay*, respecitively, to direct bmtk as to the type of input/module being used.
376 * **spikes_file** is the name of the recurrent spiking activity we want to replay when we rerun the simulation. In this case it is the locations of the output spikes results when we ran the fully connected simulation.
377 * **edges** is the location of the edges and edge-types SONATA network files, in this case it is the files containing the recurrent internal-to-internal connections.
378
379 Then we update the "networks" section since we don't want to have any external-to-internal type connections:
380
381 .. code:: json
382
383 {
384 "networks": {
385 "nodes": [
386 {
387 "nodes_file": "$NETWORK_DIR/internal_nodes.h5",
388 "node_types_file": "$NETWORK_DIR/internal_node_types.csv"
389 }
390 ]
391 }
392 }
393
394 And we can run the simulation with the updated config and see what the network looks like when activity is only being
395 drived by recurrent activity
396
397 .. image:: _static/images/disconnected_recurrent_only.png
398
399 The module also has optional arguments **source_node_set** and **target_node_set** which allows us to rerun recurrent
400 connections, but only on edges where the source (pre-synaptic) and target (post-synaptic) cells meet certain criteria.
401 For example, we only want to run simulation on edges where the target cells are "biophysically-detailed Scnn1a" cells
402 and the source cells are either "Scnn1a", "Rorb", or "Nr5a1" cell-types.
403
404 .. code:: json
405
406 {
407 "inputs": {
408 "recurrent_replay": {
409 "input_type": "replay_spikes",
410 "module": "replay",
411 "spikes_file": "$PREV_RESULTS_DIR/spikes.h5",
412 "source_node_set": {
413 "population": "internal",
414 "model_name": ["Scnn1a", "Rorb", "Nr5a1"]
415 },
416 "target_node_set": {
417 "population": "internal",
418 "model_name": "Scnn1a",
419 "model_type": "biophysical"
420 },
421 "edges": {
422 "edges_file": "$NETWORK_DIR/internal_internal_edges.h5",
423 "edge_types_file": "$NETWORK_DIR/internal_internal_edge_types.csv"
424 }
425 }
426 }
427 }
428
429 .. image:: _static/images/disconnected_scnn1a.png
430
431
432 You can combine "replay" inputs with virtual inputs, current and voltage clamps. And you can have multiple
433 "replay" inputs in the same simulation by adding multiple subsections in the "inputs" sections of the config:
434
435 .. code::
436
437 {
438 "inputs": {
439 "replay_1": {
440 "input_type": "replay_spikes",
441 "module": "replay",
442 ...
443 },
444 "replay_1": {
445 "input_type": "replay_spikes",
446 "module": "replay",
447 ...
448 }
449 }
450 }
451
452 See the `examples/bio_450cells_replay/ <https://github.com/AllenInstitute/bmtk/tree/develop/examples/bio_450cells_replay>`_
453 folder for examples of running replayed simulations.
454