---
title: "FiberMargin Benchmarks"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{benchmarks}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  warning = FALSE,
  message = FALSE,
  fig.width = 8,
  fig.height = 3
)
library(fibermargin)
```

## Evaluation contract

`benchmark_spatial_refiners()` evaluates each method on identical inputs and the
same reference data:

- coordinates (`xy`)
- initial labels (`labels`)
- optional specimen ids (`samples`)
- optional boundary/sparse annotations used for stratified scores

It reports elapsed time and a standard metric table generated by
`evaluate_spatial_refinement()`.

### Standard metrics reported

- `accuracy`, `initial_accuracy`, `accuracy_gain`
- `correction_recall` and `damage_rate`
- `worst_recall`, `macro_recall`
- `boundary_accuracy`, `sparse_region_accuracy`
- `ari`

## Dataset catalog

```{r scenarios}
available_spatial_benchmarks()
```

## Load one real scenario

```{r load}
dlpfc <- load_spatial_benchmark("dlpfc", scenario = 1L)
names(dlpfc)
```

## Example benchmark run

```{r one-run, eval=FALSE}
bench <- simulate_spatial_domains(
  n = 5000L,
  pattern = "jagged_stripes",
  noise = 0.20,
  samples = 2L,
  seed = 7L
)

benchmark_spatial_refiners(
  data = bench,
  methods = list(
    FiberMargin = refine_spatial_labels,
    InitialOnly = function(xy, labels, ...) labels
  ),
  include_initial = TRUE,
  seed = 1L
)
```

## Reproducibility scripts

```bash
Rscript benchmarks/run_publication_benchmarks.R
Rscript benchmarks/run_fibermargin_publication_benchmarks.R
Rscript benchmarks/run_general_mask_repair_benchmarks.R
```

Each script stores results and artifacts with fixed random seeds so runs are
reproducible.