Comprehensive design quality inspection — cbc

This function provides detailed inspection of choice experiment designs across multiple dimensions including design structure, efficiency metrics, attribute balance, overlap patterns, and variable encoding.

Usage

cbc_inspect(design, sections = "all", verbose = FALSE)

Arguments

design: A cbc_design object created by cbc_design()
sections: Character vector specifying which sections to show. Options: "structure", "efficiency", "balance", "overlap", "encoding", or "all" (default). Can specify multiple: c("balance", "overlap")
verbose: Logical. If TRUE, shows additional technical details. If FALSE (default), shows simplified output.

Value

A cbc_inspection object containing the inspection results

Examples

library(cbcTools)

# Create profiles and design
profiles <- cbc_profiles(
  price = c(1, 2, 3),
  type = c("A", "B", "C"),
  quality = c("Low", "High")
)

design <- cbc_design(
  profiles = profiles,
  n_alts = 2,
  n_q = 4
)

# Inspect all sections (default) - prints automatically
cbc_inspect(design)
#> DESIGN SUMMARY
#> =========================
#> 
#> STRUCTURE
#> ================
#> Method: random
#> Created: 2025-07-08 13:36:55
#> Respondents: 100
#> Questions per respondent: 4
#> Alternatives per question: 2
#> Total choice sets: 400
#> Profile usage: 18/18 (100.0%)
#> 
#> SUMMARY METRICS
#> =================
#> D-error calculation not available for random designs
#> Overall balance score: 0.812 (higher is better)
#> Overall overlap score: 0.461 (lower is better)
#> 
#> VARIABLE ENCODING
#> =================
#> Format: Dummy-coded (type, quality)
#> 💡 Use cbc_decode_design() to convert to categorical format
#> 
#> ATTRIBUTE BALANCE
#> =================
#> Overall balance score: 0.812 (higher is better)
#> 
#> Individual attribute level counts:
#> 
#> price:
#> 
#>   1   2   3 
#> 264 262 274 
#>   Balance score: 0.976 (higher is better)
#> 
#> typeB:
#> 
#>   0   1 
#> 541 259 
#>   Balance score: 0.667 (higher is better)
#> 
#> typeC:
#> 
#>   0   1 
#> 537 263 
#>   Balance score: 0.674 (higher is better)
#> 
#> qualityHigh:
#> 
#>   0   1 
#> 421 379 
#>   Balance score: 0.931 (higher is better)
#> 
#> ATTRIBUTE OVERLAP
#> =================
#> Overall overlap score: 0.461 (lower is better)
#> 
#> Counts of attribute overlap:
#> (# of questions with N unique levels)
#> 
#> price: Continuous variable
#>   Questions by # unique levels:
#>   1 (complete overlap):  28.2%  (113 / 400 questions)
#>   2 (partial overlap):   71.8%  (287 / 400 questions)
#>   3 (no overlap):         0.0%  (0 / 400 questions)
#>   Average unique levels per question: 1.72
#> 
#> typeB: Continuous variable
#>   Questions by # unique levels:
#>   1 (complete overlap):  55.2%  (221 / 400 questions)
#>   2 (no overlap):        44.8%  (179 / 400 questions)
#>   Average unique levels per question: 1.45
#> 
#> typeC: Continuous variable
#>   Questions by # unique levels:
#>   1 (complete overlap):  51.7%  (207 / 400 questions)
#>   2 (no overlap):        48.2%  (193 / 400 questions)
#>   Average unique levels per question: 1.48
#> 
#> qualityHigh: Continuous variable
#>   Questions by # unique levels:
#>   1 (complete overlap):  49.2%  (197 / 400 questions)
#>   2 (no overlap):        50.7%  (203 / 400 questions)
#>   Average unique levels per question: 1.51
#> 
#> 

