Using xenium_aligned_image for multi-channel (20 channel) IF images

[singhbhavya]

Hi there! First of all, thank you so much for this amazing package - it is currently my bread and butter, and I really appreciate your team! Second, I am writing this issue about aligning a post-Xenium IF staining with our Xenium image.

I have a multi-channel OME-TIFF (20 channels), with IF staining for the same tissue section as the Xenium (staining was done post-Xenium). I ran MCMICRO on this and obtained quantifications, but I need to align this to the Xenium image, and either re-quantify per cell using the Xenium segmentation mask, or somehow import the quantification into a combined SpatialData.

I aligned this image to the Xenium image using Xenium Explorer (by following this tutorial), and it worked beautifully in the Xenium Explorer. The images were perfectly aligned, and I could see the IF staining from multiple channels. However, I've had the following issues:

1. When I run the xenium_aligned_image function, I get an assertion error since the function expects there to be (I think) only 3-4 channels.

image = xenium_aligned_image(image_path=he_path, alignment_file= alignment_matrix_path)

---------------------------------------------------------------------------
AssertionError                            Traceback (most recent call last)
Cell In[14], [line 9](vscode-notebook-cell:?execution_count=14&line=9)
      6 he_path = os.path.join(base_dir, "registration/BDBAT0246.ome.tif")
      8 assert image.shape[0] in [3, 4, 20]  # Allow 20 channels in addition to 3 and 4
----> [9](vscode-notebook-cell:?execution_count=14&line=9) image = xenium_aligned_image(image_path=he_path, alignment_file= alignment_matrix_path)

File ~/miniconda3/envs/napari-env/lib/python3.11/site-packages/spatialdata_io/readers/xenium.py:654, in xenium_aligned_image(image_path, alignment_file, imread_kwargs, image_models_kwargs, dims, rgba, c_coords)
    652     else:
    653         assert len(image.shape) == 3
