| 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 
[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
-
geom_dice— Display dice representations for data points -
create_dice_positions— Generate dice dot patterns for integers 1–6 -
make_offsets— Internal function to calculate x/y offsets for dot placement
Features
Seamless integration with ggplot2
Traditional dice dot layouts
Customizable appearance (size, color, transparency)
Support for faceting and multiple aesthetics
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
|
data |
A data frame. If |
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 |
show.legend |
Whether to include in legend. |
inherit.aes |
If |
... |
Additional arguments passed to |
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 |
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 |
Value
A ggplot2 theme