Title: Detection and Spatial Analysis of Tertiary Lymphoid Structures
Version: 0.1.2
Description: Fast, reproducible detection and quantitative analysis of tertiary lymphoid structures (TLS) in multiplexed tissue imaging. Implements Independent Component Analysis Trace (ICAT) index, local Ripley's K scanning, automated K Nearest Neighbor (KNN)-based TLS detection, and T-cell clusters identification as described in Amiryousefi et al. (2025) <doi:10.1101/2025.09.21.677465>.
Note: TLS, ICAT, KNN are correct technical acronyms.
License: MIT + file LICENSE
Encoding: UTF-8
LazyData: true
RoxygenNote: 7.3.2
Imports: fastICA, spatstat.geom, spatstat.explore, dbscan, RANN, grDevices, graphics, stats, utils
Suggests: testthat (≥ 3.0.0)
Config/testthat/edition: 3
Depends: R (≥ 3.5)
NeedsCompilation: no
Packaged: 2025-12-13 18:00:49 UTC; aliamiryousefi
Author: Ali Amiryousefi ORCID iD [aut, cre], Jeremiah Wala ORCID iD [aut], Peter Sorger ORCID iD [ctb]
Maintainer: Ali Amiryousefi <ali_amiryousefi@hms.harvard.edu>
Repository: CRAN
Date/Publication: 2025-12-18 14:40:03 UTC

tlsR: Detection and Spatial Analysis of Tertiary Lymphoid Structures

Description

Fast, reproducible detection and quantitative analysis of tertiary lymphoid structures (TLS) in multiplexed tissue imaging. Implements Independent Component Analysis Trace (ICAT) index, local Ripley's K scanning, automated K Nearest Neighbor (KNN)-based TLS detection, and T-cell clusters identification as described in Amiryousefi et al. (2025) doi:10.1101/2025.09.21.677465.

Author(s)

Maintainer: Ali Amiryousefi ali_amiryousefi@hms.harvard.edu (ORCID)

Authors:

Other contributors:

Calculate ICAT (Immune Cell Arrangement Trace) Index

Description

Quantifies linear/organized arrangement of cells within a TLS using FastICA.

Arguments

patientID

Character. Name of the sample in ldata.

tlsID

Numeric/integer. TLS identifier.

ldata

Named list of data frames (optional; defaults to global ldata).

Value

Numeric ICAT value.

Examples

data(toy_ldata)
ldata <- detect_TLS("ToySample", k = 30, ldata = toy_ldata)  # First detect TLS
if (max(ldata[["ToySample"]]$tls_id_knn) > 0) {
  icat <- calc_icat("ToySample", tlsID = 1, ldata = ldata)
  icat
}

Detect Tertiary Lymphoid Structures using a KNN-density approach

Description

This function identifies TLS candidates germinated with B cells (BIC) by: 1. Finding regions of high local B-cell density (KNN-based). 2. Requiring a minimum number of neighbouring T cells (T-B cell co-localisation). 3. Applying sensible size and shape filters.

Arguments

LSP

Character. Sample name in the global ldata list.

k

Integer. Number of nearest neighbours to consider (default 30 - works very well on 0.325 um/px imaging).

bcell_density_threshold

Numeric. Minimum average 1/k-distance for B cells to be considered "dense" (default 15 um).

min_B_cells

Integer. Minimum number of B cells in a candidate TLS (default 50).

min_T_cells_nearby

Integer. Minimum T cells within 50 um of the B-cell cluster centre (default 30).

max_distance_T

Numeric. Radius (um) to search for surrounding T cells (default 50).

ldata

Optional. Named list of data frames. If NULL, uses global ldata.

Value

The original data frame with two new columns:

tls_id_knn

0 = non-TLS, positive integer = TLS cluster ID

tls_center_x, tls_center_y

Coordinates of detected TLS centres (only for TLS cells)

Examples

data(toy_ldata)
ldata <- detect_TLS("ToySample", k = 30, ldata = toy_ldata)
table(ldata[["ToySample"]]$tls_id_knn)
plot(ldata[["ToySample"]]$x, ldata[["ToySample"]]$y,
     col = ifelse(ldata[["ToySample"]]$tls_id_knn > 0, "red", "gray"),
     pch = 19, cex = 0.5, main = "Detected TLS in toy data")

Detect Tumor-Infiltrating T-cell Clusters (TIC)

Description

Uses HDBSCAN approximation on T cells outside TLS regions to find TIC.

Arguments

sample

Character. Sample name.

ldata

Optional list.

Value

Modified data frame for the sample (invisibly).

Examples

data(toy_ldata)
ldata <- detect_TLS("ToySample", k = 30, ldata = toy_ldata)  # Need TLS first
ldata <- detect_tic("ToySample", ldata = ldata)
table(ldata[["ToySample"]]$tcell_cluster_hdbscan)

Scan Tissue for Local Immune Cell Clustering (K-integral)

Description

Sliding-window Centerel L-Function (CLF) version of the Ripley's K analysis with whole tissue pseudo-plots.

Arguments

ws

Window size in microns.

sample

Character. Sample name in ldata.

phenotype

One of "T cells", "B cells", or "Both".

plot

Logical. Show diagnostic plot?

creep

Integer. Grid density factor.

ldata

Optional list (defaults to global ldata).

Value

List of Lest objects for significant windows.

Examples

data(toy_ldata)
  # This one may produce plots and take ~10 sec
  models <- scan_clustering(ws = 500, sample = "ToySample",
                            phenotype = "B cells", plot = FALSE, ldata = toy_ldata)
  length(models)

Toy multiplexed imaging data for examples

Description

A small synthetic dataset mimicking multiplexed tissue imaging data. It contains one sample named "ToySample" with columns required by tlsR functions.

Usage

toy_ldata

Format

A named list with one element:

ToySample

A data frame with columns:

  • x: x-coordinate in microns

  • y: y-coordinate in microns

  • coarse_phen_vec: Cell phenotype ("B cells", "T cells", or "Other")

  • row_index: Integer row index (1 to nrow)

  • cflag: Integer flag column (0 for all cells)

Examples

data(toy_ldata)
str(toy_ldata[["ToySample"]])
plot(toy_ldata[["ToySample"]]$x, toy_ldata[["ToySample"]]$y,
     col = as.factor(toy_ldata[["ToySample"]]$coarse_phen_vec),
     pch = 19, cex = 0.5, main = "Toy sample cells")