Title: Dice Plot Visualization for 'ggplot2'
Version: 0.1.0
Author: Matthias Flotho ORCID iD [aut, cre]
Maintainer: Matthias Flotho <matthias.flotho@ccb.uni-saarland.de>
Description: Provides 'ggplot2' extensions for creating dice-based visualizations where each dot position represents a specific categorical variable. The package includes geom_dice() for displaying presence/absence of categorical variables using traditional dice patterns. Each dice position (1-6) represents a different category, with dots shown only when that category is present. This allows intuitive visualization of up to 6 categorical variables simultaneously.
License: MIT + file LICENSE
Encoding: UTF-8
RoxygenNote: 7.3.2
URL: https://github.com/maflot/ggdiceplot
BugReports: https://github.com/maflot/ggdiceplot/issues
Imports: ggplot2 (≥ 3.4.0), grid, legendry, scales
LazyData: true
Depends: R (≥ 4.1.0), dplyr
NeedsCompilation: no
Packaged: 2025-08-18 15:03:41 UTC; matthiasflo
Repository: CRAN
Date/Publication: 2025-08-21 20:02:06 UTC

ggdiceplot: Dice Plot Visualization for ggplot2

Description

The ggdiceplot package provides extensions for ggplot2 that allow visualizing data using dice-based dot patterns. The main feature is geom_dice(), which displays categorical variables using traditional dice face layouts (1 to 6 dots). This is especially helpful for multidimensional categorical data visualization.

Main Functions

Features

Author(s)

Maintainer: Matthias Flotho matthias.flotho@ccb.uni-saarland.de (ORCID)

See Also

Useful links:

A ggplot2 layer for creating dice representations

Description

geom_dice() creates a layer that displays dice-like symbols where each dot represents a specific category. Dots are only shown when that categorical variable is present in the data, allowing compact visual encoding.

Usage

geom_dice(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ndots = NULL,
  x_length = NULL,
  y_length = NULL,
  na.rm = FALSE,
  show.legend = TRUE,
  inherit.aes = TRUE,
  ...
)

Arguments

mapping

Set of aesthetic mappings created by aes(). Must include:

  • x, y: Position of the dice.

  • dots: The categories present (usually as a string or factor).

data

A data frame. If NULL, inherits from the plot.

stat

The statistical transformation to use.

position

Position adjustment.

ndots

Integer (1–6): number of positions shown per dice.

x_length

x_length Numeric: used for aspect ratio.

y_length

y_length Numeric: used for aspect ratio.

na.rm

Remove missing values if TRUE.

show.legend

Whether to include in legend.

inherit.aes

If FALSE, overrides the default aesthetics.

...

Additional arguments passed to layer().

Value

A ggplot2 layer that draws dice with categorical dot encodings.

Examples

library(ggplot2)

df <- data.frame(
  x = 1:3,
  y = 1,
  dots = c("A,B", "A,C,E", "F")
)

ggplot(df, aes(x, y, dots = dots)) +
  geom_dice(ndots = 6, x_length = 3, y_length = 1)

Get Dice Dot Positions as Text Grid

Description

Returns a string representing dice layout with numbered positions.

Usage

create_dice_positions(n_dots)

Arguments

n_dots

Integer between 1 and 6

Value

Character string representing dice dot layout

Calculate Dice Dot Offsets

Description

Computes the (x, y) offset positions for drawing dots on dice faces.

Usage

make_offsets(n, width = 0.5, height = 0.5, pad = 0.1)

Arguments

n

Integer from 1 to 6, indicating the number of dots on the die face.

width

Total width of the die face (default: 0.5).

height

Total height of the die face (default: 0.5).

pad

Padding to apply around the dot grid (default: 0.1).

Value

A data.frame with key, x, and y columns indicating dot positions.

Sample Dice Dataset for Basic Visualization

Description

