Placing a MERFISH section in the Allen CCF#

The same volume-to-section fit as the STARmap notebook, on a denser section and a finer raster. It is the simpler of the two to write: this section needs no anisotropic initialisation, so initial_slice, initial_rotation and initial_scale say the whole starting guess and initial_affine never appears.

STalign’s own version of this analysis: merfish-allen3Datlas-alignment.

Inputs#

Cells as a points element, the atlas and its annotation volume as 3D images. The physical placement lives on the elements, so nothing downstream builds coordinate axes by hand.

import nrrd, numpy as np, pandas as pd, spatialdata as sd
from spatialdata.models import Image3DModel, PointsModel
from spatialdata.transformations import Scale, Sequence, Translation

cells = pd.read_csv('merfish_data/datasets_mouse_brain_map_BrainReceptorShowcase'
                    '_Slice1_Replicate1_cell_metadata_S1R1.csv.gz')
xy = np.c_[cells['center_x'], cells['center_y']].astype(float)

atlas, hdr = nrrd.read('ara_nissl_50.nrrd')       # (z, y, x)
labels, _ = nrrd.read('annotation_50.nrrd')       # same frame, integer structure ids
voxel = tuple(np.diag(hdr['space directions']))

# The second channel is not decoration: the solver regresses the deformed reference onto the
# section before measuring the match, so one channel fits `a + b*I` and two fit
# `a + b*I + c*(I - mean I)**2`. A regression absorbs a rescaling of its input; it cannot
# invent a channel it was never handed.
def reference_channels(volume):
    v = volume[None] / np.mean(np.abs(volume))
    return np.concatenate([v, (v - v.mean()) ** 2])

sdata = sd.SpatialData(
    points={'cells': PointsModel.parse(xy)},
    images={'atlas': Image3DModel.parse(
        reference_channels(atlas.astype(float)), dims=('c', 'z', 'y', 'x'),
        transformations={'global': Sequence([
            Scale(list(voxel), axes=('z', 'y', 'x')),
            Translation(-(np.asarray(atlas.shape) - 1) * np.asarray(voxel) / 2,
                        axes=('z', 'y', 'x')),
        ])},
    )},
)
sdata
SpatialData object
├── Images
│     └── 'atlas': DataArray[czyx] (2, 264, 160, 228)
└── Points
      └── 'cells': DataFrame with shape: (<Delayed>, 2) (2D points)
with coordinate systems:
    ▸ 'global', with elements:
        atlas (Images), cells (Points)

The section#

rasterize_points turns the centroids into a density image: each cell deposits unit mass bilinearly, blurred once per scale, so total intensity is exactly the cell count.

from squidpy.experimental.im import rasterize_points, sample_volume

rasterize_points(sdata, points_key='cells', dx=10.0, blur=1.0, key_added='section')
sdata['section']
<xarray.DataArray 'image' (c: 1, y: 696, x: 995)> Size: 6MB
dask.array<array, shape=(1, 696, 995), dtype=float64, chunksize=(1, 696, 995), chunktype=numpy.ndarray>
Coordinates:
  * c        (c) int64 8B 0
  * y        (y) float64 6kB 0.5 1.5 2.5 3.5 4.5 ... 692.5 693.5 694.5 695.5
  * x        (x) float64 8kB 0.5 1.5 2.5 3.5 4.5 ... 991.5 992.5 993.5 994.5
