Quick Start Guide

Introduction

iTALK (intercellular communication analysis toolkit) is an R package designed to characterize and visualize cell-cell communication from transcriptomic data. This vignette provides a quick introduction to the core functionality.

Installation

# From R-Universe (recommended)
install.packages("iTALK", repos = "https://zaoqu-liu.r-universe.dev")

# From GitHub
remotes::install_github("Zaoqu-Liu/iTALK")

Load Package and Create Example Data

library(iTALK)
library(dplyr)

# Access database to get real ligand-receptor pairs
db <- iTALK:::database
cyto_db <- db[db$Classification == "cytokine", ]

# Get some real ligands and receptors from the database
ligands <- head(unique(cyto_db$Ligand.ApprovedSymbol), 10)
receptors <- head(unique(cyto_db$Receptor.ApprovedSymbol), 10)
genes <- unique(c(ligands, receptors))

cat("Using genes from database:\n")
#> Using genes from database:
cat("Ligands:", paste(ligands, collapse = ", "), "\n")
#> Ligands: CCL11, CCL13, CCL14, CCL15, CCL16, CCL17, CCL18, CCL19, CCL1, CCL20
cat("Receptors:", paste(receptors, collapse = ", "), "\n\n")
#> Receptors: ACKR2, ACKR4, CCR2, CCR3, CCR5, CXCR3, CCR1, CCR9, CCR8, HRH4

# Create synthetic expression data
set.seed(42)
n_cells <- 200
cell_types <- c("T_cell", "B_cell", "Macrophage", "Dendritic", "NK_cell")

data <- data.frame(
  cell_type = sample(cell_types, n_cells, replace = TRUE)
)

# Add gene expression
for (gene in genes) {
  data[[gene]] <- rpois(n_cells, lambda = sample(5:25, 1))
}

cat("Data dimensions:", nrow(data), "cells x", ncol(data), "columns\n")
#> Data dimensions: 200 cells x 21 columns
cat("Cell types:", paste(unique(data$cell_type), collapse = ", "), "\n")
#> Cell types: T_cell, NK_cell, B_cell, Dendritic, Macrophage
head(data[, 1:6])
#>   cell_type CCL11 CCL13 CCL14 CCL15 CCL16
#> 1    T_cell    11    22    21     7    13
#> 2   NK_cell    20    14    22     7     8
#> 3    T_cell     8    22    20     4     8
#> 4    T_cell    11    28    27    12    14
#> 5    B_cell    17    30    34     6    12
#> 6 Dendritic    12    19    18     7     7

Workflow 1: Highly Expressed Gene Analysis

Step 1: Parse Expression Data

Identify the top expressed genes in each cell type:

# Get top 50% highly expressed genes per cell type
highly_expr <- rawParse(data, top_genes = 50, stats = "mean")

cat("\nTop expressed genes found:", nrow(highly_expr), "\n")
#> 
#> Top expressed genes found: 50
cat("Cell types:", paste(unique(highly_expr$cell_type), collapse = ", "), "\n\n")
#> Cell types: T_cell, NK_cell, B_cell, Dendritic, Macrophage
head(highly_expr)
#>    gene    exprs cell_type
#> 1 CCL14 25.65306    T_cell
#> 2 CXCR3 24.55102    T_cell
#> 3 CCL13 24.24490    T_cell
#> 4  CCR8 23.89796    T_cell
#> 5  HRH4 19.02041    T_cell
#> 6 ACKR4 17.63265    T_cell

Step 2: Find Ligand-Receptor Pairs

# Find ligand-receptor pairs from cytokine category
lr_pairs <- FindLR(
  data_1 = highly_expr,
  datatype = "mean count",
  comm_type = "cytokine"
)

cat("Found", nrow(lr_pairs), "ligand-receptor pairs\n\n")
#> Found 243 ligand-receptor pairs
if (nrow(lr_pairs) > 0) {
  head(lr_pairs)
}
#>   ligand receptor cell_from_mean_exprs cell_from cell_to_mean_exprs    cell_to
#> 1  CCL11    ACKR2             13.26531    T_cell           14.34694     T_cell
#> 2  CCL11    ACKR2             13.26531    T_cell           14.58974    NK_cell
#> 3  CCL11    ACKR2             13.26531    T_cell           15.08889     B_cell
#> 4  CCL11    ACKR2             13.26531    T_cell           13.60000  Dendritic
#> 5  CCL11    ACKR2             13.26531    T_cell           13.25926 Macrophage
#> 6  CCL11    ACKR2             12.30769   NK_cell           14.34694     T_cell
#>   comm_type
#> 1  cytokine
#> 2  cytokine
#> 3  cytokine
#> 4  cytokine
#> 5  cytokine
#> 6  cytokine

Step 3: Visualize with Circos Plot

# Define cell type colors
cell_col <- c(
  "T_cell" = "#E41A1C",
  "B_cell" = "#377EB8", 
  "Macrophage" = "#4DAF4A",
  "Dendritic" = "#984EA3",
  "NK_cell" = "#FF7F00"
)

# Create circos plot
if (nrow(lr_pairs) > 0) {
  # Take top pairs for cleaner visualization
  plot_data <- lr_pairs[1:min(20, nrow(lr_pairs)), ]
  
  LRPlot(
    data = plot_data,
    datatype = "mean count",
    cell_col = cell_col,
    transparency = 0.5,
    link.arr.type = "triangle"
  )
}

Circos plot showing ligand-receptor interactions between cell types

