FiberMargin Reference Manual

Functions

Simulation

simulate_spatial_domains(...)
simulate_complex_spatial_domains(...)
simulate_spatial_clusters(...)
simulate_gradient_regions(...)
simulate_volumetric_domains(...)

All simulators return a spatial_refinement_benchmark object with xy, labels, truth, samples, and optional boundary/sparse fields.

`refine_spatial_labels()` contract

xy: a finite numeric matrix with exactly two or three columns.
labels: one non-missing categorical assignment per row.
samples: optional integer, character, or factor identifiers. Coordinates and labels never cross sample boundaries, even when coordinate values overlap.
workers: NULL or one positive integer specifying the total CPU budget.

Constant axes are removed separately in each sample. A constant z therefore uses the 2D operator, while a variable z uses the genuine 3D operator. Every sample must retain at least two varying axes.

The return value is an ordinary factor with input levels and identifiers. Its pointwise attributes are candidate, margin_score, required, repair_margin, atlas_dispersion, isolation, and changed. Summary attributes are workers, dimensions_used, labels_changed, changed_fraction, classes_before, classes_after, removed_classes, and sample_sizes. Class summaries are per-sample named lists. Class preservation is not imposed; removed_classes reports observed classes absent after repair.

set.seed(8)
xy <- matrix(runif(1200), ncol = 2)
labels <- factor(ifelse(xy[, 1] < 0.5, "left", "right"))

refined_2d <- refine_spatial_labels(xy, labels, workers = 1L)
refined_flat_3d <- refine_spatial_labels(
  cbind(xy, z = 0), labels, workers = 1L
)
stopifnot(identical(refined_2d, refined_flat_3d))

volume <- simulate_volumetric_domains(
  n = 1200L, shape = "folded_layers", samples = 2L, seed = 9L
)
refined_3d <- refine_spatial_labels(
  volume$xy, volume$labels, volume$samples, workers = 2L
)
attr(refined_3d, "dimensions_used")

## 1 2 
## 3 3

overlap_xy <- rbind(xy, xy)
overlap_labels <- factor(rep(as.character(labels), 2L))
specimen <- rep(c("first", "second"), each = nrow(xy))
refined_joint <- refine_spatial_labels(
  overlap_xy, overlap_labels, specimen, workers = 2L
)
attr(refined_joint, "sample_sizes")

##  first second 
##    600    600

Evaluation

evaluate_spatial_refinement(truth, initial, refined, ...)
Computes recovery, consistency, boundary, sparse-region, and damage/repair diagnostics.
evaluate_mask_cleaning(reference, initial, cleaned, ...)
Computes mean IoU, boundary IoU, and damage/repair decomposition for masks.

Benchmarking

benchmark_spatial_refiners(data, methods, include_initial = TRUE, seed = 1L, ...)
Runs multiple methods on one or more identical benchmark inputs.
spatial_benchmark(xy, labels, truth, samples, ...)
Validates and constructs a benchmark object.
available_spatial_benchmarks()
Lists bundled datasets and licensing information.
load_spatial_benchmark(name, scenario, seed = NULL) Loads a bundled real scenario. For CRC, an optional user-supplied seed makes the corruption generated from the stored recipe reproducible.

Scoring glossary

accuracy: overall corrected agreement.
accuracy_gain: improvement over input labeling.
correction_recall: fraction of wrong labels that become correct.
damage_rate: fraction of correct labels that become wrong.
worst_recall: minimum class recall.
boundary_accuracy: conditional accuracy on boundary-labeled spots.
sparse_region_accuracy: conditional accuracy on a sparse reference region.
ari: adjusted Rand index.
n: number of observations.