Connectome 2.0 Diffusion MRI (in vivo): sample notebook

A worked notebook for Connectome 2.0 Diffusion MRI (in vivo), with 6 code cells and the output each one printed. On Scigantic it opens in a hosted JupyterLab with the dataset already mounted, so nothing is downloaded first.

Provider
Gabriel Ramos-Llordén
License
CC0
Size
19 files, 238.9 MB
Stored at
Amazon S3, s3://openneuro.org/ds006181 (us-east-1)
Access
Free and public. No account with the data provider is needed.
DOI
10.18112/openneuro.ds006181.v1.0.0

The notebook

Inside the first public brain from the Connectome 2.0 scanner

Start here. Click the grey cell below and press Shift+Enter. It reads the headers and gradient tables of all five acquisitions on the mount (nothing is decompressed yet) and prints the shell table. Then change SHOW to 'D30' and run it again.

This is OpenNeuro ds006181: in vivo diffusion MRI from the Connectome 2.0 scanner (Siemens MAGNETOM Connectom.X) at the Athinoula A. Martinos Center, a system with 500 mT/m gradients and 600 T/m/s slew rate built for microstructure imaging (Ramos-Llorden et al., *Nature Biomedical Engineering*, 2025, project site connectome2.martinos.org, NIH U24NS137077). One subject, 2 mm isotropic, two diffusion times (13 and 30 ms), eight shells each, up to b = 17,800 s/mm2, which no clinical scanner can reach. The archive is FUSE-mounted read-only at $SCIGANTIC_MOUNT_PATH; every cell below runs against those bytes.

import os, numpy as np, nibabel as nib
SHOW = 'D13'   # 'D13' = 13 ms diffusion time, 'D30' = 30 ms

root = os.environ.get('SCIGANTIC_MOUNT_PATH', '/mnt/archive')
NOMINAL = np.array([0, 50, 200, 350, 800, 950, 1500, 2300, 2400, 3450, 4250, 4750, 6000, 6750, 9850, 13500, 17800])
nominal = lambda b: NOMINAL[np.abs(NOMINAL[:, None] - np.asarray(b)[None, :]).argmin(0)]   # the .bval files are unrounded

for acq in [f'{SHOW}d6lowb32dirs_dir-AP', f'{SHOW}d6highb64dirs_dir-AP']:
    base = f'{root}/sub-01/dwi/sub-01_acq-{acq}_dwi'
    img = nib.load(base + '.nii.gz')                 # header only
    b = nominal(np.loadtxt(base + '.bval'))
    shells = {int(k): int(v) for k, v in zip(*np.unique(b[b > 0], return_counts=True))}
    print(f'{acq:24s} {img.shape}  b0s={int((b == 0).sum()):2d}  shells (b: directions) = {shells}')
print(f'Diffusion time {SHOW[1:]} ms, pulse width 6 ms, TE 53 ms, 2 mm isotropic; the other diffusion time has a different set of eight shells.')

1. A gradient table no clinical scanner can produce

A 3T system with 80 mT/m gradients needs a long diffusion time to reach even b = 3,000. Here the gradients are six times stronger, so the same b-values are reached at 13 ms and at 30 ms, and the top shells go far beyond. The sixteen shells below are the whole acquisition, 886 diffusion-weighted volumes plus b = 0 images, colour-coded by diffusion time.

import matplotlib.pyplot as plt
plt.rcParams['figure.dpi'] = 72
rows = []
for delta in ('D13', 'D30'):
    for acq in (f'{delta}d6lowb32dirs_dir-AP', f'{delta}d6highb64dirs_dir-AP'):
        b = nominal(np.loadtxt(f'{root}/sub-01/dwi/sub-01_acq-{acq}_dwi.bval'))
        for shell, n in zip(*np.unique(b[b > 0], return_counts=True)):
            rows.append((int(delta[1:]), int(shell), int(n)))
fig, ax = plt.subplots(figsize=(7, 3.2))
for delta, color in ((13, 'tab:orange'), (30, 'tab:blue')):
    pts = [(b, n) for d, b, n in rows if d == delta]
    ax.scatter([p[0] for p in pts], [p[1] for p in pts], s=[p[1] * 2 for p in pts], color=color, alpha=0.8, label=f'diffusion time {delta} ms')
    for b, n in pts:
        ax.annotate(str(b), (b, n), textcoords='offset points', xytext=(0, 7), ha='center', fontsize=7, color=color)
ax.axvspan(0, 3000, color='0.92', zorder=0); ax.text(1500, 70, 'typical clinical range', ha='center', fontsize=8, color='0.4')
ax.set_xlabel('b-value (s/mm2)'); ax.set_ylabel('directions per shell'); ax.set_xlim(0, 18500); ax.set_ylim(20, 75)
ax.legend(loc='upper right', frameon=False); fig.tight_layout(); plt.show()
print(len(rows), 'shells,', sum(n for _, _, n in rows), 'diffusion-weighted volumes')

Output:

16 shells, 800 diffusion-weighted volumes

2. Watching the water signal fall to b = 17,800

