Build local connectivity from index pairs + kernel weights
network
classes.network
Brain-network connectivity classes for TVBO.
Defines Network and its matrix-style subclass Connectome, which carry the structural connectivity (weights and tract lengths), parcellation, nodes/edges and declarative transforms of a virtual brain. Includes constructors that load networks from HDF5/YAML database files and from BIDS derivatives, JAX pytree registration so a network can flow through differentiable simulations, and graph-Laplacian coupling primitives.
Attributes
| Name | Description |
|---|---|
| NETWORK_DIR | |
| available_connectomes | |
| connectome_data |
Classes
| Name | Description |
|---|---|
| Connectome | Deprecated alias for Network. Use Network instead. |
| LazyMaterializationWarning | A Network entered a JAX transformation with arrays its companion offers still unread. |
| Network | A brain network: parcellation, connectome, per-node dynamics, and coupling. |
Connectome
classes.network.Connectome(*args, **kwargs)Deprecated alias for Network. Use Network instead.
LazyMaterializationWarning
classes.network.LazyMaterializationWarning()A Network entered a JAX transformation with arrays its companion offers still unread.
The solver then traces nothing and reads the connectome as a constant inside the trace. Set TVBO_JAX_STRICT to make it an error.
Network
classes.network.Network(**kwargs)A brain network: parcellation, connectome, per-node dynamics, and coupling.
The spatial substrate of a SimulationExperiment. A Network ties an atlas/parcellation to a tractogram (structural connectivity matrix + optional path lengths) and, optionally, per-node Dynamics overrides and node-level coupling parameters.
Construct inline, by IRI (resolved against the curated database), or from a NumPy / pandas matrix via Network.from_array.
Examples
net = Network(
parcellation={"atlas": {"iri": "tvbo:DesikanKilliany"}},
tractogram={"iri": "tvbo:dTOR"},
)See the Network specification for the slot-by-slot reference and the Connectome subclass for matrix-style networks without an explicit parcellation.
Attributes
| Name | Description |
|---|---|
| arrays | The materialised arrays, keyed by companion dataset path — edges/weight, mesh/vertices. |
| atlas | Brain atlas associated with this connectome. |
| bids_filename | Generate BIDS-compliant filename using pybids build_path (§6.5). |
| conduction_speed | Access conduction_speed from parameters dict. |
| distances | Tract-length matrix in millimetres (alias of lengths). |
| global_coupling_strength | Access global_coupling_strength from parameters dict. |
| graph | Build NetworkX MultiDiGraph from network nodes and edges. |
| labels | Brain region labels from atlas. |
| lengths | Tract-length matrix in millimetres (alias for lengths_matrix). |
| lengths_matrix | Tract length matrix as numpy/JAX array. |
| matrix_names | Every edge matrix this network can serve, without reading one. |
| metadata | Back-compatible pointer that returns the network itself as its metadata. |
| node_labels | Node labels derived from nodes. |
| node_mapping_data | The node-to-parent mapping array, or None. |
| node_parameter_vectors | Per-node parameters as {name: (n_nodes,) array}, in declared node order. |
| number_of_regions | Deprecated alias for number_of_nodes. |
| observations | Observational-measure matrices carried by the network. |
| parent_network_obj | The parent Network object, if assigned via object reference. |
| raw_weights_matrix | Deprecated: use matrix("weight", apply_transforms=False). |
| weights | Deprecated: use matrix("weight"). |
| weights_matrix | Deprecated: use matrix("weight"). |
Methods
| Name | Description |
|---|---|
| add_edge | Add a single edge with named parameter values. |
| add_edges | Add edges in bulk using COO-style index arrays. |
| add_transform | Append a matrix transform for a named edge property. |
| array | The array at path, resident or read from the companion on first use; None when there is neither. |
| as_data_file_reference | A compact datamodel Network that points at data_file and still IS this network. |
| calculate_delays | Calculate signal propagation delays between regions. |
| compute_delays | Deprecated: use :meth:calculate_delays instead. |
| create_graph | Create NetworkX graph from network structure. |
| edge_parameter_arrays | {edge: {parameter: matrix}} for every edge-parameter matrix, resident or in the companion. |
| execute | Convert connectome to simulator-specific format. |
| from_bids | Create a Network from BEP017-compliant BIDS connectivity data. |
| from_datamodel | Create a Network from a datamodel instance. |
| from_db | Load a Network from the tvbo database by name or BIDS entities. |
| from_file | Load from YAML/JSON sidecar with lazy binary companion. |
| from_matrix | Create a Network from named edge-property matrices. |
| from_platform | Download a normative connectivity network from the tvbo platform. |
| from_string | Create a Network from a YAML string. |
| from_tvb | Import a live TVB Connectivity object. |
| from_tvb_surface | Create a multi-level Network from TVB surface simulation data. |
| from_tvb_zip | Import from TVB connectivity ZIP (weights.txt + tract_lengths.txt). |
| get_atlas | Retrieve the Atlas object for this connectome. |
| get_centers | Get 3D spatial coordinates of brain region centers. |
| invalidate_resolution | Drop everything _resolve materialised, so the next access rebuilds it. |
| list_db | List available networks in the tvbo database, optionally filtered. |
| list_platform_networks | List available normative networks on the tvbo platform. |
| load | Unified loader: file path, database name, or BIDS entities. |
| load_from_bids | Load BEP017 data into existing network. |
| load_matrix | Load weight/length matrices into existing network (preserves coupling). |
| materialize | A copy of this network with paths resident, and nothing else newly read. |
| matrix | Get a named edge matrix, optionally in a specific format. |
| matrix_info | Shape, dtype and storage format of one array, from the companion’s header alone. |
| node_index_map | {Node.id: row/column index} for the connectome matrices. |
| node_positions | Node coordinates as an (n_nodes, 3) array, in declared node order. |
| normalize | Add min-max normalization of connection weights. |
| normalize_weights | Add a normalization transform for connection weights. |
| plot_brain_surface | Render the network on the cortical brain surface. |
| plot_graph | Visualize connectome as network graph. |
| plot_lengths | Plot tract lengths matrix as heatmap. |
| plot_matrix | Plot both weights and lengths matrices side by side. |
| plot_overview | Create comprehensive visualization with brain surface and matrices. |
| plot_weights | Plot connection weights matrix as heatmap. |
| region_alias_map | Map each node’s canonical label AND every known alias -> canonical label. |
| save | Save as sidecar + binary companion. |
| set_array | Hold data as the array at path (a bare name means an edge matrix). |
| set_matrix | Set a named edge matrix. |
| set_node_mapping | Set the node-to-parent mapping array. |
| to_bep017 | Export to BEP017-compatible per-measure files. |
| to_yaml | Serialize Network to YAML format. |
| transform_expression | A transform’s equation as a sympy expression, with its arguments substituted. |
| transforms_for | The declared transforms: that retarget target, in declaration order. |
| tree_flatten | The resident arrays as JAX children, keyed by companion path, and the spec as static aux. |
| tree_unflatten | The inverse of tree_flatten: the spec rebuilt from its JSON, the children installed as the resident arrays. |
add_edge
classes.network.Network.add_edge(source, target, symmetric=True, **params)Add a single edge with named parameter values.
Convenience wrapper around :meth:add_edges for one edge.
Parameters
source, target : int Node indices. symmetric : bool If True (default), also adds the reverse edge. **params : float Named parameter values. Each name becomes a matrix name (e.g. weight=0.5 → stored in the "weight" matrix, length=30.0 → stored in "length").
Examples:
net.add_edge(0, 1, weight=0.5, length=30.0)
add_edges
classes.network.Network.add_edges(sources, targets, symmetric=True, **matrices)Add edges in bulk using COO-style index arrays.
Each keyword argument is a named matrix (e.g. weights=vals) whose entries are being added at the given (source, target) positions. Internally the data is kept in COO format for fast incremental building; call :meth:matrix with format="csr" when you need efficient row-slicing.
Parameters
sources, targets : array-like of int Source and target node index arrays (same length). symmetric : bool If True (default), each (i, j) entry is mirrored to (j, i), producing a symmetric matrix. **matrices : array-like of float Named value arrays, one per matrix to update. Length must match sources and targets.
Examples:
net.add_edges(pairs[:, 0], pairs[:, 1], … symmetric=True, weight=kernel_vals)
add_transform
classes.network.Network.add_transform(target, equation_rhs=None)Append a matrix transform for a named edge property.
Transforms are applied in order when the matrix is accessed via matrix() or weights_matrix.
Parameters
target : str Edge property name (e.g. "weight", "length", "fc"). equation_rhs : str, optional Right-hand side of the transform equation, written over the network’s own edge attributes — weight, length, or network.edges.<label>. The attribute named by target is the value under transform. Defaults to min-max normalisation of target. A reduction may be scoped by a boolean predicate, written either as a subscript or as a second argument.
Examples:
sc = Network(parcellation={"atlas": {"name": "DesikanKilliany"}})
sc.add_transform("weight", "weight / max(weight)")
sc.add_transform("weight", "weight / mean(weight[weight > 0])")
sc.add_transform("weight", "weight / mean(weight, weight > 0)")array
classes.network.Network.array(path)The array at path, resident or read from the companion on first use; None when there is neither.
A bare name is an edge matrix; mesh/vertices or nodes/coordinates is any dataset the companion carries. What this reads is kept, so the residency repr reports is exactly what has been paid for. Reads come back in their stored format.
as_data_file_reference
classes.network.Network.as_data_file_reference(data_file)A compact datamodel Network that points at data_file and still IS this network.
Freezing a connectome writes its matrices to a companion file and replaces the network in the rendered spec with this reference, so what travels beside data_file has to be everything the reloaded network needs in order to behave identically: the inline coupling / transforms / parameters, the scalar identity, the measure declarations — Network.observations and the structural resolution gate on those, so a companion holding BoldCorrelation data is invisible unless the reference also declares observational_measures: [BoldCorrelation] — and the parcellation, which names the atlas that a by_label node crosswalk resolves against. Carrying the parcellation cannot re-expand the node set, because data_file makes the loader defer connectivity to the companion store.
Note that observations is deliberately NOT copied: it is a runtime view over the companion’s measures, not a schema slot, and observational_measures is what reconstructs it.
calculate_delays
classes.network.Network.calculate_delays(
conduction_speed=None,
output_unit=None,
)Calculate signal propagation delays between regions.
Supports two network representations:
- Matrix-based — delays are
lengths / conduction_speed, with optional unit conversion via output_unit. - Edge-based — delays are extracted from explicit edge objects that carry
source,target, and a"delay"parameter.
Parameters
conduction_speed : float, optional Override conduction speed. If None, uses self.conduction_speed. output_unit : str, optional Desired output time unit (e.g. "ms", "s"). When given, sympy unit conversion is applied. If None, the result is in the network’s native time unit (defaults to ms).
Returns:
np.ndarray or jax.Array Delay matrix (N x N). For edge-based networks, entries without an edge are NaN.
Raises:
ValueError If neither lengths matrix nor edge-based delays are available.
Examples:
import matplotlib.pyplot as plt
sc = Network(parcellation={"atlas": {"name": "DesikanKilliany"}})
delays = sc.calculate_delays(conduction_speed=3.0)
plt.imshow(delays, cmap='viridis')
plt.colorbar(label='Delay (ms)')compute_delays
classes.network.Network.compute_delays(output_unit=None)Deprecated: use :meth:calculate_delays instead.
Parameters
output_unit : str, optional Passed through to calculate_delays(output_unit=...).
create_graph
classes.network.Network.create_graph(weight_threshold=0)Create NetworkX graph from network structure.
Prioritizes explicit nodes/edges representation over weight matrices. This allows proper visualization of heterogeneous networks with labeled nodes and typed edges.
Parameters
weight_threshold : float, default=0 Minimum weight for including an edge in the graph
Returns:
networkx.MultiDiGraph Directed multigraph with ‘weight’ and ‘delay’ edge attributes. Nodes have ‘label’ and ‘dynamics’ attributes when available. Edges have ‘source_var’, ‘target_var’ attributes when available. Edges point in signal direction (source to target). Stored matrices are receiver-row (W[i, j] couples node j into node i), so matrix entries are emitted as edges j -> i. Explicit pair edges declared with directed: false (the schema default) are mirrored into both directions, matching their expansion in _edge_matrix; an explicitly declared reverse edge takes precedence over the mirror.
Examples:
# From explicit nodes/edges
network = Network(nodes=[...], edges=[...])
G = network.create_graph()
# From weight matrix
sc = Network(parcellation={"atlas": {"name": "DesikanKilliany"}})
G = sc.create_graph(weight_threshold=0.1)
print(f"Nodes: {G.number_of_nodes()}, Edges: {G.number_of_edges()}")edge_parameter_arrays
classes.network.Network.edge_parameter_arrays(){edge: {parameter: matrix}} for every edge-parameter matrix, resident or in the companion.
These are kept under edges/<edge>/edge_parameters/<parameter>, the path the companion writes them at.
execute
classes.network.Network.execute(
format='tvb',
target=None,
threshold_percentile=85,
**kwargs,
)Convert connectome to simulator-specific format.
Parameters
format : str, default=“tvb” Target format: "tvb", "networkx", or "tvboptim". target : Network, optional Target network for bipartite projection graphs (used with format="networkx" when a gain matrix exists). threshold_percentile : float, default=85 Keep only gain edges above this percentile (networkx only). **kwargs Extra arguments forwarded to the adapter. For tvboptim:
- ``delays=False`` — force a ``DenseGraph`` without delays.
- ``return_type="graph"`` — return only the graph object.
- ``return_type="network"`` (default) — return a full tvboptim
``Network`` (requires ``dynamics`` and ``coupling`` kwargs).
- ``dynamics`` — tvboptim dynamics instance.
- ``coupling`` — tvboptim coupling instance(s).
- ``noise`` — tvboptim noise instance (optional).Returns:
Any Connectivity object in the specified format.
from_bids
classes.network.Network.from_bids(
bids_dir,
atlas=None,
structural_measures=None,
observational_measures=None,
**kwargs,
)Create a Network from BEP017-compliant BIDS connectivity data.
Loads structural connectivity (weights, lengths) and optionally observational targets (FC) from a BIDS derivatives directory using the BEP017 relationship matrix format.
Parameters
bids_dir : str or Path Path to BEP017-compliant BIDS directory containing _relmat files. atlas : str, optional Atlas name to filter files (e.g., “DesikanKilliany”). If None, uses the first atlas found. structural_measures : list of str, optional Measures to use for structural network. First is used as weights, second (if present) as lengths. If None, auto-discovered from available meas-* relmat files. observational_measures : list of str, optional Measures to load as observational targets for optimization (e.g., [“correlation”] for FC). Stored in network._observations. **kwargs : Any Additional keyword arguments passed to Network constructor.
Returns:
Network Network with matrices loaded from BEP017 files. Observational data accessible via network.observations dict.
Examples:
from tvbo import Network
# Auto-discover measures from directory
network = Network.from_bids("tvbo/database/networks/bids/dk_average")
# Or specify measures explicitly
network = Network.from_bids(
"tvbo/database/networks/bids/dk_average",
structural_measures=["streamlineCount", "tractLength"],
observational_measures=["BoldCorrelation"],
)
# Access structural connectivity
print(network.matrix("weight").shape) # (84, 84)from_datamodel
classes.network.Network.from_datamodel(datamodel)Create a Network from a datamodel instance.
Parameters
datamodel : tvbo_datamodel.Network Source datamodel Network instance
Returns:
Network New Network with fields copied from datamodel
Examples:
from tvbo.datamodel import schema as tvbo_datamodel
dm = tvbo_datamodel.Network(number_of_nodes=10)
sc = Network.from_datamodel(dm)from_db
classes.network.Network.from_db(name=None, **entities)Load a Network from the tvbo database by name or BIDS entities.
Supports two modes:
- By name (existing):
Network.from_db("DesikanKilliany") - By BIDS key-values:
Network.from_db(atlas="DesikanKilliany", rec="dTOR")
BIDS entity keys match the key-value pairs in filenames, e.g. atlas, rec, scale, seg, desc, cohort.
When entities match a single file, returns a Network. When multiple match, returns a list of Networks.
Parameters
name : str, optional Short name or atlas name (legacy mode). Ignored when entities are given. **entities BIDS key-value filters. All specified entities must match.
Returns:
Network or listNetwork
Examples:
sc = Network.from_db(“DesikanKilliany”) # by name sc = Network.from_db(atlas=“DesikanKilliany”, rec=“dTOR”) scs = Network.from_db(atlas=“Schaefer2018”, scale=“100”) # list
from_file
classes.network.Network.from_file(path, **kwargs)Load from YAML/JSON sidecar with lazy binary companion.
Supports YAML and JSON sidecars (auto-detected by extension). Supports HDF5, Zarr, and CSV companions. Arrays are NOT loaded into memory — loaded lazily on first access.
Parameters
path : str or Path Path to YAML or JSON sidecar file.
Returns:
Network Network with lazy array references.
Examples:
net = Network.from_db(“dk87”) net.number_of_nodes # metadata: instant, no I/O 87 net.matrix(“weight”).shape # arrays: loaded on first access (87, 87)
from_matrix
classes.network.Network.from_matrix(
weights=None,
lengths=None,
labels=None,
**kwargs,
)Create a Network from named edge-property matrices.
This is a convenience constructor for creating networks from matrix representations. For performance, matrices are stored directly and edges are generated lazily only when needed.
Any keyword argument whose value is array-like (ndarray, sparse matrix, or nested sequence) is treated as a named edge-property matrix and stored via set_matrix. All other keyword arguments are forwarded to the Network constructor.
Parameters
weights : np.ndarray, optional Connection weight matrix (N x N). Stored as "weight". lengths : np.ndarray, optional Tract length matrix (N x N). Stored as "length". labels : list of str, optional Node labels. If not provided, uses “node_0”, “node_1”, etc. **kwargs : Any Keyword arguments that are array-like are stored as named edge matrices (e.g. sc=mat → set_matrix("sc", mat)). Everything else is passed to the Network constructor.
Returns:
Network New Network with nodes derived from labels and matrices stored for efficient access.
Examples:
import numpy as np
from tvbo import Network
# Simple 3-node network
W = np.array([[0, 0.5, 0.3],
[0.2, 0, 0.4],
[0.1, 0.6, 0]])
network = Network.from_matrix(W, labels=["A", "B", "C"])
network.plot_graph()
# With tract lengths
L = np.array([[0, 10, 15],
[10, 0, 8],
[15, 8, 0]])
network = Network.from_matrix(W, lengths=L)
# Arbitrary named edge properties
sc = np.array([[0, 1], [1, 0]])
fc = np.array([[1, 0.8], [0.8, 1]])
network = Network.from_matrix(sc=sc, fc=fc, labels=["L", "R"])
network.plot_overview()from_platform
classes.network.Network.from_platform(
atlas,
tractogram='dTOR',
base_url=TVBO_PLATFORM_URL,
cache_dir=None,
)Download a normative connectivity network from the tvbo platform.
Fetches the sidecar (YAML) and companion (HDF5) from the tvbo API and caches locally for subsequent loads.
Parameters
atlas : str Atlas name (e.g., “DesikanKilliany”, “Schaefer1000”). tractogram : str Tractogram name (default: “dTOR”). base_url : str Platform base URL. cache_dir : str or Path or None Local cache directory (default: ~/.tvbo/networks).
Returns:
Network Network loaded from platform (cached locally).
from_string
classes.network.Network.from_string(yaml_string, **kwargs)Create a Network from a YAML string.
This is a convenience constructor for creating networks directly from YAML specifications, commonly used in notebooks and scripts.
Parameters
yaml_string : str YAML string defining the network with nodes and edges. **kwargs : Any Additional keyword arguments passed to Network constructor.
Returns:
Network New Network parsed from the YAML string.
Examples:
from tvbo import Network
network = Network.from_string('''
label: MyNetwork
nodes:
- id: 0
label: NodeA
dynamics: Oscillator
- id: 1
label: NodeB
dynamics: Excitable
edges:
- source: 0
target: 1
weight: 0.5
''')
print(network.label)from_tvb
classes.network.Network.from_tvb(connectivity)Import a live TVB Connectivity object.
Lossless conversion preserving all TVB fields (weights, lengths, centres, cortical flags, areas, hemispheres, conduction speed).
Parameters
connectivity : tvb.datatypes.connectivity.Connectivity Configured TVB Connectivity instance.
Returns:
Network Network with arrays loaded, ready for save().
Examples:
from tvb.datatypes.connectivity import Connectivity conn = Connectivity.from_file() net = Network.from_tvb(conn) net.number_of_nodes 76
from_tvb_surface
classes.network.Network.from_tvb_surface(connectivity, surface, region_mapping)Create a multi-level Network from TVB surface simulation data.
Produces two linked networks:
- Region-level (parent): from TVB Connectivity
- Vertex-level (child): mesh + region_mapping linking vertices to regions via hierarchical
node_mapping
Parameters
connectivity : tvb.datatypes.connectivity.Connectivity Configured TVB Connectivity (region-level). surface : tvb.datatypes.surfaces.Surface TVB CorticalSurface with vertices and triangles. region_mapping : tvb.datatypes.region_mapping.RegionMapping TVB RegionMapping (vertex → region).
Returns:
tuple[Network, Network] (region_network, surface_network)
Examples:
from tvb.datatypes.connectivity import Connectivity from tvb.datatypes.surfaces import CorticalSurface from tvb.datatypes.region_mapping import RegionMapping conn = Connectivity.from_file() surf = CorticalSurface.from_file() rmap = RegionMapping.from_file() region_net, surface_net = Network.from_tvb_surface(conn, surf, rmap)
from_tvb_zip
classes.network.Network.from_tvb_zip(zip_path)Import from TVB connectivity ZIP (weights.txt + tract_lengths.txt).
Parameters
zip_path : str or Path Path to TVB connectivity ZIP file.
Returns:
Network Network with arrays loaded, ready for save().
Examples:
net = Network.from_tvb_zip(“connectivity_76.zip”) net.number_of_nodes 76
get_atlas
classes.network.Network.get_atlas()Retrieve the Atlas object for this connectome.
Returns:
Atlas Atlas instance with parcellation metadata and terminology
Examples:
sc = Network(parcellation={"atlas": {"name": "DesikanKilliany"}})
atlas = sc.get_atlas()get_centers
classes.network.Network.get_centers()Get 3D spatial coordinates of brain region centers.
Resolution order: 1. Node.position on self.nodes (in-memory) 2. nodes/coordinates dataset in the HDF5/Zarr companion 3. Atlas metadata (terminology.entities[*].center)
Returns:
dict of int to tuple of float Mapping from region index to (x, y, z) coordinates in mm
Examples:
sc = Network(parcellation={"atlas": {"name": "DesikanKilliany"}})
centers = sc.get_centers()
for idx, (x, y, z) in centers.items():
print(f"Region {idx}: ({x:.1f}, {y:.1f}, {z:.1f})")invalidate_resolution
classes.network.Network.invalidate_resolution()Drop everything _resolve materialised, so the next access rebuilds it.
Resolution is idempotent and latches, which is what stops a network being rebuilt on every access — and what makes a spec edited AFTER load silently inert. A caller that changes the declaration (a --set on a graph_generator parameter, a swapped parcellation) has to say so, or the run reports the new value and integrates the old matrix.
list_db
classes.network.Network.list_db(**entities)List available networks in the tvbo database, optionally filtered.
Parameters
**entities BIDS key-value filters (e.g. atlas="Schaefer2018").
Returns:
list[str] Sorted list of matching network stems.
Examples:
Network.list_db() # all networks Network.list_db(atlas=“Schaefer2018”) # only Schaefer Network.list_db(rec=“dTOR”, scale=“100”) # dTOR at scale 100
list_platform_networks
classes.network.Network.list_platform_networks(
base_url=TVBO_PLATFORM_URL,
**filters,
)List available normative networks on the tvbo platform.
Parameters
base_url : str Platform base URL. **filters Filtering parameters (e.g., atlas=“DesikanKilliany”).
Returns:
list[dict] List of network summaries.
load
classes.network.Network.load(source=None, **entities)Unified loader: file path, database name, or BIDS entities.
Accepts any of:
- File path (YAML, JSON, or HDF5): loads from disk. For HDF5, automatically finds the companion YAML sidecar.
- Short name: resolves via the tvbo database (e.g.
"Lobar","DesikanKilliany"). - BIDS entities as keyword arguments (e.g.
atlas="Schaefer2018", scale="100").
Parameters
source : str or Path, optional A file path or database name. When omitted, BIDS entity kwargs are used to search the database. **entities BIDS key-value filters (atlas, rec, scale, desc, seg, cohort, …).
Returns:
Network or listNetwork A single Network, or a list when multiple BIDS matches occur.
Examples:
Network.load(“Lobar”) # database name Network.load(“networks/my_network.yaml”) # YAML file Network.load(“networks/my_network.h5”) # HDF5 companion Network.load(atlas=“Schaefer2018”, scale=“100”) # BIDS entities
load_from_bids
classes.network.Network.load_from_bids(
bids_dir,
structural_measures=None,
observational_measures=None,
atlas=None,
)Load BEP017 data into existing network.
Allows loading structural connectivity and/or observational targets independently into an already-configured network (preserves coupling).
Parameters
bids_dir : str or Path Path to BEP017-compliant BIDS directory. structural_measures : list of str, optional Measures for structural connectivity. If None, auto-discovered from available meas-* relmat files. observational_measures : list of str, optional Measures for observational targets (e.g., [“BoldCorrelation”]). If None, does not load observational data. atlas : str, optional Atlas name to filter files. Auto-detected if not provided.
Returns:
Network Self (for method chaining).
Example:
network = Network() network.load_from_bids( … “tvbo/database/networks/bids/dk_average”, … ) network.load_from_bids( … “tvbo/database/networks/bids/dk_average”, … observational_measures=[“BoldCorrelation”], … )
load_matrix
classes.network.Network.load_matrix(weights, lengths=None, labels=None)Load weight/length matrices into existing network (preserves coupling).
Use this instead of from_matrix when you need to update connectivity data while keeping the network’s coupling definitions intact.
Parameters
weights : np.ndarray Connection weight matrix (N x N). lengths : np.ndarray, optional Tract length matrix (N x N). labels : list of str, optional Node labels. Updates nodes if provided.
Returns:
Network Self (for chaining).
materialize
classes.network.Network.materialize(*paths)A copy of this network with paths resident, and nothing else newly read.
The explicit point at which arrays are read: net.materialize("weight", "length") reads two datasets of however many the companion holds, and the copy’s arrays then holds exactly what a solver or a gradient will see. A bare name is an edge matrix; mesh/vertices names any dataset. The copy shares the arrays already resident here (references, not copies) and the lazy store; its residency is its own.
Raises KeyError for a path neither resident nor in the companion, so a typo is a typo and not an absent leaf.
matrix
classes.network.Network.matrix(name, format=None, apply_transforms=True)Get a named edge matrix, optionally in a specific format.
The single canonical connectivity accessor. Resolution order: the resident arrays, a JAX array among them returned untouched (the live leaf under a transformation) → the companion file, whose matrix is then kept resident → the explicit edges → None. Each SOURCE is exhausted across every alias spelling before the next is consulted — precedence is between sources, and a spelling is not a precedence, so a companion file holding weight cannot shadow a user-set weights.
Being canonical means subsuming what the deprecated properties returned, so a WEIGHT target on a node set with no edges yields zeros rather than None: an unconnected network is a legitimate one, and every consumer of this builds an (n, n) array from the result.
Parameters
name : str Matrix name (e.g. "weight", "length"). Alias spellings (weights/sc, lengths) resolve to the same matrix. format : str, optional Return format: "dense", "csr", "coo", "lil". If None, returns the matrix in whatever format it is currently stored in. apply_transforms : bool Apply the declared transforms: targeting this matrix. Pass False for the raw matrix — the tvboptim codegen path does, so a frozen kit keeps raw SC in the network file and the declared op visible in the rendered script rather than hidden in this runtime.
Returns:
np.ndarray or scipy.sparse matrix or None
matrix_info
classes.network.Network.matrix_info(name)Shape, dtype and storage format of one array, from the companion’s header alone.
name is an edge matrix ("weight") or any dataset path the companion carries ("mesh/vertices"). A user-set array answers from the object in hand. Raises KeyError when nothing by that name exists.
node_index_map
classes.network.Network.node_index_map(){Node.id: row/column index} for the connectome matrices.
Node.id is a unique identifier (dcterms:identifier), not a position: a network may declare [{id: 0}, {id: 2}] and its edges then address nodes by those ids, while the matrices are indexed by declaration order. Matrix-only networks (no nodes) address rows directly, so the map is the identity there.
node_positions
classes.network.Network.node_positions()Node coordinates as an (n_nodes, 3) array, in declared node order.
A missing z defaults to 0; a node with no position at all raises, since a partial coordinate matrix (a mesh, a distance calc) is silently wrong rather than merely incomplete. Use _get_node_position for a tolerant per-node lookup.
normalize
classes.network.Network.normalize()Add min-max normalization of connection weights.
Appends a transform to scale weights to [0, 1] range. Equivalent to add_transform("weight"), whose default is that normalisation.
Examples:
sc = Network(parcellation={"atlas": {"name": "DesikanKilliany"}})
sc.normalize()
normalized_weights = sc.matrix("weight") # Now in [0, 1] rangeSee Also:
add_transform : Add a transform on any edge property normalize_weights : Set custom normalization equation
normalize_weights
classes.network.Network.normalize_weights(equation_rhs=None)Add a normalization transform for connection weights.
Convenience wrapper for add_transform("weight", ...).
Parameters
equation_rhs : str, optional Right-hand side of the normalization equation, written over the network’s edge attributes. Defaults to min-max normalisation of weight.
Examples:
sc = Network(parcellation={"atlas": {"name": "DesikanKilliany"}})
sc.normalize_weights("weight / max(weight)") # Normalize to [0, 1]
normalized = sc.matrix("weight") # Returns normalized weightsSee Also:
add_transform : Add a transform on any edge property
plot_brain_surface
classes.network.Network.plot_brain_surface(
ax=None,
weight_matrix=None,
**kwargs,
)Render the network on the cortical brain surface.
Nodes are rendered as coloured spheres at their MNI coordinates (from atlas metadata); edges as tubes. Requires bsplot.
Parameters
ax : matplotlib.axes.Axes, optional If None, a new figure is created. weight_matrix : ndarray, optional Custom matrix for edge colouring. If None, uses the default weights matrix. **kwargs Forwarded to :func:tvbo.plot.network.plot_graph_brain.
Returns:
fig : Figure ax : Axes mappables : dict ScalarMappable objects (keys "nodes" / "edges").
See Also:
tvbo.plot.network.plot_graph_brain : Full parameter list
plot_graph
classes.network.Network.plot_graph(
ax=None,
node_cmap='viridis',
edge_cmap='viridis',
node_colors='in-strength',
node_size=8,
threshold_percentile=0,
pos_scaling=1,
node_labels=True,
edge_labels=True,
log_in_strength=True,
node_size_scaling=0,
edge_color='weight',
pos='spring',
plot_brain=None,
edge_kwargs=None,
node_kwargs=None,
fontsize=12,
format='networkx',
)Visualize connectome as network graph.
Delegates to :func:tvbo.plot.network_graph.plot_graph_networkx or :func:tvbo.plot.network_graph.plot_graph_bsplot depending on format.
Parameters
ax : matplotlib.axes.Axes, optional Axes to plot on. If None, creates new figure node_cmap : str or Colormap, default=“viridis” Colormap for node colors edge_cmap : str or Colormap, default=“viridis” Colormap for edge colors node_colors : str, default=“in-strength” Node coloring scheme: “in-strength” or “node” node_size : str or float, default=“in-strength” Node size scheme: “in-strength” or numeric value threshold_percentile : float, default=0 Only show edges above this percentile of weights pos_scaling : float, default=1 Scaling factor for spring layout positions node_labels : bool, default=True Whether to show node index labels edge_labels : bool, default=True Whether to show edge weight labels log_in_strength : bool, default=True Use log scale for in-strength calculations node_size_scaling : float, default=100 Scaling factor for node sizes edge_color : str, default=“weight” Edge attribute to use for coloring pos : str or dict, default=“spring” Node positions: “spring” for automatic layout or dict of positions plot_brain : str, optional Brain view for anatomical layout: “horizontal”, “sagittal”, or “coronal” edge_kwargs : dict, optional Additional arguments passed to nx.draw_networkx_edges node_kwargs : dict, optional Additional arguments passed to nx.draw_networkx_nodes fontsize : float, default=8 Font size for labels format : str, default=“networkx” Plotting format: “networkx” for standard plotting, “bsplot” for fancy node/edge plotting with text boxes and curved edges.
Returns:
Figure or ScalarMappable Figure if ax is None, otherwise ScalarMappable for colorbar
Examples:
import matplotlib.pyplot as plt
sc = Network(parcellation={"atlas": {"name": "DesikanKilliany"}})
# Simple graph
fig, ax = plt.subplots(figsize=(10, 10))
mappable = sc.plot_graph(ax, threshold_percentile=75)
plt.colorbar(mappable, ax=ax)
# Anatomical layout
fig, ax = plt.subplots()
sc.plot_graph(ax, plot_brain="horizontal", node_labels=False)See Also:
plot_brain_surface : 3-D brain surface rendering with bsplot tvbo.plot.network.plot_graph_networkx : NetworkX backend tvbo.plot.network.plot_graph_bsplot : bsplot backend
plot_lengths
classes.network.Network.plot_lengths(ax, cmap='magma')Plot tract lengths matrix as heatmap.
Parameters
ax : matplotlib.axes.Axes Axes to plot on cmap : str, default=“magma” Matplotlib colormap name
Returns:
matplotlib.image.AxesImage Image object for adding colorbar
Examples:
import matplotlib.pyplot as plt
sc = Network(parcellation={"atlas": {"name": "DesikanKilliany"}})
fig, ax = plt.subplots()
im = sc.plot_lengths(ax)
plt.colorbar(im, ax=ax, label="mm")plot_matrix
classes.network.Network.plot_matrix(log_weights=False, cmap='magma')Plot both weights and lengths matrices side by side.
Parameters
log_weights : bool, default=False If True, use log scale for weights colormap cmap : str, default=“magma” Matplotlib colormap name
Returns:
matplotlib.figure.Figure Figure containing both matrix plots
Examples:
sc = Network(parcellation={"atlas": {"name": "DesikanKilliany"}})
sc.plot_matrix(log_weights=True)plot_overview
classes.network.Network.plot_overview(
edge_properties=None,
weights_kwargs=None,
lengths_kwargs=None,
graph_kwargs=None,
log_weights=False,
plot_brain=None,
brain_kwargs=None,
cmap='magma',
edge_percentile=0,
show_nodes=True,
show_edges=True,
max_edge_labels=15,
)Create comprehensive visualization with brain surface and matrices.
Produces a multi-panel figure with one row per edge property. Each row contains either a brain surface + matrix heatmap (when plot_brain is True) or just a matrix heatmap, both coloured by the same property.
Parameters
edge_properties : list of str, optional Names of edge matrices to plot (e.g. ["weight", "length"] or ["weight", "length", "fc"]). Each name must match a matrix stored in the network (see set_matrix / matrix). If None, auto-discovers all available edge properties. weights_kwargs : dict, optional Deprecated — use edge_properties instead. lengths_kwargs : dict, optional Deprecated — use edge_properties instead. graph_kwargs : dict, optional Keyword arguments passed to plot_graph log_weights : bool, default=False Use logarithmic scale for the "weight" panel plot_brain : bool, optional If True, render on brain surface (requires bsplot). If False, use matrix-only layout. If None (default), auto-detect: use brain surface when bsplot is installed and atlas coordinates are available. brain_kwargs : dict, optional Keyword arguments passed to plot_brain_surface when the brain surface panel is used. cmap : str, default=“magma” Default colormap for matrix heatmaps. edge_percentile : float, default=0 Only show edges above this percentile of weights in the brain surface and graph panels. 0 (default) plots all connections. show_nodes : bool, default=True Show node spheres on the brain surface panel. show_edges : bool, default=True Show edge tubes on the brain surface panel. max_edge_labels : int, default=15 In graph panels (plot_brain=False), automatically hide edge labels when the number of visible edges exceeds this value. Set to a negative value to always show edge labels.
Returns:
matplotlib.figure.Figure Figure with subplots
Examples:
sc = Network(parcellation={"atlas": {"name": "DesikanKilliany"}})
sc.plot_overview(log_weights=True)See Also:
plot_graph : Network graph visualization plot_brain_surface : 3-D brain surface rendering plot_matrix : Side-by-side matrix visualization
plot_weights
classes.network.Network.plot_weights(ax, cmap='magma', log=False)Plot connection weights matrix as heatmap.
Parameters
ax : matplotlib.axes.Axes Axes to plot on cmap : str, default=“magma” Matplotlib colormap name log : bool, default=False If True, use logarithmic color scale
Returns:
matplotlib.image.AxesImage Image object for adding colorbar
Examples:
import matplotlib.pyplot as plt
sc = Network(parcellation={"atlas": {"name": "DesikanKilliany"}})
fig, ax = plt.subplots()
im = sc.plot_weights(ax, log=True)
plt.colorbar(im, ax=ax)region_alias_map
classes.network.Network.region_alias_map()Map each node’s canonical label AND every known alias -> canonical label.
Aliases are alternative label strings that denote the SAME region under a different nomenclature. They come from two sources, unioned: each node’s own alternateName (inline on the network) and, when the network declares a parcellation atlas, that atlas terminology’s names per region. The atlas join is by NAME, never by position, and matches a region to a node whose label is either the region’s canonical name or any of its alternateName entries — so a network that spells a region divergently (Left-Thalamus-Proper where the atlas says L_Thalamus) still inherits that region’s whole crosswalk, keyed on the label the network itself uses. The identity label -> label is always included so exact matches still resolve.
Used by by_label node reconciliation so a dataset-sourced target whose nodes carry a divergent convention (e.g. THALAMUS_LEFT for L_Thalamus) aligns by name. Raises when one alias would map to two different canonical labels, or when one atlas region’s names match several nodes — an ambiguous crosswalk must fail loudly rather than silently mis-assign a region (and, in particular, a hemisphere).
save
classes.network.Network.save(path, binary_format='h5', sidecar_format='yaml')Save as sidecar + binary companion.
Sidecar is written via LinkML yaml_dumper or json_dumper — always schema-valid output, no manual serialization.
Parameters
path : str or Path Output path for sidecar. binary_format : str “h5” (default), “zarr”, or “csv”. sidecar_format : str “yaml” (default) or “json”.
Examples:
net.save(“output/”) # dir → BIDS filename net.save(“output/dk87.yaml”) # YAML + HDF5 net.save(“output/dk87.yaml”, sidecar_format=“json”) # JSON + HDF5 net.save(“output/dk87.yaml”, binary_format=“zarr”) # YAML + Zarr net.save(“output/dk87.yaml”, binary_format=“csv”) # YAML + CSV
set_array
classes.network.Network.set_array(path, data)Hold data as the array at path (a bare name means an edge matrix).
The one write into the resident set. A scipy sparse matrix is kept sparse; anything else becomes an ndarray. Declares no template edge — :meth:set_matrix does, for an edge matrix that should reach the sidecar.
set_matrix
classes.network.Network.set_matrix(name, data)Set a named edge matrix.
Accepts dense NumPy arrays, scipy sparse matrices (CSR, COO, etc.), or any array-like that can be converted. The matrix is stored internally and a template edge is created/updated automatically so that save() writes it to the HDF5 companion.
Parameters
name : str Matrix name (e.g. "weight", "length", "local_connectivity"). Used as the HDF5 group name under edges/. data : array-like or scipy.sparse matrix The edge matrix to store.
Examples:
net.set_matrix(“weight”, W_dense) net.set_matrix(“local_connectivity”, LC_sparse_csr)
set_node_mapping
classes.network.Network.set_node_mapping(
mapping,
parent_network=None,
dataset_path='/nodes/parent_index',
)Set the node-to-parent mapping array.
This stores the mapping data internally so that :func:save writes it into the HDF5 companion automatically — no manual h5py code required.
Parameters
mapping : array-like of int Int32 array of shape (N,) where entry i is the parent node index that node i maps to (e.g. a region mapping that assigns each cortical vertex to a parcellation region). parent_network : str or Network, optional Path/URI of the parent Network YAML sidecar, or the parent Network object itself. When a Network is passed its reference string is derived automatically (see :func:_network_ref_string). dataset_path : str HDF5 dataset path written into self.node_mapping (default "/nodes/parent_index").
Examples:
surface_net.set_node_mapping(region_mapping, … parent_network=“dk_sc.yaml”) # or pass the Network object directly: surface_net.set_node_mapping(region_mapping, … parent_network=sc) surface_net.save(tmpdir / “surface_rh.yaml”)
to_bep017
classes.network.Network.to_bep017(output_dir)Export to BEP017-compatible per-measure files.
Each template edge becomes a separate TSV + JSON sidecar.
Parameters
output_dir : str or Path Output directory for BEP017 files.
to_yaml
classes.network.Network.to_yaml(filepath=None, format='tvbo')Serialize Network to YAML format.
Parameters
filepath : str, optional Path to save YAML file. If None, returns YAML string. format : str Output format: “tvbo” (default) or “pyrates”. PyRates format generates a complete experiment YAML (network + dynamics).
Returns:
str YAML representation of the Network
Examples:
sc = Network(parcellation={"atlas": {"name": "DesikanKilliany"}})
yaml_str = sc.to_yaml()
sc.to_yaml("connectome.yaml") # Save to file
sc.to_yaml("network.yaml", format="pyrates") # PyRates formattransform_expression
classes.network.Network.transform_expression(func)A transform’s equation as a sympy expression, with its arguments substituted.
Shared by the runtime and by codegen so a spec resolves to the same expression on both paths. Scalar values come from Function.arguments, falling back to Equation.parameters for legacy specs.
An argument declared without a value substitutes nothing and its symbol survives, so the caller reports it as an undeclared name. Substituting the None instead raises SympifyError: None, which names neither the transform nor the argument.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| func | The Function transform. |
required |
Returns
| Name | Type | Description |
|---|---|---|
A (expression, mask_bindings) pair; the expression is None when func |
||
| declares no equation (a callable-based transform) or it does not parse. Each | ||
| mask binding is evaluated once, before the expression that reads it. |
transforms_for
classes.network.Network.transforms_for(target)The declared transforms: that retarget target, in declaration order.
The one place the target name is matched, so the singular and plural spellings of an edge property stay equivalent everywhere and a new alias is added once. The aliases mirror the ones matrix already resolves when it looks the matrix itself up, so matrix("weights") and matrix("weight") cannot disagree about whether a transform applies. Both the runtime and the emitters that inline a transform into a generated script select through this.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| target | str | Edge property a transform retargets, e.g. "weight" or "length". |
required |
Returns
| Name | Type | Description |
|---|---|---|
List of Function transforms declared against target. |
tree_flatten
classes.network.Network.tree_flatten()The resident arrays as JAX children, keyed by companion path, and the spec as static aux.
JAX flattens a dict by sorted key, so the order arrays were materialised in never retraces and the key set is the treedef: materialize("weight", "gain") and materialize("gain", "weight") compile once, materialize("weight") compiles again. Every resident array is a leaf whatever its shape or dtype — a (276, 16384) leadfield and a (327684, 3) vertex array as much as the connectome — so jax.grad returns a cotangent for each float one and, with allow_int=True, a float0 for integer topology.
Nothing is read here. A network whose companion offers arrays it has not materialised flattens to an empty set and warns, because the solver would then trace nothing and read the connectome as a constant inside the trace; under TVBO_JAX_STRICT that is an error. A scipy sparse matrix is refused by name: it is not a JAX type, and converting it here would decide a treedef the caller never asked for.
The aux is the spec as canonical JSON, compared as a string, which is what keeps treedef equality cheap.
tree_unflatten
classes.network.Network.tree_unflatten(aux_data, children)The inverse of tree_flatten: the spec rebuilt from its JSON, the children installed as the resident arrays.
The arrays are installed as they arrive — tracers under a transformation — and matrix hands a JAX array back untouched, so what a traced computation reads is the leaf JAX gave it and never a pre-trace attribute.
Functions
| Name | Description |
|---|---|
| get_normative_connectome_data | Load normative connectivity matrices from tvbo/database/networks/ HDF5 files. |
| graph_laplacian | Combinatorial graph Laplacian L = W - diag(rowsum(W)) of a weight matrix. |
| normalized_graph_laplacian | Graph Laplacian of the max-normalised weight matrix: L(W / max(W)). |
get_normative_connectome_data
classes.network.get_normative_connectome_data(
atlas,
tractogram='dTOR',
segmentation=None,
scale=None,
with_nodes=False,
)Load normative connectivity matrices from tvbo/database/networks/ HDF5 files.
Parameters
atlas : str Name of the brain parcellation atlas (e.g., “DesikanKilliany”, “Destrieux”) tractogram : str Tractogram/reconstruction pipeline (e.g., “dTOR”, “MghUscHcp32”, “PPMI85”) segmentation, scale : str, optional BIDS seg- and scale- entity values used to disambiguate sub-resolutions of the same atlas (e.g. Schaefer2018 7Networks/1000).
Returns:
weights : np.ndarray Connection strength matrix (N x N) lengths : np.ndarray or None Tract length matrix (N x N), or None if not available nodes : list of Node, optional Only when with_nodes=True: the sidecar’s labelled + positioned region nodes, so the network is keyed by region (alignment by label, never by position). None if the sidecar declares no nodes.
Examples:
weights, lengths = get_normative_connectome_data("DesikanKilliany", "dTOR")
weights, lengths = get_normative_connectome_data(
"Schaefer2018", "dTOR", segmentation="7Networks", scale="1000"
)graph_laplacian
classes.network.graph_laplacian(M)Combinatorial graph Laplacian L = W - diag(rowsum(W)) of a weight matrix.
A standard network primitive (diffusive coupling operator): every row of L sums to zero. Referenced declaratively from a Network.transforms entry via callable: {module: tvbo.classes.network, name: graph_laplacian} — e.g. for a delay/diffusion-coupled Hopf network whose coupling matrix is the Laplacian of the (normalised) connectome. Cannot be expressed in the elementwise symbolic transform path because it needs a diagonal built from the row sums.
normalized_graph_laplacian
classes.network.normalized_graph_laplacian(M)Graph Laplacian of the max-normalised weight matrix: L(W / max(W)).
The coupling operator for a diffusion-coupled network whose global coupling strength G is expressed in the max-normalised connectome scale (so G stays O(0.01–0.1) regardless of the raw streamline-count magnitude). Referenced via callable: {module: tvbo.classes.network, name: normalized_graph_laplacian}. Equivalent to the reference two-liner W = W / W.max(); L = W - diag(W.sum(1)).