Waffle Charts for Categorical Data Visualization

Creates professional waffle charts (square pie charts) to visualize categorical distributions using a grid of colored squares. Each square represents a fixed proportion of the total, making it ideal for showing parts-of-whole relationships in clinical and pathological data.

Value

A jamovi analysis object with waffle chart visualization, optional summary, and optional methodology explanation

Details

Data Requirements:

• Categorical grouping variable (factor, character, or logical)

• Minimum 30 cases recommended for stable proportions

• 2-10 categories optimal for visual clarity (>10 categories may be cluttered)

• Haven labelled data automatically converted to factors

How Waffle Charts Work: A waffle chart uses a grid of colored squares (typically 10x10 = 100 squares) where each square represents a fixed proportion of the total sample. This makes percentages immediately intuitive - each square ≈ 1% of the sample.

Clinical Applications:

• Disease Classification: Show distribution of tumor grades, cancer stages, or pathological subtypes

• Treatment Outcomes: Display response rates (complete/partial/no response) across patient cohorts

• Demographic Analysis: Present patient characteristics, risk factors, or comorbidity patterns

• Quality Metrics: Visualize compliance rates, diagnostic accuracy, or safety outcomes

Advantages over Other Charts:

• More intuitive than pie charts for showing proportions

• Each square = 1% makes percentages immediately clear

• Handles many categories better than bar charts

• Effective for presentations and publications

• Faceting enables subgroup comparisons

Statistical Considerations:

• Most effective with n≥30; smaller samples may show unstable proportions

• Works best when no single category dominates (>80%)

• Each square represents approximately 1% of the sample

• Categories with <5 cases may be statistically unreliable

• Chi-square tests can evaluate proportion differences between groups

Performance Optimization

The function implements sophisticated caching:

• Data aggregation cached based on variable selection and data content

• Color palettes cached separately to minimize recomputation

• Plot state management prevents unnecessary regeneration

• Automatic width scaling for faceted plots

Clinical Validation

The function performs comprehensive data quality checks:

• Validates categorical data types (with automatic labelled data conversion)

• Detects single-category data (requires multiple categories)

• Warns about many categories (>10 may need grouping)

• Alerts to small samples (<30 cases)

• Identifies rare categories (<5 cases)

• Checks for negative count values (must be non-negative)

References

Wilke, C. O. (2019). waffle: Create Waffle Chart Visualizations in R. R package version 1.0.1.

See also

geom_waffle for the underlying waffle geom

Super classes

jmvcore::Analysis -> ClinicoPath::jwaffleBase -> jwaffleClass

Methods

Public methods

• jwaffleClass$asSource()

• jwaffleClass$clone()

Inherited methods

• jmvcore::Analysis$.createImage()
• jmvcore::Analysis$.createImages()
• jmvcore::Analysis$.createPlotObject()
• jmvcore::Analysis$.load()
• jmvcore::Analysis$.render()
• jmvcore::Analysis$.save()
• jmvcore::Analysis$.savePart()
• jmvcore::Analysis$.setCheckpoint()
• jmvcore::Analysis$.setParent()
• jmvcore::Analysis$.setReadDatasetHeaderSource()
• jmvcore::Analysis$.setReadDatasetSource()
• jmvcore::Analysis$.setResourcesPathSource()
• jmvcore::Analysis$.setStatePathSource()
• jmvcore::Analysis$addAddon()
• jmvcore::Analysis$asProtoBuf()
• jmvcore::Analysis$check()
• jmvcore::Analysis$init()
• jmvcore::Analysis$optionsChangedHandler()
• jmvcore::Analysis$postInit()
• jmvcore::Analysis$print()
• jmvcore::Analysis$readDataset()
• jmvcore::Analysis$run()
• jmvcore::Analysis$serialize()
• jmvcore::Analysis$setError()
• jmvcore::Analysis$setStatus()
• jmvcore::Analysis$translate()
• ClinicoPath::jwaffleBase$initialize()

---

Method asSource()

Generate R source code for jwaffle analysis

Usage

jwaffleClass$asSource()

Returns

Character string with R syntax for reproducible analysis

---

Method clone()

The objects of this class are cloneable with this method.

Usage

jwaffleClass$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

Examples

if (FALSE) { # \dontrun{
# Basic tumor grade distribution
jwaffle(
    data = pathology_data,
    groups = "TumorGrade",
    color_palette = "colorblind",
    show_legend = TRUE,
    showSummaries = TRUE
)

# Treatment response by cohort with faceting
jwaffle(
    data = clinical_data,
    groups = "Response",
    facet = "TreatmentArm",
    color_palette = "professional",
    mytitle = "Treatment Response Rates by Arm",
    showSummaries = TRUE
)

# Weighted risk distribution
jwaffle(
    data = aggregated_data,
    groups = "RiskCategory",
    counts = "PatientCount",
    color_palette = "presentation",
    legendtitle = "Risk Level"
)
} # }