Each raw file is a 4D NIfTI; the big one holds 345 volumes (1.1 GB as float32), so we never load a whole file. img.dataobj[:, :, z0:z1, :] reads a six-slice slab in one pass through the gzip stream (about 30 MB per file). The brain mask is just "b = 0 signal above 150". The curve is the log of the mean signal relative to b = 0, per shell and per diffusion time.

SLAB_Z = slice(30, 36)     # six axial slices through the centre of the brain
decay = {}                  # (delta, b) -> mean signal in the brain slab
for delta in ('D13', 'D30'):
    for acq in (f'{delta}d6lowb32dirs_dir-AP', f'{delta}d6highb64dirs_dir-AP'):
        base = f'{root}/sub-01/dwi/sub-01_acq-{acq}_dwi'
        b = nominal(np.loadtxt(base + '.bval'))
        slab = np.asarray(nib.load(base + '.nii.gz').dataobj[:, :, SLAB_Z, :])      # (110,110,6,N) float32
        mask = slab[..., b == 0].mean(-1) > 150
        for shell in np.unique(b):
            decay.setdefault((int(delta[1:]), int(shell)), []).append(slab[mask][:, b == shell].mean())
fig, ax = plt.subplots(figsize=(7, 3.4))
for delta, color in ((13, 'tab:orange'), (30, 'tab:blue')):
    s0 = np.mean(decay[(delta, 0)])
    bs = sorted(b for d, b in decay if d == delta and b > 0)
    ax.plot(bs, [np.log(np.mean(decay[(delta, b)]) / s0) for b in bs], 'o-', color=color, label=f'{delta} ms')
ax.set_xlabel('b-value (s/mm2)'); ax.set_ylabel('ln S(b) / S(0), brain slab mean'); ax.legend(frameon=False, title='diffusion time')
fig.tight_layout(); plt.show()
for delta in (13, 30):
    top = max(b for d, b in decay if d == delta)
    print(f'{delta} ms: at b = {top:5d} the mean brain signal is {np.mean(decay[(delta, top)]) / np.mean(decay[(delta, 0)]) * 100:.1f}% of b = 0')

Output:

13 ms: at b =  6000 the mean brain signal is 7.1% of b = 0
30 ms: at b = 17800 the mean brain signal is 3.9% of b = 0

The curve bends: a single diffusion coefficient would give a straight line. The bend is the kurtosis, the signature of water trapped in and between cells, and the point of pushing b this high is to measure it well.

3. Where the diffusion time matters

Water that is confined changes its apparent diffusivity with the time it is given to move; free water does not. The dataset pairs nearly matched shells across diffusion times (b = 2,400 at 13 ms, b = 2,300 at 30 ms), so a voxel-by-voxel comparison of the two shows where restriction is at work. White matter, with its narrow axons, should stand out.

def shell_mean(delta, want, z=SLAB_Z):
    for acq in (f'{delta}d6lowb32dirs_dir-AP', f'{delta}d6highb64dirs_dir-AP'):
        base = f'{root}/sub-01/dwi/sub-01_acq-{acq}_dwi'
        b = nominal(np.loadtxt(base + '.bval'))
        if want in b:
            idx = np.flatnonzero(b == want); lo, hi = idx.min(), idx.max() + 1
            block = np.asarray(nib.load(base + '.nii.gz').dataobj[:, :, z, lo:hi])     # the shell's volumes only
            b0 = np.asarray(nib.load(base + '.nii.gz').dataobj[:, :, z, :][..., b == 0]).mean(-1)
            return block[..., idx - lo].mean(-1), b0
s13, b0_13 = shell_mean('D13', 2400)
s30, b0_30 = shell_mean('D30', 2300)
mask = (b0_13 > 150) & (b0_30 > 150)
ratio = np.where(mask, (s30 / np.maximum(b0_30, 1)) / np.maximum(s13 / np.maximum(b0_13, 1), 1e-6), np.nan)
k = 3     # slice within the slab to show
fig, axes = plt.subplots(1, 3, figsize=(8.4, 3.0))
for ax, im, title, kw in ((axes[0], s13[..., k], 'b=2400, 13 ms', dict(cmap='gray')), (axes[1], s30[..., k], 'b=2300, 30 ms', dict(cmap='gray')),
                          (axes[2], ratio[..., k], 'normalised signal, 30 ms / 13 ms', dict(cmap='coolwarm', vmin=0.7, vmax=1.3))):
    m = ax.imshow(np.rot90(im), interpolation='nearest', **kw); ax.set_title(title, fontsize=9); ax.axis('off')
fig.colorbar(m, ax=axes[2], fraction=0.046); fig.tight_layout(); plt.show()
print(f'median ratio in brain {np.nanmedian(ratio):.3f}; 10th-90th percentile {np.nanpercentile(ratio, 10):.3f} to {np.nanpercentile(ratio, 90):.3f}')

Output:

median ratio in brain 0.973; 10th-90th percentile 0.876 to 1.051

A ratio below 1 means the signal fell more in 30 ms than in 13 ms at the same b: water is still being hindered as time goes on. The two shells differ by 100 s/mm2, so the absolute level carries a small bias, but the spatial pattern is the measurement.

