STalign

https://jef.works/STalign
Admin
STalign aligns spatial transcriptomics tissue sections to each other and to 3D atlases using...
Tokens:43,693
Snippets:435
Trust Score:9
Update:5 months ago
Show doc for...
Tokens:
Raw
### Import STalign (Option A: Installed)

Source: https://jef.works/STalign/notebooks/xenium-starmap-alignment.html

Imports the STalign library after it has been installed via pip or pipenv.

```python
# OPTION A: import STalign after pip or pipenv install
from STalign import STalign

```

--------------------------------

### Install STalign using Pipfile

Source: https://jef.works/STalign/overview.html

Install STalign and its dependencies using pipenv from the source repository. This command creates a Pipfile.lock.

```bash
pipenv install requests
```

--------------------------------

### Install STalign using pip

Source: https://jef.works/STalign/overview.html

Use this command to install STalign and its dependencies into your selected Python environment.

```bash
pip install --upgrade "git+https://github.com/JEFworks-Lab/STalign.git"
```

--------------------------------

### Import STalign (Option B: From Source)

Source: https://jef.works/STalign/notebooks/xenium-starmap-alignment.html

Imports the STalign library from an upper directory, useful if STalign was not installed via pip but is available in the local path.

```python
# OPTION B: skip cell if installed STalign with pip or pipenv
import sys
sys.path.append("../../STalign")

## import STalign from upper directory
import STalign

```

--------------------------------

### Compute Initial Affine Transformation from Points

Source: https://jef.works/STalign/notebooks/xenium-xenium-alignment.html

Calculates the initial affine transformation matrix (A) using landmark points from both images. This provides a starting point for the iterative alignment process.

```python
# compute initial affine transformation from points
L,T = STalign.L_T_from_points(pointsI, pointsJ)
A = STalign.to_A(torch.tensor(L),torch.tensor(T))
```

--------------------------------

### Set Device for STalign

Source: https://jef.works/STalign/notebooks/merfish-allen3Datlas-alignment.html

Determines whether to use CUDA if available, otherwise defaults to CPU. This is a common setup step before running STalign.

```python
if torch.cuda.is_available():
    device = 'cuda:0'
else:
    device = 'cpu'
```

--------------------------------

### Import STalign Library

Source: https://jef.works/STalign/notebooks/merfish-allen3Datlas-alignment.html

Imports the STalign library. Use Option A if installed via pip/pipenv, or Option B if importing from a local directory.

```python
# OPTION A: import STalign after pip or pipenv install
from STalign import STalign

```

```python
## OPTION B: skip cell if installed STalign with pip or pipenv
import sys
sys.path.append("../../STalign")

## import STalign from upper directory
import STalign

```

--------------------------------

### Import Dependencies for STalign

Source: https://jef.works/STalign/notebooks/starmap-allen3Datlas-alignment.html

Imports essential Python libraries for data manipulation, visualization, and STalign functionality. Ensure all listed libraries are installed.

```python
#Import dependencies

import numpy as np
%matplotlib notebook
import matplotlib.pyplot as plt
import pandas as pd # for csv. 
from matplotlib import cm
from matplotlib.lines import Line2D
import os
from os.path import exists,split,join,splitext
from os import makedirs
import glob
import requests
from collections import defaultdict
import nrrd
import torch
from torch.nn.functional import grid_sample
import tornado
from STalign import STalign
import copy
import pandas as pd

```

--------------------------------

### Import Dependencies for MERFISH Alignment

Source: https://jef.works/STalign/notebooks/merfish-allen3Datlas-alignment.html

Imports necessary Python libraries for data manipulation, visualization, and STalign functionality. Ensure all libraries are installed.

```python
#Import dependencies

import numpy as np
#%matplotlib notebook
import matplotlib.pyplot as plt
import pandas as pd # for csv. 
from matplotlib import cm
from matplotlib.lines import Line2D
import os
from os.path import exists,split,join,splitext
from os import makedirs
import glob
import requests
from collections import defaultdict
import nrrd
import torch
from torch.nn.functional import grid_sample
import tornado
import copy
import skimage
from mpl_toolkits.mplot3d.art3d import Poly3DCollection
import pandas as pd

```

--------------------------------

### build_transform3D

Source: https://jef.works/STalign/STalign.html

Create sample points to transform source to target from affine and velocity.

```APIDOC
## build_transform3D

### Description
Create sample points to transform source to target from affine and velocity.

### Method
`build_transform3D`

### Parameters
- **xv** (type) - Required - Description
- **v** (type) - Required - Description
- **A** (type) - Required - Description
- **direction** (type) - Optional - Description
- **XJ** (type) - Optional - Description

### Response
#### Success Response (200)
- **Description**: Returns the sample points for 3D transformation.

#### Response Example
```json
{
  "example": "response body"
}
```
```

--------------------------------

### Initialize Alignment Transformation Parameters

Source: https://jef.works/STalign/notebooks/merfish-allen3Datlas-alignment.html

Sets up initial parameters for the alignment transformation, including scaling factors (`scale_x`, `scale_y`, `scale_z`), rotation angle (`theta0`), and translation vector (`T`). The translation is adjusted if corresponding points were previously defined.

```python
# initialize variables
scale_x = 0.9 #default = 0.9
scale_y = 0.9 #default = 0.9
scale_z = 0.9 #default = 0.9
theta0 = (np.pi/180)*theta_deg

# get an initial guess
if 'Ti' in locals():
    T = np.array([-xI[0][slice],np.mean(xJ[0])-(Ti[0]*scale_y),np.mean(xJ[1])-(Ti[1]*scale_x)])
else:
    T = np.array([-xI[0][slice],np.mean(xJ[0]),np.mean(xJ[1])])

scale_atlas = np.array([[scale_z,0,0],
                        [0,scale_x,0],
                        [0,0,scale_y]])
L = np.array([[1.0,0.0,0.0],
             [0.0,np.cos(theta0),-np.sin(theta0)],
              [0.0,np.sin(theta0),np.cos(theta0)]])
L = np.matmul(L,scale_atlas)#np.identity(3)
```

