---
title: "From palette to plot with Tessera"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{From palette to plot with Tessera}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

Choosing colors is only the beginning of a figure. A useful palette must match
the data, remain clear in the intended graphical marks, and fit into code that
another person can reproduce.

[Tessera](https://folio.evanzhou.org/tessera) brings those steps together. It
offers palettes to choose from, datasets to work with, and complete figure
recipes to take into R. [Palette Lab](https://folio.evanzhou.org/apps/palette-lab)
adds a quick visual way to switch palettes across familiar plot structures.

This article follows the path a reader can take from discovering a palette to
using it in a finished R figure.

```{r load}
library(biopalette)
library(ggplot2)
```

## Discover a palette

A Tessera palette page starts with the material needed to make a choice:

- the palette name used in R;
- its qualitative, sequential, or diverging type;
- the color swatches and HEX values;
- the image from which the colors were drawn;
- the source context and reference labels;
- practical notes about suitable figures and known limitations.

Explore the [Tessera palette collection](https://folio.evanzhou.org/tessera),
or begin with a few contrasting examples:

- [`three_body`](https://folio.evanzhou.org/tessera/palettes/three_body) — three
  qualitative colors for distinct groups;
- [`mitonuclear_blue`](https://folio.evanzhou.org/tessera/palettes/mitonuclear_blue)
  — a cool sequential ramp;
- [`walter_white`](https://folio.evanzhou.org/tessera/palettes/walter_white) — a
  diverging palette with a pale center;
- [`babel`](https://folio.evanzhou.org/tessera/palettes/babel) — a large
  qualitative palette for many groups.

The displayed name is the handoff to biopalette:

```{r palette-name}
get_palette("mitonuclear_blue", n = 5)
```

The complete English source records are also available in the
[`palettes/`](https://github.com/evanbio/biopalette/tree/main/palettes) directory
of the biopalette repository.

## Compare it in Palette Lab

A row of swatches does not reveal how colors behave as small points, thin
lines, neighboring tiles, or large filled regions. Palette Lab provides a fast
way to look beyond the swatch.

Choose a palette and view it across a consistent set of displays, including
grouped points, lines, bars, distributions, heatmaps, maps, survival curves,
embeddings, volcano plots, and Manhattan plots. The data and graphical
structure remain fixed while the colors change, making visual differences
easy to inspect.

Open a palette directly in the lab:

- [`three_body` in Palette Lab](https://folio.evanzhou.org/apps/palette-lab?palette=three_body)
- [`mitonuclear_blue` in Palette Lab](https://folio.evanzhou.org/apps/palette-lab?palette=mitonuclear_blue)
- [`walter_white` in Palette Lab](https://folio.evanzhou.org/apps/palette-lab?palette=walter_white)
- [`babel` in Palette Lab](https://folio.evanzhou.org/apps/palette-lab?palette=babel)

When a qualitative palette has fewer colors than a display has groups, the
remaining groups stay visible in a neutral color. This makes the palette's
capacity visible without removing observations or recycling category colors.

Palette Lab is a visual overview. When a plot is relevant to your work, follow
it into the corresponding Tessera recipe for the R implementation and the
reasoning behind it.

## Learn from an R recipe

Tessera recipes are complete, working figure examples. Each one is organized
around the question the figure answers and the data shape it requires. A recipe
typically provides:

- the expected input variables;
- the dataset used in the example;
- suitable R packages and alternative methods;
- the selected biopalette palette and why it fits;
- complete R code;
- rendered outputs;
- common mistakes and interpretation notes;
- the R and package versions used to produce the figures.

Browse recipes by the figure you need:

- [Grouped scatter](https://folio.evanzhou.org/tessera/figures/grouped_scatter)
- [Correlation heatmap](https://folio.evanzhou.org/tessera/figures/correlation_heatmap)
- [Choropleth map](https://folio.evanzhou.org/tessera/figures/choropleth_map)
- [Survival curve](https://folio.evanzhou.org/tessera/figures/survival_curve)
- [Expression heatmap](https://folio.evanzhou.org/tessera/figures/expression_heatmap)
- [Manhattan plot](https://folio.evanzhou.org/tessera/figures/manhattan)

The emphasis is practical: see the finished figure, understand the choices,
and take the R implementation into your own analysis.

## Work with the same data

Tessera data pages make the recipe examples inspectable and reusable. Depending
on the dataset, a page includes:

- a downloadable CSV;
- its origin and intended purpose;
- dimensions, variable types, missingness, and a row preview;
- notes for important variables;
- the script used to generate or prepare the data.

Examples range from familiar R datasets to biomedical, economic, weather, and
reference data:

- [`iris`](https://folio.evanzhou.org/tessera/data/iris) for grouped points and
  distributions;
- [`mtcars`](https://folio.evanzhou.org/tessera/data/mtcars) for correlation
  and comparison examples;
- [`lung_survival`](https://folio.evanzhou.org/tessera/data/lung_survival) for
  Kaplan–Meier curves;
- [`economy_countries`](https://folio.evanzhou.org/tessera/data/economy_countries)
  for choropleth maps;
- [`pbmc5k_donor4_embeddings`](https://folio.evanzhou.org/tessera/data/pbmc5k_donor4_embeddings)
  for UMAP and t-SNE displays.

Because the data page and recipe are linked, a reader can move from the figure
to the exact example data instead of reconstructing an undocumented simulation.

## Follow one complete path

Suppose you need a sequential palette for a choropleth map.

### 1. Read the palette

Open [`mitonuclear_blue`](https://folio.evanzhou.org/tessera/palettes/mitonuclear_blue)
to inspect its source image, six-color sequence, direction, and notes about the
lightest classes.

### 2. Look at the graphical behavior

Open [`mitonuclear_blue` in Palette Lab](https://folio.evanzhou.org/apps/palette-lab?palette=mitonuclear_blue)
and inspect the map, heatmap, and other continuous displays.

### 3. Open the R recipe

The [choropleth map recipe](https://folio.evanzhou.org/tessera/figures/choropleth_map)
explains the input data, geographic join, missing-value treatment, continuous
and binned versions, and the choice of a sequential palette.

### 4. Inspect or download the data

The [`economy_countries`](https://folio.evanzhou.org/tessera/data/economy_countries)
page documents the example variables and provides the CSV used by the recipe.

### 5. Use the palette in R

The palette name carries directly into biopalette:

```{r sequential-handoff, eval = FALSE}
ggplot(map_data) +
  geom_sf(aes(fill = value), color = "white", linewidth = 0.2) +
  scale_fill_biopalette_gradient(
    "mitonuclear_blue",
    na.value = "grey85"
  )
```

The same path works for a diverging quantity. Read
[`walter_white`](https://folio.evanzhou.org/tessera/palettes/walter_white), view
it in Palette Lab, open a heatmap recipe, and place the scientific reference at
the center in R:

```{r diverging-handoff, eval = FALSE}
scale_fill_biopalette_gradient(
  "walter_white",
  midpoint = 0
)
```

## Choose where to begin

- **I need colors:** browse [Tessera palettes](https://folio.evanzhou.org/tessera).
- **I want a quick visual comparison:** open [Palette Lab](https://folio.evanzhou.org/apps/palette-lab).
- **I need to make a particular figure in R:** browse the
  [Tessera figure recipes](https://folio.evanzhou.org/tessera).
- **I need example data:** browse the
  [Tessera datasets](https://folio.evanzhou.org/tessera).
- **I already know the palette name:** use `get_palette()` or a biopalette
  scale directly.

Tessera helps move from looking at colors to understanding a figure. Palette
Lab makes comparison immediate, recipes provide the reproducible R work, and
biopalette brings the selected colors into your own data.