Title: DicePlot Visualization for 'ggplot2'
Version: 1.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.3
URL: https://github.com/maflot/ggdiceplot
BugReports: https://github.com/maflot/ggdiceplot/issues
Imports: dplyr, ggplot2 (≥ 3.4.0), grid, legendry, scales, tibble
LazyData: true
Depends: R (≥ 4.1.0)
NeedsCompilation: no
Packaged: 2026-03-23 12:00:43 UTC; matthias
Repository: CRAN
Date/Publication: 2026-03-23 12:20:02 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,
  pip_scale = 0.75,
  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

Numeric: number of x categories (used for aspect ratio).

y_length

Numeric: number of y categories (used for aspect ratio).

pip_scale

Numeric (0–1): controls pip diameter relative to the maximum available space. When size is constant (not mapped), all pips are drawn at pip_scale fraction of the die face. When size is mapped to a variable, pips scale between 0.25 (smallest value) and pip_scale (largest value) of the maximum pip diameter. Default is 0.75. Set to NULL to disable auto-scaling and use the raw size aesthetic.

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 Visualization

Description

This toy dataset (sample_dice_data1) is used to demonstrate the geom_dice() function. It simulates log fold-change (LFC) and adjusted p-values (q-values) for a range of oral taxa across disease types and specimen sites.

Usage

data(sample_dice_data1)

Format

A data frame with 160 rows and 5 columns:

taxon

Character. Microbial taxon name (8 taxa).

disease

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

specimen

Character. Body site specimen (Saliva, Plaque, Tongue, Buccal, Gingival).

lfc

Numeric. Simulated log2 fold change value; may contain NA.

q

Numeric. Simulated adjusted p-value (q-value); may contain NA.

Examples

data(sample_dice_data1)
head(sample_dice_data1)

Sample Dice Dataset 2 for Visualization

Description

sample_dice_data2 is a toy dataset designed to demonstrate geom_dice() with multiple specimen types. It simulates log2 fold-change (LFC) and adjusted p-values (q-values) for oral taxa across disease conditions and specimen sites, with some missing values.

Usage

data(sample_dice_data2)

Format

A data frame with 160 rows and 5 columns:

taxon

Character. Microbial taxon name (8 taxa).

disease

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

specimen

Character. Body site specimen (Saliva, Plaque, Tongue, Buccal, Gingival).

lfc

Numeric. Simulated log2 fold change; may contain NA.

q

Numeric. Simulated adjusted p-value (q-value); may contain NA.

Examples

data(sample_dice_data2)
head(sample_dice_data2)

Large Sample Dice Dataset

Description

sample_dice_large is a larger toy dataset with 60 taxa, designed to test geom_dice() at higher density. It simulates log2 fold-change and q-values with approximately 50\

Usage

data(sample_dice_large)

Format

A data frame with 480 rows and 6 columns:

taxon

Character. Taxon name (Taxon_1 through Taxon_60).

disease

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

specimen

Character. Specimen type (Saliva, Plaque).

replicate

Integer. Replicate identifier.

lfc

Numeric. Simulated log2 fold change; may contain NA.

q

Numeric. Simulated adjusted p-value; may contain NA.

Examples

data(sample_dice_large)
head(sample_dice_large)

Sample miRNA Dice Dataset

Description

sample_dice_miRNA is a toy dataset for demonstrating geom_dice() with categorical fill mapping. It simulates miRNA dysregulation across compounds and organs, with direction (Up, Down, Unchanged) as the fill variable.

Usage

data(sample_dice_miRNA)

Format

A data frame with approximately 90 rows and 5 columns:

miRNA

Factor. miRNA identifier (miR-1 through miR-5).

Compound

Factor. Treatment compound (Control, Compound_1 through Compound_4).

Organ

Factor. Target organ (Lung, Liver, Brain, Kidney).

log2FC

Numeric. Simulated log2 fold change.

direction

Factor. Regulation direction (Down, Unchanged, Up).

Examples

data(sample_dice_miRNA)
head(sample_dice_miRNA)

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