Debian Codegraph @

docs/autodocs/source/builder.rst

raw
1 The Network Builder
2 ===================
3
4 .. figure:: _static/images/bmtk_architecture_builder_highlight.jpg
5 :scale: 40%
6
7 The class for building a brain network is :py:class:`bmtk.builder.NetworkBuilder <bmtk.builder.network.Network>`. This
8 should be used whether one is building a biophysically detailed network for BioNet, a point-neuron network for PointNet,
9 A filter-based lnp network for FitlerNet, or a population-level network for PopNet. In general, it can be used to build
10 any type of heterogeneous parameter multi-graph.
11
12 The process of building the network can break down into four parts:
13
14 1. Initialize the Network. Here all one needs is a unique name to identify the population of nodes - usually, the region
15 being model
16
17 .. code:: python
18
19 from bmtk.builder import NetworkBuilder
20
21 net = NetworkBuilder("network_name")
22
23
24 2. Create the nodes (ie. cells) using the :py:meth:`add_nodes() <bmtk.builder.network.Network.add_nodes>` method. For
25 different types/models of cells we can use separate calls to add_nodes (often with different model parameters).
26
27 .. code:: python
28
29 net.add_nodes(N=80, model_type='Biophysical', ei='exc')
30 net.add_nodes(N=20, model_type='IntFire', ei='inh', vrest=-50.0)
31
32 .. figure:: _static/images/builder_add_nodes.jpg
33 :scale: 80%
34
35
36 3. Create Connection rules between different subsets of nodes using :py:meth:`add_edges() <bmtk.builder.network.Network.add_edges>`
37 method.
38
39 .. code:: python
40
41 net.add_edges(source={'ei': 'exc'}, target={'ei': 'inh'}, connection_rule=my_conn_func, synaptic_model='e2i')
42 net.add_edges(source={'ei': inh}, target={'ei': 'exc'}, connection_rule=1, synaptic_model='i2e')
43
44 .. figure:: _static/images/builder_add_edges.jpg
45 :scale: 75%
46
47
48 4. Finally use :py:meth:`build() <bmtk.builder.network.Network.build>` and :py:meth:`save() <bmtk.builder.network.Network.save>`
49 methods to build and save the model to the file
50
51 .. code:: python
52
53 net.build()
54 net.save(output_dir='/path/to/network/output/')
55
56
57 .. figure:: _static/images/builder_complete_network.jpg
58 :scale: 100%
59
60
61 Building Nodes
62 --------------
63 In BMTK and SONATA a node usually is synonymous with a cell (although a node can be used to represent a population of
64 cells with `PopNet <./popnet.html>`_). To add a group of nodes to a network is to use the
65 :py:meth:`NetworkBuilder.add_nodes() <bmtk.builder.network.Network.add_nodes>`.
66
67 The only thing that is required is an integer value N for the number of individual nodes. The modeler can also pass in
68 any parameter they want to describe their model - although SONATA/BMTK does contain a number of reserved node parameters
69 that will be useful in generating an instantiable model.
70
71 .. code:: python
72
73 net.add(N=100, model_type='biophysical', dynamics_params='rorb_params.json', morphology='rorb.swc')
74
75 In the above example, all 100 nodes share the same values for ``model_type``, ``dynamics_params``, and ``morphology``.
76 To have unique parameter values for each N node you only need to pass in a list or array of size N. In the below example
77 the ``rotation_angle_xaxis`` and ``rotation_angle_yaxis`` will be unique for every node
78
79 .. code:: python
80
81 net.add(
82 N=100,
83 rotation_angle_xaxis=np.linspace(0.0, 360.0, 100),
84 rotation_angle_yaxis=np.random.rand(0.0, 360.0, 100),
85 model_type='biophysical',
86 ...
87 )
88
89
90 If a parameter requires compounded data you can use a tuple or a list of tuples. For example, we may want to represent a
91 cell’s position by a range:
92
93
94 .. code:: python
95
96 net.add(N=100,
97 pos_with_jitter=[(p-rand(), p+rand()) for p in positions],
98 ...)
99
100 Node Representation
101 +++++++++++++++++++
102 When :py:meth:`NetworkBuilder.build() <bmtk.builder.network.Network.build>` is called, each node will be given a unique
103 **node_id** value, and each type model (eg each call to add_nodes) will also be given a **node_type_id**. It is possible
104 to set the **node_id** and **node_type_id** parameter yourself but it’s generally not a good idea.
105
106 The :py:meth:`NetworkBuilder.nodes() <bmtk.builder.network.Network.nodes>` will return an iterator of the nodes in a
107 network. By default, it returns all nodes but one can filter by specific property values. The nodes themselves can have
108 their properties accessed like a dictionary. For example to get all biophysically detailed inh neurons:
109
110 .. code:: python
111
112 for node in net.nodes(model_type='biophysical', ei='inh'):
113 x = node['position_x']
114 ...
115
116
117 Useful Node Parameters
118 ++++++++++++++++++++++
119 As mentioned above the modeler can use any parameters and values they require to represent their models. The following
120 are parameters that will be recognized and used by the BMTK simulator (but not necessarily required). For a complete
121 list see `SONATA <https://github.com/AllenInstitute/sonata/blob/master/docs/SONATA_DEVELOPER_GUIDE.md#nodes---required-attributes>`_:
122
123
124 .. csv-table::
125 :header: "Name", "Description"
126 :widths: 20, 40
127
128 "x (or y, z)", "x positions of soma in world coordinates"
129 "rotation_angle_xaxis (or y, z)", "rotation of the morphology around the soma"
130 "model_type", "level of representation of neurons (biophysical, point_neuron, virtual)"
131 "model_template", "String name of the template to create (eg, ctdb:Biophys1.hoc, nest:glif_lif, etc)"
132 "model_processing", "Directive or function that will be applied to neuron model after creation. For Allen Cell Types models use aibs_perisomatic or aibs_allactive"
133 "dynamics_params", "Channel and mechanism parameters for neuron, usually a name of a json or NeuronML file. Will overwrite model_template."
134 "morphology", "Name of the detailed morphology file (usually SWC)."
135
136
137 Building Edges
138 --------------
139
140 To define different types of edges between two subsets of nodes you should use the
141 :py:meth:`NetworkBuilder.add_edges() <bmtk.builder.network.Network.add_edges>` method. Then once
142 :py:meth:`NetworkBuilder.build() <bmtk.builder.network.Network.build>` method is called the the actual connections will
143 be instantiated based on the **connectivity_rule** property the user defines. A typical call to add_edges would be the following
144
145 .. code:: python
146
147 net.add_edges(
148 source={'ei': 'inh'}, # 1
149 target={'ei': 'exc', 'ephys_type': 'fast_spiking'},
150 connection_rule=my_connection_func, # 2
151 dynamic_parameters='i2e.json', # 3
152 synaptic_model='alphaSyn',
153 syn_weight=1.34e-05,
154 delay=2.0
155 )
156
157 1. parameters ``source`` and ``target`` are used to filter out the subset of nodes used pre-and post-synapse, respectively.
158 In this case, the source population consists of all inhibitory (ei=inh) neurons, while the target population consists
159 only of excitatory (ei=exc) fast-spiking neurons. If the source or target is not specified then all possible nodes will
160 be used.
161
162 2. ``connection_rule`` is used to determine the number of connections between each source and the target node. If the value
163 is given as an integer N then all possible source/target pairs with have N different connections. You can also pass
164 in a list-of-list or a matrix. But usually, a user-defined function is used, which will be better described in the
165 next section.
166
167 3. ``dynamic_parameters``, ``synaptic_model``, ``syn_weight``, and ``delay`` are all shared connection parameters. Like
168 with nodes, modelers can choose whatever parameters they deem best to represent their network. A list of useful
169 parameters pre-defined by BMTK and SONATA is described below.
170
171 Also, like the nodes, it is possible to have unique values for every individual edge, but it is a little more difficult.
172 See the section on ConnectionMap for more info.
173
174 Connection rules
175 ++++++++++++++++
176 The connection_rule parameter of add_edges() method will usually be a user-defined function (but may also be an integer,
177 list-of-lists, or matrix). The function’s first two parameters will be source and target, Node objects whose properties
178 can be accessed like a dictionary. It should return an integer N for the number of connections between the source and
179 target, 0 or None if there is no connection.
180
181 .. code:: python
182
183 def my_connection_func(source, target):
184 src_pos = source['position']
185 trg_pos = target['position']
186 ...
187 return N_syns
188
189 net.add_edges(
190 source={'ei': 'inh'}, target={'ei': 'exc', 'ephys_type': 'fast_spiking'},
191 connection_rule=my_connection_func,
192 dynamic_parameters='i2e.json',
193 ...
194 )
195
196 If the connection_rule function requires additional arguments, use the connection_params option:
197
198 .. code:: python
199
200 def my_connection_func(source, target, min_edges, max_edges):
201 src_pos = source['position']
202 trg_pos = target['position']
203 ...
204 return N_syns
205
206 net.add_edges(
207 source={'ei': 'inh'}, target={'ei': 'exc', 'ephys_type': 'fast_spiking'},
208 connection_rule=my_connection_func,
209 connection_params={'min_edges': 0, 'max_edges': 20},
210 dynamic_parameters='i2e.json',
211 ...
212 )
213
214
215 When :py:meth:`NetworkBuilder.build() <bmtk.builder.network.Network.build>` is executed my_connection_func() will be
216 automatically called for all possible source/target pair of nodes and the connectivity matrix will be called.
217
218 Sometimes it may be more efficient or necessary to set all incoming (or outgoing) connections in one function. For
219 example, we may need to limit the total number of synapses on a target. The ``iterator`` parameter allows the modeler to
220 change the signature and return values of their connection_rule function. By setting ``iterator`` to **all_to_one**,
221 instead of passing in a single source neuron it will pass in a list of all N source neurons, and will expect a
222 corresponding list of size N
223
224 .. code:: python
225
226 def bulk_connection_func(sources, target):
227 trg_pos = target['position']
228 syn_list = np.zeros(len(sources))
229 for source in sources:
230 src_pos = source['position']
231 ...
232 return syn_list
233
234
235 There is also an **all_to_one** iterator option that will pair each source node with a list of all available target nodes.
236
237
238 Individual Edge Properties (The ConnectionMap)
239 ++++++++++++++++++++++++++++++++++++++++++++++
240 Sometimes it is necessary for each edge to have unique property values. For example, the individual syn_weight value for
241 each synapse may vary depending on the location and type of the pre-and post-synaptic nodes. With nodes,
242 you can pass in a list or array of size N for each N node. But when edges are built using a connection_rule function
243 the exact number of connections will not be known in advance.
244
245 each call to add_edges returns a :py:class:`ConnectionMap <bmtk.builder.connection_map.ConnectionMap>` object. The
246 :py:meth:`ConnectionMap.add_properties() <bmtk.builder.connection_map.ConnectionMap.add_properties>` method allows us to
247 add individual properties for each edge using our own user defined functions. Like with our connection_rule function,
248 the connection_map ``rule`` function takes in a source and target node and returns a corresponding value:
249
250 .. code:: python
251
252 def set_syn_weight_by_dist(source, target):
253 src_pos, trg_pos = source['position'], target['position']
254 ...
255 return syn_weight
256
257 cm = net.add_edges(....)
258 cm.add_properties('syn_weight', rule=set_syn_weight_by_dist, dtypes=float)
259 cm.add_properties('delay', rule=lambda *_: np.random.rand(0.01, 0.50), dtypes=float)
260
261
262 If the ``rule`` requires extra arguments we can use the ``rule_params`` option:
263
264 .. code:: python
265
266 def set_syn_weight_by_dist(source, target, min_weight, max_weight):
267 src_pos, trg_pos = source['position'], target['position']
268 ...
269 return syn_weight
270
271 cm.add_properties(
272 name='syn_weight',
273 rule=set_syn_weight_by_dist,
274 rule_params={'min_weight': 1.0e-06, 'max_weight': 1.0e-04},
275 dtypes=float
276 )
277
278
279 It is also possible to set multiple parameters in a single function. For example, for each synapse, we may want to set
280 the distance between the soma, and the neuronal area (soma, apical dendrites, basal dendrites, etc). To do so our ``name``
281 and ``dtypes`` parameters take a list, and our rule function now returns two values
282
283 .. code:: python
284
285 def set_target_location(source, target):
286 ...
287 return syn_region, syn_dist
288
289 cm.add_properties(
290 name=['syn_region', 'syn_dist'],
291 rule=set_syn_weight_by_dist,
292 dtypes=[str, float]
293 )
294
295
296 Intra-Network Connections
297 +++++++++++++++++++++++++
298 Both BMTK and SONATA support a network to be built piecemeal and combined into one at simulation time. A cortical
299 the region will receive inputs from many other regions, and a modeler may want to test the dynamics when different
300 combinations of inputs are turned on and off. Instead of building multiple models of the region with different inputs,
301 instead, we can build the nodes, recurrent and inter-network connections each region independently and turn them on and
302 off during the simulation (see `simulation config <./simulators.html#configuration-files>`_)
303
304 Creating connections between two different networks is very similar to creating recurrent connections and still use the
305 add_edges method. The main difference is for our ``source`` or ``target`` argument, instead of using a dictionary we must
306 use the :py:meth:`NetworkBuilder.nodes() <bmtk.builder.network.Network.nodes>` method of another network. For example, we
307 have two networks called **LGN** and **V1** and we want to create a connection type from LGN’s excitatory neurons (ei=exc)
308 V1’s pyramidal cells
309
310 .. code:: python
311
312 v1 = NetworkBuilder('V1')
313 ... # Build V1 network
314
315 lgn = NetworkBuilder('LGN')
316 lgn.add_nodes(N=30000, model_type='virtual', ei='exc')
317 lgn.add_edges(
318 source={'ei': 'exc'}, # dict indicates source population coming from lgn_net
319 target=v1.nodes('model_type': 'pyr'), # target population coming form V1 network
320 connection_rule=input_conn_fnc,
321 ...
322 )
323 lgn.build()
324
325 When creating intra-network connections the :py:meth:`NetworkBuilder.import() <bmtk.builder.network.Network.import>`
326 method can be very useful.
327
328 Edge Accessor methods
329 +++++++++++++++++++++
330
331 :py:meth:`NetworkBuilder.edges() <bmtk.builder.network.Network.edges>`
332 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
333
334 The method will return an iterator of edges filtered by edge and/or node properties. Each edge will be
335 represented using a :py:class:`Edge <bmtk.builder.edge.Edge>` object
336
337
338 Useful Edge Parameters
339 ++++++++++++++++++++++
340
341 .. csv-table::
342 :header: "Name", "Description"
343 :widths: 20, 40
344
345 "syn_weight", "synaptic weight"
346 "delay", "synaptic delay, in ms"
347 "model_template", "String name of the template to create an object from parameters in dynamics_params"
348 "dynamics_params", "dynamic parameter overrides for edges"
349 "efferent_section_id", "location of (NEURON) section where the connection will target"
350 "efferent_section_pos", "distance within the (NEURON) section where synapse will target"
351 "target_sections", "A list of neuronal sections where the synapse will target (soma, axon, apical, basal). When used in place of section_id, BioNet will randomly select a section on the target neuron"
352 "distance_range", "A range in um of the distance from the soma, used along with target_sections param to randomly target certain areas of the post-synaptic neuron."
353 "weight_function", "Name of the detailed morphology file (usually SWC)."
354
355 Saving and Building
356 -------------------
357 Once all calls to add_nodes and ad_edges have been made, use the build() method to actually complete and fully
358 instantiate the network. Certain accessor functions, like
359 :py:meth:`NetworkBuilder.nodes() <bmtk.builder.network.Network.nodes>` and
360 :py:meth:`NetworkBuilder.edges() <bmtk.builder.network.Network.edges>` will not work until all the edges have been
361 completed. Depending on the size of the network and the complexity of the connectivity rules, it can take anywhere from
362 less than a second to days to build the full model.
363
364 The :py:meth:`NetworkBuilder.save(output_dir=’/path/to/output/net/’) <bmtk.builder.network.Network.save>` method will
365 write the network to a disk in SONATA format at the given output_dir path. By default nodes and edges will be written to
366 different files using the network names to determine the sonata file names. The
367 :py:meth:`NetworkBuilder.save_nodes() <bmtk.builder.network.Network.save_nodes>` and
368 :py:meth:`NetworkBuilder.save_edges() <bmtk.builder.network.Network.save_edges>` functions may also used to only write
369 out the nodes or the edges, respectively.
370
371
372 Network Format
373 --------------
374 This is a brief overview of how NetworkBuilder saves the network’s nodes and edges files. As mentioned BMTK uses the
375 SONATA format, so more in-depth descriptions may be
376 `found here <https://github.com/AllenInstitute/sonata/blob/master/docs/SONATA_DEVELOPER_GUIDE.md#representing-networks-of-neurons>`_.
377 Opening the HDF5 file will require a hdf browser like HDFView, or a library like h5py. You can also use
378 `pySONATA <https://github.com/AllenInstitute/sonata/tree/master/src/pysonata>`_ or
379 `libSONATA <https://github.com/BlueBrain/libsonata>`_ which are API’s for reading in SONATA files
380
381 .. figure:: _static/images/sonata_structure.jpg
382 :scale: 90%
383
384
385
386 Advanced Features
387 -----------------