---
title: "All color palettes"
author: "Hansjoerg Neth"
date: "`r Sys.Date()`"
output: 
  rmarkdown::html_vignette
vignette: > 
  %\VignetteIndexEntry{All color palettes}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

options(max.print = "75")

knitr::opts_chunk$set(collapse = FALSE, 
                      comment = "#>", 
                      prompt = FALSE,
                      tidy = FALSE,
                      echo = TRUE, 
                      message = FALSE,
                      warning = FALSE,
                      # Default figure options:
                      dpi = 100, 
                      fig.align = 'center',
                      fig.height = 5.0,
                      fig.width  = 7.5,
                      out.width = "600px")

# URLs: ------ 

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

url_github_doc_rel <- "https://hneth.github.io/unicol/"      # release version  
url_github_doc_dev <- "https://hneth.github.io/unicol/dev/"  # dev version

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

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

<!-- unikn logo and link: -->
<!-- <a href = "`r url_unikn`"> -->
<!-- <img src = "../man/figures/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 = "../man/figures/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_cran`">
<img src = "../man/figures/logo.png" alt = "unicol::" align = "right" width = "150px" style = "width: 150px; float: right; border:0;"/>
</a>


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

We install and 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 -->

## Overview 

```{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**.  

<!-- ### Overview -->

<!-- **Table\ 1** provides an overview of **all `r n_pals`\ color palettes** from **`r n_inst`\ institutions**.  -->

**Table\ 1** provides an overview of all included institutions and color palettes. 
Clicking on the name of a color palette opens the corresponding page of the [online reference](`r paste0(url_github_doc_dev, "/reference/")`). 

```{r unicol-pals-table-static, echo = FALSE, eval = FALSE}
# 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)
```

```{r source-util-funs, echo = FALSE}
# 1. Utility functions: ------

# Current path properties:
wd    <- getwd()
nc_wd <- nchar(wd)
# nchar("vignettes") # = 9 
fin_chars <- substr(wd, nc_wd - 8, nc_wd)  # final 9 characters

# Source utility file:
if (fin_chars == "vignettes"){
  source("../R/5_util.R")  # from pkg/vignettes dir
} else {
  source("./R/5_util.R")   # from pkg wd
}
```

```{r unicol-data-table, echo = FALSE}
# 2. Process unicol_data: ------

all_pals <- unicol_data$pal

# Look up URLs and create links for all_pals:
pal_urls <- lookup(all_pals, unicol_data, v_1 = "pal", v_2 = "url")
pal_inst_links <- link_inst(all_pals)
pal_doc_links  <- link_github_doc(all_pals)
pal_lengths    <- sapply(X = unicol_data$pal, FUN = n_col)

# mean(pal_lengths)  # mean number of colors 


# Determine countries from URLs:
pal_countries <- url_2_country(pal_urls)

# Create summary df:
pal_df <- data.frame(inst = pal_inst_links, 
                     # url = pal_urls, 
                     country = pal_countries, 
                     pal = pal_doc_links,
                     n_col = pal_lengths)

row.names(pal_df) <- 1:nrow(pal_df)
col_names <- c("University / Institution", 
               # "URL", 
               "Country", 
               "Color palette", 
               "N of colors")

# 3. Print df as table: ------

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

knitr::kable(pal_df, caption = df_caption, col.names = col_names, row.names = TRUE)
```



### Illustration 

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

set.seed(26) # 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: 273 on 2024-05-07 
n_inst  # number of institutions:   116 on 2024-05-07
# Colors (in current set):
length(unlist(pal_list))          # number of colors: 243
length(unique(unlist(pal_list)))  # number of unique colors: 220
```

<!-- 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 a random sample of `r n` color palettes: 

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

<!-- Use and show figure generated from README file: -->

![**Figure 1:** Examples of **unicol** color palettes.](../man/figures/README-unicol-pals-example-1-figure-1.png)



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

## Your color palettes

<!-- unicol pkg logo and link: -->
<!-- <a href = "`r url_unicol_cran`"> -->
<!-- <img src = "./man/figures/logo.png" alt = "unicol::" align = "right" width = "150px" style = "width: 150px; 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/inst_colors.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 = "../man/figures/todo.png" alt = "unicol::todo" align = "right" width = "150px" style = "width: 150px; 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_cran`">
<img src = "../man/figures/logo.png" alt = "unicol::" align = "right" width = "150px" style = "width: 150px; 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. | [All 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. -->
