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 or cbc_choices 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-10-12 18:05:30
#> 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 this design
#> Overall balance score: 0.960 (higher is better)
#> Overall overlap score: 0.365 (lower is better)
#> 
#> VARIABLE ENCODING
#> =================
#> Format: Standard (categorical) (type, quality)
#> 💡 Use cbc_encode() to convert to dummy or effects coding
#> 
#> ATTRIBUTE BALANCE
#> =================
#> Overall balance score: 0.960 (higher is better)
#> 
#> Individual attribute level counts:
#> 
#> price:
#> 
#>   1   2   3 
#> 284 253 263 
#>   Balance score: 0.944 (higher is better)
#> 
#> type:
#> 
#>   A   B   C 
#> 281 271 248 
#>   Balance score: 0.940 (higher is better)
#> 
#> quality:
#> 
#>  Low High 
#>  401  399 
#>   Balance score: 0.996 (higher is better)
#> 
#> ATTRIBUTE OVERLAP
#> =================
#> Overall overlap score: 0.365 (lower is better)
#> 
#> Counts of attribute overlap:
#> (# of questions with N unique levels)
#> 
#> price: Continuous variable
#>   Questions by # unique levels:
#>   1 (complete overlap):  33.8%  (135 / 400 questions)
#>   2 (partial overlap):   66.2%  (265 / 400 questions)
#>   3 (no overlap):         0.0%  (0 / 400 questions)
#>   Average unique levels per question: 1.66
#> 
#> type: Categorical variable
#>   Questions by # unique levels:
#>   1 (complete overlap):  29.5%  (118 / 400 questions)
#>   2 (partial overlap):   70.5%  (282 / 400 questions)
#>   3 (no overlap):         0.0%  (0 / 400 questions)
#>   Average unique levels per question: 1.71
#> 
#> quality: Categorical 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.960 (higher is better)
#> 
#> Individual attribute level counts:
#> 
#> price:
#> 
#>   1   2   3 
#> 284 253 263 
#>   Balance score: 0.944 (higher is better)
#> 
#> type:
#> 
#>   A   B   C 
#> 281 271 248 
#>   Balance score: 0.940 (higher is better)
#> 
#> quality:
#> 
#>  Low High 
#>  401  399 
#>   Balance score: 0.996 (higher is better)
#> 

# Verbose output with technical details
cbc_inspect(design, verbose = TRUE)
#> DESIGN SUMMARY
#> =========================
#> 
#> STRUCTURE
#> ================
#> Method: random
#> Created: 2025-10-12 18:05:30
#> Generation time: 0.186 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 this design
#> Overall balance score: 0.960 (higher is better)
#> Overall overlap score: 0.365 (lower is better)
#>   Profiles used: 18/18
#> 
#> VARIABLE ENCODING
#> =================
#> Format: Standard (categorical) (type, quality)
#> 
#> Categorical variable details:
#>   type: A, B, C (reference: A)
#>   quality: Low, High (reference: Low)
#> 💡 Use cbc_encode() to convert to dummy or effects coding
#> 
#> ATTRIBUTE BALANCE
#> =================
#> Overall balance score: 0.960 (higher is better)
#> 
#> Individual attribute level counts:
#> 
#> price:
#> 
#>   1   2   3 
#> 284 253 263 
#>   Balance score: 0.944 (higher is better), CV: 0.059 (lower is better)
#> 
#> type:
#> 
#>   A   B   C 
#> 281 271 248 
#>   Balance score: 0.940 (higher is better), CV: 0.063 (lower is better)
#> 
#> quality:
#> 
#>  Low High 
#>  401  399 
#>   Balance score: 0.996 (higher is better), CV: 0.004 (lower is better)
#> 
#> ATTRIBUTE OVERLAP
#> =================
#> Overall overlap score: 0.365 (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):  33.8%  (135 / 400 questions)
#>   2 (partial overlap):   66.2%  (265 / 400 questions)
#>   3 (no overlap):         0.0%  (0 / 400 questions)
#>   Average unique levels per question: 1.66
#> 
#> type: Categorical variable
#>   Questions by # unique levels:
#>   1 (complete overlap):  29.5%  (118 / 400 questions)
#>   2 (partial overlap):   70.5%  (282 / 400 questions)
#>   3 (no overlap):         0.0%  (0 / 400 questions)
#>   Average unique levels per question: 1.71
#> 
#> quality: Categorical 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
#> 
#>