---
title: "Color palettes"
author: "Hansjoerg Neth"
date: "`r Sys.Date()`"
output: 
  rmarkdown::html_vignette: 
    fig_caption: yes
vignette: > 
  %\VignetteIndexEntry{Color palettes}
  %\VignetteEncoding{UTF-8}
  %\VignetteEngine{knitr::rmarkdown}
editor_options: 
  chunk_output_type: console
---

```{r setup, include = FALSE}
org_opt <- options()  # store original user options

options(max.print = "75")

knitr::opts_chunk$set(echo = TRUE,
                      cache = FALSE,
                      prompt = FALSE,
                      tidy = FALSE,
                      collapse = TRUE, 
                      comment = "#>",
                      message = FALSE,
                      warning = FALSE,
                      # Default figure options:
                      # fig.width = 6, 
                      # fig.asp = .80 # .618, # golden ratio
                      fig.align = "center",
                      out.width = "60%"
)

# URLs: ------ 

# unikn:
url_unikn <- "https://www.uni-konstanz.de/"

url_unikn_cran   <- "https://CRAN.R-project.org/package=unikn"
url_unikn_github <- "https://github.com/hneth/unikn"

# unicol: 
url_unicol_cran   <- "" # "https://CRAN.R-project.org/package=unicol"
url_unicol_github <- "https://github.com/hneth/unicol"
```

<!-- unikn logo and link: -->
<!-- <a href = "`r url_unikn`"> -->
<!-- <img src = "../inst/pix/logo_unikn.png" alt = "unikn::" align = "right" width = "300px" style = "width: 300px; float: right; border:0;"/> -->
<!-- </a> -->

<!-- unikn pkg logo and link: -->
<!-- <a href = "`r url_unikn_cran`"> -->
<!-- <img src = "../inst/pix/logo_unikn_pkg.png" alt = "unikn::" align = "right" width = "140px" style = "width: 140px; float: right; border:0;"/> -->
<!-- </a> -->

<!-- unicol pkg logo and link: -->
<a href = "`r url_unicol_github`">
<img src = "../inst/pix/logo.png" alt = "unicol::" align = "right" width = "165px" style = "width: 165px; float: right; border:0;"/>
</a>

This vignettes provides an overview of the **color palettes** provided by the **unicol** package. 
(See the vignette on [Using color palettes](using_pals.html) for how to use the **unicol** color palettes.) 

We install or load the **unicol** package to get started: 

```{r load-unicol-pkg, message = FALSE, warning = FALSE}
# install.packages('unicol')  # install unicol from CRAN client
library('unicol')             # load the package
```


## The color palettes of the **unicol** package

```{r unicol-stats, echo = FALSE}
n_pals <- length(unique(unicol_data$pal))
n_inst <- length(unique(unicol_data$inst))
```

The **unicol** package currently provides **`r n_pals`\ color palettes** from **`r n_inst`\ institutions**. 


### Illustration 

```{r unicol-pals-example, echo = FALSE, eval = TRUE}
# Parameters:
N <- length(unicol_data$pal)
n <- 50 # N

set.seed(102) # 77 102 123  # reproducible randomness

# A: Get sample_n of my_pals from all unicol_data$pal:
sample_n <- sort(sample(x = 1:N, size = n, replace = FALSE))
my_pals <- unicol_data$pal[sample_n]

# B: Get sample_n of primary_pals:
is_pal_1 <- grepl(pattern = "_1", unicol_data$pal)
# sum(is_pal_1)
primary_pals <- unicol_data$pal[is_pal_1]

N <- length(primary_pals)
sample_n <- sort(sample(x = 1:N, size = n, replace = FALSE))
my_pals <- primary_pals[sample_n]

# Initialize data structures:
pal_list  <- vector(mode = "list", length = n)
pal_names <- vector(mode = "character", length = n)
col_count <- 0

# Loop: Iterate through n palettes:
for (i in 1:n){
  
  cur_name  <- my_pals[i]
  cur_pal   <- get(cur_name)
  cur_count <- length(cur_pal)
    
  pal_list[[i]] <- cur_pal
  pal_names[i]  <- cur_name
  col_count     <- col_count + cur_count
    
} # for i loop end.

# Check:
# pal_list
# pal_names

# Captions:
tab_caption <- paste0("A sample of ", n, " unicol palettes (containing ", col_count, " colors).")
fig_caption <- paste0("Figure 1: A sample of ", n, " unicol palettes (containing ", col_count, " colors).")
my_main     <- paste0("Illustrating ", n, " unicol palettes (with ", col_count, " colors)")
```