--------------------------------

### Build and Visualize Target-to-Source Transformation

Source: https://jef.works/STalign/notebooks/merfish-merfish-alignment.html

Builds the inverse transformation from target to source and visualizes it along with the transformed target image. Ensure 'extentI' is correctly defined for image display.

```python
# transform is invertible
phi = STalign.build_transform(xv,v,A,XJ=[YI,XI],direction='f')
phiiJ = STalign.transform_image_target_to_source(xv,v,A,[YJ,XJ],J,[YI,XI])

#switch tensor from cuda to cpu for plotting with numpy
if phi.is_cuda:
    phi = phi.cpu()
if phiiJ.is_cuda:
    phiiJ = phiiJ.cpu()

# plot with grids
fig,ax = plt.subplots()
levels = np.arange(-100000,100000,1000)
ax.contour(XI,YI,phi[...,0],colors='r',linestyles='-',levels=levels)
ax.contour(XI,YI,phi[...,1],colors='g',linestyles='-',levels=levels)
ax.set_aspect('equal')
ax.set_title('target to source')
ax.imshow(phiiJ.permute(1,2,0)/torch.max(phiiJ),extent=extentI)
ax.invert_yaxis()
```

--------------------------------

### Load MERFISH and Visium Landmark Points

Source: https://jef.works/STalign/notebooks/merfish-visium-alignment-with-point-annotator.html

Loads MERFISH and Visium landmark points from .npy files. These points are initially loaded as lists and will be converted to arrays for further processing.

```python
# read from file
pointsIlist = np.load('../visium_data/Merfish_S2_R3_points.npy', allow_pickle=True).tolist()
print(pointsIlist)
pointsJlist = np.load('../visium_data/tissue_hires_image_points.npy', allow_pickle=True).tolist()
print(pointsJlist)
```

--------------------------------

### Build and Visualize Source-to-Target Transformation

Source: https://jef.works/STalign/notebooks/merfish-merfish-alignment.html

Builds the transformation from source to target and visualizes it along with the transformed source image. Ensure 'extentJ' is correctly defined for image display.

```python
# apply transform
phii = STalign.build_transform(xv,v,A,XJ=[YJ,XJ],direction='b')
phiI = STalign.transform_image_source_to_target(xv,v,A,[YI,XI],I,[YJ,XJ])

#switch tensor from cuda to cpu for plotting with numpy
if phii.is_cuda:
    phii = phii.cpu()
if phiI.is_cuda:
    phiI = phiI.cpu()

# plot with grids
fig,ax = plt.subplots()
levels = np.arange(-100000,100000,1000)
ax.contour(XJ,YJ,phii[...,0],colors='r',linestyles='-',levels=levels)
ax.contour(XJ,YJ,phii[...,1],colors='g',linestyles='-',levels=levels)
ax.set_aspect('equal')
ax.set_title('source to target')
ax.imshow(phiI.permute(1,2,0)/torch.max(phiI),extent=extentJ)
ax.invert_yaxis()
```

--------------------------------

### build_transform

Source: https://jef.works/STalign/STalign.html

Create sample points to transform source to target from affine and velocity.

```APIDOC
## build_transform

### Description
Create sample points to transform source to target from affine and velocity.

### Method
`build_transform`

### Parameters
- **xv** (type) - Required - Description
- **v** (type) - Required - Description
- **A** (type) - Required - Description
- **direction** (type) - Optional - Description
- **XJ** (type) - Optional - Description

### Response
#### Success Response (200)
- **Description**: Returns the sample points for transformation.

#### Response Example
```json
{
  "example": "response body"
}
```
```

--------------------------------

### Build and Transform Image Target to Source

Source: https://jef.works/STalign/notebooks/xenium-starmap-alignment.html

Builds the transformation and applies it to the target image to align it to the source. Switches tensors to CPU for plotting.

```python
# transform is invertible
phi = STalign.build_transform(xv,v,A,XJ=[YI,XI],direction='f')
phiiJ = STalign.transform_image_target_to_source(xv,v,A,[YJ,XJ],Jfoo,[YI,XI])

#switch tensor from cuda to cpu for plotting with numpy
if phi.is_cuda:
    phi = phi.cpu()
if phiiJ.is_cuda:
    phiiJ = phiiJ.cpu()

# plot with grids
fig,ax = plt.subplots()
levels = np.arange(-100000,100000,1000)
ax.contour(XI,YI,phi[...,0],colors='r',linestyles='-',levels=levels)
ax.contour(XI,YI,phi[...,1],colors='g',linestyles='-',levels=levels)
ax.set_aspect('equal')
ax.set_title('target to source')
ax.imshow(phiiJ.permute(1,2,0)/torch.max(phiiJ),extent=extentI)
ax.invert_yaxis()
```

--------------------------------

### STalign.STalign.build_transform3D

Source: https://jef.works/STalign/STalign.html

Creates sample points to transform source to target from affine and velocity fields in a 3D context.

```APIDOC
## build_transform3D

### Description
Create sample points to transform source to target from affine and velocity.

### Parameters
- **_xv_** (list of array) - Sample points for velocity.
- **_v_** (array) - Time dependent velocity field.
- **_A_** (array) - Affine transformation matrix.
- **_direction_** (char, optional, default='b') - 'f' for forward and 'b' for backward. 'b' is default and is used for transforming images. 'f' is used for transforming points.
- **_XJ_** (array, optional) - Sample points for target (meshgrid with ij index style). Defaults to None to keep sampling on the xv.

### Returns
- **Xs_** (array) - Sample points in meshgrid format.
```

