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.

The S3 plot method generates faceted scatter plots for specified principal component (PC) combinations within an anomaly detection object. It allows visualization of the relationship between specified PCs and highlights anomalies detected by the Isolation Forest algorithm.

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_treshold = 0.6,
  assay_name = "logcounts",
  ...
)

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

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_treshold: 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.
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 S3 plot method 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. Anomalies are highlighted in red, while normal points are shown in black.

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_treshold = 0.6)

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