```{r unicol-pals-example-stats, echo = FALSE, eval = FALSE}
# Stats (for n <- N):
n_pals  # number of color palettes: 202 on 2023-04-08. 
n_inst  # number of institutions: 86 on 2023-08-03.
# Colors:
length(unlist(pal_list))          # number of colors: 1327 on 2023-04-08. 
length(unique(unlist(pal_list)))  # number of unique colors: 1130 on 2023-04-08. 
```


<!-- Show as table: -->

```{r unicol-pals-table-sample, echo = FALSE, eval = FALSE}
knitr::kable(unicol_data[sample_n, ], caption = tab_caption)
```


<!-- Show as figure: -->

**Figure\ 1** illustrates `r n` random color palettes: 

```{r unicol-pals-figure-sample, echo = FALSE, eval = TRUE, fig.width = 8, out.width = "90%", fig.asp = 1.5, fig.cap = fig_caption}
# Figure: Illustrate color palettes:
unikn::seecol(pal = pal_list,
              pal_names = pal_names,         
              main = my_main)
```


### Overview

**Table\ 1** provides an overview of **all `r n_pals`\ color palettes** from from **`r n_inst`\ institutions**: 

```{r unicol-pals-table-all, echo = FALSE, eval = TRUE}
# Data:
all_pals_df <- unicol_data
names(all_pals_df) <- c("Institution", "(aka.)", "URL", "Palette name")

tab_caption <- paste0("Overview of ", n_pals, " unicol palettes (from ", n_inst, " institutions).")

# Print table:
knitr::kable(all_pals_df, caption = tab_caption, row.names = TRUE)
```


<!-- Collecting contributed color palettes (in unicol): -->

## Your color palettes

<!-- unicol pkg logo and link: -->
<!-- <a href = "`r url_unicol_github`"> -->
<!-- <img src = "./inst/pix/logo.png" alt = "unicol::" align = "right" width = "165px" style = "width: 165px; float: right; border:0;"/> -->
<!-- </a>  -->

The current range of color palettes included in **unicol** is selective and incomplete. 
We are always happy to include new color palettes and institutions from all over the world. 

If you are missing a color palette, you can easily create it. 
For instructions how this can be done, please see the documentation of the `newpal()` function (of the **[unikn](`r url_unikn_cran`)** package). 
The vignette on [Institutional colors](https://hneth.github.io/unikn/articles/color_inst.html) provides a corresponding example. 

**Call for contributions: Collecting color palettes**

- Are you using the **unikn** color functions to create **your own color palettes**? 

<!-- ToDo: -->
<a href = "https://github.com/hneth/unicol/issues/30">
<img src = "../inst/pix/todo.png" alt = "unicol::todo" align = "right" width = "165px" style = "width: 165px; float: right; border:0;"/>
</a>

If you do create a new color palette, **please let us know** (on this [GitHub issue](https://github.com/hneth/unicol/issues/30)) 
so that we can include it in future versions of the **unicol** package. 
To enable us to verify and provide credit to your contributions, please send us the following information:  
   
1. your code (e.g., the `newpal()` command creating your color palette),   
2. your reference or source information (e.g., some URL with color definitions),   
3. your name and some contact information (e.g., an Email address).  
  
We're looking forward to **your inputs and contributions** (at this [GitHub issue](https://github.com/hneth/unicol/issues/30))! 

<!-- +++ here now +++  -->


## Vignettes

<!-- unicol pkg logo and link: -->
<a href = "`r url_unicol_github`">
<img src = "../inst/pix/logo.png" alt = "unicol::" align = "right" width = "165px" style = "width: 165px; float: right; border:0;"/>
</a>

The following vignettes provide an overview of and examples for using the **unicol** color palettes: 

<!-- Table of vignettes: -->

| Nr.  | Vignette | Content    |        
| ---: |:---------|:-----------|
| 1. | [Color palettes](color_pals.html) | The color palettes of the **unicol** R package |
| 2. | [Using color palettes](using_pals.html) | Recipes for using the **unicol** color palettes |


```{r restore-org-options, include = FALSE}
options(org_opt)  # restore original user options
```

<!-- eof. -->
