Build local connectivity from index pairs + kernel weights
network
classes.network
Attributes
| Name | Description |
|---|---|
| NETWORK_DIR | |
| available_connectomes | |
| connectome_data |
Classes
| Name | Description |
|---|---|
| Connectome | Deprecated alias for Network. Use Network instead. |
| Network | A brain network: parcellation, connectome, per-node dynamics, and coupling. |
Connectome
classes.network.Connectome(*args, **kwargs)Deprecated alias for Network. Use Network instead.
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 |
|---|---|
| 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. |
| 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_matrix | Tract length matrix as numpy/JAX array. |
| node_labels | Node labels derived from nodes. |
| node_mapping_data | The node-to-parent mapping array, or None. |
| 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. |
| weights_matrix | Connection weights matrix as numpy/JAX array. |
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. |
| calculate_delays | Calculate signal propagation delays between regions. |
| compute_delays | Deprecated: use :meth:calculate_delays instead. |
| create_graph | Create NetworkX graph from network structure. |
| execute | Convert connectome to simulator-specific format. |
| from_bids | Create a Network from BEP017-compliant BIDS connectivity data. |
| from_datamodel | Create a Connectome 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. |
| 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). |
| matrix | Get a named edge matrix, optionally in a specific format. |
| 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. |
| save | Save as sidecar + binary companion. |
| 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 Connectome to YAML format. |
| tree_flatten | Return children and auxiliary data for JAX pytree support. |
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='(M - M_min) / (M_max - M_min)',
)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, default=“(M - M_min) / (M_max - M_min)” Right-hand side of the transform equation. Can reference M (matrix), M_min, M_max.
Examples
sc = Connectome(parcellation={"atlas": {"name": "DesikanKilliany"}})
sc.add_transform("weight", "M / M_max")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 = Connectome(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.
Examples
# From explicit nodes/edges
network = Network(nodes=[...], edges=[...])
G = network.create_graph()
# From weight matrix
sc = Connectome(parcellation={"atlas": {"name": "DesikanKilliany"}})
G = sc.create_graph(weight_threshold=0.1)
print(f"Nodes: {G.number_of_nodes()}, Edges: {G.number_of_edges()}")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.weights_matrix.shape) # (84, 84)from_datamodel
classes.network.Network.from_datamodel(datamodel)Create a Connectome from a datamodel instance.
Parameters
datamodel : tvbo_datamodel.Network Source datamodel Connectome instance
Returns
Connectome New Connectome with fields copied from datamodel
Examples
from tvbo.datamodel import schema as tvbo_datamodel
dm = tvbo_datamodel.Network(number_of_nodes=10)
sc = Connectome.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.weights_matrix.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 = Connectome(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 = Connectome(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})")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).
matrix
classes.network.Network.matrix(name, format=None)Get a named edge matrix, optionally in a specific format.
Resolution order: _arrays (user-set) → _store (lazy file) → _cached_* (legacy) → None.
Parameters
name : str Matrix name (e.g. "weight", "length"). format : str, optional Return format: "dense", "csr", "coo", "lil". If None, returns the matrix in whatever format it is currently stored in.
Returns
np.ndarray or scipy.sparse matrix or None
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", "(M - M_min) / (M_max - M_min)").
Examples
sc = Connectome(parcellation={"atlas": {"name": "DesikanKilliany"}})
sc.normalize()
normalized_weights = sc.weights_matrix # 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='(M - M_min) / (M_max - M_min)',
)Add a normalization transform for connection weights.
Convenience wrapper for add_transform("weight", ...).
Parameters
equation_rhs : str, default=“(M - M_min) / (M_max - M_min)” Right-hand side of normalization equation. Can reference M (matrix), M_min, M_max.
Examples
sc = Connectome(parcellation={"atlas": {"name": "DesikanKilliany"}})
sc.normalize_weights("M / M_max") # Normalize to [0, 1]
normalized = sc.weights_matrix # 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 = Connectome(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 = Connectome(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 = Connectome(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 = Connectome(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 = Connectome(parcellation={"atlas": {"name": "DesikanKilliany"}})
fig, ax = plt.subplots()
im = sc.plot_weights(ax, log=True)
plt.colorbar(im, ax=ax)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_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 Connectome 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 Connectome
Examples
sc = Connectome(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 formattree_flatten
classes.network.Network.tree_flatten()Return children and auxiliary data for JAX pytree support.
Children: (weights, lengths) so JAX can map/transform numerical payloads. Aux data: metadata dict WITHOUT the array data to avoid duplication.
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,
)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
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)).