--> [654](https://file+.vscode-resource.vscode-cdn.net/Users/bhavyasingh/Library/CloudStorage/OneDrive-TheMountSinaiHospital/Falcomata%2C%20Chiara%27s%20files%20-%20Xenium_Perturbmap/Xenium_Custom1/~/miniconda3/envs/napari-env/lib/python3.11/site-packages/spatialdata_io/readers/xenium.py:654)         assert image.shape[0] in [3, 4]
    655         dims = ("c", "y", "x")
    656 else:

AssertionError:

2. I tried to do a manual affine transformation (not involving xenium explorer), which worked. But when I try to output the new transformed image, there's still a very strange offset. The IF images are a different resolutoin from the Xenium.

The alignment works beautifully in Xenium explorer (and when I do the affine transformation), but how do I actually implement it and output a new OME-TIFF with new coordinates? Or alternatively, add this information to my Xenium SpatialData? Your help is greatly appreciated!

[quentinblampey]

Hello @singhbhavya, thanks for the very kind words!

Indeed, currently, xenium_aligned_image assumes the aligned image has 3 channels (typically, an H&E image). I'll discuss that in spatialdata-io and try to make a Pull Request soon to update it.

Meanwhile, could you try a more manual approach? I made this small code snippet for you, but you may have to adapt it:

import sopa
from spatialdata.transformations import set_transformation

image = sopa.io.ome_tif(image_path, as_image=True)

# check that it read the channel names
print(sopa.utils.get_channel_names(image))

alignment = pd.read_csv(alignment_file, header=None).values
transformation = Affine(alignment, input_axes=("x", "y"), output_axes=("x", "y"))

set_transformation(image, transformation=transformation, set_all=True)

# now you can add the image to the spatialdata object

Please let me know if that works!

The alignment works beautifully in Xenium explorer (and when I do the affine transformation), but how do I actually implement it and output a new OME-TIFF with new coordinates? Or alternatively, add this information to my Xenium SpatialData?

I think it's better to keep the original image, and just add it to the spatialdata object as above. If it's not working, we'll try other approaches!

NB: This repository is currently deprecated, do you confirm that you use sopa and not spatialdata_xenium_explorer?

[singhbhavya]

Thank you so much for your help!! I was able to do the image transformation using sopa! Sorry for the confusion, I did not realize initially that this repository was deprecated, otherwise I would've posted the issue elsewhere.

For my IF images, I also have intensity quantifications for each staining, which is mapped to the (old) X & Y centroids of the IF ome.tiff image. I attempted to apply the exact same transformation, but it is not working & the points associated with the quantification are rotated differently (and the whole image becomes a lot smaller). I think the issue is that the CyCIF ome.tiff & the xenium have different resolutions (~0.65 um for the former and 0.2125 for the latter). Do I need to convert microns to pixels, then apply the transformation, and then convert back to microns? I am just confused as to how it's possible that the image aligns perfectly post-transformation, but it doesn't work when I try to do the same for the coordinates.

[quentinblampey]

Could you please show me the transformation matrix file that was output by the Xenium Explorer? It will help me better understand what's happening. It should normally contain the scale factor between the two images' pixel sizes.

Could you please give me more details concerning your intensity quantifications @singhbhavya? Is it a point layer? Does it refer to cell centroids?
If so, how were the cells segmented?
I imagine you have some columns, e.g. x and y, to denote the coordinates of the cell centroids - if so, what's the unit / coordinate system of x/y?

Sorry for the confusion, I did not realize initially that this repository was deprecated, otherwise I would've posted the issue elsewhere.

No worries at all!

[vraghu90]

I am very much interested in this as well. Were you able to figure this out? The only solution I've been utilizing off-hand is importing in the already aligned/transformed image? I am attempting to apply the xenium cell segmentation onto the mIF image to extract average channel intensities for each cell. If this repository is deprecated - where would be a good place to follow up?

[quentinblampey]

Hi @vraghu90,

Do you also have different images resolutions? If so, could you please show me the transformation matrix file that was output by the Xenium Explorer? If not, the snippet of code I gave above in this feed should work for you.

If this repository is deprecated - where would be a good place to follow up?

All these functionnalities are in sopa, e.g., here in the API.

Regarding channel intensities, you can run Sopa as in the tutorial (i.e., on the transcriptomic layer) and, after running sopa.aggregate, you can run the channel aggregation with image_key=<name-of-your-protein-image>. It will create a new numpy array that contains your cell-by-protein intensities - you can add it to your adata, e.g. in adata.obsm["intensities"].

[vraghu90]

Yes , I do have different image resolutions? Is there a vignette in Sopa to resolve this? Best, Vineeth

…

--- *Vineeth Raghuram, Ph.D.* *(603)-943-0489*

On Thu, Aug 21, 2025 at 8:16 AM Quentin Blampey ***@***.***> wrote: *quentinblampey* left a comment (quentinblampey/spatialdata_xenium_explorer#7) <#7 (comment)> Hi @vraghu90 <https://github.com/vraghu90>, Do you also have different images resolutions? If so, could you please show me the transformation matrix file that was output by the Xenium Explorer? If not, the snippet of code I gave above in this feed should work for you. If this repository is deprecated - where would be a good place to follow up? All these functionnalities are in sopa <https://github.com/gustaveroussy/sopa>, e.g., here in the API <https://gustaveroussy.github.io/sopa/api/misc/#sopa.io.explorer.write>. Regarding channel intensities, you can run Sopa as in the tutorial (i.e., on the transcriptomic layer) and, after running sopa.aggregate, you can run the channel aggregation <https://gustaveroussy.github.io/sopa/api/aggregation/#sopa.aggregation.aggregate_channels> with image_key=<name-of-your-protein-image>. It will create a new numpy array that contains your cell-by-protein intensities - you can add it to your adata, e.g. in adata.obsm["intensities"]. — Reply to this email directly, view it on GitHub <#7 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/BAT7LOING6KC3E3STXUZWVD3OW2BDAVCNFSM6AAAAACCYTJZCCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTEMJQGM2TONRVGQ> . You are receiving this because you were mentioned.Message ID: ***@***.*** com>