PCA Anomaly Scores via Isolation Forests with Visualization

This function detects anomalies in single-cell data by projecting the data onto a PCA space and using an isolation forest algorithm to identify anomalies.

This S3 plot method generates faceted scatter plots for specified principal component (PC) combinations within an anomaly detection object. It visualizes the relationship between specified PCs, highlights anomalies detected by the Isolation Forest algorithm, and provides a background gradient representing anomaly scores.

detectAnomaly(
  reference_data,
  query_data = NULL,
  ref_cell_type_col,
  query_cell_type_col = NULL,
  cell_types = NULL,
  pc_subset = 1:5,
  n_tree = 500,
  anomaly_threshold = 0.6,
  assay_name = "logcounts",
  ...
)

# S3 method for class 'detectAnomalyObject'
plot(
  x,
  cell_type = NULL,
  pc_subset = NULL,
  data_type = c("query", "reference"),
  n_tree = 500,
  ...
)

Arguments

reference_data: A SingleCellExperiment object containing numeric expression matrix for the reference cells.
query_data: An optional SingleCellExperiment object containing numeric expression matrix for the query cells. If NULL, then the isolation forest anomaly scores are computed for the reference data. Default is NULL.
ref_cell_type_col: A character string specifying the column name in the reference dataset containing cell type annotations.
query_cell_type_col: A character string specifying the column name in the query dataset containing cell type annotations.
cell_types: A character vector specifying the cell types to include in the plot. If NULL, all cell types are included.
pc_subset: A numeric vector specifying the indices of the PCs to be included in the plots. If NULL, all PCs in reference_mat_subset will be included.
n_tree: An integer specifying the number of trees for the isolation forest. Default is 500
anomaly_threshold: A numeric value specifying the threshold for identifying anomalies, Default is 0.6.
assay_name: Name of the assay on which to perform computations. Default is "logcounts".
...: Additional arguments passed to the `isolation.forest` function.
x: A list object containing the anomaly detection results from the detectAnomaly function. Each element of the list should correspond to a cell type and contain reference_mat_subset, query_mat_subset, var_explained, and anomaly.
cell_type: A character string specifying the cell type for which the plots should be generated. This should be a name present in x. If NULL, the "Combined" cell type will be plotted. Default is NULL.
data_type: A character string specifying whether to plot the "query" data or the "reference" data. Default is "query".

Value

A list containing the following components for each cell type and the combined data:

anomaly_scores: Anomaly scores for each cell in the query data.
anomaly: Logical vector indicating whether each cell is classified as an anomaly.
reference_mat_subset: PCA projections of the reference data.
query_mat_subset: PCA projections of the query data (if provided).
var_explained: Proportion of variance explained by the retained principal components.

The S3 plot method returns a ggplot object representing the PCA plots with anomalies highlighted.

Details

This function projects the query data onto the PCA space of the reference data. An isolation forest is then built on the reference data to identify anomalies in the query data based on their PCA projections. If no query dataset is provided by the user, the anomaly scores are computed on the reference data itself. Anomaly scores for the data with all combined cell types are also provided as part of the output.

The function extracts the specified PCs from the given anomaly detection object and generates scatter plots for each pair of PCs. It uses ggplot2 to create a faceted plot where each facet represents a pair of PCs. The plot includes the following elements:

1. A background gradient: This represents the anomaly scores across the PC space. The gradient ranges from green (low anomaly scores) through yellow to red (high anomaly scores). 2. Data points: Plotted over the gradient, with different shapes for normal and anomalous points. Anomalous points are represented as 'X', while normal points are solid circles.

The background gradient provides a visual representation of the anomaly landscape, allowing for intuitive interpretation of regions with high or low anomaly scores.

References

Liu, F. T., Ting, K. M., & Zhou, Z. H. (2008). Isolation forest. In 2008 Eighth IEEE International Conference on Data Mining (pp. 413-422). IEEE.
isotree: Isolation-Based Outlier Detection

Author

Anthony Christidis, anthony-alexander_christidis@hms.harvard.edu

Examples

# Load data
data("reference_data")
data("query_data")

# Store PCA anomaly data
anomaly_output <- detectAnomaly(reference_data = reference_data,
                                query_data = query_data,
                                ref_cell_type_col = "expert_annotation",
                                query_cell_type_col = "SingleR_annotation",
                                pc_subset = 1:5,
                                n_tree = 500,
                                anomaly_threshold = 0.6)

# Plot the output for a cell type
plot(anomaly_output,
     cell_type = "CD4",
     pc_subset = 1:3,
     data_type = "query")