--------------------------------

### Prepare Atlas and Target Image Data for Alignment

Source: https://jef.works/STalign/notebooks/merfish-allen3Datlas-alignment.html

Sets up the target image `J` and atlas image `I` for alignment. This includes normalizing intensities and adding a squared term to the atlas image to capture intensity variations.

```python
xJ = [Y_,X_]
J = W[None]/np.mean(np.abs(W))
xI = xA
I = A[None] / np.mean(np.abs(A),keepdims=True)
I = np.concatenate((I,(I-np.mean(I))**2))
```

--------------------------------

### STalign.STalign.build_transform

Source: https://jef.works/STalign/STalign.html

Creates sample points to transform source to target from affine and velocity fields.

```APIDOC
## build_transform

### Description
Create sample points to transform source to target from affine and velocity.

### Parameters
- **_xv_** (list of array) - Sample points for velocity.
- **_v_** (array) - Time dependent velocity field.
- **_A_** (array) - Affine transformation matrix.
- **_direction_** (char, optional, default='b') - 'f' for forward and 'b' for backward. 'b' is default and is used for transforming images. 'f' is used for transforming points.
- **_XJ_** (array, optional) - Sample points for target (meshgrid with ij index style). Defaults to None to keep sampling on the xv.

### Returns
- **Xs_** (array) - Sample points in meshgrid format.
```

--------------------------------

### STalign.STalign.download_aba_ontology

Source: https://jef.works/STalign/STalign.html

Creates a 3D atlas ontology by downloading it from a given URL.

```APIDOC
## STalign.STalign.download_aba_ontology

### Description
Create 3D atlas ontology.

### Parameters
* **url** (Link) - Link to URL containing atlas ontology.
* **file_name** (File Name) - File name to save atlas ontology.

### Returns
* **ontology_name** (File Name) - File name to store ontologies names.
* **dict** (Dictionary) - Dictionary of all brain region names.
```

--------------------------------

### Visualize Matching Weights

Source: https://jef.works/STalign/notebooks/xenium-xenium-alignment.html

Visualizes the matching weights by scattering points colored by their weight values. Requires xJ, yJ, tpointsI, testM to be defined.

```python
# note some cells were allocated into the artifact component (not matching and so not included, may need to tune sigmaA)
fig,ax = plt.subplots()
ax.scatter(xJ,yJ,s=1,alpha=0.2)
ax.scatter(tpointsI[:,1],tpointsI[:,0],c=testM[0,0],s=0.1, vmin=0,vmax=1, label='WM values')
```

--------------------------------

### Run STalign Point Annotator from Command Line

Source: https://jef.works/STalign/notebooks/merfish-visium-alignment-with-point-annotator.html

Executes the point annotator script from the command line to manually select landmark points on the source and target images. This is a crucial step for initializing the alignment process.

```bash
python ../../STalign/point_annotator.py ../visium_data/Merfish_S2_R3.npz ../visium_data/tissue_hires_image.npz
```

--------------------------------

### Activate Pipenv environment

Source: https://jef.works/STalign/overview.html

Activate the virtual environment created with Pipfile to use STalign.

```bash
pipenv shell
```

--------------------------------

### Apply Transform and Visualize Points

Source: https://jef.works/STalign/notebooks/xenium-xenium-alignment.html

Applies the learned spatial transformation from source to target and visualizes the transformed points along with original points. Requires STalign, xv, v, A, yI, xI, xJ, yJ to be defined.

```python
# apply transform to original points of source to target
tpointsI = STalign.transform_points_source_to_target(xv,v,A, np.stack([yI, xI], 1))

#switch tensor from cuda to cpu for plotting with numpy
if tpointsI.is_cuda:
    tpointsI = tpointsI.cpu()

# plot results
fig,ax = plt.subplots()
ax.scatter(tpointsI[:,1],tpointsI[:,0],s=1,alpha=0.2) # also needs to plot as y,x not x,y
ax.scatter(xJ,yJ,s=1,alpha=0.2)
```

--------------------------------

### Compute Initial Affine Transformation

Source: https://jef.works/STalign/notebooks/merfish-visium-alignment-with-point-annotator.html

Computes the initial affine transformation of a source image to match a target image using provided point correspondences. Ensure the source and target tensors are on the correct device before transformation.

```python
#compute initial affine transformation from points
AI= STalign.transform_image_source_with_A(A, [YI,XI], I, [YJ,XJ])

#switch tensor from cuda to cpu for plotting with numpy
if AI.is_cuda:
    AI = AI.cpu()

fig,ax = plt.subplots(1,2)

ax[0].imshow((AI.permute(1,2,0).squeeze()), extent=extentJ)
ax[1].imshow((J.transpose(1,2,0).squeeze()), extent=extentJ)

ax[0].set_title('source with affine transformation', fontsize=15)
ax[1].set_title('target', fontsize=15)
```

--------------------------------

### Visualize Landmark Points on Images

Source: https://jef.works/STalign/notebooks/merfish-visium-alignment-with-point-annotator.html

Plots the MERFISH and Visium images with their respective landmark points overlaid. Text labels are added to identify individual points.

