Color Palette Naming Convention

Overview

This document defines the official naming convention for color palettes in the evanverse package. Following these standards ensures:

Self-documenting names - Instantly understand palette type and purpose
Consistency - Predictable patterns across all palettes
Easy discovery - Find the right palette quickly
Scalability - Clear structure for future additions

Core Principle: type_name_source structure with lowercase and underscores.

Naming Structure

Format

All palette names follow this structure:

[type]_[name]_[source]
  │      │       │
  │      │       └─ Optional: Source identifier
  │      └───────── Required: Descriptive name
  └──────────────── Required: Type prefix

Components

1. Type Prefix (Required)

Use 3-letter abbreviations to indicate palette type:

Prefix	Type	Use Case	Example Scenario
`seq_`	Sequential	Continuous values, one direction	Heatmaps, gene expression levels
`div_`	Diverging	Values with meaningful midpoint	Fold change, up/down regulation
`qual_`	Qualitative	Categorical data, no inherent order	Cell types, sample groups

Examples:

seq_blues      # Sequential palette
div_redblue    # Diverging palette
qual_vivid     # Qualitative palette

Why required?

Enables automatic type inference in get_palette()
Makes filtering with list_palettes() intuitive
Eliminates ambiguity about palette purpose

2. Name (Required)

Describes the palette’s visual characteristics or intended use:

Naming strategies:

# By color characteristics
qual_vivid        # Bright, saturated colors
seq_muted         # Soft, low-saturation colors
div_warm          # Warm color tones

# By color description
div_redblue       # Red to blue gradient
seq_sunset        # Sunset-inspired colors
qual_earthy       # Earth tone palette

# By application domain
qual_pbmc         # PBMC (peripheral blood) data
seq_heatmap       # Optimized for heatmaps

# By journal/standard
qual_nejm         # New England Journal of Medicine style
qual_lancet       # The Lancet journal style

Guidelines:

Short: 1-2 words maximum
Intuitive: Reflects actual colors or application
Unique: No duplicates within the same type

3. Source Identifier (Optional)

Only use for adapted palettes from other packages or standards:

Suffix	Source	Usage
`_g`	ggsci	Adapted from ggsci package
`_rb`	RColorBrewer	Adapted from RColorBrewer
`_v`	viridis	Adapted from viridis package
`_sc`	single-cell	Single-cell data specific
`_bio`	bioinformatics	Bioinformatics standard

Examples:

qual_nejm_g       # NEJM palette from ggsci
qual_set1_rb      # Set1 from RColorBrewer
seq_viridis_v     # Viridis palette
qual_pbmc_sc      # PBMC-specific palette

Important: Custom palettes should NOT have source suffixes.

The 5 Golden Rules

All lowercase - No capital letters
Underscore separators - Use _, not camelCase or dots
No number suffixes - Color count belongs in metadata
Type prefix required - Must start with seq_, div_, or qual_
Remove redundant words - Simplify descriptions

Examples

✅ Good Names

# Clear and concise
qual_vivid           # Type + descriptive characteristic
div_redblue          # Intuitive color pair
seq_sunset           # Evocative name

# Proper source attribution
qual_nejm_g          # Journal style from ggsci
qual_set1_rb         # RColorBrewer Set1
qual_pbmc_sc         # Single-cell specific

# Domain-specific
seq_heatmap          # Application-focused
qual_cosmic_g        # Theme-based (Cosmic)

❌ Bad Names

vividset             # Missing type prefix
harmonySix           # Mixed case + number suffix
NEJM_Colors          # Capital letters
my.palette           # Dot separator
beautiful-colors     # Dash separator
palette_12_colors    # Number in name
nice_colors          # Too vague
gradient_rd_bu       # Unclear abbreviations

Usage

Getting Palettes

library(evanverse)

# Type is inferred from prefix
get_palette("seq_sunset")    # Automatically knows type = "sequential"
get_palette("div_redblue")   # Automatically knows type = "diverging"
get_palette("qual_vivid")    # Automatically knows type = "qualitative"

# Can still specify type explicitly
get_palette("seq_sunset", type = "sequential")

# Wrong type will error with helpful message
get_palette("seq_sunset", type = "diverging")
#> Error: Palette 'seq_sunset' is sequential, not diverging

Listing Palettes

# List all palettes
list_palettes()

# Filter by type
list_palettes(type = "sequential")
list_palettes(type = c("diverging", "qualitative"))

In ggplot2

library(ggplot2)

# Sequential - continuous values
ggplot(data, aes(x, y, fill = expression)) +
  geom_tile() +
  scale_fill_gradientn(colors = get_palette("seq_sunset"))

# Diverging - fold change
ggplot(data, aes(x, y, color = log2FC)) +
  geom_point() +
  scale_color_gradientn(colors = get_palette("div_redblue"))

# Qualitative - categories
ggplot(iris, aes(Sepal.Length, Sepal.Width, color = Species)) +
  geom_point() +
  scale_color_manual(values = get_palette("qual_vivid"))

Adding New Palettes

Workflow

Step 1: Determine Type

# What does your data represent?

# Continuous values (magnitude)?
type <- "sequential"     # Use seq_ prefix

# Values with midpoint (diverging)?
type <- "diverging"      # Use div_ prefix

# Unordered categories?
type <- "qualitative"    # Use qual_ prefix

