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-09-23 16:54:10
#> 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.819 (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.819 (higher is better)
#> 
#> Individual attribute level counts:
#> 
#> price:
#> 
#>   1   2   3 
#> 276 259 265 
#>   Balance score: 0.969 (higher is better)
#> 
#> typeB:
#> 
#>   0   1 
#> 531 269 
#>   Balance score: 0.683 (higher is better)
#> 
#> typeC:
#> 
#>   0   1 
#> 549 251 
#>   Balance score: 0.655 (higher is better)
#> 
#> qualityHigh:
#> 
#>   0   1 
#> 409 391 
#>   Balance score: 0.969 (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):  32.5%  (130 / 400 questions)
#>   2 (partial overlap):   67.5%  (270 / 400 questions)
#>   3 (no overlap):         0.0%  (0 / 400 questions)
#>   Average unique levels per question: 1.68
#> 
#> typeB: Continuous variable
#>   Questions by # unique levels:
#>   1 (complete overlap):  51.2%  (205 / 400 questions)
#>   2 (no overlap):        48.8%  (195 / 400 questions)
#>   Average unique levels per question: 1.49
#> 
#> typeC: Continuous variable
#>   Questions by # unique levels:
#>   1 (complete overlap):  54.2%  (217 / 400 questions)
#>   2 (no overlap):        45.8%  (183 / 400 questions)
#>   Average unique levels per question: 1.46
#> 
#> qualityHigh: Continuous variable
#>   Questions by # unique levels:
#>   1 (complete overlap):  46.2%  (185 / 400 questions)
#>   2 (no overlap):        53.8%  (215 / 400 questions)
#>   Average unique levels per question: 1.54
#> 
#> 

# Store results for later use
inspection <- cbc_inspect(design, sections = "balance")
inspection  # prints the same output
#> DESIGN SUMMARY
#> =========================
#> 
#> ATTRIBUTE BALANCE
#> =================
#> Overall balance score: 0.819 (higher is better)
#> 
#> Individual attribute level counts:
#> 
#> price:
#> 
#>   1   2   3 
#> 276 259 265 
#>   Balance score: 0.969 (higher is better)
#> 
#> typeB:
#> 
#>   0   1 
#> 531 269 
#>   Balance score: 0.683 (higher is better)
#> 
#> typeC:
#> 
#>   0   1 
#> 549 251 
#>   Balance score: 0.655 (higher is better)
#> 
#> qualityHigh:
#> 
#>   0   1 
#> 409 391 
#>   Balance score: 0.969 (higher is better)
#> 

# Verbose output with technical details
cbc_inspect(design, verbose = TRUE)
#> DESIGN SUMMARY
#> =========================
#> 
#> STRUCTURE
#> ================
#> Method: random
#> Created: 2025-09-23 16:54:10
#> Generation time: 0.178 seconds
#> Respondents: 100
#> Questions per respondent: 4
#> Alternatives per question: 2
#> Total choice sets: 400
#> Profile usage: 18/18 (100.0%)
#> Optimization attempts: 2
#> 
#> SUMMARY METRICS
#> =================
#> D-error calculation not available for random designs
#> Overall balance score: 0.819 (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.819 (higher is better)
#> 
#> Individual attribute level counts:
#> 
#> price:
#> 
#>   1   2   3 
#> 276 259 265 
#>   Balance score: 0.969 (higher is better), CV: 0.032 (lower is better)
#> 
#> typeB:
#> 
#>   0   1 
#> 531 269 
#>   Balance score: 0.683 (higher is better), CV: 0.463 (lower is better)
#> 
#> typeC:
#> 
#>   0   1 
#> 549 251 
#>   Balance score: 0.655 (higher is better), CV: 0.527 (lower is better)
#> 
#> qualityHigh:
#> 
#>   0   1 
#> 409 391 
#>   Balance score: 0.969 (higher is better), CV: 0.032 (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):  32.5%  (130 / 400 questions)
#>   2 (partial overlap):   67.5%  (270 / 400 questions)
#>   3 (no overlap):         0.0%  (0 / 400 questions)
#>   Average unique levels per question: 1.68
#> 
#> typeB: Continuous variable
#>   Unique levels:  0, 1 
#>   Questions by # unique levels:
#>   1 (complete overlap):  51.2%  (205 / 400 questions)
#>   2 (no overlap):        48.8%  (195 / 400 questions)
#>   Average unique levels per question: 1.49
#> 
#> typeC: Continuous variable
#>   Unique levels:  0, 1 
#>   Questions by # unique levels:
#>   1 (complete overlap):  54.2%  (217 / 400 questions)
#>   2 (no overlap):        45.8%  (183 / 400 questions)
#>   Average unique levels per question: 1.46
#> 
#> qualityHigh: Continuous variable
#>   Unique levels:  0, 1 
#>   Questions by # unique levels:
#>   1 (complete overlap):  46.2%  (185 / 400 questions)
#>   2 (no overlap):        53.8%  (215 / 400 questions)
#>   Average unique levels per question: 1.54
#> 
#>