Help for package outlierspinner

Title:

Geometric Multivariate Outlier Detection via Random Directional Probing

Version:

0.1.0

Description:

Provides tools for multivariate outlier detection based on geometric properties of multivariate data using random directional projections. Observation-level outlier scores are computed by jointly probing radial magnitude and angular alignment through repeated projections onto random directions, with optional robust centering and covariance adjustment. In addition to global outlier scoring, the method produces dimension-level contribution measures to support interpretation of detected anomalies. Visualization utilities are included to summarize directional contributions for extreme observations.

License:

MIT + file LICENSE

Encoding:

UTF-8

RoxygenNote:

7.3.3

Imports:

ggplot2, MASS, tidyr

Suggests:

testthat (≥ 3.0.0)

Config/testthat/edition:

NeedsCompilation:

Packaged:

2026-01-06 08:09:39 UTC; peconom

Author:

Polychronis Economou [aut, cre]

Maintainer:

Polychronis Economou <peconom@upatras.gr>

Repository:

CRAN

Date/Publication:

2026-01-08 18:50:07 UTC

Spinner-Based Geometric Multivariate Outlier Detection

Description

Computes multivariate outlier scores using random directional probing of standardized observations. The method captures both radial extremeness and angular alignment by projecting observations onto multiple random directions ("spins") and aggregating projection-based deviations.

Usage

spinner_outlier_score(
  X,
  n_spins = 1000,
  robust = TRUE,
  cov_adjust = TRUE,
  contrib_quantile = 0.9,
  plot_top_n = NULL,
  make_contrib_plot = FALSE,
  seed = NULL
)

Arguments

X

A numeric matrix or data frame of dimension n \times p, with rows as observations and columns as variables.

n_spins

Integer specifying the number of random directions for directional probing. Larger values increase stability at higher computational cost.

robust

Logical; if TRUE, robust centering (median) and scaling (MAD) are applied. If FALSE, classical centering and scaling are used.

cov_adjust

Logical; if TRUE, observations are whitened using a robust or classical covariance estimate (depending on robust) to remove linear dependence.

contrib_quantile

Numeric in (0,1) specifying the quantile threshold to select influential spinner directions for computing dimension-level contributions (default 0.90).

plot_top_n

Optional integer; if provided and make_contrib_plot = TRUE, a stacked bar plot of dimension contributions is produced for the top plot_top_n observations.

make_contrib_plot

Logical; if TRUE, generates a stacked bar plot summarizing dimension-level contributions for the most outlying observations.

seed

Optional integer seed for reproducibility of random spinner directions.

Details

In addition to a global outlier score, the function provides dimension-level contribution measures that attribute each observation's outlyingness to the original variables, enabling post hoc interpretability.

Robust centering, scaling, and optional covariance adjustment ensure affine invariance and resistance to marginal contamination.

The Spinner score combines two complementary components:

Radial deviation, measured as squared deviations of projections from their marginal centers.
Angular alignment, capturing whether an observation consistently aligns with specific directions in high-dimensional space.

Dimension-level contributions are computed by backprojecting influential spinner directions to the original coordinate system. Only directions with large projection magnitudes are retained, preserving rotational invariance while enabling interpretability.

The method is motivated by ongoing research. A detailed theoretical treatment and empirical evaluation are provided in a manuscript currently under review.

Value

A list with the following components:

score: Numeric vector of length n with Spinner outlier scores.
score_align: Numeric vector capturing angular alignment per observation.
mean_proj: Mean absolute projection per observation across all spinner directions.
proj_matrix: Matrix of signed projections of observations onto spinner directions.
dim_contrib_raw: Matrix of raw dimension-level contributions per observation.
dim_contrib_norm: Row-normalized contributions, interpretable as relative attribution weights.
top_spins: List of influential spinner directions selected for each observation.
contrib_plot: A ggplot2 object showing contributions for the most extreme observations, or NULL.
n_spins: Number of random directions used.
robust_center: Vector of location estimates used for centering.
cov_adjust: Logical indicating whether covariance adjustment was applied.

References

Economou, P. (2026). Spinner: A Geometric Multivariate Outlier Detection Method Using Random Directional Probing. Manuscript under review.

Examples

set.seed(123)
X <- matrix(rnorm(40), ncol = 4)
res <- spinner_outlier_score(
  X,
  n_spins = 100,
  robust = TRUE,
  cov_adjust = TRUE,
  contrib_quantile = 0.9,
  plot_top_n = 3,
  make_contrib_plot = TRUE
)
head(res$score)
if (!is.null(res$contrib_plot)) print(res$contrib_plot)