Initial commit

Author: mattcieslak

.github/workflows/publish.yml

@@ -0,0 +1,25 @@
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+name: Render and publish
+
+jobs:
+  build-deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Quarto
+        uses: quarto-dev/quarto-actions/setup@v2
+
+      - name: Render and publish to GitHub Pages
+        uses: quarto-dev/quarto-actions/publish@v2
+        with:
+          target: gh-pages
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -0,0 +1,21 @@
+# Quarto build outputs
+_site/
+.quarto/
+**/*.quarto_ipynb
+
+# Large neuroimaging data (not tracked — download separately)
+*.tck
+*.trx
+*.mif
+*.mif.gz
+*.nii.gz
+
+# Generated pipeline outputs
+*.csv
+*.tsf
+walkthrough/*_nodes.txt
+walkthrough/*_mean.txt
+tmp_*
+
+# Logs
+render.log

_freeze/site_libs/clipboard/clipboard.min.js

@@ -0,0 +1,31 @@
+project:
+  type: website
+  output-dir: _site
+
+website:
+  title: "TRX Tractography: A Better Way"
+  navbar:
+    left:
+      - href: index.qmd
+        text: Home
+      - href: walkthrough.qmd
+        text: Walkthrough
+  page-footer:
+    center: "Built with [Quarto](https://quarto.org)"
+
+format:
+  html:
+    theme: cosmo
+    code-tools: true
+    code-copy: true
+    toc: true
+    toc-depth: 3
+    toc-location: right
+    anchor-sections: true
+    smooth-scroll: true
+    highlight-style: monokai
+    css: styles.css
+    grid:
+      sidebar-width: 0px
+      body-width: 1050px
+      margin-width: 220px

_freeze/walkthrough/execute-results/html.json

@@ -0,0 +1,45 @@
+---
+title: "TRX Tractography in MRtrix3"
+subtitle: "A self-contained, reproducible tractography workflow"
+---
+
+## Why TRX?
+
+A typical MRtrix3 tractography pipeline for one subject produces **at least six separate files** that must travel together:
+
+```
+tracks.tck              ← 5–15 GB geometry
+sift2_weights.csv       ← per-streamline weights
+assignments.txt         ← node-pair labels (tck2connectome)
+connectome.csv          ← connectivity matrix
+node_names.txt          ← atlas label list
+exemplar_bundles.zip    ← optional
+```
+
+Lose or misplace one, and downstream analyses break silently — wrong weights get applied, the connectome is recomputed without normalisation, or the wrong atlas is used.
+
+**[TRX](https://github.com/tee-ar-ex/trx-spec)** (Tractography Exchange) is a container format that stores geometry, per-streamline data (dps), per-vertex data (dpv), and group memberships together in a single zip file.  This walkthrough demonstrates a complete tractography pipeline run two ways — classic TCK-based and TRX-based — on the same HCP subject, showing that the outputs are numerically identical while the TRX pipeline requires fewer files and fewer commands.
+
+## What you'll see
+
+| Step | Classic pipeline | TRX pipeline |
+|------|-----------------|--------------|
+| Generate streamlines | `tckgen → tracks.tck` | `tckgen → tracks.trx` |
+| SIFT2 weighting | `tcksift2 → weights.csv` | `tcksift2 -trx_dps → (embedded)` |
+| Atlas labeling | `tck2connectome -out_assignment` | `trxlabel → (groups embedded)` |
+| Connectome | `tck2connectome` | `trx2connectome` |
+| Inspect state | `ls *.tck *.csv *.txt` | `tckinfo tracks.trx` |
+
+The TRX file grows as each step adds metadata; `tckinfo` at each stage reveals its evolving contents.
+
+## Data
+
+Subject **sub-100307** from the HCP Young Adult dataset, processed through
+[QSIRecon](https://qsirecon.readthedocs.io)'s `mrtrix_multishell_msmt_hsvs` pipeline.
+Starting inputs:
+
+- WM FOD (msmt-CSD, max SH order 8)
+- Brain mask (mtnormalize inlier mask)
+- Glasser 360-region atlas (registered to T1w space)
+
+→ [Start the walkthrough](walkthrough.qmd)

_quarto.yml

@@ -0,0 +1,76 @@
+/* ── Inline code (prose `backtick` spans) ────────────────────── */
+:not(pre) > code {
+  background: #2d2d2d;
+  color: #e8e8e8;
+  padding: 0.1em 0.35em;
+  border-radius: 3px;
+  font-size: 0.88em;
+}
+
+/* ── Terminal / command output blocks ─────────────────────────── */
+pre.sourceCode.bash, pre.sourceCode.sh {
+  background: #1e1e1e;
+  color: #d4d4d4;
+  border-left: 3px solid #569cd6;
+}
+
+/* Highlight the output blocks differently from code */
+.cell-output pre {
+  background: #0d1117;
+  color: #c9d1d9;
+  border-left: 3px solid #3fb950;
+  font-size: 0.85em;
+}
+
+/* Column layout breathing room */
+.columns {
+  gap: 1.5rem;
+}
+
+/* Step headers */
+h2 {
+  border-bottom: 2px solid #dee2e6;
+  padding-bottom: 0.3em;
+  margin-top: 2.5rem;
+}
+
+/* File-inventory table */
+.file-table {
+  font-family: var(--bs-font-monospace);
+  font-size: 0.85em;
+}
+
+/* Workflow comparison badges */
+.badge-classic {
+  background: #6c757d;
+  color: white;
+  padding: 0.2em 0.6em;
+  border-radius: 4px;
+  font-size: 0.8em;
+  font-weight: bold;
+}
+.badge-trx {
+  background: #0d6efd;
+  color: white;
+  padding: 0.2em 0.6em;
+  border-radius: 4px;
+  font-size: 0.8em;
+  font-weight: bold;
+}
+
+/* tckinfo output box */
+.tckinfo-box {
+  background: #0d1117;
+  color: #c9d1d9;
+  padding: 1rem 1.2rem;
+  border-radius: 6px;
+  border-left: 4px solid #58a6ff;
+  font-family: var(--bs-font-monospace);
+  font-size: 0.82em;
+  overflow-x: auto;
+  white-space: pre;
+}
+.tckinfo-box .highlight {
+  color: #ffa657;
+  font-weight: bold;
+}

