| 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 |
----------------- |