---
title: "Colour palettes inspired by butterflies"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Colour palettes inspired by butterflies}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

`lepidochroma` is an R package including palettes that were created
inspired by the colours of butterfly species. They are intended to
provide elegant chromatic choices for any graphs or maps generated in
your analyses, while also keeping accessibility in mind, as most of
the palettes are colour blind friendly.

This vignette will briefly explain how to preview, access, and use the
colour palettes available in the package.

```{r setup}
library(lepidochroma)
```

## Listing and previewing available colour palettes

To access a palette, simply call the `lepidochroma()` function with the name
of the palette you want to use. Palettes in this package are named
after the genus of the butterfly they are inspired by.  For
example:

```{r palette_example}
lepidochroma("parthenos")
```

To get a list of all the available palettes, use the `lepidochroma_palettes()` function, 
which returns a data frame with information about each palette.

```{r lepidochroma_palettes}
lepidochroma_palettes()
```

The `lepidochroma_display()` function shows previews of the palettes.
If called without arguments, it will display all available palettes in the package.

```{r display_all, fig.dim = c(6, 6)}
lepidochroma_display()
```

It is possible to show only continuous, discrete, or colourblind-friendly
palettes by specifying the appropriate arguments to this function
(refer to its documentation for more details). For example, here are the continuous color palettes that are colorblind-friendly:

```{r display_continuous, fig.dim = c(6, 5)}
lepidochroma_display(type = "continuous", colourblind_only = TRUE)
```

Finally, a palette can be displayed by passing its name to
`lepidochroma_display()`.  The number of colours displayed can
also be controlled.  For continuous palettes, you can preview an interpolation of
their colours like this:

```{r display_one, fig.dim = c(6, 3)}
lepidochroma_display("morpho", n = 100)
```

## Plotting examples

### Discrete colour palette

Using discrete colour palettes is simple. Below, we use the Inachis palette to color the iris dataset. The plot shows the relationship between Petal.Length and Petal.Width, with different colors for different species.

```{r discrete_plot, fig.dim = c(6, 6)}
inachis <- lepidochroma("inachis")

plot_colours <- inachis[c(3, 4, 5)]
plot(
  Petal.Length ~ Petal.Width, data = iris,
  col = plot_colours[iris$Species], pch = 20,
  main = "Inachis"
)
```

### Continuous colour palette

Here, we use the Battus continuous colour palette to create a heatmap using the volcano dataset. The plot illustrates the color gradient applied to a continuous surface.

```{r continuous_plot, fig.dim = c(6, 6)}
image(volcano, col = lepidochroma("battus", n = 100), axes = FALSE)
title("Battus")
```

## Conclusions

With `lepidochroma`, you can easily enhance your visualizations using colors inspired by butterfly species. Whether you're using discrete or continuous palettes, the package ensures that your plots are not only visually appealing but also accessible to all users, including those with color blindness.

For more details, check the documentation of each function using `?lepidochroma`, `?lepidochroma_palettes`, and `?lepidochroma_display`.