tvbo network

Build brain-network connectomes. Today this sub-tree has one verb, build, a thin wrapper around MRtrix3’s tck2connectome that turns a streamline tractogram + a parcellation into a tvbo structural connectome (…_desc-SC_relmat.h5 + YAML sidecar) you can load with tvbo.Network(...).

Prerequisites

tvbo network build shells out to MRtrix3 — it does not vendor any tractography code. You need tck2connectome on your PATH:

If MRtrix is missing, the command fails fast with these same links.

Same space, not registered here

The tractogram and the parcellation image must already be co-registered in the same space (e.g. both in FSLMNI152). tvbo network build does not register them — it only assigns streamline endpoints to parcellation labels. Record the shared space with --space so it lands in the output filename and metadata.

Synopsis

tvbo network build TRACTOGRAM PARCELLATION
    [--output, -o PATH]
    [--atlas NAME] [--space NAME] [--cohort NAME]
    [--reconstruction, --rec NAME] [--seg NAME] [--scale NAME]
    [--labels FILE]
    [--symmetric / --no-symmetric]
    [--zero-diagonal / --no-zero-diagonal]
    [--keep-assignments PATH]
    [--mrtrix-arg ARG ...]
    [--overwrite] [--dry-run]

Flags

Flag Default Purpose
TRACTOGRAM (required) Streamline tractogram MRtrix can read (e.g. .tck), same space as the parcellation.
PARCELLATION (required) Integer-labelled parcellation image (e.g. dseg.nii.gz), same space as the tractogram.
--output, -o (BIDS-derived name in CWD) Sidecar path (.yaml); the .h5 companion is written next to it.
--atlas (none) Parcellation/atlas name — metadata and atlas- filename entity.
--space (none) Shared coordinate space (e.g. FSLMNI152) — the tpl- entity.
--cohort (none) Cohort/dataset — the cohort- entity (e.g. HCPYA).
--reconstruction, --rec (none) Tractography pipeline (e.g. dTOR) — the rec- entity + tractogram metadata.
--seg (none) Segmentation — the seg- entity (e.g. 17Networks).
--scale (none) Scale — the scale- entity (e.g. 1000).
--labels (none) Text file, one node label per line, ordered by parcellation label 1..N.
--symmetric / --no-symmetric --symmetric Pass -symmetric to tck2connectome.
--zero-diagonal / --no-zero-diagonal --zero-diagonal Pass -zero_diagonal to tck2connectome.
--keep-assignments (discarded) Save tck2connectome’s -out_assignments to this path.
--mrtrix-arg (none) Extra raw argument forwarded to both tck2connectome calls (repeatable).
--overwrite false Overwrite existing output.
--dry-run false Print the tck2connectome commands and exit without running them.

Behaviour

  1. Checks tck2connectome is installed (friendly error with docs links if not).
  2. Resolves the output path and the overwrite guard up front — before the (potentially minutes-long) MRtrix run — since the name is entirely entity-derived.
  3. Runs tck2connectome twice in a temp dir:
    • weights: streamline count per node pair;
    • lengths — -scale_length -stat_edge mean, the mean streamline length per edge.
  4. Loads the two CSVs, assembles a Network (descriptor: SC, distance_unit: mm) with any --labels and the provided BIDS entities, and saves the sidecar + .h5.

The result loads straight back through the normal DB path, e.g. tvbo.Network(atlas=..., tractogram=...) / get_normative_connectome_data(...) — see Networks.

Examples

# Preview the exact MRtrix commands without running them
tvbo network build dTOR.tck atlas_dseg.nii.gz --dry-run

# Minimal build → BIDS-named output in the current directory
tvbo network build dTOR.tck Schaefer1000_dseg.nii.gz \
    --space FSLMNI152 --atlas Schaefer2018 --rec dTOR \
    --seg 17Networks --scale 1000 --cohort HCPYA
#   → tpl-FSLMNI152_cohort-HCPYA_rec-dTOR_atlas-Schaefer2018_seg-17Networks_scale-1000_desc-SC_relmat.{yaml,h5}

# Explicit output path + node labels + keep the streamline assignments
tvbo network build dTOR.tck DK_dseg.nii.gz \
    --atlas DesikanKilliany --rec dTOR --labels dk_labels.txt \
    --keep-assignments assignments.csv \
    -o desikan_dTOR.yaml

