Gradient-Restricted Local Slope

Computes the local slope of z with respect to y along the gradient direction of y at each vertex. This asymmetric measure captures "for each unit increase in y along its steepest direction, how much does z change?"

The function automatically dispatches to specialized implementations based on input types: vector-vector, vector-matrix, or matrix-matrix.

Usage

lslope(
  adj.list,
  weight.list,
  y,
  z,
  type = c("slope", "normalized", "sign"),
  y.diff.type = c("logratio", "difference"),
  z.diff.type = c("logratio", "difference"),
  epsilon = 0,
  sigmoid.alpha = 0,
  sigmoid.type = c("tanh", "arctan", "algebraic"),
  ascending = TRUE,
  instrumented = FALSE,
  mc.cores = 1L
)

lslope.vector.vector(
  adj.list,
  weight.list,
  y,
  z,
  type,
  y.diff.type,
  z.diff.type,
  epsilon,
  sigmoid.alpha,
  sigmoid.type,
  ascending,
  instrumented
)

Arguments

adj.list

List of integer vectors containing 1-based vertex indices. Element i contains the neighbors of vertex i.

weight.list

List of numeric vectors containing edge weights. Must have same structure as adj.list.

y

Numeric vector or matrix of directing function values. For vectors, length must equal the number of vertices. For matrices, number of rows must equal the number of vertices.

z

Numeric vector or matrix of response function values. Dimension requirements match those for y.

type

Character scalar specifying the type of measure:

"slope": Raw ratio Delta z / Delta y (unbounded). Default.
"normalized": Sigmoid-normalized ratio (bounded to \([-1,1]\)).
"sign": Sign of Delta z along gradient direction \({-1, 0, +1}\).

y.diff.type

Character scalar specifying edge difference type for y:

"logratio": Log-ratios (compositional data). Default.
"difference": Standard differences (continuous data).

z.diff.type

Character scalar specifying edge difference type for z.

epsilon

Numeric scalar for pseudocount in log-ratios. If 0 (default), computed adaptively.

sigmoid.alpha

Numeric scalar for sigmoid normalization scale. If 0 (default), auto-calibrated from median absolute slope.

sigmoid.type

Character scalar specifying sigmoid function type:

"tanh": Hyperbolic tangent (default)
"arctan": Scaled arctangent (heavier tails)
"algebraic": Algebraic sigmoid (simpler derivative)

ascending

Logical. If TRUE (default), use ascending gradient (gradient toward higher y values). If FALSE, use descending gradient.

instrumented

Logical. If TRUE, return full diagnostic output. If FALSE (default), return only coefficients. Only applies to vector-vector case.

mc.cores

Integer scalar specifying the number of cores for parallel computation in the matrix-matrix case. Default is 1 (sequential). Note that parallel::mclapply is not available on Windows.

Value

The return type depends on the input types:

Vector-vector (y and z both vectors): If instrumented = FALSE, a numeric vector of local slope coefficients. If instrumented = TRUE, a list with class "lslope_gradient_result" containing diagnostic information (gradient neighbors, delta values, extremum flags).

Vector-matrix (y vector, z matrix): An object of class "lslope_vector_matrix_result". A numeric matrix of dimension (n.vertices x n.columns) where column j contains local slope coefficients for z[,j] with respect to y.

Matrix-matrix (y and z both matrices): An object of class "lslope_matrix_matrix_result". A 3D numeric array of dimension (n.vertices x ncol(y) x ncol(z)). Element [v, i, j] contains the local slope of z[,j] with respect to y[,i] at vertex v.

Details

The gradient edge at vertex v is the edge from v to the neighbor u that maximizes the difference Delta y = y(u) - y(v) (for ascending=TRUE) or minimizes it (for ascending=FALSE). At local extrema of y, no gradient edge exists and the coefficient is set to 0.

Functions

lslope.vector.vector(): Vector-vector implementation (internal)

Asymmetry

Unlike symmetric local correlation lcor(y,z), the local slope is asymmetric: lslope(z; y) is not equal to lslope(y; z) in general. The slope measures the response of z to changes in y, treating y as the independent (directing) variable.

Dispatch Behavior

Vector-Vector: Computes local slope of a single z on a single y.

Vector-Matrix: Efficiently computes slopes of multiple z columns with respect to a single directing function y. The gradient edges are determined once from y and reused for all z columns.

Matrix-Matrix: Computes slopes for all (y_i, z_j) pairs. Since the measure is asymmetric, all p x q pairs are computed (no symmetry optimization).

Examples

if (FALSE) { # \dontrun{
## Simple example
adj.list <- list(c(2L, 3L), c(1L, 3L), c(1L, 2L))
weight.list <- list(c(1.0, 1.0), c(1.0, 1.0), c(1.0, 1.0))

## Case (a): Vector-vector
y <- c(0.1, 0.5, 0.9)  # sPTB prevalence
z <- c(0.8, 0.4, 0.1)  # Secondary phylotype abundance
result <- lslope(adj.list, weight.list, y, z, type = "normalized")

## Case (b): Vector-matrix (feature screening)
Z <- matrix(runif(300), nrow = 100, ncol = 50)
colnames(Z) <- paste0("ASV", 1:50)
result <- lslope(adj.list, weight.list, y, Z,
                 type = "normalized",
                 z.diff.type = "logratio")

## Case (c): Matrix-matrix (multiple directing functions)
Y <- matrix(runif(200), nrow = 100, ncol = 2)
colnames(Y) <- c("sPTB", "PTB")
result <- lslope(adj.list, weight.list, Y, Z,
                 type = "normalized",
                 mc.cores = 4)
} # }