Attributes:
    transform:  {'global': Sequence \n    Scale (y, x)\n        [10. 10.]\n  ...

Putting the section on the scale the solver’s parameters assume#

sigmaM, sigmaA, sigmaB, muA and muB are all in the target’s intensity units, and upstream states its values against a mean-normalised section. Handing over the raw raster instead leaves every one of those widths wrong by the raster’s own mean – which for a dx=10 raster is a factor of nine, enough to flatten the artifact/background/matching split into near-constants and leave the fit with almost no gradient to descend.

from spatialdata.models import Image2DModel
from spatialdata.transformations import get_transformation

def mean_normalised(sdata, key):
    element = sdata.images[key]
    values = np.asarray(element)
    sdata.images[key] = Image2DModel.parse(
        values / np.abs(values).mean(), dims=('c', 'y', 'x'),
        transformations={'global': get_transformation(element, 'global')},
    )

mean_normalised(sdata, 'section')
section = np.asarray(sdata['section']).squeeze()
print(f'section now spans {section.min():.2f} to {section.max():.2f}, mean {section.mean():.2f}')
section now spans 0.00 to 7.35, mean 1.00

The fit#

The section is close to coronal and close to atlas scale, so the initialisation is three numbers: which slice to centre on, how far to rotate in plane, and one uniform scale.

Upstream also nudges the starting translation by a single landmark pair, worth about 42 um in x and 7 um in y – four pixels and under one. That is an initialisation, not an answer, and the next cell checks the initialisation directly, so it is left out here rather than reintroducing a hand-built affine to carry it.

from squidpy.experimental.tl import stalign_align_volume

slice_index, rotation, scale = 177, 0.0, 0.9

# Upstream's own values, now that the section is on the scale they were written for. One
# channel, not three: upstream passes `muA=[3, 3, 3]` against a single-channel target and sums
# over the broadcast axis, making its effective widths sigma/sqrt(3) -- divergence D13.
#
# `a` and `sigmaR` are set rather than left to the defaults, from a 3x3 sweep over
# a in {250, 500, 1000} and sigmaR in {1e5, 1e6, 1e7}. A 250 um kernel resolves the
# hippocampal arcs and cortical laminae visibly better than the 500 um default, and at
# sigmaR 1e5 it is the only sweep point that keeps every region the default assigns --
# 163 against 161, none lost -- while agreeing with it on 86% of the 78329 cells. The
# looser sigmaR 1e7 looked sharper still but dropped all of lateral auditory cortex
# (AUDv5, AUDpo5, AUDp1 and six more) to zero cells, which reads as the section's edge
# leaving the annotated volume rather than a real difference in detail.
#
# Upstream's `LDDMM_3D_to_slice` declares sigmaR 1e8, which weights the regulariser so
# weakly against squidpy's corrected rank-3 energy that the velocity field grows
# unchecked; 1e5 here is two orders below squidpy's own 1e6 default, not near upstream's.
SOLVER = dict(a=250.0, sigmaR=1e5, nt=4, sigmaM=2.0, sigmaA=2.0, sigmaB=2.0, muA=[3.0], muB=[0.0])
fit = stalign_align_volume(
    sdata, image_key=('atlas', 'section'), niter=2000,
    initial_slice=slice_index, initial_rotation=rotation, initial_scale=scale, **SOLVER,
)
print(f'{fit.n_iter} iterations, objective '
      f'{float(fit.energies[0]):.0f} -> {float(fit.energies[-1]):.0f}')
2000 iterations, objective 28029 -> 31302

Convergence#

import matplotlib.pyplot as plt

energies = np.asarray(fit.energies)[: fit.n_iter]
plt.figure(figsize=(5, 3))
plt.plot(energies, lw=0.8)
plt.xlabel('iteration'); plt.ylabel('objective'); plt.grid(alpha=0.3)
../../_images/0e870b23dfb9211d584ad6d4fd00f6e48b78228e3c070ea602cee7484b3a253f.png

Where each cell lands#

StalignFit.transform_points maps (x, y) section coordinates to (x, y, z) reference coordinates, evaluated at each point rather than at the nearest raster cell. sample_volume then reads the annotation volume there – order=0 because structure ids must not be interpolated.

coords = np.asarray(fit.transform_points(xy))  # (N, 3), (x, y, z) in microns
structure_id = sample_volume(labels, coords, axes=fit.ref_axes, order=0).astype(int)

print(f'{len(coords)} cells placed, {np.unique(structure_id).size} distinct structures, '
      f'{100 * (structure_id == 0).mean():.1f}% outside any annotated structure')
print(f'depth (z) spans {coords[:, 2].min():.0f} to {coords[:, 2].max():.0f} um')
78329 cells placed, 162 distinct structures, 3.5% outside any annotated structure
depth (z) spans 2066 to 2505 um

Structure ids become acronyms through the Allen ontology.

ontology = pd.read_csv('allen_ontology.csv').set_index('id')['acronym']
acronym = pd.Series(structure_id).map(ontology).fillna('unassigned')
acronym.value_counts().head(12)
CA1           4559
MRN           4072
MB            2870
unassigned    2734
PG            2724
SCig          2675
SCiw          2409
DG-mo         2276
PAG           2253
ProS          2222
VISp2/3       1808
POST          1634
Name: count, dtype: int64

The aligned atlas over the section#

import matplotlib as mpl
from matplotlib.lines import Line2D

def atlas_at(result):
    plane = np.moveaxis(np.asarray(result.deformation_grid()), 0, -1)[0]
    sampled = sample_volume(atlas, plane.reshape(-1, 3)[:, ::-1], axes=result.ref_axes)
    return sampled.reshape(plane.shape[:2])

section = np.asarray(sdata['section']).squeeze()
fig, ax = plt.subplots(1, 3, figsize=(15, 5))
ax[0].imshow(section, cmap=mpl.cm.Blues)
ax[1].imshow(atlas_at(fit), cmap=mpl.cm.Reds)
ax[2].imshow(section, cmap=mpl.cm.Blues, alpha=0.9)
ax[2].imshow(atlas_at(fit), cmap=mpl.cm.Reds, alpha=0.3)
for a, t in zip(ax, ('MERFISH section', 'atlas after fitting', 'overlaid'), strict=True):
    a.set_title(t); a.set_xticks([]); a.set_yticks([])
../../_images/084d1846868238933d1a6f71a4c37d6a0c58e9fc20f343653592a1959597ec26.png

Cells coloured by structure#

keep = acronym.value_counts()
keep = keep[keep >= 50].index                       # a legend of singletons reads as noise
fig, ax = plt.subplots(figsize=(7, 6))
for region in keep:
    m = (acronym == region).to_numpy()
    ax.scatter(xy[m, 0], xy[m, 1], s=0.08, label=region)
ax.invert_yaxis(); ax.set_aspect('equal')
ax.legend(handles=[Line2D([], [], marker='o', ls='', ms=4, color=h.get_facecolor()[0], label=r)
                   for r, h in zip(keep, ax.collections, strict=True)],
          fontsize=6, ncol=2, loc='center left', bbox_to_anchor=(1, 0.5))
<matplotlib.legend.Legend at 0x7fb084905fd0>
../../_images/a716e7b7685cea73bb5b7c095adba1801f1a8c93570e5dad281a68f373b44db0.png