
<!-- README.md is generated from README.Rmd. Please edit that file -->

# NDPalette

`NDPalette` provides color palettes that approximate the University of
Notre Dame brand colors, together with `ggplot2` color and fill scales.
These colors are well suited to statistical visualization and
psychometric analysis: the white-safe ordering keeps groups legible in
plots of data, and the near-white-to-navy ramps suit continuous
quantities such as correlations and factor loadings. The default palette
leads with six Notre Dame brand colors that read clearly on a white
background and extends through seven former Notre Dame colors,
interpolating when more colors are needed than the brand supplies. This
is an independent project and is not affiliated with or endorsed by the
University.

## Installation

``` r
# install.packages("remotes")
remotes::install_github("yelleKneK/NDPalette")
```

A gallery of the palettes with `ggplot2` examples (one through ten
groups, common chart types, the alternative palettes, the brand tints,
and theming) is in the package vignette. Run `vignette("NDPalette")`, or
read [`vignettes/NDPalette.Rmd`](vignettes/NDPalette.Rmd).

## The Notre Dame palette

The default `"nd"` palette begins with six Notre Dame brand colors, in
white-safe priority order:

``` r
library(NDPalette)

cols <- nd_palette(6)
labs <- c("ND Blue", "Bright Gold", "Green",
          "Bright Blue", "Metallic Gold", "Dark Sky Blue")
txt  <- c("white", "black", "white", "white", "black", "black")

op <- par(mar = c(0, 0, 0, 0))
image(seq_along(cols), 1, as.matrix(seq_along(cols)),
      col = cols, axes = FALSE, xlab = "", ylab = "")
text(seq_along(cols), 1.15, labs, col = txt, cex = 0.9)
text(seq_along(cols), 0.85, cols, col = txt, cex = 0.8)
```

<img src="man/figures/README-swatch-1.png" width="100%" />

``` r
par(op)
```

Beyond six, it continues through the seven former Notre Dame brand
colors, thirteen in all. `show_palette()` previews the whole thing (it
defaults to the full Notre Dame palette):

``` r
show_palette()
```

<img src="man/figures/README-full-1.png" width="100%" />

Each color has a readable name, too. Passing a character vector to the
`labels` argument prints those names on the swatches in place of the hex
values (`nd_colors` is the full table of names, hex values, and roles):

``` r
show_palette(nd_palette(), labels = nd_colors$name[match(nd_palette(), nd_colors$hex)])
```

<img src="man/figures/README-full-named-1.png" width="100%" />

## Usage

In a `ggplot2` plot, add the scale; it maps the grouping levels to the
Notre Dame colors automatically:

``` r
library(ggplot2)

ggplot(iris, aes(Sepal.Length, Petal.Length, colour = Species)) +
  geom_point() +
  scale_colour_nd()

ggplot(mtcars, aes(factor(cyl), fill = factor(cyl))) +
  geom_bar() +
  scale_fill_nd()
```

Outside `ggplot2`, ask `nd_palette()` for the hex vector and use it
anywhere that accepts colors:

``` r
nd_palette(3)
#> [1] "#0c2340" "#d39f10" "#0a843d"
barplot(c(3, 5, 2), col = nd_palette(3))
```

<img src="man/figures/README-barplot-1.png" width="100%" />

Past the first six, the palette continues into the former Notre Dame
colors, interpolating beyond the thirteen anchors:

``` r
nd_palette(8)
#> [1] "#0c2340" "#d39f10" "#0a843d" "#1c4f8f" "#c1cddd" "#ae9142" "#36deb8"
#> [8] "#4c1c2a"
```

A colorblind-friendly ordering of the *actual* Notre Dame colors is
available as `"nd_cvd"`, arranged so the colors stay distinguishable
under simulated deuteranopia, protanopia, and tritanopia. It leads with
the CVD-safe ND Blue and Bright Gold:

``` r
nd_palette(5, palette = "nd_cvd")
#> [1] "#0c2340" "#d39f10" "#36deb8" "#0a843d" "#1c4f8f"
```

