DOCSEARCHbyAlgolia
Submit Docs

cols4all R Package

repository·main·Indexed 18 days ago

https://github.com/cols4all/cols4all-r

An R package for selecting accessible color palettes, specifically designed for people with color vision deficiency. It includes an interactive dashboard via c4a_gui() to analyze palettes based on fairness, contrast, and vividness, and provides tools to integrate scientifically-vetted palettes into ggplot2 visualizations using specialized scale functions.

Tokens
2K
Snippets
11
Records
14
Agent score
13%

What's inside cols4all

  1. Install cols4all

    main

    You can install the stable version of cols4all from CRAN or the development version from GitHub.

    CRAN Installation:

    install.packages("cols4all", dependencies = TRUE)

    GitHub Installation (Development Version):

    install.packages("remotes")
remotes::install_github("cols4all/cols4all-R", dependencies = TRUE)
    install.packages("cols4all", dependencies = TRUE)

  2. Integrate cols4all with ggplot2

    main

    You can use cols4all palettes directly in ggplot2 using specialized scale functions.

    Discrete Categorical Scales

    Use scale_color_discrete_c4a_cat() or scale_fill_discrete_c4a_cat() for qualitative palettes.

    library(ggplot2)
library(cols4all)

# Example: using a carto palette for discrete colors
ggplot(data, aes(x = x_var, y = y_var, color = category_var)) +
    geom_point() +
    scale_color_discrete_c4a_cat("carto.safe")

    Continuous Diverging Scales

    Use scale_color_continuous_c4a_div() or scale_fill_continuous_c4a_div() for diverging palettes. You can specify a mid value to define the center of the divergence.

    # Example: using a wes palette for continuous colors
ggplot(data, aes(x = x_var, y = y_var, color = continuous_var)) +
    geom_point() +
    scale_color_continuous_c4a_div("wes.zissou1", mid = mean(data$continuous_var))
    ggplot(diam_exp, aes(x = carat, y = price, color = color)) +
    geom_point(size = 2) +
    scale_color_discrete_c4a_cat("carto.safe") +
    theme_light()

  3. Launch the cols4all dashboard GUI

    main

    The c4a_gui() function starts an interactive dashboard. This tool allows you to compare palettes and analyze them in depth using various properties such as:

    • Colorblind friendly: Checks if the palette is usable for people with color vision deficiency.
    • Fair: Checks if colors stand out about equally.
    • Hues: Shows the range of hues used.
    • Vivid: Identifies highly saturated colors.
    • Contrast: Checks contrast against white, black (WACG criteria), and between colors.
    • 3D Blues: Detects potential 3D visual illusions in blue palettes.

    To use it, load the library and call the function:

    library(cols4all)
c4a_gui()
    library(cols4all)
c4a_gui()

  4. How to use the cols4all GUI dashboard

    main

    The c4a_gui() function launches a dashboard designed to help you find the best color palette for your specific visualization needs. You can compare palettes based on several scored properties:

    • Colorblind friendly: Indicates if the palette is usable for people with color vision deficiency.
    • Fair: Indicates if colors stand out about equally (important for categorical data).
    • Hues: Shows the range of hues used (e.g., full spectrum vs. limited range).
    • Vivid: Identifies if there are overly saturated/intense colors.
    • Contrast: Checks for sufficient contrast against white, black (WACG criteria), and between colors.
    • 3D Blues: Warns if blue colors might create a 3D visual illusion.
    • Naming: (In development) How easily colors can be named.

    You can filter and sort the palette table using these properties to find optimal trade-offs (e.g., filtering for 'Fair' palettes and sorting by 'Colorblind-friendly').

  5. Get started with cols4all

    main

    To use the package, load it into your R session and you can launch the interactive dashboard to explore and compare color palettes.

    library(cols4all)

# Launch the interactive dashboard
c4a_gui()

# List available palette series
c4a_series()
    library(cols4all)
c4a_gui()

  6. Get color for missing values with c4a_na()

    main

    For spatial data visualization, it is important to have a consistent color for missing values. Use c4a_na(palette_name) to retrieve the color assigned to missing values for a specific palette.

    c4a_na("hcl.purple_green")

  7. Retrieve colors from a palette with c4a()

    main

    Use c4a(palette_name, n) to get a vector of hex color codes from a specific palette. n specifies the number of colors to retrieve.

    Example: retrieving 11 colors from the hcl.purple_green palette:

    # select purple green palette from the hcl series:
c4a("hcl.purple_green", 11)
    c4a("hcl.purple_green", 11)

  8. Get available palette series

    main
    Use c4a_series() to see the available palette series. Default series include brewer, carto, cols4all, gmt, hcl, kovesi, matplotlib, met, meteo, misc, ocean, parks, poly, powerbi, scico, seaborn, stevens, tableau, tol, and wes.
    c4a_series()

  9. List palettes by type and series

    main

    To find specific palettes, use c4a_palettes() with the type and series arguments.

    Example: finding all diverging (type = "div") palettes in the hcl series:

    c4a_palettes(type = "div", series = "hcl")
    c4a_palettes(type = "div", series = "hcl")

  10. Explore available palettes and series

    main

    Use the following functions to discover what palettes are available in the package:

    • c4a_palettes(type, series): Get available palette names. You can filter by type (e.g., "div" for diverging) and series (e.g., "hcl").
    • c4a_series(): Get available palette series names.
    • c4a_types(): Get implemented palette types (e.g., categorical, sequential, diverging, etc.).
    • c4a_overview(): Get an overview of palettes organized by series and type.
    # Find diverging palettes specifically from the 'hcl' series
c4a_palettes(type = "div", series = "hcl")
    # Diverging palettes from the 'hcl' series
c4a_palettes(type = "div", series = "hcl")

  11. Extract colors from a palette with c4a() and c4a_na()

    main

    Use c4a() to retrieve the actual color values from a specific palette. You can specify the number of colors required.

    Use c4a_na() to retrieve the specific color assigned to missing values for a given palette, which is useful for maintaining consistency in spatial data visualizations.

    # Get 11 colors from the 'hcl.purple_green' palette
colors <- c4a("hcl.purple_green", 11)

# Get the color assigned for missing values in this palette
na_color <- c4a_na("hcl.purple_green")
    # select purple green palette from the hcl series:
c4a("hcl.purple_green", 11)

# get the associated color for missing values
c4a_na("hcl.purple_green")

  12. Plot a color palette with c4a_plot_cvd()

    main

    To visualize a palette (including its missing value color), use c4a_plot_cvd(). This is particularly useful for diverging palettes.

    # Plot the 'hcl.purple_green' palette with 11 colors, including the NA color
c4a_plot_cvd("hcl.purple_green", 11, include.na = TRUE)
    c4a_plot_cvd("hcl.purple_green", 11, include.na = TRUE)