ALLEN INSTITUTE

# The Network Builder

The class for building a brain network is `bmtk.builder.NetworkBuilder`. This should be used whether one is building a biophysically detailed network for BioNet, a point-neuron network for PointNet, A filter-based lnp network for FitlerNet, or a population-level network for PopNet. In general, it can be used to build any type of heterogeneous parameter multi-graph.

The process of building the network can break down into four parts:

1. Initialize the Network. Here all one needs is a unique name to identify the population of nodes - usually, the region being model

    from bmtk.builder import NetworkBuilder

    net = NetworkBuilder("network_name")

2. Create the nodes (ie. cells) using the `add_nodes()` method. For different types/models of cells we can use separate calls to add_nodes (often with different model parameters).

    net.add_nodes(N=80, model_type='Biophysical', ei='exc')
    net.add_nodes(N=20, model_type='IntFire', ei='inh', vrest=-50.0)

3. Create Connection rules between different subsets of nodes using `add_edges()` method.

    net.add_edges(source={'ei': 'exc'}, target={'ei': 'inh'}, connection_rule=my_conn_func, synaptic_model='e2i')
    net.add_edges(source={'ei': inh}, target={'ei': 'exc'}, connection_rule=1, synaptic_model='i2e')

4. Finally use `build()` and `save()` methods to build and save the model to the file

    net.build()
    net.save(output_dir='/path/to/network/output/')

## Building Nodes

In BMTK and SONATA a node usually is synonymous with a cell (although a node can be used to represent a population of cells with PopNet). To add a group of nodes to a network is to use the `NetworkBuilder.add_nodes()`.

The only thing that is required is an integer value N for the number of individual nodes. The modeler can also pass in any parameter they want to describe their model - although SONATA/BMTK does contain a number of reserved node parameters that will be useful in generating an instantiable model.

    net.add(N=100, model_type='biophysical', dynamics_params='rorb_params.json', morphology='rorb.swc')

In the above example, all 100 nodes share the same values for `model_type`, `dynamics_params`, and `morphology`. 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 the `rotation_angle_xaxis` and `rotation_angle_yaxis` will be unique for every node

    net.add(
       N=100,
       rotation_angle_xaxis=np.linspace(0.0, 360.0, 100),
       rotation_angle_yaxis=np.random.rand(0.0, 360.0, 100),
       model_type='biophysical',
       ...
    )

If a parameter requires compounded data you can use a tuple or a list of tuples. For example, we may want to represent a cell’s position by a range:

    net.add(N=100,
            pos_with_jitter=[(p-rand(), p+rand()) for p in positions],
            ...)

### Node Representation

When `NetworkBuilder.build()` is called, each node will be given a unique node_id value, and each type model (eg each call to add_nodes) will also be given a node_type_id. It is possible to set the node_id and node_type_id parameter yourself but it’s generally not a good idea.

The `NetworkBuilder.nodes()` will return an iterator of the nodes in a network. By default, it returns all nodes but one can filter by specific property values. The nodes themselves can have their properties accessed like a dictionary. For example to get all biophysically detailed inh neurons:

    for node in net.nodes(model_type='biophysical', ei='inh'):
       x = node['position_x']
       ...

### Useful Node Parameters

As mentioned above the modeler can use any parameters and values they require to represent their models. The following are parameters that will be recognized and used by the BMTK simulator (but not necessarily required). For a complete list see SONATA:

Name | Description
--- | ---
x (or y, z) | x positions of soma in world coordinates
rotation_angle_xaxis (or y, z) | rotation of the morphology around the soma
model_type | level of representation of neurons (biophysical, point_neuron, virtual)
model_template | String name of the template to create (eg, ctdb:Biophys1.hoc, nest:glif_lif, etc)
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
dynamics_params | Channel and mechanism parameters for neuron, usually a name of a json or NeuronML file. Will overwrite model_template.
morphology | Name of the detailed morphology file (usually SWC).

## Building Edges

