Preamble

SPICEY is designed to work with the results of differential analyses performed on single-cell ATAC-seq (to assess chromatin accessibility) or single-cell RNA-seq (to measure gene expression). These analyses typically compare features—either regulatory elements (e.g., peaks) or genes—across cell types to identify cell-type-specific activity or expression.

Rather than performing differential testing itself, SPICEY leverages pre-computed statistics from such analyses, specifically the log2 fold-change and associated adjusted p-values, which reflect both the magnitude and significance of cell-type enrichment. Using these inputs, SPICEY computes composite specificity scores that capture both the intensity and selectivity of differential signal across cell types.

In this tutorial, we illustrate the application of SPICEY on single-cell datasets derived from non-diabetic human pancreatic islets obtained through the Human Pancreas Analysis Program (HPAP) @ref. We analyzed paired single-nucleus ATAC-seq and RNA-seq data from three donors with similar total cell counts and comparable distributions of major pancreatic islet cell types. To associate distal regulatory elements with their putative target genes, we used co-accessibility links inferred via the Cicero package.

Differential expression and accessibility analyses were conducted using Seurat (FindMarkers()) function on both RNA and ATAC assays. All genes and regions were considered (logfc.threshold = 0), and the Wilcoxon Rank Sum test was used (test.use = "wilcox"), following Seurat default parameters.

Cell-Type Specificity Indices: RETSI and GETSI

SPICEY defines two complementary metrics to quantify cell-type specificity:

• RETSI (Regulatory Element Tissue Specificity Index): Evaluates the specificity of regulatory elements (e.g., ATAC-seq peaks) across different cell types.
• GETSI (Gene Expression Tissue Specificity Index): Evaluates the specificity of gene expression patterns across cell types.

Both RETSI and GETSI are calculated using a weighted specificity score for each feature (regulatory region or gene), reflecting the level of enrichment in each cell type. These specificity indices are computed as follows:

\[ TSI_{i,x} = \frac{FC_{i,x}}{\max(FC)_x} \cdot w_{i} \]

\[ w_{i} = \text{rescale}\left( -\log_{10}(padj_{i}),\ [0, 1] \right) \]

where:

• \(i\) is a specific cell type
• \(x \in \{r, g\}\), with \(r\) for regulatory region (RETSI) and \(g\) for gene (GETSI)
• \(\text{FC}_{i,x}\) is the log fold-change of feature \(x\) in cell type \(i\)
• \(w_{i}\) is the weight term, defined as the rescaled value of \(-\log_{10}(\text{adjusted } p\text{-value})\) between 0 and 1

SPICEY offers two strategies for linking regulatory elements to their putative target genes:

1. Nearest-gene assignment: based on proximity to the closest transcription start site (TSS).
2. Co-accessibility-based linking: leveraging correlations in chromatin accessibility (e.g., via Cicero).

These linking methods enable the integration of regulatory specificity (RETSI) and gene expression specificity (GETSI), facilitating the construction of detailed cell-type-specific regulatory networks from single-cell data.

Note: This vignette illustrates the use of SPICEY with preprocessed GRanges inputs, which must be prepared externally as they are not provided within the package.

Entropy-based Specificity Indices

In addition to fold change–based metrics, SPICEY incorporates an entropy-based approach to quantify the distributional concentration or distributional skewness of feature activity across cell types using Shannon entropy.

For each feature \(x\) (e.g., gene or regulatory region), the activity or expression scores across \(N\) cell types are normalized into a probability distribution. This allows measuring how specific or broadly distributed a feature’s activity is across cell types. Lower entropy values indicate higher cell-type specificity, while higher entropy reflects more ubiquitous expression or accessibility. These entropy-based indices are computed as follows:

\[ H(x) = - \sum_{i=1}^{N} p_{i,x} \log_2(p_{i,x}) \]

\[ H_{\text{norm}}(x) = 1 - e^{-H(x)} \] where:

\[ p_{i,x} = \frac{s_{i,x}}{\sum_{j=1}^{N} s_{j,x}} \]

being:

• \(s_{i,x}\) is the specificity score (e.g., RETSI or GETSI) of feature \(x\) in cell type \(i\)
• \(p_{i,x}\) is the normalized score, interpreted as the probability of feature \(x\)’s activity in cell type \(i\)
• \(H(x)\) is the Shannon entropy, quantifying signal dispersion across cell types
• \(H_{\text{norm}}(x)\) is the normalized entropy, bounded between 0 and 1:
  • Values close to 0 indicate strong specificity
  • Values close to 1 indicate broad distribution

