| Title: | Spatially Aware Adjusted Rand Index for Evaluating Spatial Transcritpomics Clustering |
|---|---|
| Description: | The R package used in the manuscript "Spatially Aware Adjusted Rand Index for Evaluating Spatial Transcritpomics Clustering". |
| Authors: | Yinqiao Yan [aut, cre], Xiangnan Feng [aut, fnd], Xiangyu Luo [aut, fnd] |
| Maintainer: | Yinqiao Yan <[email protected]> |
| License: | GPL (>= 2) |
| Version: | 1.3.0 |
| Built: | 2026-05-30 09:47:28 UTC |
| Source: | https://github.com/bioc/spARI |
This function identifies all object pairs that belong to the same group in the reference partition but different clusters in the clustering partition
c_labels |
An integer vector of clustering labels. |
r_labels |
An integer vector of reference labels. |
An integer matrix with two columns, where each row is a pair of object indices.
c_labels <- c(1,1,2,2,2,3,3) r_labels <- c(1,1,1,2,2,3,1) generate_gs_pairs_int(c_labels, r_labels)c_labels <- c(1,1,2,2,2,3,3) r_labels <- c(1,1,1,2,2,3,1) generate_gs_pairs_int(c_labels, r_labels)
This function identifies all object pairs that belong to the same cluster in the clustering partition but different groups in the reference partition
c_labels |
An integer vector of clustering labels. |
r_labels |
An integer vector of reference labels. |
An integer matrix with two columns, where each row is a pair of object indices.
c_labels <- c(1,1,2,2,2,3,3) r_labels <- c(1,1,1,2,2,3,1) generate_sg_pairs_int(c_labels, r_labels)c_labels <- c(1,1,2,2,2,3,3) r_labels <- c(1,1,1,2,2,3,1) generate_sg_pairs_int(c_labels, r_labels)
The function perm_test is the main function to carry out the hypothesis test procedure proposed in the paper.
perm_test( r_labels, c_labels, coords = NULL, dist_mat = NULL, f_func_input = NULL, h_func_input = NULL, alpha_val = 0.8, use_parallel = TRUE, replicate_times = 100, random_seed = 42, spe = NULL )perm_test( r_labels, c_labels, coords = NULL, dist_mat = NULL, f_func_input = NULL, h_func_input = NULL, alpha_val = 0.8, use_parallel = TRUE, replicate_times = 100, random_seed = 42, spe = NULL )
r_labels |
Annotated labels of all spots/cells. Can be numeric vector or character vector. |
c_labels |
Estimated labels obtained by a certain spatial clustering method. |
coords |
Spatial coordinates (2 columns). 1st column: first dimension coordinate. 2nd column: second dimension coordinate. Default is NULL. |
dist_mat |
Distance matrix provided by users. If both coords and dist_mat are provided, we will directly use the distance matrix. Default is NULL. Please notice that if dist_mat is sparse, the weight function for object pairs without recorded distances degenerates to the setting used in the classical Rand index. |
f_func_input |
R function; function f provided by users. |
h_func_input |
R function; function h provided by users. |
alpha_val |
Parameter in the default functions f and h, which belongs to the open interval (0, 1) to keep a positive gap between the maximal weight of the disagreement pair and the weight one of the agreement pair. Default is 0.8. |
use_parallel |
Logical; if TRUE, use parallel code to permute the two partitions. Default is TRUE. |
replicate_times |
Number of permutations for both the reference and clustering partitions. Default is 100. |
random_seed |
Random seed for reproducibility. Default is 42. |
spe |
SpatialExperiment object; stores various components of spatial transcriptomics data, including spatialCoords: A matrix containing the spatial coordinates; colData$cell_type: Annotated cell type labels for each spot or cell; colData$cluster: Clustering labels for each spot or cell. Default is NULL. |
spARI returns an R numeric including the following information.
spARI_obs |
numeric, the observed spARI value calculated by r_labels and c_labels |
p_value |
numeric, the p-value of the hypothesis testing |
library(spARI) data(spARI_example_data) true_labels = spARI_example_data$true_labels c1_labels = spARI_example_data$c1_labels c2_labels = spARI_example_data$c2_labels coords = spARI_example_data$coords test_res1 = perm_test(r_labels=true_labels, c_labels=c1_labels, coords=coords, use_parallel=FALSE) test_res2 = perm_test(r_labels=true_labels, c_labels=c2_labels, coords=coords, use_parallel=FALSE)library(spARI) data(spARI_example_data) true_labels = spARI_example_data$true_labels c1_labels = spARI_example_data$c1_labels c2_labels = spARI_example_data$c2_labels coords = spARI_example_data$coords test_res1 = perm_test(r_labels=true_labels, c_labels=c1_labels, coords=coords, use_parallel=FALSE) test_res2 = perm_test(r_labels=true_labels, c_labels=c2_labels, coords=coords, use_parallel=FALSE)
The function spARI is the main function to calculate spRI and spARI values proposed in the paper.
spARI( r_labels, c_labels, coords = NULL, dist_mat = NULL, f_func_input = NULL, h_func_input = NULL, alpha_val = 0.8, spe = NULL )spARI( r_labels, c_labels, coords = NULL, dist_mat = NULL, f_func_input = NULL, h_func_input = NULL, alpha_val = 0.8, spe = NULL )
r_labels |
Annotated labels of all spots/cells. Can be numeric vector or character vector. |
c_labels |
Estimated labels obtained by a certain spatial clustering method. |
coords |
Spatial coordinates (2 columns). 1st column: first dimension coordinate. 2nd column: second dimension coordinate. Default is NULL. |
dist_mat |
Distance matrix provided by users. If both coords and dist_mat are provided, we will directly use the distance matrix. Default is NULL. Please notice that if dist_mat is sparse, the weight function for object pairs without recorded distances degenerates to the setting used in the classical Rand index. |
f_func_input |
R function; function f provided by users. |
h_func_input |
R function; function h provided by users. |
alpha_val |
Parameter in the default functions f and h, which belongs to the open interval (0, 1) to keep a positive gap between the maximal weight of the disagreement pair and the weight one of the agreement pair. Default is 0.8. |
spe |
SpatialExperiment object; stores various components of spatial transcriptomics data, including spatialCoords: A matrix containing the spatial coordinates; colData$cell_type: Annotated cell type labels for each spot or cell; colData$cluster: Clustering labels for each spot or cell. Default is NULL. |
spARI returns an R numeric including the following information.
spRI_value |
numeric, the spRI value calculated by r_labels and c_labels |
spARI_value |
numeric, the spARI value calculated by r_labels and c_labels |
library(spARI) ### --- Import example data --- ### # (1) true_labels: ground truth of 160 spots (input as r_labels) # (2) c1_labels: one partition results of these spots (input as c_labels) # (3) c2_labels: another partition results of these spots (input as c_labels) # (4) coords: spatial coordinates of these spots (2 columns) data(spARI_example_data) true_labels = spARI_example_data$true_labels c1_labels = spARI_example_data$c1_labels c2_labels = spARI_example_data$c2_labels coords = spARI_example_data$coords ### --- Compute spRI and spARI --- ### res1 = spARI(r_labels=true_labels, c_labels=c1_labels, coords=coords) res2 = spARI(r_labels=true_labels, c_labels=c2_labels, coords=coords) cat(paste0("1st: spRI=", round(res1[1], 3), ", spARI=", round(res1[2], 3), "\n")) cat(paste0("2nd: spRI=", round(res2[1], 3), ", spARI=", round(res2[2], 3), "\n"))library(spARI) ### --- Import example data --- ### # (1) true_labels: ground truth of 160 spots (input as r_labels) # (2) c1_labels: one partition results of these spots (input as c_labels) # (3) c2_labels: another partition results of these spots (input as c_labels) # (4) coords: spatial coordinates of these spots (2 columns) data(spARI_example_data) true_labels = spARI_example_data$true_labels c1_labels = spARI_example_data$c1_labels c2_labels = spARI_example_data$c2_labels coords = spARI_example_data$coords ### --- Compute spRI and spARI --- ### res1 = spARI(r_labels=true_labels, c_labels=c1_labels, coords=coords) res2 = spARI(r_labels=true_labels, c_labels=c2_labels, coords=coords) cat(paste0("1st: spRI=", round(res1[1], 3), ", spARI=", round(res1[2], 3), "\n")) cat(paste0("2nd: spRI=", round(res2[1], 3), ", spARI=", round(res2[2], 3), "\n"))
This dataset includes simulated spatial clustering results for demonstration purposes. It contains the following objects:
true_labels: Ground-truth labels of 160 spots.
c1_labels: First clustering result to compare.
c2_labels: Second clustering result to compare.
coords: Spatial coordinates (matrix with 2 columns).
data(spARI_example_data)data(spARI_example_data)
An environment containing 4 objects:
Numeric or factor vector of length 160.
Numeric or factor vector of length 160.
Numeric or factor vector of length 160.
Numeric matrix of size 160x2.