---
title: "Get started with biopalette"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Get started with biopalette}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

biopalette provides image-inspired color palettes for biomedical
visualization. Each palette has a documented source and one of three types:

- **qualitative** palettes distinguish unordered groups;
- **sequential** palettes represent values progressing from low to high;
- **diverging** palettes show variation around a meaningful center.

This guide follows the usual workflow: find a palette, inspect it, retrieve the
colors, and apply it directly to a plot. See
`vignette("install", package = "biopalette")` if the package is not yet
installed.

## Find a palette

Load biopalette and inspect the bundled collection:

```{r list-palettes}
library(biopalette)

list_palettes()[c("name", "type", "n_color")]
```

Filter by type when the visual role is already known:

```{r filter-palettes}
list_palettes(type = "sequential")[c("name", "n_color")]
```

`palette_info()` returns the complete metadata for one palette without drawing
it:

```{r palette-info}
palette_info("mitonuclear_blue")
```

For visual browsing, call `palette_gallery()` in an interactive R session. It
builds one gallery page per palette type and reports each page as it is ready.

```{r gallery, eval = FALSE}
palette_gallery()
```

## Retrieve colors

`get_palette()` returns a character vector of HEX colors. Palette names are
unique across the bundled collection, so `type` is normally unnecessary:

```{r get-palette}
get_palette("three_body")
get_palette("mitonuclear_blue")
```

The meaning of `n` follows the palette type. For a qualitative palette, it
selects the first `n` category colors and cannot exceed the palette size:

```{r qualitative-n}
get_palette("babel", n = 5)
```

For sequential and diverging palettes, the stored colors are stops along a
ramp. Asking for `n` colors samples the whole ramp in Lab color space rather
than taking colors from only one end:

```{r continuous-n}
get_palette("mitonuclear_blue", n = 3)
get_palette("walter_white", n = 7)
```

Use `reverse = TRUE` when the direction of a palette should be flipped:

```{r reverse}
get_palette("mitonuclear_blue", n = 3, reverse = TRUE)
```

The returned vector can be used anywhere that accepts R color values. For
ggplot2, the scale functions provide a shorter and safer route.

## Use a discrete scale

Map a qualitative palette to unordered groups with
`scale_color_biopalette()`:

```{r discrete-color, fig.height = 4}
library(ggplot2)

ggplot(iris, aes(Sepal.Length, Sepal.Width, color = Species)) +
  geom_point(size = 2.5) +
  scale_color_biopalette("three_body") +
  theme_minimal()
```

Use a `color` scale when the mapped aesthetic is `color` (or `colour`), and a
`fill` scale when the mapped aesthetic is `fill`. This distinction belongs to
the geometry, not to the palette itself:

```{r discrete-fill, fig.height = 4}
ggplot(iris, aes(Species, Sepal.Length, fill = Species)) +
  geom_boxplot() +
  scale_fill_biopalette("three_body", guide = "none") +
  theme_minimal()
```

Discrete scales request exactly as many colors as the trained data has levels.
Qualitative palettes use their first `n` colors; sequential and diverging
palettes sample `n` colors across the complete ramp. A qualitative palette
raises an informative error when it does not contain enough colors.

## Use a continuous gradient

Continuous data requires a sequential or diverging palette and one of the
gradient functions. A sequential fill gradient is appropriate for density:

```{r sequential-gradient, fig.height = 4}
ggplot(faithfuld, aes(waiting, eruptions, fill = density)) +
  geom_raster() +
  scale_fill_biopalette_gradient("mitonuclear_blue") +
  theme_minimal()
```

For values interpreted relative to a reference point, use a diverging palette
and set `midpoint`. Here zero means no deviation from the mean:

```{r diverging-gradient, fig.height = 4}
plot_data <- transform(
  mtcars,
  cylinders = factor(cyl),
  gears = factor(gear),
  mpg_difference = mpg - mean(mpg)
)

ggplot(plot_data, aes(cylinders, gears, fill = mpg_difference)) +
  geom_tile(color = "white", linewidth = 0.5) +
  scale_fill_biopalette_gradient("walter_white", midpoint = 0) +
  labs(x = "Cylinders", y = "Gears", fill = "MPG difference") +
  theme_minimal()
```

Qualitative palettes cannot define continuous gradients because interpolating
unordered category colors has no stable meaning.

## Preview one palette

`preview_palette()` draws directly to the active graphics device. Its five
styles are `"bar"`, `"pie"`, `"point"`, `"rect"`, and `"circle"`:

```{r preview, fig.height = 2.5}
preview_palette("walter_white", plot_type = "rect")
```

The same `n` and `reverse` rules used by `get_palette()` also apply to previews:

```{r preview-options, fig.height = 2.5}
preview_palette(
  "mitonuclear_orange",
  n = 4,
  reverse = TRUE,
  plot_type = "circle"
)
```

## Convert color formats

`hex2rgb()` and `rgb2hex()` convert between HEX and RGB or RGBA values. Alpha
is preserved when present:

```{r color-conversion}
rgba <- hex2rgb(c("#1688A7", "#FF450080"))
rgba
rgb2hex(rgba)
```

## Next steps

- Read `vignette("palette", package = "biopalette")` for the sources, intended
  uses, and limitations of every bundled palette.
- Open `?scale_color_biopalette` for discrete scale options.
- Open `?scale_color_biopalette_gradient` for continuous gradients,
  transformations, custom stop positions, and diverging midpoints.
- Read `vignette("tessera", package = "biopalette")` to explore palettes,
  example datasets, Palette Lab, and complete R figure recipes.
- Report reproducible problems in [GitHub Issues](https://github.com/evanbio/biopalette/issues).