smoother.utils

Utility functions

Functions

normalize_minmax(x[, min_zero, return_scale])

Normalize data to [0, 1] or [-1, 1].

_z_score(features)

Z-score standardization.

_pca(features, dim)

Dimension reduction by PCA.

calc_feature_similarity_sparse(features, indices[, ...])

Calculate pairwise feature similarity between spots for a given set of spot pairs.

calc_feature_similarity(features[, dist_metric, ...])

Calculate pairwise feature similarity between spots.

get_histology_vector(image, x_pixel, y_pixel, ...[, ...])

Get the histology image vector of one spot.

calc_histology_similarity_sparse(coords, indices, ...)

Calculate pairwise histology similarity between spots for a given set of points.

calc_histology_similarity(coords, image, scale_factors)

Calculate pairwise histology similarity between spots.

quantile_feature_similarity_neighbor(features, coords, k)

Calculate cosine similarity of features between physical k-nearest neighbors.

quantile_feature_similarity_decay(features, coords[, ...])

Calculate cosine similarity of features between physical neighbors of varying degrees.

get_neighbor_quantile_value_by_k(sq_mat, coords[, ...])

Extract values of neighboring pairs of spots from the square matrix.

plot_similarity_cdf(df_k[, title, k])

Plot cumulative distribution of pairwise cosine similarity between neighboring spots.

plot_similarity_decay(df_all[, title, plot_type])

Plot decay of pairwise cosine similarity between neighboring spots.

_mono_exp(x, alpha, beta)

estimate_decay_rate(x, y[, return_all_params])

Estimate decay rate of a mono-exponential decay function.

Module Contents

smoother.utils.normalize_minmax(x, min_zero=True, return_scale=False)

Normalize data to [0, 1] or [-1, 1].

Parameters:

  • x (2D array) – data to be normalized.

  • min_zero (bool) – If True, set column minimum to 0.

  • return_scale (bool) – If True, return the scaling factor.

smoother.utils._z_score(features)

Z-score standardization.

smoother.utils._pca(features, dim)

Dimension reduction by PCA.

smoother.utils.calc_feature_similarity_sparse(features: torch.Tensor, indices: torch.Tensor, dist_metric='cosine', reduce='none', dim=10, nonneg=False, return_type='flat')

Calculate pairwise feature similarity between spots for a given set of spot pairs.

Similarity s is transformed from distance d by 1) Cosine similarity: s = (1 - d) (if nonneg, (1 - d).clamp(min = 0)) 2) Others: s = exp(- d^2/(2 * band_width^2)))

Parameters:

  • features (2D tensor) – Feature matrix, num_feature x num_spot.

  • indices (2D tensor) – Pairs of spot indices of which to calculate the similarity, 2 x num_pairs.

  • dist_metric (str) – Distance metric.

  • reduce (str) – If PCA, calculate distance on the reduced PCA space.

  • dim (int) – Number of dimension of the reduced space.

  • nonneg (bool) – If True, set negative similarity to 0.

  • return_type (str) – If sparse, return a sparse tensor. If dense, return a dense tensor. If flat, return a flat tensor of length num_pairs.

Returns:

A 2D tensor containing pairwise similarities, num_spot x num_spot.

Return type:

feature_sim

smoother.utils.calc_feature_similarity(features: torch.Tensor, dist_metric='cosine', reduce='pca', dim=10, nonneg=False)

Calculate pairwise feature similarity between spots.

Similarity s is transformed from distance d by 1) Cosine similarity: s = (1 - d) (if nonneg, (1 - d).clamp(min = 0)) 2) Others: s = exp(- d^2/(2 * band_width^2)))

Parameters:

  • features (2D tensor) – Feature matrix, num_feature x num_spot.

  • dist_metric (str) – Distance metric.

  • reduce (str) – If PCA, calculate distance on the reduced PCA space.

  • dim (int) – Number of dimension of the reduced space.

  • nonneg (bool) – If True, set negative similarity to 0.

Returns:

A 2D tensor containing pairwise similarities, num_spot x num_spot.

Return type:

feature_sim

smoother.utils.get_histology_vector(image, x_pixel, y_pixel, spot_radius, scale_factor, padding=True)

Get the histology image vector of one spot.

Parameters:

  • image (3D array) – Histology image, num_pixel x num_pixel x num_channel.

  • x_pixel (float) – Spot centric position (in fullres).

  • y_pixel (float) – Spot centric position (in fullres).

  • spot_radius (float) – Spot size (in fullres).

  • scale_factor (float) – Scale factor that transforms fullres image to the given image.

  • paddings (bool) – Whether to pad for boundary spots. If False, will return the averaged color vector.

Returns:

A vector containing histology information around the spot.

Return type:

spot_vec (1D array)

smoother.utils.calc_histology_similarity_sparse(coords, indices, image, scale_factors, dist_metric='euclidean', reduce='none', dim=3, nonneg=True)

Calculate pairwise histology similarity between spots for a given set of points.

