Fisher Exact Scanning for Dependency

Implements Fisher exact scanning (FES), a multiscale test of dependence for continuous or discrete bivariate data. The method scans nested binary partitions using Fisher's exact tests and combines evidence across windows and resolutions with Sidak, Bonferroni, and meta-analysis corrections. The methodology is described in Ma and Mao (2019) .

FES

FES implements Fisher exact scanning, a multiscale method for testing and identifying dependence between two variables. It applies Fisher's exact test to nested 2-by-2 windows and combines evidence across windows and resolutions without resampling.

Version 1.0 is the first official release of FES for CRAN. It provides the reference R implementation of the method together with tools for testing, visualizing, and interpreting multiscale dependence.

Installation

Install the official release from CRAN:

install.packages("FES")

The development version can be installed from GitHub with pak:

# install.packages("pak")
pak::pak("mastatlab/fes")

Example

library(FES)

set.seed(12345)
x <- runif(200)
y <- x + rnorm(200, sd = 0.15)

fes(x, y, K1 = 4, K2 = 4)

The result contains four global p-values: Sidak, Bonferroni, a Stouffer-type meta-analysis p-value, and the unadjusted minimum window p-value. The Sidak value is the primary FES result.

Use ?fes for partition controls, mid-p values, and optional window plots. Set plot.sidak = TRUE to display multiplicity-adjusted p-values. To write those plots to disk, supply an explicit directory with output.dir; otherwise FES uses the active graphics device.

Learning the nature of a dependency

Set return.details = TRUE to retain the windows that created the evidence, not just the global test result:

set.seed(12345)
x <- runif(500)
y <- (x - 0.5)^2 + rnorm(500, sd = 0.025)

fit <- fes(x, y, K1 = 4, K2 = 4, M = 4, return.details = TRUE)
fit$p.value
head(fit$significant.windows)
plot(fit)

Each window reports its transformed bounds, four cell counts, raw and adjusted p-values, and a local log-odds ratio. Positive log-odds indicate concordant movement within the window; negative values indicate discordant movement. This allows FES to locate a dependency, reveal changes in direction, and distinguish localized, curved, circular, and alternating structures.

The structure plot shows one coherent partition stratum at a time so its windows do not overlap. It automatically chooses the stratum with the richest significant structure. Select one explicitly with plot(fit, stratum = c(k1, k2)); use stratum = "all" only when a cross-resolution overlay is desired.

Visual demos

List the installed demos with:

demo(package = "FES")

Then run any demo individually:

demo("quick_start", package = "FES")
demo("nonlinear_gallery", package = "FES")
demo("local_dependence", package = "FES")
demo("dependency_maps", package = "FES")
demo("direction_changes", package = "FES")
demo("resolution_path", package = "FES")

The quick-start demo expands the example above into a visual walkthrough. The remaining demos compare nonlinear relationships, locate a signal confined to one region, map positive and negative local association, inspect direction changes programmatically, and show how evidence develops as the scan becomes finer. Scan heatmaps use a common color scale, overlay the transformed observations, and outline globally significant windows in red.

Reference

Ma, L. and Mao, J. (2019). Fisher exact scanning for dependency. Journal of the American Statistical Association, 114(525), 245--258. DOI

License

GPL (>= 3)