# Store results for later use
inspection <- cbc_inspect(design, sections = "balance")
inspection  # prints the same output
#> DESIGN SUMMARY
#> =========================
#> 
#> ATTRIBUTE BALANCE
#> =================
#> Overall balance score: 0.812 (higher is better)
#> 
#> Individual attribute level counts:
#> 
#> price:
#> 
#>   1   2   3 
#> 264 262 274 
#>   Balance score: 0.976 (higher is better)
#> 
#> typeB:
#> 
#>   0   1 
#> 541 259 
#>   Balance score: 0.667 (higher is better)
#> 
#> typeC:
#> 
#>   0   1 
#> 537 263 
#>   Balance score: 0.674 (higher is better)
#> 
#> qualityHigh:
#> 
#>   0   1 
#> 421 379 
#>   Balance score: 0.931 (higher is better)
#> 

# Verbose output with technical details
cbc_inspect(design, verbose = TRUE)
#> DESIGN SUMMARY
#> =========================
#> 
#> STRUCTURE
#> ================
#> Method: random
#> Created: 2025-07-08 13:36:55
#> Generation time: 0.250 seconds
#> Respondents: 100
#> Questions per respondent: 4
#> Alternatives per question: 2
#> Total choice sets: 400
#> Profile usage: 18/18 (100.0%)
#> Optimization attempts: 3
#> 
#> SUMMARY METRICS
#> =================
#> D-error calculation not available for random designs
#> Overall balance score: 0.812 (higher is better)
#> Overall overlap score: 0.461 (lower is better)
#>   Profiles used: 18/18
#> 
#> VARIABLE ENCODING
#> =================
#> Format: Dummy-coded (type, quality)
#> 
#> Categorical variable details:
#>   type: A, B, C (reference: A)
#>   quality: Low, High (reference: Low)
#> 💡 Use cbc_decode_design() to convert to categorical format
#> 
#> ATTRIBUTE BALANCE
#> =================
#> Overall balance score: 0.812 (higher is better)
#> 
#> Individual attribute level counts:
#> 
#> price:
#> 
#>   1   2   3 
#> 264 262 274 
#>   Balance score: 0.976 (higher is better), CV: 0.024 (lower is better)
#> 
#> typeB:
#> 
#>   0   1 
#> 541 259 
#>   Balance score: 0.667 (higher is better), CV: 0.499 (lower is better)
#> 
#> typeC:
#> 
#>   0   1 
#> 537 263 
#>   Balance score: 0.674 (higher is better), CV: 0.484 (lower is better)
#> 
#> qualityHigh:
#> 
#>   0   1 
#> 421 379 
#>   Balance score: 0.931 (higher is better), CV: 0.074 (lower is better)
#> 
#> ATTRIBUTE OVERLAP
#> =================
#> Overall overlap score: 0.461 (lower is better)
#> 
#> Counts of attribute overlap:
#> (# of questions with N unique levels)
#> 
#> price: Continuous variable
#>   Unique levels:  1, 2, 3 
#>   Questions by # unique levels:
#>   1 (complete overlap):  28.2%  (113 / 400 questions)
#>   2 (partial overlap):   71.8%  (287 / 400 questions)
#>   3 (no overlap):         0.0%  (0 / 400 questions)
#>   Average unique levels per question: 1.72
#> 
#> typeB: Continuous variable
#>   Unique levels:  0, 1 
#>   Questions by # unique levels:
#>   1 (complete overlap):  55.2%  (221 / 400 questions)
#>   2 (no overlap):        44.8%  (179 / 400 questions)
#>   Average unique levels per question: 1.45
#> 
#> typeC: Continuous variable
#>   Unique levels:  0, 1 
#>   Questions by # unique levels:
#>   1 (complete overlap):  51.7%  (207 / 400 questions)
#>   2 (no overlap):        48.2%  (193 / 400 questions)
#>   Average unique levels per question: 1.48
#> 
#> qualityHigh: Continuous variable
#>   Unique levels:  0, 1 
#>   Questions by # unique levels:
#>   1 (complete overlap):  49.2%  (197 / 400 questions)
#>   2 (no overlap):        50.7%  (203 / 400 questions)
#>   Average unique levels per question: 1.51
#> 
#>