This entropy framework provides a robust and interpretable measure of cell-type specificity that is complementary to fold change–based approaches.

Single-cell ATAC-seq Data

• Accepted Formats:

  • A named list of GRanges objects or data.frames (convertible to GRanges), where each element contains differential accessibility results for a specific cell type.
    
  • A GRangesList with each element representing a distinct cell type.

  All inputs must be named with cell type identifiers.

• Required Columns (per element):

  • region_id — Unique peak identifier matching the format in your ATAC data (e.g., chr1-5000-5800 or chr1:5000-5800).
  • avg_log2FC — Average log2 fold-change of accessibility in the given cell type.
  • p_val_adj — Adjusted p-value from the differential test.
  • cell_type — Cell type or cluster label for each measurement.

Each peak should have multiple entries, one per cell type, allowing SPICEY to assess cell-type-specific accessibility patterns.

data("atac")

Single-cell RNA-seq Data

• Accepted Formats:

  • A named list of GRanges objects or data.frames (convertible to GRanges), with each element containing differential expression results for a specific cell type.
    
  • A GRangesList, where each element corresponds to a distinct cell type.

  The list or GRangesList must be named with cell type identifiers.

• Required Columns (per element):

  • gene_id — Gene identifier column, consistent across all entries, using official gene symbols (e.g., GAPDH).
  • avg_log2FC — Average log2 fold-change in expression for the gene within the specific cell type.
  • p_val_adj — Adjusted p-value from the differential test.
  • cell_type — Cell type or cluster label associated with the measurement.

Each gene should have multiple entries—one per cell type—enabling SPICEY to evaluate expression specificity across cell populations.

data("rna")

Co-accessibility Links (Optional for Region-to-Gene Linking)

• Purpose:
  Link regulatory elements to putative target genes based on co-accessibility, typically derived from tools like Cicero. This input is required only when using the annotation parameter for RETSI/GETSI integration.

• Format:
  A data.frame containing co-accessibility pairs and their scores.

• Required Columns:

  • Peaks1 — Genomic coordinate or ID of the first peak in the pair.
  • Peaks2 — Genomic coordinate or ID of the second peak.
  • coaccess — Co-accessibility score or correlation value between the paired peaks.

Note: Peak identifiers in Peaks1 and Peaks2 must exactly match those in the ATAC input, including coordinate formatting (e.g., chr1:5000-6000 vs. chr1-5000-6000). Inconsistent formats will disrupt accurate annotation.

data("cicero_links")
head(cicero_links)
#>                      Peak1                    Peak2  coaccess
#> 1 chr1-110209621-110211746 chr1-110211947-110212475 0.6000726
#> 2 chr1-110211947-110212475 chr1-110209621-110211746 0.6000726
#> 3 chr1-119541413-119543141 chr1-119552715-119554580 0.6251863
#> 4 chr1-119552715-119554580 chr1-119541413-119543141 0.6251863
#> 5 chr1-167654711-167655798 chr1-167683611-167684550 0.8876609
#> 6 chr1-167661501-167662210 chr1-167683611-167684550 0.6807298

Computing RETSI

To calculate the Regulatory Element Tissue Specificity Index (RETSI), the following inputs are required:

• atac: A named list of GRanges objects or data.frames (convertible to GRanges), each representing differential accessibility results for a distinct cell type.

SPICEY returns a data.frame combining the input differential accessibility data with RETSI scores for each regulatory region.

Note: Confirm that your inputs comply with the format outlined in the Input Requirements section prior to execution.

retsi <- SPICEY(atac = atac)
head(retsi)
#>   cell_type     p_val_adj         p_val avg_log2FC                 region_id
#> 1    Acinar 3.353304e-302  0.000000e+00   6.025791  chr7-142748901-142749963
#> 2    Acinar 3.353304e-302  0.000000e+00   6.160286    chr2-79119834-79120951
#> 3    Acinar 3.353304e-302  0.000000e+00   6.299025 chr10-116587488-116588562
#> 4    Acinar 3.353304e-302  0.000000e+00   6.849885 chr10-116553223-116553959
#> 5    Acinar 4.272632e-232 9.160344e-238   6.694460 chr10-116589603-116590250
#> 6    Acinar 4.123107e-214 8.839769e-220   5.184217   chr16-75217280-75217880
#>       RETSI RETSI_entropy
#> 1 1.0000000  0.0524689042
#> 2 1.0000000  0.0020261572
#> 3 1.0000000  0.0005612349
#> 4 1.0000000  0.0002746290
#> 5 0.7674589  0.0001781440
#> 6 0.7078037  0.0013891926

Computing GETSI

