---
title: "Reproducing the Application Note figures"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Reproducing the Application Note figures}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  eval = FALSE  # every chunk needs a local database or a browser
)
```

This vignette shows how to reproduce the visualizations published in the
dbVisuals Application Note. For a general introduction, see
`vignette("getting-started", package = "dbVisuals")`.

## Install

```{r, eval = FALSE}
install.packages("dbVisuals")

# development version
install.packages("dbVisuals",
                 repos = c("https://dbverse-org.r-universe.dev",
                           "https://cloud.r-project.org"))

# rendering packages and database dependencies, from CRAN
install.packages(c("DBI", "duckdb", "rDeckgl", "rMosaic"))
```

The figures and benchmarks in the Application Note were made with `dbVisuals`
0.1.0 (commit `7f6eb52` of <https://github.com/dbverse-org/dbVisuals>).

## Reproducing the published figures

The published in-situ panels need a GiottoDB DuckDB database holding cell
polygons, cell centroids and transcript coordinates. The Application Note uses
the 10x Genomics Atera In Situ Gene Expression, FFPE Human Breast Cancer preview
dataset.

The two scripts below are in the repository under `r-package/examples/`. They
are not installed with the package, and the large public input datasets are not
bundled. Use the same release for the installed package and the cloned scripts.

| Script | Renders |
| --- | --- |
| `03_dimred_concat.R` | UMAP / PCA dimension pairs linked to a `leiden_clus` bar |
| `06_in_situ_zoom_overlay_transcripts_interactive.R` | **the published panel**, with interactive ROI selection |

Run them from a clone of the repository, with `r-package/` as the working
directory:

```bash
git clone --branch v0.1.0 https://github.com/dbverse-org/dbVisuals.git
```

`03_dimred_concat.R` needs the `Giotto` and `GiottoData` packages (see the
Giotto Suite installation instructions) and downloads the mini Visium object. It
needs no local database:

```r
setwd("path/to/dbVisuals/r-package")
source("examples/03_dimred_concat.R")
```

For the in-situ script, point the environment at your data and run it from an
interactive R session:

```r
setwd("path/to/dbVisuals/r-package")
Sys.setenv(DBLENS_DEMO_DB = "/path/to/WTA_Preview_FFPE_Breast_Cancer_xenium.duckdb")
Sys.setenv(DBLENS_TRANSCRIPT_FILE = "/path/to/transcripts.parquet")
source("examples/06_in_situ_zoom_overlay_transcripts_interactive.R")
```

Neither variable is needed if the files sit in the working directory under their
default names. Optional overrides: `DBLENS_TRANSCRIPT_TABLE` reads transcripts
from a table inside the database instead of a file, and `DBLENS_ROI_CELL_ID`
centres the region of interest on a specific cell.

Script 06 starts a Shiny app: dragging the `select` control re-queries only the
transcripts inside the chosen region, and `detail` picks a nested sub-region.
Under `Rscript` it prints the widget instead of launching Shiny. The published
panel is a full-window capture of the resulting three-view layout. Missing
expression or cell-type annotations are shown as unavailable, not simulated.

## See also

`vignette("visualization-examples", package = "dbVisuals")` builds the same
linked-view patterns from self-contained data, with no database required.