The `scale_*_nd()` scales take a `palette` argument, so the
colorblind-friendly palette drops into a plot just like the default,
with `scale_color_nd(palette = "nd_cvd")`.

The fixed anchors are exported as `nd_palettes` for tools (for example
[paletteer](https://emilhvitfeldt.github.io/paletteer/)) and for users
who want the raw values:

``` r
nd_palettes$nd
#>  [1] "#0c2340" "#d39f10" "#0a843d" "#1c4f8f" "#c1cddd" "#ae9142" "#36deb8"
#>  [8] "#4c1c2a" "#342551" "#a8a600" "#456300" "#e3e361" "#1e1a13"
```

## Statistical and psychometric visualization

These colors are meant for plots of data. A two-group fill maps to ND
Blue and Bright Gold, which suits the figures that recur in psychometric
work, such as a chart of standardized factor loadings:

``` r
loadings <- matrix(
  c(.74, .18, .69, .12, .78, .24, .81, .07,
    .22, .71, .15, .79, .09, .66, .25, .80),
  nrow = 2,
  dimnames = list(c("Verbal", "Quantitative"), paste0("Item ", 1:8)))

barplot(loadings, beside = TRUE, col = nd_palette(2), border = NA,
        ylab = "standardized loading", xlab = "item",
        main = "Factor loadings", legend.text = rownames(loadings),
        args.legend = list(bty = "n"))
```

<img src="man/figures/README-loadings-1.png" width="100%" />

The package vignette carries the idea further with `ggplot2`: a
correlation heatmap that ramps from a near-white tint to navy for a
matrix of item intercorrelations, and a set of item characteristic
curves that gives each item one of the well-separated brand colors. Run
`vignette("NDPalette")` for those.

## Finding a color by name

Every color the package knows about is cataloged in `nd_colors`, a data
frame that labels each color with its brand (University, Athletics, or
none) and its role (primary, secondary, former, tint, informal, or
neutral). It now includes every official color on the University
branding page, among them Medium Blue, Dark Gold, and Light Green.
`nd_color()` pulls hex values out of that table by name or by role,
which is handier than a palette name when you want one or two specific
colors:

``` r
nd_color("navy", "green")
#> [1] "#0c2340" "#0a843d"
nd_color(role = "former")
#> [1] "#36deb8" "#4c1c2a" "#342551" "#a8a600" "#456300" "#e3e361" "#1e1a13"
```

The table also carries the Notre Dame Athletics colors for reference.
Athletics is a separate brand system: it shares ND Blue with the
University, pairs it with a warmer Standard Dome Gold and a metallic
gold that has no sanctioned digital value (its hex is `NA`), and uses an
Irish Green a single Pantone step from the University green. The
Athletics colors are reference only and never enter `nd_palette()` or
the scales.

``` r
nd_colors
#>                   name                key     hex      brand      role
#> 1              ND Blue               navy #0c2340 university   primary
#> 2     ND Metallic Gold      metallic_gold #ae9142 university   primary
#> 3          Medium Blue        medium_blue #143865 university secondary
#> 4          Bright Blue        bright_blue #1c4f8f university secondary
#> 5            Dark Gold          dark_gold #8c7535 university secondary
#> 6          Bright Gold        bright_gold #d39f10 university secondary
#> 7                Green              green #0a843d university secondary
#> 8          Light Green        light_green #b3dac5 university secondary
#> 9        Dark Sky Blue      dark_sky_blue #c1cddd university secondary
#> 10          Warm White         warm_white #efe9d9 university      tint
#> 11    Light Warm White   light_warm_white #f8f4ec university      tint
#> 12     Medium Sky Blue    medium_sky_blue #e1e8f2 university      tint
#> 13      Light Sky Blue     light_sky_blue #edf2f9 university      tint
#> 14                Teal               teal #36deb8 university    former
#> 15              Maroon             maroon #4c1c2a university    former
#> 16              Purple             purple #342551 university    former
#> 17         Light Olive        light_olive #a8a600 university    former
#> 18          Dark Olive         dark_olive #456300 university    former
#> 19         Pale Yellow        pale_yellow #e3e361 university    former
#> 20               Black              black #1e1a13 university    former
#> 21         Faint White        faint_white #fdfcfa       none  informal
#> 22          Soft White         soft_white #faf7f1       none  informal
#> 23        Faint Yellow       faint_yellow #fefdf3       none  informal
#> 24 Soft Yellow (light)  soft_yellow_light #fdf9e6       none  informal
#> 25         Soft Yellow        soft_yellow #faf3d7       none  informal
#> 26  Soft Yellow (warm)   soft_yellow_warm #f6edc6       none  informal
#> 27     Notre Dame Blue     athletics_blue #0c2340  athletics   primary
#> 28  Standard Dome Gold          dome_gold #c99700  athletics   primary
#> 29  Metallic Dome Gold metallic_dome_gold    <NA>  athletics   primary
#> 30         Irish Green        irish_green #00843d  athletics secondary
#> 31               White    athletics_white #ffffff  athletics   neutral
#>    white_safe   pms
#> 1        TRUE   289
#> 2        TRUE 10127
#> 3        TRUE  2154
#> 4        TRUE  2945
#> 5        TRUE  4495
#> 6        TRUE   117
#> 7        TRUE   347
#> 8        TRUE  2246
#> 9        TRUE  5376
#> 10      FALSE  4545
#> 11      FALSE  9064
#> 12      FALSE   650
#> 13      FALSE   656
#> 14       TRUE  <NA>
#> 15       TRUE  <NA>
#> 16       TRUE  <NA>
#> 17       TRUE  <NA>
#> 18       TRUE  <NA>
#> 19       TRUE  <NA>
#> 20       TRUE  <NA>
#> 21      FALSE  <NA>
#> 22      FALSE  <NA>
#> 23      FALSE  <NA>
#> 24      FALSE  <NA>
#> 25      FALSE  <NA>
#> 26      FALSE  <NA>
#> 27       TRUE   289
#> 28       TRUE   117
#> 29         NA  8642
#> 30       TRUE   348
#> 31      FALSE  <NA>
#>                                                                                            description
#> 1                                                              Primary. The signature Notre Dame Blue.
#> 2                                                               Primary. The metallic Notre Dame Gold.
#> 3                                              Secondary. A deep blue between ND Blue and Bright Blue.
#> 4                                                                        Secondary. A bright mid blue.
#> 5                                                                     Secondary. A muted, darker gold.
#> 6                                    Secondary. A saturated gold; the anchor gold of the data palette.
#> 7                                                                     Secondary. The Notre Dame green.
#> 8                                                                       Secondary. A pale, soft green.
#> 9                                      Secondary. The one sky blue dark enough to use as a data color.
#> 10                                                 Near-white tint. A warm cream for page backgrounds.
#> 11                                                              Near-white tint. A lighter warm cream.
#> 12                                                                       Near-white tint. A pale blue.
#> 13                                                            Near-white tint. The lightest pale blue.
#> 14                                                   Former secondary Notre Dame color. A bright teal.
#> 15                               Former secondary Notre Dame color. A deep maroon (dark brownish red).
#> 16 Former tertiary Notre Dame color; the only former color of the tertiary tier. A dark violet purple.
#> 17                                            Former secondary Notre Dame color. A yellow-green olive.
#> 18                                              Former secondary Notre Dame color. A dark olive green.
#> 19                                        Former secondary Notre Dame color. A soft chartreuse yellow.
#> 20                                               Former secondary Notre Dame color. A warm near-black.
#> 21                      Informal background (not an ND brand color). A warm white just off pure white.
#> 22                                     Informal background (not an ND brand color). A soft warm white.
#> 23                     Informal background (not an ND brand color). A soft yellow just off pure white.
#> 24                             Informal background (not an ND brand color). A light, soft warm yellow.
#> 25                                         Informal background (not an ND brand color). A soft yellow.
#> 26                                  Informal background (not an ND brand color). A warmer soft yellow.
#> 27                                             Athletics. Notre Dame Blue, shared with the University.
#> 28                                                           Athletics. The warmer Standard Dome Gold.
#> 29                          Athletics. Metallic Dome Gold; a Pantone metallic ink with no digital hex.
#> 30                                 Athletics. Irish Green, one Pantone step from the University green.
#> 31                                                                                   Athletics. White.
```

## Former Notre Dame colors

The seven colors past the first six are former Notre Dame brand colors:
historical brand colors no longer in the current brand guide. They are
approximate, legacy colors, included only to extend the palette past
six, and are not part of the current Notre Dame brand. A color such as
purple appearing in this set should not be read as a current, primary,
or signature Notre Dame color. They round out the default `"nd"` palette
beyond six, and they are also available on their own:

``` r
nd_palette(palette = "former")
#> [1] "#36deb8" "#4c1c2a" "#342551" "#a8a600" "#456300" "#e3e361" "#1e1a13"
show_palette(nd_palette(palette = "former"))
```

<img src="man/figures/README-former-1.png" width="100%" />

## Brand tints

Four Notre Dame brand tints are too light to read as data on a white
background, so `nd_palette()` never returns them. They remain useful
brand colors away from the data layer, exported as `nd_tints` for panel
backgrounds, fills behind text, and the light end of a sequential ramp
running from a pale tint to a dark brand color:

``` r
nd_tints
#>       warm_white light_warm_white  medium_sky_blue   light_sky_blue 
#>        "#efe9d9"        "#f8f4ec"        "#e1e8f2"        "#edf2f9"

ramp <- grDevices::colorRampPalette(c(nd_tints[["light_sky_blue"]],
                                      nd_palette(1)))(7)
show_palette(ramp)
```

<img src="man/figures/README-tints-1.png" width="100%" />

Six informal warm backgrounds are also provided as `nd_informal_tints`,
from a very light warm white to a warmer soft yellow (the two `faint_*`
tints sit just off pure white for the lightest touch). These are **not**
Notre Dame brand colors; they are alternatives to a white background for
HTML reports, vignettes, and Shiny apps (`vignette("NDPalette-shiny")`
uses them):

``` r
nd_informal_tints
#>       faint_white        soft_white      faint_yellow soft_yellow_light 
#>         "#fdfcfa"         "#faf7f1"         "#fefdf3"         "#fdf9e6" 
#>       soft_yellow  soft_yellow_warm 
#>         "#faf3d7"         "#f6edc6"
```

## Color choices

The default palette deliberately excludes four Notre Dame brand colors
that read poorly as data colors on a white background: Warm White, Light
Warm White, Medium Sky Blue, and Light Sky Blue. Among the sky blues
only Dark Sky Blue is admissible as a data color. Those four tints are
not discarded; they are exported as `nd_tints` for backgrounds and ramps
(see above). The thirteen data colors are the six leading brand colors
and the seven former Notre Dame brand colors; past thirteen the set is
interpolated. The colors approximate those in the [University branding
guidelines](https://onmessage.nd.edu/university-branding/colors/).

## Related color tools

`NDPalette` is a small, single-purpose palette package. For general
color-palette machinery, see Emil Hvitfeldt’s
[palettes](https://cran.r-project.org/package=palettes) package and the
companion
[r-color-palettes](https://github.com/EmilHvitfeldt/r-color-palettes)
gallery, which catalogs many palette packages for R. `NDPalette` is
distinct in focusing on one institution’s colors, curated and ordered
for statistical visualization and psychometric analysis rather than as a
general framework.

## Citation

To cite `NDPalette` in a publication, use

``` r
citation("NDPalette")
```

which returns the entry in `inst/CITATION`. Please cite a specific
version so the reference is unambiguous. Once a release is archived on
Zenodo the citation carries a DOI; cite the DOI whenever one is
available, since a single consistent, DOI-backed citation is what lets
indexes such as Google Scholar group citations to the package into one
record.