```python
# plot

fig,ax = plt.subplots(1,2)
ax[0].imshow((I.transpose(1,2,0).squeeze()), extent=extentI)
ax[1].imshow((J.transpose(1,2,0).squeeze()), extent=extentJ)

trans_offset_0 = mtransforms.offset_copy(ax[0].transData, fig=fig,
                                       x=0.05, y=-0.05, units='inches')
trans_offset_1 = mtransforms.offset_copy(ax[1].transData, fig=fig,
                                       x=0.05, y=-0.05, units='inches')

ax[0].scatter(pointsI[:,1],pointsI[:,0], c='red', s=10)
ax[1].scatter(pointsJ[:,1],pointsJ[:,0], c='red', s=10)

for i in pointsIlist.keys():
    for j in range(len(pointsIlist[i])):
        ax[0].text(pointsIlist[i][j][0], pointsIlist[i][j][1],f'{i}{j}', c='red', transform=trans_offset_0, fontsize= 8)
for i in pointsJlist.keys():
    for j in range(len(pointsJlist[i])):
        ax[1].text(pointsJlist[i][j][0], pointsJlist[i][j][1],f'{i}{j}', c='red', transform=trans_offset_1, fontsize= 8)

ax[0].set_title('source with pointsI', fontsize=15)
ax[1].set_title('target with pointsJ', fontsize=15)

# invert only rasterized image
ax[0].invert_yaxis()
```

--------------------------------

### Visualize Weight Distribution

Source: https://jef.works/STalign/notebooks/xenium-xenium-alignment.html

Visualizes the distribution of matching weight values using a histogram to help identify a suitable cutoff threshold. Requires testM to be defined.

```python
# visualize the distribution to identify reasonable cutoff
fig,ax = plt.subplots()
ax.hist(testM[0,0], bins = 20)
```

--------------------------------

### Prepare Atlas and Target Images for Normalization

Source: https://jef.works/STalign/notebooks/starmap-allen3Datlas-alignment.html

Sets up the target image (J) and atlas image (I) for alignment. It normalizes their intensities to a common range and applies a transformation to the atlas image to match the target image's coordinate system. It also concatenates the normalized image with its squared version to capture more intensity information.

```python
xJ = [Y_,X_]
J = W[None]/np.mean(np.abs(W))
xI = xA
I = A[None] / np.mean(np.abs(A),keepdims=True)
I = np.concatenate((I,(I-np.mean(I))**2))
Inorm = STalign.normalize(I, t_min=0, t_max=1)
Jnorm = STalign.normalize(J, t_min=0, t_max=1)

```

--------------------------------

### Compute Initial Affine Transformation

Source: https://jef.works/STalign/notebooks/merfish-visium-alignment-with-point-annotator.html

Calculates the initial affine transformation matrix (A) from corresponding landmark points using linear transformation (L) and translation (T) components derived from the points.

```python
# compute initial affine transformation from points
L,T = STalign.L_T_from_points(pointsI,pointsJ)
A = STalign.to_A(torch.tensor(L),torch.tensor(T))
```

--------------------------------

### download_aba_ontology

Source: https://jef.works/STalign/STalign.html

Create 3D altas ontology.

```APIDOC
## download_aba_ontology

### Description
Create 3D altas ontology.

### Method
`download_aba_ontology`

### Parameters
- **url** (type) - Required - Description
- **file_name** (type) - Required - Description

### Response
#### Success Response (200)
- **Description**: Returns the 3D altas ontology.

#### Response Example
```json
{
  "example": "response body"
}
```
```

--------------------------------

### Load and Inspect First Xenium Dataset

Source: https://jef.works/STalign/notebooks/xenium-xenium-alignment.html

Read the cell information CSV file for the first Xenium dataset using pandas and display the first few rows.

```python
# Single cell data 1
# read in data
fname = '../xenium_data/Xenium_FFPE_Human_Breast_Cancer_Rep1_cells.csv.gz'
df1 = pd.read_csv(fname)
print(df1.head())
```

--------------------------------

### Apply and Visualize Target-to-Source Transform

Source: https://jef.works/STalign/notebooks/xenium-xenium-alignment.html

Demonstrates the invertibility of the LDDMM transformation by applying the inverse transform to visualize the target image deformed to match the source. Converts tensors to CPU for plotting and displays contour lines, the transformed image, and scattered points.

```python
# transform is invertible
phi = STalign.build_transform(xv,v,A,XJ=[YI,XI],direction='f')
phiiJ = STalign.transform_image_target_to_source(xv,v,A,[YJ,XJ],J,[YI,XI])
phiipointsJ = STalign.transform_points_target_to_source(xv,v,A,pointsJ)

#switch tensor from cuda to cpu for plotting with numpy
if phi.is_cuda:
    phi = phi.cpu()
if phiiJ.is_cuda:
    phiiJ = phiiJ.cpu()
if phiipointsJ.is_cuda:
    phiipointsJ = phiipointsJ.cpu()

# plot with grids
fig,ax = plt.subplots()
levels = np.arange(-100000,100000,1000)
ax.contour(XI,YI,phi[...,0],colors='r',linestyles='-',levels=levels)
ax.contour(XI,YI,phi[...,1],colors='g',linestyles='-',levels=levels)
ax.set_aspect('equal')
ax.set_title('target to source')
ax.imshow(phiiJ.permute(1,2,0)/torch.max(phiiJ),extent=extentI)
ax.scatter(phiipointsJ[:,1].detach(),phiipointsJ[:,0].detach(),c="m")
ax.invert_yaxis()
```

--------------------------------

### Apply Transformation and Prepare for Plotting

Source: https://jef.works/STalign/notebooks/xenium-starmap-alignment.html

Builds the transformation matrix and applies it to the source image to align it with the target. It also converts PyTorch tensors to CPU tensors if they are on the GPU, preparing them for plotting with NumPy.

```python
# apply transform
phii = STalign.build_transform(xv,v,A,XJ=[YJ,XJ],direction='b')
phiI = STalign.transform_image_source_to_target(xv,v,A,[YI,XI],Ifoo,[YJ,XJ])

#switch tensor from cuda to cpu for plotting with numpy
if phii.is_cuda:
    phii = phii.cpu()
if phiI.is_cuda:
    phiI = phiI.cpu()
```