connectome_comparison.png

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+# timing_utils.sh — source this file before running the walkthrough
+#
+# Provides mtime(): runs a command, shows its stderr live in the chunk output,
+# then appends a one-line timing + memory summary.
+#
+# How the stderr separation works:
+#   /usr/bin/time -l writes its timing block to stderr AFTER the command exits.
+#   The command's own progress output also goes to stderr.  Both land in $tmp.
+#   We locate the timing block by finding the last line matching
+#   "^ *[0-9.]+ real " (the first line of /usr/bin/time -l output), forward
+#   every line before that as the command's stderr, then parse the timing block.
+#
+# Memory metric: "peak memory footprint" (phys_footprint from TASK_VM_INFO).
+#   Excludes clean read-only mmap pages, so TRX files are not counted twice.
+#   RSS ("maximum resident set size") would be inflated for TRX inputs.
+#
+# Linux: replace -l with -v; the footprint grep becomes:
+#   awk '/Maximum resident/{print $NF * 1024}' "$tmp"
+
+mtime() {
+    local label="$1"; shift
+    local tmp; tmp=$(mktemp)
+
+    /usr/bin/time -l "$@" 2>"$tmp"
+    local exit_code=$?
+
+    # Find where /usr/bin/time's own output starts.
+    # Its first line always matches "^ *[0-9.]+ real " (BSD time format).
+    local timing_line
+    timing_line=$(grep -n "^[[:space:]]*[0-9.]\+ real " "$tmp" \
+                  | tail -1 | cut -d: -f1)
+
+    if [ -n "$timing_line" ] && [ "$timing_line" -gt 1 ]; then
+        # Replay the command's stderr (lines before the timing block)
+        head -n "$((timing_line - 1))" "$tmp"
+    fi
+
+    if [ -z "$timing_line" ]; then
+        # /usr/bin/time didn't produce output — command likely failed
+        cat "$tmp"
+        rm -f "$tmp"
+        return "$exit_code"
+    fi
+
+    # Parse wall / user / sys from the timing line
+    local wall user sys
+    read -r wall _ user _ sys _ \
+        < <(sed -n "${timing_line}p" "$tmp")
+
+    # Parse physical footprint (excludes clean mmap pages)
+    local fp_bytes fp_gb
+    fp_bytes=$(tail -n "+${timing_line}" "$tmp" \
+               | awk '/peak memory footprint/{print $1}')
+    fp_gb=$(awk "BEGIN {printf \"%.2f\", ${fp_bytes:-0} / 1073741824}")
+
+    printf "\n┌─ %-28s ─────────────────────────────────────────────┐\n" "$label"
+    printf "│  wall: %8ss    user: %8ss    sys: %6ss    peak mem: %5s GB  │\n" \
+           "$wall" "$user" "$sys" "$fp_gb"
+    printf "└────────────────────────────────────────────────────────────────────────────┘\n\n"
+
+    rm -f "$tmp"
+    return "$exit_code"
+}