4. Fibre directions from the tensor

The familiar picture. A diffusion tensor fit on the 13 ms low-b acquisition (b up to 1,500, 150 volumes) gives fractional anisotropy and the principal direction, drawn as red = left-right, green = anterior-posterior, blue = up-down. This runs in a couple of seconds on the slab.

from dipy.core.gradients import gradient_table
from dipy.reconst.dti import TensorModel, color_fa
base = f'{root}/sub-01/dwi/sub-01_acq-D13d6lowb32dirs_dir-AP_dwi'
bvals, bvecs = np.loadtxt(base + '.bval'), np.loadtxt(base + '.bvec')
gtab = gradient_table(bvals, bvecs=bvecs, b0_threshold=10)      # b=50 is a real shell here, so not dipy's default of 50
slab = np.asarray(nib.load(base + '.nii.gz').dataobj[:, :, SLAB_Z, :])
mask = slab[..., gtab.b0s_mask].mean(-1) > 150
fit = TensorModel(gtab).fit(slab, mask=mask)
fa = np.clip(fit.fa, 0, 1); rgb = color_fa(fa, fit.evecs)
fig, axes = plt.subplots(1, 2, figsize=(6.6, 3.3))
axes[0].imshow(np.rot90(fa[..., k]), cmap='gray', vmin=0, vmax=0.8, interpolation='nearest'); axes[0].set_title('fractional anisotropy', fontsize=9)
axes[1].imshow(np.rot90(rgb[..., k, :]), interpolation='nearest'); axes[1].set_title('principal direction (RGB = x, y, z)', fontsize=9)
for ax in axes: ax.axis('off')
fig.tight_layout(); plt.show()
print(f'FA median in brain {np.median(fa[mask]):.3f}; voxels with FA > 0.5 (coherent white matter): {int((fa[mask] > 0.5).sum())} of {int(mask.sum())}')

Output:

FA median in brain 0.174; voxels with FA > 0.5 (coherent white matter): 1731 of 19273

5. Beyond the tensor: kurtosis from the high shells

The tensor assumes Gaussian diffusion and ignores the bend in section 2. Diffusion kurtosis imaging fits that bend; it needs at least two non-zero shells and benefits from strong gradients at short diffusion times, which is what this scanner provides. Here the 13 ms shells up to b = 2,400 (the low-b file plus the first shell of the high-b file) go into dipy's DKI model on the same slab.

from dipy.reconst.dki import DiffusionKurtosisModel
lo_base = f'{root}/sub-01/dwi/sub-01_acq-D13d6lowb32dirs_dir-AP_dwi'
hi_base = f'{root}/sub-01/dwi/sub-01_acq-D13d6highb64dirs_dir-AP_dwi'
b_hi = nominal(np.loadtxt(hi_base + '.bval')); keep_hi = (b_hi == 2400) | (b_hi == 0)
idx = np.flatnonzero(keep_hi); lo, hi = idx.min(), idx.max() + 1
hi_block = np.asarray(nib.load(hi_base + '.nii.gz').dataobj[:, :, SLAB_Z, lo:hi])[..., idx - lo]
data = np.concatenate([slab, hi_block], -1)
bv = np.concatenate([bvals, b_hi[keep_hi]]); bvec = np.concatenate([bvecs, np.loadtxt(hi_base + '.bvec')[:, keep_hi]], 1)
gtab_k = gradient_table(bv, bvecs=bvec, b0_threshold=10)
kfit = DiffusionKurtosisModel(gtab_k).fit(data, mask=mask)
mk = np.clip(kfit.mk(0, 3), 0, 3)
fig, ax = plt.subplots(figsize=(3.8, 3.6))
im = ax.imshow(np.rot90(mk[..., k]), cmap='magma', vmin=0, vmax=1.6, interpolation='nearest'); ax.set_title('mean kurtosis', fontsize=9); ax.axis('off')
fig.colorbar(im, fraction=0.046); fig.tight_layout(); plt.show()
print(f'{data.shape[-1]} volumes over shells {sorted(set(nominal(bv).tolist()))}; mean kurtosis median in brain {np.median(mk[mask]):.2f}, in FA > 0.5 voxels {np.median(mk[mask & (fa > 0.5)]):.2f}')

Output:

234 volumes over shells [0, 50, 350, 800, 1500, 2400]; mean kurtosis median in brain 0.77, in FA > 0.5 voxels 1.03

Kurtosis is higher in white matter than in cortex, and higher still where fibres cross. With the 30 ms shells and the b = 4,000 to 17,800 data the same model can be pushed into the regime where axon diameters become measurable, which is the scanner's purpose.

6. Where to go next

Data: OpenNeuro ds006181, CC0. Cite Ramos-Llorden G., Lee H.-H., Ma Y., Lee H., Huang S.Y., "Connectome 2.0: Next-Generation Connectomics and Microstructure MRI Scanner for Imaging of Human Brain Circuits across Scales", Nature Biomedical Engineering, 2025.

Run it

Open this notebook to run it, see the dataset page for the full description, or browse the full catalog.