--------------------------------

### Initialize Scale and Rotation Parameters

Source: https://jef.works/STalign/notebooks/starmap-allen3Datlas-alignment.html

Initializes the scaling factors for the x, y, and z dimensions, as well as the initial rotation angle (theta0) in radians. These parameters are used to set the initial transformation of the atlas to match the target image's dimensions and orientation.

```python
# initialize variables
scale_x = 4 #default = 0.9
scale_y = 4 #default = 0.9
scale_z = 0.9 #default = 0.9
theta0 = (np.pi/180)*theta_deg

```

--------------------------------

### Plotting Target Data Before Alignment

Source: https://jef.works/STalign/notebooks/merfish-visium-alignment-with-point-annotator.html

Visualizes the target Visium image (J) with its corresponding landmark points (pointsJ) before any alignment transformation is applied.

```python
fig,ax = plt.subplots()
ax.imshow((J.transpose(1,2,0).squeeze()), extent=extentJ)
ax.scatter(pointsJ[:,1],pointsJ[:,0], c='red', s=100)
ax.set_title('Before alignment: target with pointsJ', fontsize=15)
```

--------------------------------

### Estimate Initial Transformation Matrix

Source: https://jef.works/STalign/notebooks/starmap-allen3Datlas-alignment.html

Calculates the initial transformation matrix 'T' based on image properties and potentially an existing transformation 'Ti'. This is a prerequisite for the alignment process.

```python
if 'Ti' in locals():
    T = np.array([-xI[0][slice],np.mean(xJ[0])-(Ti[0]*scale_y),np.mean(xJ[1])-(Ti[1]*scale_x)])
else:
    T = np.array([-xI[0][slice],np.mean(xJ[0]),np.mean(xJ[1])])
```

--------------------------------

### Create 3D Atlas Ontology

Source: https://jef.works/STalign/STalign.html

Downloads an atlas ontology file from a given URL and saves it to a specified file name. Returns the ontology file name and a dictionary of brain region names.

--------------------------------

### Load, Visualize, and Rasterize Second Xenium Dataset

Source: https://jef.works/STalign/notebooks/xenium-xenium-alignment.html

Read the second Xenium dataset, extract cell centroids, plot them, and then rasterize the centroids into an image at 30 micron resolution.

```python
# Single cell data 2
# read in data
fname = '../xenium_data/Xenium_FFPE_Human_Breast_Cancer_Rep2_cells.csv.gz'
df2 = pd.read_csv(fname)

# get cell centroids
xJ = np.array(df2['x_centroid'])
yJ = np.array(df2['y_centroid'])

# plot
fig,ax = plt.subplots()
ax.scatter(xJ,yJ,s=1,alpha=0.2,c='#ff7f0e')

# rasterize and plot
XJ,YJ,J,fig = STalign.rasterize(xJ,yJ,dx=30)
ax = fig.axes[0]
ax.invert_yaxis()
```

--------------------------------

### Compute Initial Affine Transformation

Source: https://jef.works/STalign/notebooks/xenium-heimage-alignment.html

Calculates the initial linear transformation (L) and translation (T) from corresponding landmark points in two images.

```python
L,T = STalign.L_T_from_points(pointsI,pointsJ)
```

--------------------------------

### Load Landmark Points from NPZ Files

Source: https://jef.works/STalign/notebooks/xenium-xenium-alignment.html

Loads landmark points previously saved in .npy files. These points are initially loaded as lists and will require conversion for further processing.

```python
# read from file
pointsIlist = np.load('../xenium_data/Xenium_Breast_Cancer_Rep1_points.npy', allow_pickle=True).tolist()
print(pointsIlist)
pointsJlist = np.load('../xenium_data/Xenium_Breast_Cancer_Rep2.npy', allow_pickle=True).tolist()
print(pointsJlist)
```

--------------------------------

### Apply Affine Transformation to Source Points

Source: https://jef.works/STalign/notebooks/merfish-visium-alignment-with-point-annotator.html

Applies an affine transformation matrix 'A' to source points. This is useful for aligning landmark points from the source to the target coordinate space. Ensure the transformation matrix is on the CPU before performing the multiplication.

```python
#apply A to sources points in row, column (y,x) orientation
affine = np.matmul(np.array(A.cpu()),np.array([yI, xI, np.ones(len(xI))]))

xIaffine = affine[1,:]
yIaffine = affine[0,:]


#apply A to sources landmark points in row, column (y,x) orientation
ypointsI = pointsI[:,0]
xpointsI = pointsI[:,1]
affine = np.matmul(np.array(A.cpu()),np.array([ypointsI, xpointsI, np.ones(len(ypointsI))]))

xpointsIaffine = affine[1,:]
ypointsIaffine = affine[0,:]
pointsIaffine = np.column_stack((ypointsIaffine,xpointsIaffine))


# plot results
fig,ax = plt.subplots()

ax.imshow((J).transpose(1,2,0),extent=extentJ)

ax.scatter(xIaffine,yIaffine,s=1,alpha=0.1, label = 'source aligned')
ax.scatter(pointsIaffine[:,1],pointsIaffine[:,0],c="blue", label='source landmarks aligned', s=100)

ax.scatter(pointsJ[:,1],pointsJ[:,0], c='red', label='target landmarks', s=100)
ax.set_aspect('equal')

lgnd = plt.legend(loc="upper right", scatterpoints=1, fontsize=10)
for handle in lgnd.legend_handles:
    handle.set_sizes([10.0])

ax.set_title('Landmark-based Affine Alignment', fontsize=15)
```

--------------------------------

### Define Corresponding Points for Alignment Initialization