To calculate the Gene Expression Tissue Specificity Index (GETSI), the following inputs are required:

• rna: A named list of GRanges objects or data.frames (convertible to GRanges), each containing differential gene expression results for a specific cell type.

SPICEY outputs a data.frame that integrates the input differential expression data with computed GETSI scores for each gene.

Note: Verify that your inputs adhere to the format described in the Input Requirements section before execution.

getsi <- SPICEY(rna = rna)
head(getsi)
#>   gene_id         p_val avg_log2FC pct.1 pct.2     p_val_adj cell_type
#> 1   REG1A  0.000000e+00   6.446878 0.392 0.012 1.053548e-303    Acinar
#> 2   PRSS1 3.793351e-218   5.111544 0.608 0.067 7.442554e-214    Acinar
#> 3   PNLIP 5.687535e-208   5.156786 0.471 0.038 1.115894e-203    Acinar
#> 4   PRSS2 1.241892e-185   4.545974 0.568 0.066 2.436593e-181    Acinar
#> 5   REG1B 9.599031e-101   4.519686 0.176 0.010  1.883330e-96    Acinar
#> 6   PLCB4  5.936709e-84  -2.027707 0.458 0.933  1.164782e-79    Acinar
#>        GETSI GETSI_entropy
#> 1 1.00000000   0.001229388
#> 2 0.70344625   0.104333983
#> 3 0.66985991   0.006319652
#> 4 0.59612780   0.432573280
#> 5 0.31594796   0.000000000
#> 6 0.05136069   0.700016953

Computing SPICEY

SPICEY offers an integrated approach to quantify tissue specificity at both the epigenetic and transcriptional levels by simultaneously computing Regulatory Element Tissue Specificity Indices (RETSI) and Gene Expression Tissue Specificity Indices (GETSI) from single-cell data.

By supplying both atac and rna inputs together to the SPICEY() function, the tool calculates RETSI and GETSI scores and returns a list with each specificity measure provided separately.

spicey <- SPICEY(
  atac = atac,
  rna = rna
)
lapply(spicey, head)
#> $RETSI
#>   cell_type     p_val_adj         p_val avg_log2FC                 region_id
#> 1    Acinar 3.353304e-302  0.000000e+00   6.025791  chr7-142748901-142749963
#> 2    Acinar 3.353304e-302  0.000000e+00   6.160286    chr2-79119834-79120951
#> 3    Acinar 3.353304e-302  0.000000e+00   6.299025 chr10-116587488-116588562
#> 4    Acinar 3.353304e-302  0.000000e+00   6.849885 chr10-116553223-116553959
#> 5    Acinar 4.272632e-232 9.160344e-238   6.694460 chr10-116589603-116590250
#> 6    Acinar 4.123107e-214 8.839769e-220   5.184217   chr16-75217280-75217880
#>       RETSI RETSI_entropy
#> 1 1.0000000  0.0524689042
#> 2 1.0000000  0.0020261572
#> 3 1.0000000  0.0005612349
#> 4 1.0000000  0.0002746290
#> 5 0.7674589  0.0001781440
#> 6 0.7078037  0.0013891926
#> 
#> $GETSI
#>   gene_id         p_val avg_log2FC pct.1 pct.2     p_val_adj cell_type
#> 1   REG1A  0.000000e+00   6.446878 0.392 0.012 1.053548e-303    Acinar
#> 2   PRSS1 3.793351e-218   5.111544 0.608 0.067 7.442554e-214    Acinar
#> 3   PNLIP 5.687535e-208   5.156786 0.471 0.038 1.115894e-203    Acinar
#> 4   PRSS2 1.241892e-185   4.545974 0.568 0.066 2.436593e-181    Acinar
#> 5   REG1B 9.599031e-101   4.519686 0.176 0.010  1.883330e-96    Acinar
#> 6   PLCB4  5.936709e-84  -2.027707 0.458 0.933  1.164782e-79    Acinar
#>        GETSI GETSI_entropy
#> 1 1.00000000   0.001229388
#> 2 0.70344625   0.104333983
#> 3 0.66985991   0.006319652
#> 4 0.59612780   0.432573280
#> 5 0.31594796   0.000000000
#> 6 0.05136069   0.700016953

Building Tissue-Specific Regulatory Networks

SPICEY facilitates the construction of tissue-specific regulatory networks by integrating RETSI and GETSI scores through the association of regulatory elements with their putative target genes. This linkage connects each regulatory region’s cell type-specific RETSI score to the corresponding gene’s GETSI score, enabling comprehensive downstream network analyses.

To establish these links, regulatory regions must be annotated to target genes. SPICEY supports two annotation strategies:

1. Proximity-based annotation — assigning regions to the nearest transcription start site (TSS).
   
2. Co-accessibility-based annotation — leveraging promoter–enhancer co-accessibility relationships derived from snATAC-seq data (e.g., via Cicero).

Annotating Regions to Putative Target Genes (Optional)

peaks <- unique(unlist(atac)[, c("region_id")])

annotation_near <- annotate_with_nearest(
  peaks = peaks,
  txdb = TxDb.Hsapiens.UCSC.hg38.knownGene,
  annot_dbi = org.Hs.eg.db,
  protein_coding_only = TRUE,
  verbose = TRUE,
  add_tss_annotation = FALSE,
  upstream = 2000,
  downstream = 2000
)

head(annotation_near)
#>                                           region_id distanceToTSS gene_id
#> chr7-142748901-142749963   chr7-142748901-142749963      25424083    WNT2
#> chr2-79119834-79120951       chr2-79119834-79120951             0   REG1A
#> chr10-116587488-116588562 chr10-116587488-116588562      15524492 KAZALD1
#> chr10-116553223-116553959 chr10-116553223-116553959      15490227 KAZALD1
#> chr10-116589603-116590250 chr10-116589603-116590250      15526607 KAZALD1
#> chr16-75217280-75217880     chr16-75217280-75217880       8850526    CDH5
#>                           annotation
#> chr7-142748901-142749963      Distal
#> chr2-79119834-79120951      Promoter
#> chr10-116587488-116588562     Distal
#> chr10-116553223-116553959     Distal
#> chr10-116589603-116590250     Distal
#> chr16-75217280-75217880       Distal

peaks <- unique(unlist(atac)[, c("region_id")])

annotation_coacc <- annotate_with_coaccessibility(
  peaks = peaks,
  txdb = TxDb.Hsapiens.UCSC.hg38.knownGene,
  links_df = cicero_links,
  annot_dbi = org.Hs.eg.db,
  protein_coding_only = TRUE,
  verbose = TRUE,
  add_tss_annotation = FALSE,
  upstream = 2000,
  downstream = 2000
)

head(annotation_coacc)
#>                   region_id gene_id
#> 1  chr1-110209621-110211746   KCNC4
#> 2    chr1-20290295-20292065  UBXN10
#> 3    chr1-20290295-20292065 PLA2G2C
#> 4 chr11-102177735-102178851    YAP1
#> 5 chr11-102551894-102553101   BIRC3
#> 6 chr11-102551894-102553101    MMP7

# Using nearest gene annotation data
spicey_near <- SPICEY(
  rna = rna,
  atac = atac,
  annotation = annotation_near
)


# Using co-accessibility gene annotation data
spicey_coacc <- SPICEY(
  rna = rna,
  atac = atac,
  annotation = annotation_coacc
)

SPICEY Measures

Linked SPICEY Measures

This annotated data.frame serves as a comprehensive resource combining genomic coordinates, cell type-specific regulatory activity, gene associations, and expression specificity—enabling advanced functional genomics analyses.

Required inputs:

To run spicey_heatmap(), the input must be a data.frame with the following columns:

• gene_id:
  • For RETSI: The gene annotated to the given regulatory region (e.g., from co-accessibility or distance to the nearest TSS).
  • For GETSI: The expressed gene for which expression specificity is measured.
• cell_type: Cell type or cluster label (e.g., "Acinar").
• GETSI and/or RETSI score.

Arguments

• df: A data.frame containing the columns described above.
• top_n: Number of top-ranked genes to retain per cell type (default: 5).
• spicey_measure: Score type to visualize. Must be one of "RETSI", "GETSI", or "SPICEY".
• combined_score: Logical. If TRUE and spicey_measure = "SPICEY", computes a combined mean score across RETSI and GETSI (default: FALSE).

# RETSI and/or GETSI separately
spicey_heatmap(spicey_coacc$GETSI,
  spicey_measure = "GETSI"
)

# If only RETSI is calculated (only ATAC data available), join with coaccessibility or nearest gene annotation to show gene_id in the plots
retsi <- spicey_coacc$RETSI
retsi <- retsi |> left_join(annotation_near, by = c("region_id"))
spicey_heatmap(retsi,
  spicey_measure = "RETSI"
)

spicey_heatmap(spicey_coacc$linked,
  spicey_measure = "SPICEY",
  combined_score = FALSE
)

# SPICEY: combined average RETSI and GETSI scores
spicey_heatmap(spicey_coacc$linked,
  spicey_measure = "SPICEY",
  combined_score = TRUE
)