# Forward an extra MRtrix flag to both tck2connectome calls
tvbo network build dTOR.tck atlas_dseg.nii.gz --rec dTOR \
    --mrtrix-arg -tck_weights_in --mrtrix-arg sift2_weights.txt \
    -o weighted.yaml

Suggested methods description

If you use the TVB-O network builder to construct connectomes for a publication, the paragraphs below are starting points for your Methods section. Pick the tab that matches your data, adapt the parcellation and any non-default choices to what you ran, and cite the tools. The normative variant describes how the connectomes shipped with TVB-O were produced.

Structural connectomes were constructed for each participant with the network builder of The Virtual Brain Ontology (TVB-O) [1], the metadata and code-generation framework for The Virtual Brain [2], which calls the connectome tool of MRtrix3 [3]. A whole-brain streamline tractogram, reconstructed from the participant’s diffusion-weighted MRI, and a parcellation image in the same space were used as input. Each end of every streamline was assigned to the nearest parcellation node found by a radial search out to 4 mm, and endpoints with no node in range were left unassigned [4]. Two matrices were derived over these assignments. In the weight matrix, each entry is the number of streamlines that connect a pair of nodes. In the length matrix, every streamline contributes its own length, and the entry for a node pair is the mean of those lengths across the streamlines assigned to it, so the value is the mean streamline length of that connection. Both matrices were written in undirected form, meaning a node pair carries a single value that does not depend on which node is treated as the streamline’s start or end, and the matrix diagonal was set to zero so that self-connections are excluded. The weight and length matrices were stored together as one connectome, an HDF5 array file with a YAML sidecar named following the Brain Imaging Data Structure [5], from which TVB-O reads them at simulation time.

Group-level structural connectomes were constructed with the network builder of The Virtual Brain Ontology (TVB-O) [1], the metadata and code-generation framework for The Virtual Brain [2], which calls the connectome tool of MRtrix3 [3]. In place of subject-specific tractography, we used a normative whole-brain tractogram, the dTOR-985 connectome [6], which holds roughly 12 million streamlines reconstructed in MNI space from the diffusion MRI of 985 Human Connectome Project subjects. This tractogram and a parcellation in the same MNI template space were used as input. Each end of every streamline was assigned to the nearest parcellation node found by a radial search out to 4 mm, and endpoints with no node in range were left unassigned [4]. In the weight matrix, each entry is the number of streamlines that connect a pair of nodes. In the length matrix, every streamline contributes its own length, and the entry for a node pair is the mean of those lengths, so the value is the mean streamline length of that connection. Both matrices were written in undirected form with a zeroed diagonal, so each node pair carries a single value and self-connections are excluded. The matrices were stored together as one connectome, an HDF5 array file with a YAML sidecar named following the Brain Imaging Data Structure [5]. The normative connectomes distributed with TVB-O were produced this way.

Edge weights are raw streamline counts and index the relative density of a connection rather than an absolute measure of axonal strength. Because streamline endpoints are matched to parcellation labels by proximity, the tractogram and the parcellation must already lie in the same coordinate space; the builder performs no registration.

References

[1]
L. Martin et al., “The virtual brain ontology: A digital knowledge framework for reproducible brain network modeling,” bioRxiv, Nov. 2025, doi: 10.1101/2025.11.19.689211.
[2]
P. Sanz Leon et al., “The virtual brain: A simulator of primate brain network dynamics,” Frontiers in Neuroinformatics, vol. 7, Jun. 2013, doi: 10.3389/fninf.2013.00010.
[3]
J.-D. Tournier et al., “MRtrix3: A fast, flexible and open software framework for medical image processing and visualisation,” NeuroImage, vol. 202, p. 116137, Aug. 2019, doi: 10.1016/j.neuroimage.2019.116137.
[4]
R. E. Smith, J.-D. Tournier, F. Calamante, and A. Connelly, “The effects of SIFT on the reproducibility and biological accuracy of the structural connectome,” NeuroImage, vol. 104, pp. 253–265, 2015, doi: 10.1016/j.neuroimage.2014.10.004.
[5]
K. J. Gorgolewski et al., “The brain imaging data structure, a format for organizing and describing outputs of neuroimaging experiments,” Scientific Data, vol. 3, no. 1, Jun. 2016, doi: 10.1038/sdata.2016.44.
[6]
G. J. B. Elias et al., “A large normative connectome for exploring the tractographic correlates of focal brain interventions,” Scientific Data, vol. 11, no. 1, Apr. 2024, doi: 10.1038/s41597-024-03197-0.

See also