Source: https://jef.works/STalign/notebooks/merfish-allen3Datlas-alignment.html

Optionally, specify corresponding points between the atlas and the target image to accelerate the alignment process. The points should be in the format `[[x1, y1], [x2, y2], ...]`. This step helps in obtaining an initial guess for the transformation.

```python
points_atlas = np.array([[0,2580]])
points_target = np.array([[8,2533]])
Li,Ti = STalign.L_T_from_points(points_atlas,points_target)
```

--------------------------------

### Import STalign in Python

Source: https://jef.works/STalign/overview.html

Import the STalign class into your Python script to begin using its functionalities.

```python
from STalign import STalign
```

--------------------------------

### Initialize Affine Alignment with Landmarks

Source: https://jef.works/STalign/notebooks/xenium-heimage-alignment.html

Manually defines corresponding landmark points between the H&E image and the rasterized single-cell image. These points are used to initialize an affine alignment, and are plotted to verify their placement.

```python
# manually make corresponding points
pointsI = np.array([[1050.,950.], [700., 2200.], [500., 1550.], [1550., 1840.]])
pointsJ = np.array([[3108.,2100.], [4480., 6440.], [5040., 4200.], [1260., 5320.]])

# plot
extentJ = STalign.extent_from_x((YJ,XJ))

fig,ax = plt.subplots(1,2)
ax[0].imshow((I.transpose(1,2,0).squeeze()), extent=extentI)
ax[1].imshow((J.transpose(1,2,0).squeeze()), extent=extentJ)

ax[0].scatter(pointsI[:,1],pointsI[:,0], c='red')
ax[1].scatter(pointsJ[:,1],pointsJ[:,0], c='red')
for i in range(pointsI.shape[0]):
    ax[0].text(pointsI[i,1],pointsI[i,0],f'{i}', c='red')
    ax[1].text(pointsJ[i,1],pointsJ[i,0],f'{i}', c='red')

# invert only rasterized image
ax[1].invert_yaxis()
```

--------------------------------

### Define Corresponding Points for Alignment Initialization

Source: https://jef.works/STalign/notebooks/starmap-allen3Datlas-alignment.html

Defines pairs of corresponding points between the atlas and the target image. These points are used to help initialize the alignment process, potentially speeding up convergence.

```python
points_atlas = np.array([[0,0]]) #(-y,-x)
points_target = np.array([[-3700,0]]) # (-y,-x)
Li,Ti = STalign.L_T_from_points(points_atlas,points_target)

```

--------------------------------

### Transform Points Target to Source

Source: https://jef.works/STalign/notebooks/xenium-starmap-alignment.html

Applies the built transformation to the original points to find their new aligned positions. Switches tensors to CPU if necessary.

```python
# apply transform to original points
tpointsJ = STalign.transform_points_target_to_source(xv,v,A, np.stack([yJ, xJ], 1))

#switch tensor from cuda to cpu for plotting with numpy
if tpointsJ.is_cuda:
    tpointsJ = tpointsJ.cpu()

# just original points for visualizing later
tpointsI = np.stack([xI, yI])
```

--------------------------------

### download_aba_image_labels

Source: https://jef.works/STalign/STalign.html

Create 3D altas image and region annotations.

```APIDOC
## download_aba_image_labels

### Description
Create 3D altas image and region annotations.

### Method
`download_aba_image_labels`

### Parameters
- **imageurl** (type) - Required - Description

### Response
#### Success Response (200)
- **Description**: Returns the 3D altas image and region annotations.

#### Response Example
```json
{
  "example": "response body"
}
```
```

--------------------------------

### Load STARmap PLUS Cell Data

Source: https://jef.works/STalign/notebooks/xenium-starmap-alignment.html

Placeholder for loading the second dataset (STARmap PLUS) similar to how the first dataset (Xenium) was loaded.

```python
# Single cell data 2

```

--------------------------------

### Visualize LDDMM Transformation

Source: https://jef.works/STalign/notebooks/xenium-heimage-alignment.html

Builds and visualizes the resulting non-linear transformation (phi) and applies it to the target image and points. This helps in evaluating the alignment quality.

```python
# now transform the points
phi = STalign.build_transform(xv,v,A,XJ=[YI,XI],direction='f')
phiiJ = STalign.transform_image_target_to_source(xv,v,A,[YJ,XJ],J,[YI,XI])
phiipointsJ = STalign.transform_points_target_to_source(xv,v,A,pointsJ)

#switch tensor from cuda to cpu for plotting with numpy
if phi.is_cuda:
    phi = phi.cpu()
if phiiJ.is_cuda:
    phiiJ = phiiJ.cpu()
if phiipointsJ.is_cuda:
    phiipointsJ = phiipointsJ.cpu()

# plot
fig,ax = plt.subplots()

levels = np.arange(-50000,50000,500)

ax.contour(XI,YI,phi[...,0],colors='r',linestyles='-',levels=levels)
ax.contour(XI,YI,phi[...,1],colors='g',linestyles='-',levels=levels)
ax.set_aspect('equal')
ax.set_title('target to source')

ax.imshow(phiiJ.permute(1,2,0),extent=extentI)
ax.scatter(phiipointsJ[:,1].detach(),phiipointsJ[:,0].detach(),c="m")
```

--------------------------------

### Create Matplotlib Figure for Visualization

Source: https://jef.works/STalign/notebooks/starmap-allen3Datlas-alignment.html

Initializes a matplotlib figure and axes to display the original STARmap slice and the aligned atlas section. This sets up the plotting environment for visual comparison.

```python
import matplotlib as mpl
fig,ax = plt.subplots(1,3, figsize=(15,5))
ax0 = ax[0].imshow(Ishow_target, cmap = mpl.cm.Blues,alpha=0.9)
ax[0].set_title('STARmap Slice')
```