To define different types of edges between two subsets of nodes you should use the `NetworkBuilder.add_edges()` method. Then once `NetworkBuilder.build()` method is called the the actual connections will be instantiated based on the connectivity_rule property the user defines. A typical call to add_edges would be the following

    net.add_edges(
          source={'ei': 'inh'},                                 # 1
          target={'ei': 'exc', 'ephys_type': 'fast_spiking'},
          connection_rule=my_connection_func,                   # 2
          dynamic_parameters='i2e.json',                        # 3
          synaptic_model='alphaSyn',
          syn_weight=1.34e-05,
          delay=2.0
    )

1. parameters `source` and `target` are used to filter out the subset of nodes used pre-and post-synapse, respectively. In this case, the source population consists of all inhibitory (ei=inh) neurons, while the target population consists only of excitatory (ei=exc) fast-spiking neurons. If the source or target is not specified then all possible nodes will be used.

2. `connection_rule` is used to determine the number of connections between each source and the target node. If the value is given as an integer N then all possible source/target pairs with have N different connections. You can also pass in a list-of-list or a matrix. But usually, a user-defined function is used, which will be better described in the next section.

3. `dynamic_parameters`, `synaptic_model`, `syn_weight`, and `delay` are all shared connection parameters. Like with nodes, modelers can choose whatever parameters they deem best to represent their network. A list of useful parameters pre-defined by BMTK and SONATA is described below.

Also, like the nodes, it is possible to have unique values for every individual edge, but it is a little more difficult. See the section on ConnectionMap for more info.

### Connection rules

The connection_rule parameter of add_edges() method will usually be a user-defined function (but may also be an integer, list-of-lists, or matrix). The function’s first two parameters will be source and target, Node objects whose properties can be accessed like a dictionary. It should return an integer N for the number of connections between the source and target, 0 or None if there is no connection.

    def my_connection_func(source, target):
       src_pos = source['position']
       trg_pos = target['position']
       ...
       return N_syns

    net.add_edges(
       source={'ei': 'inh'}, target={'ei': 'exc', 'ephys_type': 'fast_spiking'},
       connection_rule=my_connection_func,
       dynamic_parameters='i2e.json',
       ...
    )

If the connection_rule function requires additional arguments, use the connection_params option:

    def my_connection_func(source, target, min_edges, max_edges):
       src_pos = source['position']
       trg_pos = target['position']
       ...
       return N_syns

    net.add_edges(
       source={'ei': 'inh'}, target={'ei': 'exc', 'ephys_type': 'fast_spiking'},
       connection_rule=my_connection_func,
       connection_params={'min_edges': 0, 'max_edges': 20},
       dynamic_parameters='i2e.json',
       ...
    )

When `NetworkBuilder.build()` is executed my_connection_func() will be automatically called for all possible source/target pair of nodes and the connectivity matrix will be called.

Sometimes it may be more efficient or necessary to set all incoming (or outgoing) connections in one function. For example, we may need to limit the total number of synapses on a target. The `iterator` parameter allows the modeler to change the signature and return values of their connection_rule function. By setting `iterator` to all_to_one, instead of passing in a single source neuron it will pass in a list of all N source neurons, and will expect a corresponding list of size N

    def bulk_connection_func(sources, target):
       trg_pos = target['position']
       syn_list = np.zeros(len(sources))
       for source in sources:
          src_pos = source['position']
          ...
       return syn_list

There is also an all_to_one iterator option that will pair each source node with a list of all available target nodes.

### Individual Edge Properties (The ConnectionMap)

Sometimes it is necessary for each edge to have unique property values. For example, the individual syn_weight value for each synapse may vary depending on the location and type of the pre-and post-synaptic nodes. With nodes, 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 the exact number of connections will not be known in advance.

each call to add_edges returns a `ConnectionMap` object. The `ConnectionMap.add_properties()` method allows us to add individual properties for each edge using our own user defined functions. Like with our connection_rule function, the connection_map `rule` function takes in a source and target node and returns a corresponding value:

    def set_syn_weight_by_dist(source, target):
       src_pos, trg_pos = source['position'], target['position']
       ...
       return syn_weight

    cm = net.add_edges(....)
    cm.add_properties('syn_weight', rule=set_syn_weight_by_dist, dtypes=float)
    cm.add_properties('delay', rule=lambda *_: np.random.rand(0.01, 0.50), dtypes=float)

