Question about Xenium Sample Alignment and Integration

[ymoneych]

Hi, thank you for your excellent work on developing HEST.

I have two questions regarding the integration of new Xenium samples into HEST:

1. Alignment Process for New Xenium Samples
   I'm trying to understand the process of aligning new Xenium samples. When using XeniumReader, it requires an 'imagealignment.csv' file. I understand that VALIS is being used for image registration to align the DAPI image with the H&E slide. I've checked Aligning new HE-Xenium data #74, but couldn't find any alignment method within the auto_read or read functions. Could you please provide guidance on how to generate the 'imagealignment.csv' file?

2. XeniumReader Alignment File Handling
   I've noticed a potential issue in the XeniumReader's read function. While alignment_file_path is marked as an optional parameter, setting it to None causes alignment_matrix to be None.
   This leads to an error in the __xenium_estimate_pixel_size during matrix multiplication between he_to_morph_matrix and two_points.T.
   

   HEST/src/hest/readers.py

   Line 817 in 5a0cbba

   scaled_points = (he_to_morph_matrix @ two_points.T).T

If I've misunderstood any part of the process, I apologize and would appreciate any corrections.
Any clarification on these points would be greatly appreciated. Thank you!

[ekansh09]

I am experiencing the same issue where the auto_read function is not using VALIS for new samples.

Additionally, when using XeniumReader().auto_read(path), I noticed that this function does not have a return statement. Please correct me if I’m wrong, but shouldn’t it include one?

HEST/src/hest/readers.py

Line 770 in 5a0cbba

super().auto_read(path, **read_kwargs)

[pauldoucet]

Hi @ymoneych,
You can obtain an imagealignment.csv file by manually aligning with the Xenium Explorer provided by 10x Genomics. From experience, the affine alignment provided by the Xenium Explorer isn’t always enough and you might need to use Valis micro-registration to get a very accurate alignment.

I’ve added a simple interface to Valis in the latest version, however note that you might need >20Go RAM for aligning a large number of transcripts/shapes. You can use the following code snippet:

xenium_input_dir = 'FFPE Human Cervical Cancer with 5K Human Pan Tissue and Pathways Panel plus 100 Custom Genes'

st = XeniumReader().auto_read(xenium_input_dir )

# Save image to Generic pyramidal tiff
st.save('processed_sample/', save_img=True)

# Path to the H&E image we just saved
he_path = 'processed_sample/aligned_fullres_HE.tif'
dapi_path = 'path_to_morphology_focus_0000.ome.tif'


# Warning Valis alignment might require a significant amount or RAM based on the number of transcripts, shapes and image size
# Feel free to set align_transcripts, align_cells or align_nuclei to False
st.align_with_valis('.', he_path, dapi_path, align_transcripts=True, align_cells=True, align_nuclei=True)

Let me know if that work :)
Best,

Paul

[pauldoucet]

@ekansh09 thanks for pointing this out! I've just pushed a quick fix

[ymoneych]

Hi @pauldoucet,
Thank you so much for your quick and detailed response.

Your solution worked perfectly for me.
The provided code snippet for using Valis was exactly what I needed.

My issue is now completely resolved.

[ymoneych]

Hi @pauldoucet

I encountered an error when using Valis for registration through the align_with_valis method:

The truth value of a DataFrame is ambiguous. Use a.empty, a.bool(), a.item(), a.any() or a.all().

The error occurs in registration.py line 189:

HEST/src/hest/registration.py

Line 189 in 07bda9b

if dapi_transcripts:

The error happens because a Pandas DataFrame is being used directly in a conditional statement.
I believe the conditional statement should be modified to:

if dapi_transcripts is not None:

Thanks :)