--------------------------------

### Print Affine Transformation Matrix

Source: https://jef.works/STalign/notebooks/starmap-allen3Datlas-alignment.html

Displays the computed affine transformation matrix 'A', which represents the final rigid and scaling transformation applied during the alignment.

```python
print(A)
```

--------------------------------

### STalign.STalign.transform_points_target_to_source

Source: https://jef.works/STalign/STalign.html

Transforms points from target to source coordinates. Points are in row-column order.

```APIDOC
## STalign.STalign.transform_points_target_to_source(_xv_, _v_, _A_, _pointsI_)

### Description
Transform points. Note points are in row column order, not xy.
```

--------------------------------

### Transform Points with STalign

Source: https://jef.works/STalign/notebooks/xenium-heimage-alignment.html

Applies the STalign transformation to map points from the target to the source coordinate system. Ensure necessary libraries like STalign and numpy are imported.

```python
tpointsJ = STalign.transform_points_target_to_source(xv,v,A,np.stack([yM, xM], -1))
```

--------------------------------

### STalign.STalign.download_aba_image_labels

Source: https://jef.works/STalign/STalign.html

Downloads and creates a 3D atlas image and its corresponding region annotations from provided URLs.

```APIDOC
## download_aba_image_labels

### Description
Create 3D atlas image and region annotations

### Parameters
- **_imageurl_** (string) - URL for the 3D atlas image.
- **_labelurl_** (string) - URL for the region labels.
- **_imagefile_** (string) - Local file path to save the image.
- **_labelfile_** (string) - Local file path to save the labels.
```

--------------------------------

### Apply and Visualize Source-to-Target Transform

Source: https://jef.works/STalign/notebooks/heart-alignment.html

Applies the computed transformation from the source image to the target image space. It builds the transform, transforms the source image, and then plots the transformation contours and the transformed source image overlaid on the target image.

```python
# apply transform
phii = STalign.build_transform(xv,v,A,XJ=[YJ,XJ],direction='b')
phiI = STalign.transform_image_source_to_target(xv,v,A,[YI,XI],Ifoo,[YJ,XJ])


#switch tensor from cuda to cpu for plotting with numpy
if phii.is_cuda:
    phii = phii.cpu()
if phiI.is_cuda:
    phiI = phiI.cpu()

# plot with grids
fig,ax = plt.subplots()
levels = np.arange(-100000,100000,1000)
ax.contour(XJ,YJ,phii[...,0],colors='r',linestyles='-',levels=levels)
ax.contour(XJ,YJ,phii[...,1],colors='g',linestyles='-',levels=levels)
ax.set_aspect('equal')
ax.set_title('source to target')
ax.imshow(phiI.permute(1,2,0)/torch.max(phiI),extent=extentJ)
ax.invert_yaxis()
```

--------------------------------

### Plot Initial Images

Source: https://jef.works/STalign/notebooks/heart-alignment.html

Plots the source (I) and target (J) images using matplotlib. The images are transposed and squeezed for display, and their extents are applied. Y-axis is inverted for both plots.

```python
fig,ax = plt.subplots(2,1)
ax[0].imshow((I.transpose(1,2,0).squeeze()), extent=extentI)
ax[1].imshow((J.transpose(1,2,0).squeeze()), extent=extentJ)
ax[0].invert_yaxis()
ax[1].invert_yaxis()
```

--------------------------------

### Create Compressed CSV File

Source: https://jef.works/STalign/notebooks/xenium-heimage-alignment.html

Saves the combined results (original data and aligned points) to a compressed gzip CSV file. Ensure the `results` object is a pandas DataFrame or similar structure that has a `to_csv` method.

```python
results.to_csv('../xenium_data/Xenium_Breast_Cancer_Rep1_STalign_to_HE.csv.gz',
               compression='gzip')
```

--------------------------------

### Visualize Target Image Intensity Histogram

Source: https://jef.works/STalign/notebooks/merfish-allen3Datlas-alignment.html

Generates and displays a histogram of the target image intensities. This visualization is helpful for determining appropriate values for `muA`, `muB`, `sigmaA`, `sigmaB`, and `sigmaM`.

```python
fig,ax = plt.subplots()
ax.hist(J.ravel())
plt.xlabel('Intensity')
plt.ylabel('Number of Pixels')
plt.title('Intensity Histogram of Target Image')
```

```python
Text(0.5, 1.0, 'Intensity Histogram of Target Image')
```

--------------------------------

### Set Default Device for PyTorch Tensors

Source: https://jef.works/STalign/notebooks/merfish-merfish-alignment.html

Configures PyTorch to use the GPU if available, otherwise defaults to CPU. This is essential for performance optimization.

```python
# set device for building tensors
if torch.cuda.is_available():
    torch.set_default_device('cuda:0')
else:
    torch.set_default_device('cpu')
```

--------------------------------

### Apply Affine Transformation for Initial Alignment

Source: https://jef.works/STalign/notebooks/merfish-merfish-alignment.html

Constructs a rotation matrix `L` and translation vector `T` based on `theta_deg` to align the source data. This prepares the data for rasterization.

