Title: Dice Plot Visualization for 'ggplot2'
Version: 1.0.1
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: ggplot2 (≥ 3.4.0), grid, dplyr, legendry, scales
LazyData: true
Depends: R (≥ 4.1.0)
NeedsCompilation: no
Packaged: 2025-12-08 15:22:58 UTC; matthiasflo
Author: Matthias Flotho ORCID iD [aut, cre]
Repository: CRAN
Date/Publication: 2025-12-08 15:40: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.

Example dice dataset 1

Description

Small toy dataset shipped with ggdiceplot and used in basic examples of geom_dice().

Usage

data(sample_dice_data1)

Format

A data frame with 5 columns:

taxon

Taxonomic unit (e.g. genus or species).

disease

Disease / condition group (factor).

specimen

Sample / specimen identifier.

lfc

Numeric effect size (log2 fold change).

q

Numeric q-value / FDR associated with the effect.

Example dice dataset 2

Description

A second toy dataset for geom_dice() examples.

Usage

data(sample_dice_data2)

Format

A data frame; similar structure to sample_dice_data1.

Larger example dice dataset

Description

Larger illustrative dataset for more complex dice-plots.

Usage

data(sample_dice_large)

Format

A data frame; similar structure to sample_dice_data1.

Example miRNA dice dataset

Description

Example miRNA × compound × organ dataset used in the vignette / examples.

Usage

data(sample_dice_miRNA)

Format

A data frame with at least:

miRNA

miRNA identifier (factor).

Compound

compound / treatment (factor).

Organ

organ label (factor).

log2FC

numeric log2 fold change.

direction

factor with levels Down, Unchanged, Up.

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