refine_spatial_labels()
refine_spatial_labels(xy, labels, samples = NULL, workers = NULL)
xy must be a finite numeric matrix with two or three
columns. labels must contain one non-missing categorical
value per row. samples is optional and defines independent
coordinate systems. Integer, character, and factor specimen identifiers
are accepted. workers = NULL uses a conservative automatic
CPU budget; set a positive integer for an explicit total budget.
Effective dimensionality is determined separately within every
specimen. Zero-range axes are removed before refinement. At least two
varying axes must remain, so constant z reduces a
three-column specimen to 2D while variable z remains part
of a genuine 3D analysis.
The output is a factor with the input levels and row names. Seven
pointwise audit attributes are attached:
diagnostic_names <- c(
"candidate", "margin_score", "required", "repair_margin",
"atlas_dispersion", "isolation", "changed"
)
diagnostics <- data.frame(
observed = head(as.character(gradient$labels), 8L),
refined = head(as.character(refined_gradient), 8L),
candidate = head(as.character(attr(refined_gradient, "candidate")), 8L),
margin_score = head(attr(refined_gradient, "margin_score"), 8L),
required = head(attr(refined_gradient, "required"), 8L),
repair_margin = head(attr(refined_gradient, "repair_margin"), 8L),
changed = head(attr(refined_gradient, "changed"), 8L)
)
diagnostics
#> observed refined candidate margin_score required repair_margin changed
#> spot1 C B B 0.7351437 0.06036058 0.6747831 TRUE
#> spot2 B B B 0.0000000 0.00000000 0.0000000 FALSE
#> spot3 A A A 0.0000000 0.00000000 0.0000000 FALSE
#> spot4 B B B 0.0000000 0.00000000 0.0000000 FALSE
#> spot5 A A A 0.0000000 0.00000000 0.0000000 FALSE
#> spot6 A A A 0.0000000 0.00000000 0.0000000 FALSE
#> spot7 B B B 0.0000000 0.00000000 0.0000000 FALSE
#> spot8 B B B 0.0000000 0.00000000 0.0000000 FALSE
setdiff(diagnostic_names, names(attributes(refined_gradient)))
#> character(0)
candidate is the locally preferred class.
margin_score is its support contrast, required
is the local admission barrier, and repair_margin is
margin_score - required. These are deterministic scores,
not calibrated probabilities. atlas_dispersion describes
disagreement across path charts, isolation protects locally
isolated observations, and changed identifies accepted
edits.
Eight summary attributes provide a specimen-level audit:
summary_names <- c(
"workers", "dimensions_used", "labels_changed", "changed_fraction",
"classes_before", "classes_after", "removed_classes", "sample_sizes"
)
lapply(summary_names, function(name) attr(refined_gradient, name))
#> [[1]]
#> [1] 1
#>
#> [[2]]
#> 1 2
#> 2 2
#>
#> [[3]]
#> 1 2
#> 61 59
#>
#> [[4]]
#> 1 2
#> 0.10166667 0.09833333
#>
#> [[5]]
#> [[5]]$`1`
#> [1] "A" "B" "C"
#>
#> [[5]]$`2`
#> [1] "A" "B" "C"
#>
#>
#> [[6]]
#> [[6]]$`1`
#> [1] "A" "B" "C"
#>
#> [[6]]$`2`
#> [1] "A" "B" "C"
#>
#>
#> [[7]]
#> [[7]]$`1`
#> character(0)
#>
#> [[7]]$`2`
#> character(0)
#>
#>
#> [[8]]
#> 1 2
#> 600 600
dimensions_used, labels_changed,
changed_fraction, and sample_sizes are named
vectors. The three class summaries are named lists. An unused factor
level is not counted as a class present before refinement. FiberMargin
does not impose class preservation; if an observed class disappears, it
is listed in removed_classes.
The output contract can be checked directly:
identical(
as.logical(attr(refined_gradient, "changed")),
as.character(refined_gradient) != as.character(gradient$labels)
)
#> [1] TRUE
attr(refined_gradient, "workers")
#> [1] 1
Binary
specialization
With exactly two observed classes, the function uses the fixed local
ballot instead of the multiclass path enclosure.
binary_data <- simulate_spatial_clusters(
n = 700L,
dimensions = 2L,
k = 2L,
samples = 1L,
noise = 0.12,
seed = 21L
)
binary_refined <- refine_spatial_labels(
binary_data$xy, binary_data$labels,
samples = binary_data$samples, workers = 1L
)
c(
input_accuracy = mean(binary_data$labels == binary_data$truth),
refined_accuracy = mean(binary_refined == binary_data$truth),
changed_fraction = mean(binary_refined != binary_data$labels)
)
#> input_accuracy refined_accuracy changed_fraction
#> 0.88 1.00 0.12
For this route, isolation is one and
atlas_dispersion is zero because no multiclass path atlas
is used.
Effective 2D and
genuine 3D coordinates
A constant third axis is removed within the specimen, producing the
same labels and every same pointwise diagnostic as the 2D call.
flat_2d <- refine_spatial_labels(
gradient$xy, gradient$labels, gradient$samples, workers = 1L
)
flat_3d <- refine_spatial_labels(
cbind(gradient$xy, z = 0), gradient$labels,
gradient$samples, workers = 1L
)
identical(flat_2d, flat_3d)
#> [1] TRUE
attr(flat_3d, "dimensions_used")
#> 1 2
#> 2 2
For variable z, all three coordinates participate in
chart construction and distance calculations.
volume_example <- simulate_volumetric_domains(
n = 1800L,
shape = "folded_layers",
samples = 2L,
noise = 0.18,
seed = 23L
)
volume_refined <- refine_spatial_labels(
volume_example$xy, volume_example$labels,
volume_example$samples, workers = 2L
)
attr(volume_refined, "dimensions_used")
#> 1 2
#> 3 3
Multiple
specimens
Specimen identifiers prevent evidence from crossing tissue or section
boundaries. Numeric coordinates may overlap completely because each
specimen has its own coordinate system. The combined result is
equivalent to refining each specimen separately and is restored to the
original row order.
source_rows <- which(gradient$samples == levels(gradient$samples)[1L])
overlapping_xy <- rbind(
gradient$xy[source_rows, , drop = FALSE],
gradient$xy[source_rows, , drop = FALSE]
)
overlapping_labels <- factor(
rep(as.character(gradient$labels[source_rows]), 2L),
levels = levels(gradient$labels)
)
overlapping_samples <- rep(
c("section_1", "section_2"), each = length(source_rows)
)
joint <- refine_spatial_labels(
overlapping_xy, overlapping_labels,
samples = overlapping_samples, workers = 2L
)
separate <- unsplit(
lapply(split(seq_len(nrow(overlapping_xy)), overlapping_samples), function(rows) {
refine_spatial_labels(
overlapping_xy[rows, , drop = FALSE],
overlapping_labels[rows],
workers = 1L
)
}),
overlapping_samples
)
identical(as.character(joint), as.character(separate))
#> [1] TRUE
Deterministic CPU
use
workers is one total native budget, not workers per
specimen. Specimens reuse the budget and native stages do not create
nested pools. The implementation uses standard C++ threads on macOS,
Linux, and Windows. Changing workers changes execution
only, not labels or diagnostics.
one_worker <- refine_spatial_labels(
gradient$xy, gradient$labels, gradient$samples, workers = 1L
)
four_workers <- refine_spatial_labels(
gradient$xy, gradient$labels, gradient$samples, workers = 4L
)
attr(one_worker, "workers") <- NULL
attr(four_workers, "workers") <- NULL
identical(one_worker, four_workers)