Parameters:

  • coords (2D array) – Spatial coordinate matrix (in fullres pixel), num_spot x 2.

  • indices (2D tensor) – Pairs of spot indices of which to calculate the similarity, 2 x num_pairs.

  • image (3D array) – Histology image, num_pixel x num_pixel x num_channel.

  • scale_fators (dict) – The JSON dictionary from 10x Visium’s scalefactors_json.json ‘spot_diameter_fullres’ (float): Spot size (fullres) ‘tissue_hires_scalef’ (float): Scale factor that transforms fullres image to the given image.

  • reduce (str) –

    How to compute histological similarity. Can be one of ‘pca’, ‘mean’, and ‘none’. If ‘none’, will concatenate pixel-level histology vectors of each spot and calculate distance. If ‘pca’, will concatenate pixel-level histology vectors of each spot, apply PCA to reduce

    the dimension of the histology space, then calculate the distance.

    If ‘mean’, will average the histology vector of each spot over its covering area.

  • dim (int) – Number of dimension of the reduced space.

  • nonneg (bool) – Whether to remove negative similarity.

Returns:

A 2D tensor containing pairwise histology similarities, num_spot x num_spot.

Return type:

hist_sim

smoother.utils.calc_histology_similarity(coords, image, scale_factors, dist_metric='euclidean', reduce='pca', dim=3, nonneg=True)

Calculate pairwise histology similarity between spots.

Parameters:

  • coords (2D array) – Spatial coordinate matrix (in fullres pixel), num_spot x 2.

  • image (3D array) – Histology image, num_pixel x num_pixel x num_channel.

  • scale_fators (dict) – The JSON dictionary from 10x Visium’s scalefactors_json.json ‘spot_diameter_fullres’ (float): Spot size (fullres) ‘tissue_hires_scalef’ (float): Scale factor that transforms fullres image to the given image.

  • reduce (str) –

    How to compute histological similarity. Can be one of ‘pca’, ‘mean’, and ‘none’. If ‘none’, will concatenate pixel-level histology vectors of each spot and calculate distance. If ‘pca’, will concatenate pixel-level histology vectors of each spot, apply PCA to reduce

    the dimension of the histology space, then calculate the distance.

    If ‘mean’, will average the histology vector of each spot over its covering area.

  • dim (int) – Number of dimension of the reduced space.

  • nonneg (bool) – Whether to remove negative similarity.

Returns:

A 2D tensor containing pairwise histology similarities, num_spot x num_spot.

Return type:

hist_sim

smoother.utils.quantile_feature_similarity_neighbor(features, coords, k, reduce='pca', dim=20, n_null=100)

Calculate cosine similarity of features between physical k-nearest neighbors.

Parameters:

  • features (2D tensor) – Feature matrix, num_gene x num_spot.

  • coords (2D tensor) – Coordinates of spots, num_spot x 2.

  • k (int) – Number of neighbors.

  • reduce (str) – Dimension reduction method, ‘pca’ or ‘none’.

  • dim (int) – Number of dimensions to reduce to.

  • n_null (int) – Number of null distribution samples.

Returns:

Quantiles of cosine similarity between neighbors.

Return type:

df (dataframe)

smoother.utils.quantile_feature_similarity_decay(features, coords, max_k=50, topk=False, reduce='pca', dim=20)

Calculate cosine similarity of features between physical neighbors of varying degrees.

Parameters:

  • features (2D tensor) – Feature matrix, num_gene x num_spot.

  • coords (2D tensor) – Coordinates of spots, num_spot x 2.

  • max_k (int) – Maximum number of neighbors.

  • topk (bool) – Whether to keep all neighbors within the threshold or only the k nearest neighbors.

  • reduce (str) – Dimension reduction method, ‘pca’ or ‘none’.

  • dim (int) – Number of dimensions to reduce to.

Returns:

Quantiles of cosine similarity between neighbors.

Return type:

df (dataframe)

smoother.utils.get_neighbor_quantile_value_by_k(sq_mat, coords, min_k=0, max_k=50)

Extract values of neighboring pairs of spots from the square matrix.

Parameters:

  • sq_mat (2D tensor) – Data to extract, num_spot x num_spot.

  • coords (2D tensor) – Coordinates of spots, num_spot x 2.

  • min_k (int) – Minimum number of neighbors. k = 0: self.

  • max_k (int) – Maximum number of neighbors.

smoother.utils.plot_similarity_cdf(df_k, title='', k=None)

Plot cumulative distribution of pairwise cosine similarity between neighboring spots.

Parameters:

  • df_k (dataframe) – Quantiles of cosine similarity between neighbors. Output of quantile_feature_similarity_neighbor.

  • title (str) – Plot title.

  • k (int) – Number of neighbors (labeling only).

smoother.utils.plot_similarity_decay(df_all, title='', plot_type='shadow')

Plot decay of pairwise cosine similarity between neighboring spots.

Parameters:

  • df_all (dataframe) – Quantiles of cosine similarity between neighbors. Output of quantile_feature_similarity_decay.

  • title (str) – Plot title.

  • plot_type (str) – Type of plot, “shadow”, “boxplot” or “lineplot”.

smoother.utils._mono_exp(x, alpha, beta)
smoother.utils.estimate_decay_rate(x, y, return_all_params=False)

Estimate decay rate of a mono-exponential decay function.

Parameters:

  • x (array) – x values.

  • y (array) – y values.

  • return_all_params (bool) – If False, only return decay rate (beta).