```python
theta_deg = 45
theta0 = (np.pi/180)*-theta_deg

#rotation matrix
#rotates about the origin
L = np.array([[np.cos(theta0),-np.sin(theta0)],
              [np.sin(theta0),np.cos(theta0)]])

source_L = np.matmul(L , np.array([xI, yI]))
xI_L = source_L[0]
yI_L = source_L[1]

#translation matrix
#effectively makes the rotation about the centroid of I (i.e the means of xI and yI])
#and also moves the centroid of I to the centroid of J
T = np.array([ np.mean(xI)- np.cos(theta0)*np.mean(xI) +np.sin(theta0)*np.mean(yI) - (np.mean(xI)-np.mean(xJ)),
              np.mean(yI)- np.sin(theta0)*np.mean(xI) -np.cos(theta0)*np.mean(yI) - (np.mean(yI)-np.mean(yJ))])

xI_L_T = xI_L + T[0]
yI_L_T = yI_L + T[1]


fig,ax = plt.subplots()
ax.scatter(xI_L_T,yI_L_T,s=1,alpha=0.1, label='source with initial affine transformation')
ax.scatter(xJ,yJ,s=1,alpha=0.1, label = 'target')
ax.legend(markerscale = 10)
```

--------------------------------

### Prepare Rasterized Image for Alignment

Source: https://jef.works/STalign/notebooks/xenium-heimage-alignment.html

Converts the 1D grayscale rasterized image into an RGB image by stacking the channel three times and then normalizes the intensity values to be between 0 and 1. This prepares the image for alignment with an RGB H&E image.

```python
print(M.shape)
J = np.vstack((M, M, M)) # make into 3xNxM
print(J.min())
print(J.max())

# normalize
J = STalign.normalize(J)
print(J.min())
print(J.max())

# double check size of things
print(I.shape)
print(M.shape)
print(J.shape)
```

--------------------------------

### Plotting Source Data Before Alignment

Source: https://jef.works/STalign/notebooks/merfish-visium-alignment-with-point-annotator.html

Visualizes the original MERFISH data points (xI, yI) along with their corresponding landmark points (pointsI) before any alignment transformation is applied.

```python
# plot
fig,ax = plt.subplots()
ax.scatter(xI,yI,s=1,alpha=0.2)
ax.set_aspect('equal', 'box')
ax.scatter(pointsI[:,1],pointsI[:,0], c='blue', s=100)
ax.set_title('Before alignment: source with pointsI', fontsize=15)
```

--------------------------------

### Load and Inspect First MERFISH Dataset

Source: https://jef.works/STalign/notebooks/merfish-merfish-alignment.html

Reads the cell metadata for the first MERFISH dataset using pandas and prints the head of the DataFrame to inspect its contents.

```python
# Single cell data 1
# read in data
fname = '../merfish_data/datasets_mouse_brain_map_BrainReceptorShowcase_Slice2_Replicate3_cell_metadata_S2R3.csv.gz'
df1 = pd.read_csv(fname)
print(df1.head())
```

--------------------------------

### Print Converted Landmark Point Arrays

Source: https://jef.works/STalign/notebooks/merfish-visium-alignment-with-point-annotator.html

Displays the landmark points after conversion to NumPy arrays, showing the structure and values of the transformed coordinates.

```python
# now arrays
print(pointsI)
print(pointsJ)
```

--------------------------------

### STalign.STalign.transform_image_target_to_source

Source: https://jef.works/STalign/STalign.html

Transforms an image from target to source coordinates.

```APIDOC
## STalign.STalign.transform_image_target_to_source(_xv_, _v_, _A_, _xJ_, _J_, _XI =None_)

### Description
Transform an image.
```

--------------------------------

### Initial Scatter Plot of Source and Target Data

Source: https://jef.works/STalign/notebooks/merfish-merfish-alignment.html

Visualizes the source and target datasets using scatter plots to assess initial similarity. Adjust `theta_deg` to match rotation angles.

```python
fig,ax = plt.subplots()
ax.scatter(xI,yI,s=1,alpha=0.2, label='source')
ax.scatter(xJ,yJ,s=1,alpha=0.1, label= 'target')
ax.legend(markerscale = 10)
```

--------------------------------

### Compute Matching Weights for Transformed Points

Source: https://jef.works/STalign/notebooks/xenium-xenium-alignment.html

Computes the matching weights for transformed source points using target image pixel locations and a weight 2D array. Requires out, STalign, YI, XI, tpointsI to be defined.

```python
# get the weights
WM = out['WM']
# compute weight values for transformed source points from target image pixel locations and weight 2D array (matching)
testM = STalign.interp([YI,XI],WM[None].float(),tpointsI[None].permute(-1,0,1).float())
```

--------------------------------

### Rasterize dataset with multiple kernels

Source: https://jef.works/STalign/STalign.html

Rasterizes a dataset using specified pixel size and multiple Gaussian kernels. Set draw to a positive integer to visualize progress.

```python
>>> X,Y,M,fig = tools.rasterize(x,y,dx=30.0,blur=[2.0,1.0,0.5],draw=10000)
```

--------------------------------

### Plot Rasterized Images with Landmark Points

Source: https://jef.works/STalign/notebooks/xenium-xenium-alignment.html

Visualizes the rasterized images along with the selected landmark points. This helps verify the accuracy of the chosen points before proceeding with alignment.

```python
# get extent of images
extentI = STalign.extent_from_x((YI,XI))
extentJ = STalign.extent_from_x((YJ,XJ))

# plot rasterized images
fig,ax = plt.subplots(2,1)
ax[0].imshow((I.transpose(1,2,0).squeeze()), extent=extentI) # just want 201x276 matrix
ax[1].imshow((J.transpose(1,2,0).squeeze()), extent=extentJ) # just want 201x276 matrix
# with points
ax[0].scatter(pointsI[:,1], pointsI[:,0], c='red')
ax[1].scatter(pointsJ[:,1], pointsJ[:,0], c='red')
for i in range(pointsI.shape[0]):
    ax[0].text(pointsI[i,1],pointsI[i,0],f'{i}', c='red')
    ax[1].text(pointsJ[i,1],pointsJ[i,0],f'{i}', c='red')
ax[0].invert_yaxis()
ax[1].invert_yaxis()
```
Tokens:
Raw