Step 2: Choose Name

# For custom palette
name <- "qual_ocean"              # type + descriptive name

# For adapted palette
name <- "qual_nature_g"           # type + name + source
name <- "seq_thermal_v"           # viridis-based

Step 3: Create

create_palette(
  name = "qual_ocean",
  type = "qualitative",
  colors = c("#006BA4", "#FF7F0E", "#2CA02C", "#D62728", "#9467BD"),
  color_dir = system.file("extdata", "palettes", package = "evanverse")
)

Step 4: Validate

Checklist:

# ✓ Has type prefix? (seq_/div_/qual_)
# ✓ All lowercase?
# ✓ Uses underscores?
# ✓ No number suffixes?
# ✓ Source suffix only if adapted?
# ✓ Unique within its type?

Step 5: Compile

# Recompile palettes.rds
compile_palettes(
  palettes_dir = system.file("extdata", "palettes", package = "evanverse"),
  output_rds = system.file("extdata", "palettes.rds", package = "evanverse")
)

# Test
get_palette("qual_ocean")
preview_palette("qual_ocean", type = "qualitative")

Best Practices

Naming Strategies

By Visual Characteristics

# Color intensity
qual_vivid          # High saturation
seq_muted           # Low saturation
qual_pastel         # Pastel colors

# Color temperature
div_warm            # Warm tones
seq_cool            # Cool tones

# Color composition
qual_earthy         # Earth tones
seq_blues           # Blue gradient
div_redblue         # Red-blue diverging

By Application

# Data type
qual_pbmc           # PBMC cell types
seq_heatmap         # Heat map optimized
div_volcano         # Volcano plot

# Domain
qual_clinical       # Clinical data
seq_genomic         # Genomic data

By Source

# Journals
qual_nejm_g         # NEJM from ggsci
qual_lancet_g       # Lancet from ggsci
qual_jama_g         # JAMA from ggsci

# Standard palettes
qual_set1_rb        # RColorBrewer Set1
seq_viridis_v       # Viridis

Do’s

# ✅ Use clear, descriptive names
seq_sunset          # Immediately understandable
qual_vivid          # Describes the style
div_fireice         # Evocative metaphor

# ✅ Keep it short
qual_ocean          # Concise
seq_warm            # Direct

# ✅ Credit sources
qual_nejm_g         # Acknowledges ggsci
qual_set1_rb        # Acknowledges RColorBrewer

# ✅ Be consistent in series
qual_earth_light    # Clear series
qual_earth_medium   # pattern
qual_earth_dark     #

Don’ts

# ❌ Don't use mixed case
MyPalette           # Use: qual_mypalette
qualVivid           # Use: qual_vivid

# ❌ Don't use other separators
my.palette          # Use: qual_mypalette
custom-colors       # Use: qual_custom

# ❌ Don't include numbers
palette_12          # Use metadata instead
colors_v2           # Use: qual_colors (version in docs)

# ❌ Don't omit type
beautiful           # Use: qual_beautiful
sunset              # Use: seq_sunset

# ❌ Don't be vague
nice_colors         # Too generic
palette1            # Not descriptive
good_palette        # Meaningless

Series Naming

For related palettes:

# ✅ GOOD - Consistent pattern
seq_warm_light
seq_warm_medium
seq_warm_dark

# Or with explicit color counts
qual_earth_3        # 3-color version
qual_earth_6        # 6-color version
qual_earth_12       # 12-color version

# ❌ BAD - Inconsistent
seq_warm_light
seq_warm            # Missing variant identifier
warm_dark           # Missing type prefix
seq_warm2           # Number without underscore

Quick Reference

Type Prefixes

seq_   →  Sequential    (one-direction gradients)
div_   →  Diverging     (two-direction from center)
qual_  →  Qualitative   (discrete categories)

Source Suffixes

_g     →  ggsci package
_rb    →  RColorBrewer package
_v     →  viridis package
_sc    →  single-cell specific
_bio   →  bioinformatics standard

Templates

# Custom palettes
[type]_[descriptive_name]
seq_sunset           # Example
qual_vivid           # Example
div_warm             # Example

# Adapted palettes
[type]_[original_name]_[source]
qual_nejm_g          # Example
seq_viridis_v        # Example
qual_set1_rb         # Example

Validation Checklist

□ Starts with seq_, div_, or qual_
□ All lowercase letters
□ Uses underscores for separation
□ No numbers in the name
□ Descriptive and intuitive
□ Source suffix only if adapted
□ Unique within its type

Summary

Core Principles

Type identification - Prefix clearly indicates palette purpose
Descriptive naming - Names reflect colors or application
Source attribution - Credit adapted palettes appropriately
Consistency - Follow uniform standards
Simplicity - Keep names concise and clear

The Golden Rule

type_name_source structure All lowercase + underscores only

Benefits

✅ Instant recognition - Know palette type at a glance
✅ Automatic inference - Functions detect type from name
✅ Easy filtering - Find palettes by type quickly
✅ Clear attribution - Proper credit to sources
✅ Scalable system - Easy to add new palettes

Resources

Main documentation: ?evanverse
Color system guide: vignette("get-started", package = "evanverse")
Package website: evanverse documentation

Document Version: 1.0 Last Updated: 2025-11-12 Status: Official Standard

Official Naming Standards for evanverse Palette System

evanverse package

2025-11-12