Step 4: Visualize with Network Plot

if (nrow(lr_pairs) > 0) {
  g <- NetView(
    data = lr_pairs,
    col = cell_col,
    vertex.size = 30,
    edge.max.width = 8,
    edge.curved = 0.2,
    arrow.width = 1.5,
    margin = 0.2
  )
}

Network visualization of cell-cell communication

Workflow 2: Multi-Category Analysis

You can analyze different communication types separately:

# Communication categories in database
comm_types <- c("cytokine", "growth factor", "checkpoint", "other")

# Analyze each category
results_list <- list()
for (comm in comm_types) {
  lr <- FindLR(highly_expr, datatype = "mean count", comm_type = comm)
  if (nrow(lr) > 0) {
    results_list[[comm]] <- lr
    cat(comm, ":", nrow(lr), "pairs\n")
  }
}
#> cytokine : 243 pairs

Workflow 3: Using the Ligand-Receptor Database

iTALK includes a curated database of ligand-receptor pairs:

# Access the built-in database
data(database)

cat("Database contains", nrow(database), "ligand-receptor pairs\n\n")
#> Database contains 2649 ligand-receptor pairs
cat("Categories:", paste(unique(database$Classification), collapse = ", "), "\n\n")
#> Categories: other, checkpoint, cytokine, growth factor

# Preview
head(database[, c("Pair.Name", "Ligand.ApprovedSymbol", "Receptor.ApprovedSymbol", "Classification")])
#>      Pair.Name Ligand.ApprovedSymbol Receptor.ApprovedSymbol Classification
#> 1     A2M_LRP1                   A2M                    LRP1          other
#> 2 AANAT_MTNR1A                 AANAT                  MTNR1A          other
#> 3 AANAT_MTNR1B                 AANAT                  MTNR1B          other
#> 4    ACE_AGTR2                   ACE                   AGTR2          other
#> 5   ACE_BDKRB2                   ACE                  BDKRB2          other
#> 6   ADAM10_AXL                ADAM10                     AXL          other

Summary

This quick start covered:

Data preparation - Expression matrix with cell type annotations
Gene parsing - Identifying highly expressed genes per cell type
L-R detection - Finding ligand-receptor pairs from the database
Visualization - Circos and network plots

For more advanced usage, see:

vignette("algorithm") - Statistical methods and database
vignette("species-conversion") - Cross-species analysis
vignette("visualization") - Comprehensive visualization guide

Session Info

sessionInfo()
#> R version 4.6.0 (2026-04-24)
#> Platform: x86_64-pc-linux-gnu
#> Running under: Ubuntu 24.04.4 LTS
#> 
#> Matrix products: default
#> BLAS:   /usr/lib/x86_64-linux-gnu/openblas-pthread/libblas.so.3 
#> LAPACK: /usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblasp-r0.3.26.so;  LAPACK version 3.12.0
#> 
#> locale:
#>  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C              
#>  [3] LC_TIME=en_US.UTF-8        LC_COLLATE=en_US.UTF-8    
#>  [5] LC_MONETARY=en_US.UTF-8    LC_MESSAGES=en_US.UTF-8   
#>  [7] LC_PAPER=en_US.UTF-8       LC_NAME=C                 
#>  [9] LC_ADDRESS=C               LC_TELEPHONE=C            
#> [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C       
#> 
#> time zone: Etc/UTC
#> tzcode source: system (glibc)
#> 
#> attached base packages:
#> [1] stats     graphics  grDevices utils     datasets  methods   base     
#> 
#> other attached packages:
#> [1] dplyr_1.2.1    igraph_2.3.2   iTALK_0.1.1    rmarkdown_2.31
#> 
#> loaded via a namespace (and not attached):
#>  [1] sass_0.4.10         generics_0.1.4      tidyr_1.3.2        
#>  [4] shape_1.4.6.1       stringi_1.8.7       hms_1.1.4          
#>  [7] digest_0.6.39       magrittr_2.0.5      evaluate_1.0.5     
#> [10] grid_4.6.0          RColorBrewer_1.1-3  circlize_0.4.18    
#> [13] fastmap_1.2.0       jsonlite_2.0.0      progress_1.2.3     
#> [16] GlobalOptions_0.1.4 purrr_1.2.2         scales_1.4.0       
#> [19] pbapply_1.7-4       randomcoloR_1.1.0.1 jquerylib_0.1.4    
#> [22] cli_3.6.6           crayon_1.5.3        rlang_1.2.0        
#> [25] withr_3.0.3         cachem_1.1.0        yaml_2.3.12        
#> [28] otel_0.2.0          Rtsne_0.17          parallel_4.6.0     
#> [31] tools_4.6.0         colorspace_2.1-2    ggplot2_4.0.3      
#> [34] curl_7.1.0          buildtools_1.0.0    vctrs_0.7.3        
#> [37] R6_2.6.1            lifecycle_1.0.5     stringr_1.6.0      
#> [40] V8_8.2.0            cluster_2.1.8.2     pkgconfig_2.0.3    
#> [43] pillar_1.11.1       bslib_0.11.0        gtable_0.3.6       
#> [46] glue_1.8.1          Rcpp_1.1.1-1.1      xfun_0.59          
#> [49] tibble_3.3.1        tidyselect_1.2.1    sys_3.4.3          
#> [52] knitr_1.51          farver_2.1.2        htmltools_0.5.9    
#> [55] maketools_1.3.2     compiler_4.6.0      prettyunits_1.2.0  
#> [58] S7_0.2.2