---
updatedAt: 2026-08-18T23:55:06.000Z
agentTools:
projectIndex: https://docs.sparc.science/llms.txt
---
# Scaffold Mapping Tools: Using Subject-Specific Vagus (SSV) Scaffolds For Population-Level Analysis
This tutorial shows how to use the **Scaffold Mapping Tools** to visualize branching patterns of subject-specific vagus scaffolds using the vagus material coordinates.
Vagus material coordinates, also known as vagus coordinates, are defined as a straight line along the vagal trunk, with the origin as the top of the trunk and 1 as the bottom end of the trunk. The branches are defined as lines with the same orientation as when they leave the trunk.
Mapping branches into these coordinates allows branches from different subjects to be visualized along the same trunk geometry, making it easier to locate branch origins or spatial distributions along a length scale between 0 and 1 for systematic quantification of branch behavior.
Any number of subjects can be added to the visualization. For demonstration purposes, this tutorial uses vagus scaffolds derived from two subjects (**f009**, DOI: [10.26275/un0a-zzdl](https://doi.org/10.26275/un0a-zzdl)) and **f019**, DOI: [10.26275/8ekx-tqxe](https://doi.org/10.26275/8ekx-tqxe)), from the Feinstein collection (DOI: [10.26275/2vva-qmjw](https://doi.org/10.26275/2vva-qmjw)).
By the end of this tutorial, you will learn how to:
* retrieve subject-specific vagus scaffolds from the SPARC Portal;
* map branches onto a common vagus material coordinates; and
* generate qualitative branch distribution visualizations.
***
## Step 1: Create and execute the workflow
Launch **MAP Client Mapping Tools** from the Start Menu under `MAP-Client-mapping-tools vX.Y.Z` (X, Y, and Z will be the actual version numbers).
Set up a new workflow named *SSV-vagus-coordinates* on your Desktop by
creating a new folder on the Desktop named `SSV-vagus-coordinates`. In **MAP Client Mapping Tools**, go to **File → New Workflow** (`Ctrl+Shift+N`). Select the `SSV-vagus-coordinates` directory you just created.
To set up the organ inserter workflow, add the following steps to the workflow area and connect them as shown in **Figure 1**:
* One **Retrieve Portal Data** steps
* One **Argon Viewer** step
* One **Argon Scene Exporter** step
### Retrieve Portal Data step
Configure the first **Retrieve Portal Data** by setting its identifier to `SSV scaffolds` as shown in **Figure 2**.
### Argon Scene Exporter step
Configure the **Argon Scene Exporter** step by changing Export type to `image`, the prefix to `branch_directions_left` and selecting an output directory for saving the image. Set Width and Height to 2048 in order to export a high-resolution image as shown in **Figure 3**.
Once the workflow is complete, save it (`Ctrl+S`) and click `Execute`.
## Step 2: Retrieve data from the SPARC Portal
In this example, we will retrieve the SSV scaffolds for the left side only but the same steps apply to generating visualizations for the right vagus.
Enter `https://doi.org/10.26275/tjzi-muqm` in the **Search term** field and click `Search`. The search results will show up in the **Search results** panel.
To filter the results to scaffold files, enter `scaffold-exf` in the **Filter** field and select `Mimetype`. Click the **Filename** header to sort the results alphabetically.
In this example, we are inserting vagus scaffolds from two subjects (**f009** and **f019**). From the list, locate the following two files:
`f009-left_vagus_scaffold.exf`
`f019-left_vagus_scaffold.exf`
Hold `Ctrl` while selecting both files, then click `Download`. Once the selected files are loaded in the **Provided files** panel as shown in **Figure 4**, click `Done` to proceed.
In the next section, we will use **Argon Viewer** to visualize the SSV scaffolds in vagus coordinates.
***
## Step 3: Visualize vagus scaffolds with vagus coordinates
### Set up view, regions and model sources
Click **Add View** to add a `Layout1` view panel.
Open the **Region Editor**. Right-click and select **Add child region** to create two child regions. Double-click each newly created region to rename them `f009` and `f019`. The resulting region hierarchy should look like **Figure 5**.
Next, click the **Model Sources** tab in the top panel. Assign each scaffold file to its corresponding child region by selecting the appropriate region and then clicking the **green plus** icon, as shown in **Figure 6**.
### Create vagus nerve centroid and normalised branching directions with vagus coordinates
Next, we will set up the vagus trunk centroids. This only needs to be done once per side using any subject, since the trunks from all different subjects should be mapped to the same vagal trunk in the vagus material coordinates. In this tutorial, we will set it up for `/f009`.
Go to **Field Editor** and use the following settings to set up a field called `left vagus nerve centroid` in the **Region** for `/f009` as shown in **Figure 7**:
**Add …**: `And`
**Source Field 1**: `left vagus nerve`
**Source Field 2**: `vagus centroid`
**Name**: `left vagus nerve centroid`
As we will be visualizing the origins and initial directions of vagal branches, we first need to create a group called `vagus nerve branches`.
For each of the vagus sub-regions (`/f009` and `/f019`), create the following field as shown in **Figure 8**:
**Add...:** `Not`
**Source Field**: `left vagus nerve`
**Name**: `left vagus nerve branches`
Next, as shown in **Figure 9**, we add a **Derivative** field for the same regions with the following settings:
**Coordinate Field**: `vagus coordinates`
**xi index**: `1`
**Name**: `vc_dx_dxi1`
As the derivative of the coordinates field with respect to the first element coordinates (`xi1`) provides a vector tangent to the branch, the vector `vc_dx_dxi1` represents the local direction of the branch in the vagus coordinate system.
Then, we add a **Normalise** field as shown in **Figure 10** for each of the vagus regions:
**Source Field**: `vc_dx_dxi1`
**Name**: `norm_vc_dx_dxi1`
Normalising `vc_dx_dxi1` removes its magnitude while retaining its direction. This allows it to be used to orient the glyphs later for visualization.
### Visualize branches using vagus coordinates
#### Visualize vagus trunk in vagus coordinates
Go to **Scene Editor**, and for `/f009` region, add **lines** with the following settings:
**Subgroup**: `left vagus nerve centroid`
**Coordinates**: `vagus coordinates`
**Shape**: `circle extrusion`
**Base size**: `0.01*0.01`
At this stage, the **Layout1** panel will still be empty. To display the graphics you have just created, open **Sceneviewer Editor** and click `View All`. Adjust the graphics to a comfortable viewing position using **left-click** to rotate, **middle-click** to pan and **right-click** to zoom. From this point onward, any newly added graphic objects should appear in the view panel when they are configured correctly.
If you would like to visualize the level markers in the vagus coordinates, add **node points** with the following settings:
**Subgroup**: `marker`
**Coordinates**: `marker vagus coordinates`
**Glyph**: `line`
**Base size**: `0.5*0.5*0.5`
**Label field**: `marker_name`
**Glyph offset**: `-0.5, 0, 0`
**Label text offset**: `-0.1, 0.0, 0.0`
#### Visualize branch groups
It is often helpful to create translucent materials when visualizing multiple branch groups, as it makes it easier to see how different groups of branches interact with and overlap one another.
Go to **Material Editor**, and click `Create`. Double-click the new material and rename it to `magenta50`. Select magenta for both **Ambient Colour** and **Diffuse Colour**. Then set:
**Alpha**: `0.5`
**Shininess**: `0.2`
Follow the same steps to create `green50`, which is a translucent version of the **green** material.
Go to `/f009` region and add **element points** to visualize the left superior laryngeal nerve with the following settings:
**Subgroup**: `left superior laryngeal nerve`
**Coordinates**: `vagus coordinates`
**Material**: `magenta50`
**Glyph**: `cylinder`
**Base size**: `0.1*0.01*0.01`
**Scale field**: `norm_vc_dx_dxi1`
**Scaling**: `0.01*0.01*0.01`
Repeat these steps for `/f019`. You should now be able to see the left superior laryngeal nerves from both **f009** and **f019** mapped onto the same vagus material coordinates.
We recommend using a translucent material, such as `magenta50`, to make it easier to identify overlapping branches. Additional vagal branch groups can also be visualized using different materials. For example, the **left cardiovascular branch of cervical vagus nerve** can be added using a different material (`green50`) to investigate how different branch groups are distributed along the vagal trunk, as shown in **Figure 12**.
Because a translucent material is being used, adjust the scene settings in **Sceneviewer Editor** by setting **Transparency mode** to `slow`.
### Visualize branch distribution and density
Sometimes it can be helpful to visualize branches from multiple subjects on a common coordinate system without including their branch trajectories.
In the next visualization, we will generate a qualitative representation of branch density, whereby regions where multiple branches overlap appear more prominent because of the increased opacity.
Regions where branches from multiple subjects overlap can reveal areas of consistent branching, while differences in overlap can highlight inter-subject differences. This provides a qualitative view of branch density and distribution and can help identify patterns for further quantitative analysis.
First, clear the **Layout** view by unchecking all graphic objects in **Scene Editor**.
In **Scene Editor**, select `/f009` from the **Region** and turn on visibility of the line graphic previously created for `left vagus nerve centroid` using the `vagus coordinates`.
Next, add **element points** with the following settings:
**Subgroup**: `left superior laryngeal nerve`
**Coordinates**: `vagus coordinates`
**Material**: `magenta10`
**Glyph**: `cylinder`
**Base size**: `0.2*0.01*0.01`
**Glyph offset**: `-0.5, 0.0, 0.0`
We use `magenta10` rather than `magenta50` for the density plot because `magenta10` is a more transparent version of the magenta material. This makes overlapping branches easier to identify and provides a better representation of branch density.
The `magenta10` material can be created using the same steps described previously for creating `magenta50` in the ‘Material Editor’. The only difference is to set the **Alpha** value to `0.1`.
Next, follow the same steps to add **element points** for **left cardiovascular branch of cervical vagus nerve** from **f009**. Select the appropriate branch group under **Subgroup** and use the `green10` material to visualize these branches.
Repeat these steps for any additional subjects you wish to include. In this example, repeat the process for `/f019`, adding graphics for the corresponding branch groups until you derive a visualization as shown in **Figure 13**.
### Exporting the generated visualization
Once you have successfully generated the visualization required for your publication or presentation, click `Done`. This will end the workflow, and the visualization displayed in the **Layout** view will automatically be exported to the directory specified during the **Argon Scene Exporter** configuration step.
### Summary
In this tutorial, we mapped the subject-specific scaffolds to a common coordinate framework, thereby enabling comparison of branch distributions across subjects and generation of qualitative visualizations of branch density.