If the `rule` requires extra arguments we can use the `rule_params` option:

    def set_syn_weight_by_dist(source, target, min_weight, max_weight):
       src_pos, trg_pos = source['position'], target['position']
       ...
       return syn_weight

    cm.add_properties(
       name='syn_weight',
       rule=set_syn_weight_by_dist,
       rule_params={'min_weight': 1.0e-06, 'max_weight': 1.0e-04},
       dtypes=float
    )

It is also possible to set multiple parameters in a single function. For example, for each synapse, we may want to set the distance between the soma, and the neuronal area (soma, apical dendrites, basal dendrites, etc). To do so our `name` and `dtypes` parameters take a list, and our rule function now returns two values

    def set_target_location(source, target):
       ...
       return syn_region, syn_dist

    cm.add_properties(
       name=['syn_region', 'syn_dist'],
       rule=set_syn_weight_by_dist,
       dtypes=[str, float]
    )

### Intra-Network Connections

Both BMTK and SONATA support a network to be built piecemeal and combined into one at simulation time. A cortical the region will receive inputs from many other regions, and a modeler may want to test the dynamics when different combinations of inputs are turned on and off. Instead of building multiple models of the region with different inputs, instead, we can build the nodes, recurrent and inter-network connections each region independently and turn them on and off during the simulation (see simulation config)

Creating connections between two different networks is very similar to creating recurrent connections and still use the add_edges method. The main difference is for our `source` or `target` argument, instead of using a dictionary we must use the `NetworkBuilder.nodes()` method of another network. For example, we have two networks called LGN and V1 and we want to create a connection type from LGN’s excitatory neurons (ei=exc) V1’s pyramidal cells

    v1 = NetworkBuilder('V1')
    ... # Build V1 network

    lgn = NetworkBuilder('LGN')
    lgn.add_nodes(N=30000, model_type='virtual', ei='exc')
    lgn.add_edges(
       source={'ei': 'exc'},                  # dict indicates source population coming from lgn_net
       target=v1.nodes('model_type': 'pyr'),  # target population coming form V1 network
       connection_rule=input_conn_fnc,
       ...
    )
    lgn.build()

When creating intra-network connections the `NetworkBuilder.import()` method can be very useful.

### Edge Accessor methods

#### `NetworkBuilder.edges()`

The method will return an iterator of edges filtered by edge and/or node properties. Each edge will be represented using a `Edge` object

### Useful Edge Parameters

Name | Description
--- | ---
syn_weight | synaptic weight
delay | synaptic delay, in ms
model_template | String name of the template to create an object from parameters in dynamics_params
dynamics_params | dynamic parameter overrides for edges
efferent_section_id | location of (NEURON) section where the connection will target
efferent_section_pos | distance within the (NEURON) section where synapse will target
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
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.
weight_function | Name of the detailed morphology file (usually SWC).

## Saving and Building

Once all calls to add_nodes and ad_edges have been made, use the build() method to actually complete and fully instantiate the network. Certain accessor functions, like `NetworkBuilder.nodes()` and `NetworkBuilder.edges()` will not work until all the edges have been completed. Depending on the size of the network and the complexity of the connectivity rules, it can take anywhere from less than a second to days to build the full model.

The `NetworkBuilder.save(output_dir=’/path/to/output/net/’)` method will write the network to a disk in SONATA format at the given output_dir path. By default nodes and edges will be written to different files using the network names to determine the sonata file names. The `NetworkBuilder.save_nodes()` and `NetworkBuilder.save_edges()` functions may also used to only write out the nodes or the edges, respectively.

## Network Format

This is a brief overview of how NetworkBuilder saves the network’s nodes and edges files. As mentioned BMTK uses the SONATA format, so more in-depth descriptions may be found here. Opening the HDF5 file will require a hdf browser like HDFView, or a library like h5py. You can also use pySONATA or libSONATA which are API’s for reading in SONATA files

## Advanced Features