Landmark-based alignment
You can align any omic layer by defining manual landmark annotations. This can either be done via the Xenium Explorer, or napari-spatialdata
.
Via the Xenium Explorer
You'll need two things for alignment with the Xenium Explorer:
- A
SpatialData
object (seesopa.io
) and it's corresponding Xenium Explorer directory (see next section). - An image (usually
.tif
or.ome.tif
) that you want to align to theSpatialData
object.
Explorer data
If not done yet, convert your SpatialData
object to the Xenium Explorer's inputs. This can be done as detailed in this tutorial. For instance:
import spatialdata
import sopa
sdata = spatialdata.read_zarr("/path/to/your/data.zarr")
sopa.io.explorer.write("data.explorer", sdata)
This will create a experiment.xenium
file under data.explorer
that you'll use later to open the data in the Xenium Explorer.
Image conversion
You need to have the right image format for the Xenium Explorer. Here, we convert the image you want to align to the right format.
Xenium users
If using the Xenium machine, then you don't need conversion; the images provided by the Xenium machine already have the correct format.
You can convert the image with QuPath as written in this 10x genomics webpage. Otherwise, if you are not familiar with QuPath, you can also use our API to write the image:
# use sopa.io.ome_tif to read your image, or any reader from sopa.io
image = sopa.io.ome_tif("path/to/your/image.tif", as_image=True)
# write this image so that it can be open with the Xenium Explorer
sopa.io.explorer.write_image("my_image.ome.tif", image, is_dir=False)
Keypoint placement
Warning
Make sure your Xenium Explorer version is at least 1.3.0
Double-click on the experiment.xenium
file to open the Xenium Explorer, or select this file from the Xenium Explorer interface. It will display the data in the explorer.
On the Xenium Explorer, under the "Images" panel, click "Add image" and follow the instructions on the screen (you'll need to choose the image you created in the previous section).
Afterwards, the explorer will automatically align the images based on the key points you selected on both images.
Update your SpatialData object
After alignment, export the transformation matrix as a .csv
file. For that, select your aligned image under the "Images" panel and click on "Download Alignment File":
Then, select only the "Transformation Matrix" box and download it:
Via the API, you can now update your SpatialData
object as follows:
# specify below the location of the matrix.csv file:
sopa.io.explorer.align(sdata, image, "image_test_matrix.csv")
Via the CLI, you'll need the path to the .zarr
directory corresponding to your SpatialData
object (SDATA_PATH
), the path to the .ome.tif
image that you converted above (IMAGE_PATH
), and the .csv
transformation matrix that you exported from the Xenium Explorer (TRANSFORMATION_MATRIX_PATH
):
Via napari-spatialdata
Intead of the Xenium Explorer, you can also use napari-spatialdata
to align images.
Refer to this existing tutorial for more details.