A toy dataset for demonstrating the geom_dice() function. It simulates log fold-change (LFC) and adjusted p-values (q-values) for oral taxa across disease types and specimen sites.

Usage

data("sample_dice_data1")

Format

A data frame with 48 rows and 5 variables:

taxon

character. Microbial taxon name

disease

character. Disease condition (Caries, Periodontitis, Healthy, Gingivitis)

specimen

character. Body site specimen (Saliva, Plaque)

lfc

numeric. Simulated log2 fold change value

q

numeric. Simulated adjusted p-value (q-value)

Details

This dataset contains simulated microbiome data across different oral health conditions and specimen types. It is designed to demonstrate basic dice plot functionality with categorical mapping of diseases to dice positions.

Source

Simulated data for package demonstration purposes.

Examples

data(sample_dice_data1)
head(sample_dice_data1)

# Basic dice plot example
library(ggplot2)
ggplot(sample_dice_data1, aes(x = specimen, y = taxon)) +
  geom_dice(aes(dots = disease, fill = lfc, size = -log10(q)),
            ndots = 4, show.legend = TRUE)

Extended Sample Dice Dataset

Description

An extended toy dataset for demonstrating advanced geom_dice() functionality with missing data handling and more complex scenarios.

Usage

data("sample_dice_data2")

Format

A data frame with variables:

taxon

character. Microbial taxon name

disease

character. Disease condition

specimen

character. Body site specimen

replicate

numeric. Replicate number

lfc

numeric. Log2 fold change value (may contain NA)

q

numeric. Adjusted p-value (q-value, may contain NA)

Details

This dataset extends sample_dice_data1 with additional complexity including missing values and edge cases. It is designed to demonstrate how dice plots handle missing data and various data preprocessing scenarios.

Source

Simulated data for package demonstration purposes.

Examples

data(sample_dice_data2)
head(sample_dice_data2)

# Example with missing data handling
library(ggplot2)
ggplot(sample_dice_data2, aes(x = specimen, y = taxon)) +
  geom_dice(aes(dots = disease, fill = lfc, size = -log10(q)),
            ndots = 4, na.rm = TRUE, show.legend = TRUE)

Large Sample Dataset for Performance Testing

Description

A larger toy dataset for testing geom_dice() performance and demonstrating scalability with bigger datasets.

Usage

data("sample_dice_large")

Format

A data frame with variables:

taxon

character. Microbial taxon name

disease

character. Disease condition

specimen

character. Body site specimen

replicate

numeric. Replicate number

lfc

numeric. Log2 fold change value

q

numeric. Adjusted p-value (q-value)

Details

This dataset contains a larger number of observations than the basic sample datasets. It is designed to test performance and demonstrate how dice plots scale with larger data, including automatic sizing and boundary validation.

Source

Simulated data for package demonstration purposes.

Examples

data(sample_dice_large)
head(sample_dice_large)
dim(sample_dice_large)

# Example with larger dataset
library(ggplot2)
ggplot(sample_dice_large, aes(x = specimen, y = taxon)) +
  geom_dice(aes(dots = disease, fill = lfc, size = -log10(q)),
            ndots = 6, na.rm = TRUE, show.legend = TRUE) +
  theme_minimal() +
  theme(axis.text.y = element_text(size = 8))

Discrete Scale for Dice Dot Colors

Description

Creates a ggplot2 discrete scale for dice dot aesthetics.

Usage

scale_dots_discrete(..., aesthetics = "dots")

Arguments

...

Passed to ggplot2::discrete_scale()

aesthetics

Character string of the target aesthetic (default: "dots")

Value

A ggplot2 scale

Dice Theme for ggplot2

Description

A minimal ggplot2 theme for dice plots.

Usage

theme_dice(x_length, y_length, ...)

Arguments

x_length

Width of the plotting area (kept for compatibility)

y_length

Height of the plotting area (kept for compatibility)

...

Additional arguments passed to theme_grey()

Value

A ggplot2 theme