---
title: "Spatial Elemental Mapping"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Spatial Elemental Mapping}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
resource_files:
  - figures/logo.svg
  - figures/logo-dark.svg
---

<!-- cttir-vignette-logo: start -->
<style>
.cttir-vignette-logo { float: right; width: 120px; max-width: 30%; margin: 0 0 1rem 1.5rem; }
.cttir-vignette-logo img { width: 100%; height: auto; border: 0; background: transparent; box-shadow: none; }
.cttir-vignette-logo .cttir-vignette-logo-light { display: block; }
.cttir-vignette-logo .cttir-vignette-logo-dark { display: none; }
@media (prefers-color-scheme: dark) {
  .cttir-vignette-logo .cttir-vignette-logo-light { display: none; }
  .cttir-vignette-logo .cttir-vignette-logo-dark { display: block; }
}
[data-bs-theme="light"] .cttir-vignette-logo .cttir-vignette-logo-light { display: block; }
[data-bs-theme="light"] .cttir-vignette-logo .cttir-vignette-logo-dark { display: none; }
[data-bs-theme="dark"] .cttir-vignette-logo .cttir-vignette-logo-light { display: none; }
[data-bs-theme="dark"] .cttir-vignette-logo .cttir-vignette-logo-dark { display: block; }
</style>
<div class="cttir-vignette-logo">
  <img class="cttir-vignette-logo-light" src="figures/logo.svg" alt="libscanR logo" width="120" height="139" />
  <img class="cttir-vignette-logo-dark" src="figures/logo-dark.svg" alt="libscanR logo" width="120" height="139" />
</div>
<!-- cttir-vignette-logo: end -->

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

```{r}
library(libscanR)
```

## Raster scan dataset

```{r data}
ds <- ls_example_data("spatial")
ds
```

The simulated tissue section has:

- A left-to-right **Ca** gradient (decreasing)
- A top-to-bottom **Fe** gradient (increasing)
- A **Zn**-enriched hotspot simulating a tumor region

## Build a single elemental map

```{r single, fig.alt="A 20 by 20 fictional raster map of integrated response near 393.37 nm. The viridis legend ranges from low purple to high yellow; values are peak area, not calibrated concentration."}
m_ca <- ls_build_map(ds, "Ca", 393.37)
ls_plot_map(m_ca)
```

## Multi-element panel

```{r panel, fig.alt="Three fictional raster maps labelled Ca, Fe and Zn, each showing integrated response at its specified teaching wavelength and its own colour scale."}
maps <- ls_map_elements(ds, c("Ca", "Fe", "Zn"),
                        c(Ca = 393.37, Fe = 371.99, Zn = 213.86))
ls_plot_map_panel(maps)
```

## Applying a calibration to the map

```{r calib, fig.alt="The fictional Ca-labelled raster map after applying the teaching calibration, with predicted concentration in ppm. This demonstrates model application, not validated tissue concentrations."}
cal_ds <- ls_example_data("calibration")
cal <- ls_calibrate(cal_ds, "Ca", 393.37,
                    concentrations = cal_ds$sample_info$concentration,
                    verbose = FALSE)
m_cal <- ls_build_map(ds, "Ca", 393.37, calibration = cal)
ls_plot_map(m_cal)
```

## Hotspot detection

```{r hotspot}
zn <- ls_build_map(ds, "Zn", 213.86)
hot_idx <- which(zn$values > stats::quantile(zn$values, 0.9))
head(data.frame(x = zn$x[hot_idx],
                y = zn$y[hot_idx],
                zn = round(zn$values[hot_idx], 1)))
```