cbcTools

https://jhelvy.github.io/cbcTools/
Admin
An R package for generating and inspecting survey designs for choice-based conjoint (CBC)...
Tokens:43,515
Snippets:460
Trust Score:9.7
Update:4 months ago
Show doc for...
Tokens:
Raw
### Simulating Choices Example

Source: https://jhelvy.github.io/cbcTools/articles/getting-started.html

This snippet shows how to simulate choices based on attribute levels.

```R
table(choices_cat$price)
#> 
#>   1 1.5   2 2.5   3 
#> 713 146 240 159 542
table(choices_cat$type)
#> 
#>       Fuji       Gala Honeycrisp 
#>        504        627        669
table(choices_cat$freshness)
#> 
#>      Poor   Average Excellent 
#>       414       557       829
```

--------------------------------

### Example Data Setup for Power Analysis

Source: https://jhelvy.github.io/cbcTools/articles/power.html

This code block sets up example data for a power analysis, including defining profiles, creating a design, setting priors, and simulating choices.

```R
library(cbcTools)

# Create example data for power analysis
profiles <- cbc_profiles(
  price = c(1, 1.5, 2, 2.5, 3),
  type = c('Fuji', 'Gala', 'Honeycrisp'),
  freshness = c('Poor', 'Average', 'Excellent')
)

# Create design and simulate choices
design <- cbc_design(
  profiles = profiles,
  n_alts = 2,
  n_q = 6,
  n_resp = 600, # Large sample for power analysis
  method = "random"
)

priors <- cbc_priors(
  profiles = profiles,
  price = -0.25,
  type = c(0.5, 1.0),
  freshness = c(0.6, 1.2)
)

choices <- cbc_choices(design, priors = priors)
head(choices)
#> CBC Choice Data
#> ===============
#> Encoding: standard
#> Observations: 3 choice tasks
#> Alternatives per task: 2
#> Total choices made: 3
#> 
#> Simulation method: utility_based
#> Priors: Used for utility-based simulation
#> Simulated at: 2025-11-01 00:56:08
#> 
#> Choice rates by alternative:
#>   Alt 1: 66.7% (2 choices)
#>   Alt 2: 33.3% (1 choices)
#> 
#> First few rows:
#>   profileID respID qID altID obsID price       type freshness choice
#> 1        31      1   1     1     1   1.0       Fuji Excellent      0
#> 2        15      1   1     2     1   3.0 Honeycrisp      Poor      1
#> 3        14      1   2     1     2   2.5 Honeycrisp      Poor      1
#> 4         3      1   2     2     2   2.0       Fuji      Poor      0
#> 5        42      1   3     1     3   1.5 Honeycrisp Excellent      1
#> 6        43      1   3     2     3   2.0 Honeycrisp Excellent      0

```

--------------------------------

### Summary of Power Analysis

Source: https://jhelvy.github.io/cbcTools/articles/getting-started.html

This snippet demonstrates how to use the `summary()` function to determine the exact sample size required for a specified power threshold.

```R
summary(power, power_threshold = 0.9)
#> CBC Power Analysis Summary
#> ===========================
#> 
#> Sample size requirements for 90% power:
#> 
#> price          : n >= 60 (achieves 98.9% power, SE = 0.0754)
#> typeGala       : n >= 30 (achieves 97.0% power, SE = 0.2352)
#> typeHoneycrisp : n >= 30 (achieves 100.0% power, SE = 0.2493)
#> freshnessAverage: n >= 60 (achieves 95.2% power, SE = 0.1595)
#> freshnessExcellent: n >= 30 (achieves 100.0% power, SE = 0.2163)
```

--------------------------------

### Generate a CBC Design

Source: https://jhelvy.github.io/cbcTools/articles/getting-started.html

Example of generating a CBC design using the `cbc_design` function with stochastic method, specifying number of alternatives, questions, respondents, and priors.

```r
design <- cbc_design(
  profiles = profiles,
  method = "stochastic", # D-optimal method
  n_alts = 3, # 2 alternatives per choice question
  n_q = 6, # 6 questions per respondent
  n_resp = 300, # 300 respondents
  priors = priors # Use our priors for optimization
)

design
#> Design method: stochastic
#> Encoding: standard
#> Structure: 300 respondents × 6 questions × 3 alternatives
#> Profile usage: 16/45 (35.6%)
#> D-error: 0.875074
#> 
#> 💡 Use cbc_inspect() for a more detailed summary
#> 
#> First few rows of design:
#>   profileID blockID respID qID altID obsID price       type freshness
#> 1         1       1      1   1     1     1     1       Fuji      Poor
#> 2        45       1      1   1     2     1     3 Honeycrisp Excellent
#> 3        21       1      1   1     3     1     1       Gala   Average
#> 4        31       1      1   2     1     2     1       Fuji Excellent
#> 5        20       1      1   2     2     2     3       Fuji   Average
#> 6        15       1      1   2     3     2     3 Honeycrisp      Poor
#> ... and 5394 more rows

```

--------------------------------

### Examples

Source: https://jhelvy.github.io/cbcTools/reference/cbc_compare.html

Example of creating profiles, different designs, and comparing them using cbc_compare.

```R
library(cbcTools)

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

# Create different designs
design_random <- cbc_design(
  profiles = profiles,
  method = "random",
  n_alts = 2, n_q = 4
)

design_stochastic <- cbc_design(
  profiles = profiles,
  method = "stochastic",
  n_alts = 2, n_q = 4
)
#> Stochastic design will be optimized into 1 design block, then allocated across 100 respondents
#> Running 5 design searches using 3 cores...
#> 
#> D-error results from all starts:
#> Start 1: 1.206045   (Best)
#> Start 3: 1.414214 
#> Start 2: 2.309401 
#> Start 4: 2.828427 
#> Start 5: Inf 

# Compare designs
cbc_compare(design_random, design_stochastic)
#> CBC Design Comparison
#> =====================
#> Designs compared: 2
#> Metrics: structure, efficiency, balance, overlap
#> Sorted by: d_error (ascending)
#> 
#> Structure
#> =====================
#>    Design     Method respondents questions
#>  Design 2 stochastic         100         4
#>  Design 1     random         100         4
#>  Alternatives Blocks Profile Usage
#>             2      1  (8/18) 44.4%
#>             2      1  (18/18) 100%
#>  No Choice Labeled?
#>         No       No
#>         No       No
#> 
#> Design Metrics
#> =====================
#>    Design     Method D-Error (Null) D-Error (Prior) Balance Overlap
#>  Design 2 stochastic       1.206045              NA   0.707   0.167
#>  Design 1     random             NA              NA   0.958   0.343
#> 
#> Interpretation:
#> - D-Error: Lower is better (design efficiency)
#> - Balance: Higher is better (level distribution)
#> - Overlap: Lower is better (attribute variation)
#> - Profile Usage: Higher means more profiles used
#> 
#> Best performers:
#> - Balance: Design 1 (0.958)
#> - Overlap: Design 2 (0.167)
#> - Profile Usage: Design 1 (100.0%)
#> 
#> Use summary() for detailed information on any one design.

# Named comparison with specific metrics
cbc_compare(
  Random = design_random,
  Stochastic = design_stochastic,
  metrics = c("efficiency", "balance"),
  sort_by = "d_error"
)
#> CBC Design Comparison
#> =====================
#> Designs compared: 2
#> Metrics: efficiency, balance
#> Sorted by: d_error (ascending)
#> 
#> Design Metrics
#> =====================
#>      Design     Method D-Error (Null) D-Error (Prior) Balance
#>  Stochastic stochastic       1.206045              NA   0.707
#>      Random     random             NA              NA   0.958
#> 
#> Interpretation:
#> - D-Error: Lower is better (design efficiency)
#> - Balance: Higher is better (level distribution)
#> 
#> Best performers:
#> - Balance: Random (0.958)
#> 
#> Use summary() for detailed information on any one design.

```

--------------------------------

### Use suggestions as a starting point

Source: https://jhelvy.github.io/cbcTools/reference/cbc_suggest_priors.html

Demonstrates how to use the suggestions from `cbc_suggest_priors()` as a starting point and then manually adjust the prior utility values based on domain knowledge.

```r
priors <- cbc_priors(
  profiles,
  price = -0.5,  # Adjusted from suggestion
  type = c("Gala" = 0.3, "Honeycrisp" = 0.8),
  freshness = c("Average" = 0.4, "Excellent" = 0.9)
)
```

--------------------------------

### Install cbcTools from GitHub

Source: https://jhelvy.github.io/cbcTools/index.html

You can install the development version of cbcTools from GitHub.

```r
# install.packages("pak")
pak::pak("jhelvy/cbcTools")
```

--------------------------------

### Example

Source: https://jhelvy.github.io/cbcTools/reference/cbc_power.html

Example of how to use the cbc_power function to run a power analysis.

```R
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, n_alts = 2, n_q = 6)

# Simulate choices
priors <- cbc_priors(profiles, price = -0.1, type = c(0.5, 0.2), quality = 0.3)
choices <- cbc_choices(design, priors)

# Run power analysis
power_results <- cbc_power(choices, n_breaks = 8)
#> Auto-detected parameters: price, type, quality
#> Using 'respID' as panelID for panel data estimation.
#> Estimating models using 3 cores...
#> Model estimation complete!

# View results
print(power_results)
#> CBC Power Analysis Results
#> ==========================
#> 
#> Sample sizes tested: 12 to 100 (8 breaks)
#> Significance level: 0.050
#> Parameters: price, typeB, typeC, qualityHigh
#> 
#> Power summary (probability of detecting true effect):
#> 
#> n = 12:
#>   price       : Power = 0.079, SE = 0.1959
#>   typeB       : Power = 0.199, SE = 0.3850
#>   typeC       : Power = 0.201, SE = 0.4036
#>   qualityHigh : Power = 0.054, SE = 0.3341
#> 
#> n = 38:
#>   price       : Power = 0.584, SE = 0.1146
#>   typeB       : Power = 0.574, SE = 0.2425
#>   typeC       : Power = 0.148, SE = 0.2341
#>   qualityHigh : Power = 0.116, SE = 0.1867
#> 
#> n = 50:
#>   price       : Power = 0.570, SE = 0.1002
#>   typeB       : Power = 0.287, SE = 0.2006
#>   typeC       : Power = 0.052, SE = 0.2001
#>   qualityHigh : Power = 0.294, SE = 0.1618
#> 
#> n = 75:
#>   price       : Power = 0.884, SE = 0.0811
#>   typeB       : Power = 0.161, SE = 0.1634
#>   typeC       : Power = 0.055, SE = 0.1628
#>   qualityHigh : Power = 0.557, SE = 0.1358
#> 
#> n = 100:
#>   price       : Power = 0.804, SE = 0.0709
#>   typeB       : Power = 0.698, SE = 0.1432
#>   typeC       : Power = 0.075, SE = 0.1412
#>   qualityHigh : Power = 0.869, SE = 0.1147
#> 
#> Use plot() to visualize power curves.
#> Use summary() for detailed power analysis.
plot(power_results)

```

--------------------------------

### Example 1: Inspect all sections

Source: https://jhelvy.github.io/cbcTools/reference/cbc_inspect.html

This example demonstrates how to create profiles and a design, then inspect all sections of the design using cbc_inspect. The output is printed automatically.

```R
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)
```

--------------------------------

### CBC Power Analysis

Source: https://jhelvy.github.io/cbcTools/articles/getting-started.html

This snippet demonstrates how to use the `cbc_power()` function to assess statistical power for different sample sizes.

```R
power <- cbc_power(choices)
power
#> CBC Power Analysis Results
#> ==========================
#> 
#> Sample sizes tested: 30 to 300 (10 breaks)
#> Significance level: 0.050
#> Parameters: price, typeGala, typeHoneycrisp, freshnessAverage, freshnessExcellent
#> 
#> Power summary (probability of detecting true effect):
#> 
#> n = 30:
#>   price       : Power = 0.897, SE = 0.1065
#>   typeGala    : Power = 0.970, SE = 0.2352
#>   typeHoneycrisp: Power = 1.000, SE = 0.2493
#>   freshnessAverage: Power = 0.536, SE = 0.2239
#>   freshnessExcellent: Power = 1.000, SE = 0.2163
#> 
#> n = 90:
#>   price       : Power = 0.982, SE = 0.0601
#>   typeGala    : Power = 0.998, SE = 0.1312
#>   typeHoneycrisp: Power = 1.000, SE = 0.1382
#>   freshnessAverage: Power = 0.990, SE = 0.1282
#>   freshnessExcellent: Power = 1.000, SE = 0.1237
#> 
#> n = 180:
#>   price       : Power = 1.000, SE = 0.0421
#>   typeGala    : Power = 1.000, SE = 0.0913
#>   typeHoneycrisp: Power = 1.000, SE = 0.0968
#>   freshnessAverage: Power = 1.000, SE = 0.0904
#>   freshnessExcellent: Power = 1.000, SE = 0.0869
#> 
#> n = 240:
#>   price       : Power = 1.000, SE = 0.0364
#>   typeGala    : Power = 1.000, SE = 0.0789
#>   typeHoneycrisp: Power = 1.000, SE = 0.0839
#>   freshnessAverage: Power = 1.000, SE = 0.0782
#>   freshnessExcellent: Power = 1.000, SE = 0.0752
#> 
#> n = 300:
#>   price       : Power = 1.000, SE = 0.0327
#>   typeGala    : Power = 1.000, SE = 0.0709
#>   typeHoneycrisp: Power = 1.000, SE = 0.0754
#>   freshnessAverage: Power = 1.000, SE = 0.0702
#>   freshnessExcellent: Power = 1.000, SE = 0.0675
#> 
#> Use plot() to visualize power curves.
#> Use summary() for detailed power analysis.
```

--------------------------------

### Generate Profiles

Source: https://jhelvy.github.io/cbcTools/articles/getting-started.html

Defines the attributes and levels for the choice experiment, creating all possible combinations of attribute levels.

```R
profiles <- cbc_profiles(
  price = c(1.0, 1.5, 2.0, 2.5, 3.0), # Price per pound ($)
  type = c('Fuji', 'Gala', 'Honeycrisp'),
  freshness = c('Poor', 'Average', 'Excellent')
)

profiles
#> CBC Profiles
#> ============ 
#> price       : Continuous (5 levels, range: 1.00-3.00)
#> type        : Categorical (3 levels: Fuji, Gala, Honeycrisp)
#> freshness   : Categorical (3 levels: Poor, Average, Excellent)
#> 
#> Profiles: 45
#> First few rows:
#>   profileID price type freshness
#> 1         1   1.0 Fuji      Poor
#> 2         2   1.5 Fuji      Poor
#> 3         3   2.0 Fuji      Poor
#> 4         4   2.5 Fuji      Poor
#> 5         5   3.0 Fuji      Poor
#> 6         6   1.0 Gala      Poor
#> ... and 39 more rows

```

--------------------------------

### Examples

Source: https://jhelvy.github.io/cbcTools/reference/cbc_choices.html

Examples of simulating random and utility-based choices using cbc_choices.

```R
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
)

# Simulate random choices (default)
choices_random <- cbc_choices(design)

# Create priors and simulate utility-based choices
priors <- cbc_priors(
  profiles = profiles,
  price = -0.1,
  type = c(0.5, 0.2),  # vs reference level
  quality = 0.3
)

choices_utility <- cbc_choices(design, priors = priors)

```

--------------------------------

### Example 1: Moderate effect size suggestions (default)

Source: https://jhelvy.github.io/cbcTools/reference/cbc_suggest_priors.html

This example demonstrates how to generate moderate effect size suggestions using the default settings of the cbc_suggest_priors function. It includes creating example profiles and then calling the function.

```R
library(cbcTools)

# Create example profiles
profiles <- cbc_profiles(
  price = c(1, 1.5, 2, 2.5, 3),
  type = c('Fuji', 'Gala', 'Honeycrisp'),
  freshness = c('Poor', 'Average', 'Excellent')
)

# Get moderate effect size suggestions (default)
cbc_suggest_priors(profiles)
```

--------------------------------

### Frequency-Based Methods Examples

Source: https://jhelvy.github.io/cbcTools/articles/design.html

Generates designs using 'shortcut', 'minoverlap', and 'balanced' methods.

```r
design_shortcut <- cbc_design(
  profiles = profiles,
  method = "shortcut",
  n_alts = 2,
  n_q = 6,
  n_resp = 100
)

design_minoverlap <- cbc_design(
  profiles = profiles,
  method = "minoverlap",
  n_alts = 2,
  n_q = 6,
  n_resp = 100
)

design_balanced <- cbc_design(
  profiles = profiles,
  method = "balanced",
  n_alts = 2,
  n_q = 6,
  n_resp = 100
)
```

--------------------------------

### Random Parameters Example

Source: https://jhelvy.github.io/cbcTools/articles/priors.html

Demonstrates how to define random parameters for 'price' and 'freshness' using normal distributions with `rand_spec()`.

```R
priors_random <- cbc_priors(
  profiles = profiles,
  price = rand_spec(
    dist = "n",
    mean = -0.25,
    sd = 0.1
  ),
  type = c(0.5, 1.0),
  freshness = rand_spec(
    dist = "n",
    mean = c(0.6, 1.2),
    sd = c(0.1, 0.1)
  )
)

priors_random
#> CBC Prior Specifications:
#> 
#> price:
#>   Continuous variable
#>   Levels: 1, 1.5, 2, 2.5, 3 
#>   Random - Normal distribution
#>     Mean: -0.25
#>     SD:   0.1
#> 
#> type:
#>   Categorical variable
#>   Levels: Fuji, Gala, Honeycrisp 
#>   Reference level: Fuji
#>   Fixed parameter
#>     Gala: 0.5
#>     Honeycrisp: 1
#> 
#> freshness:
#>   Categorical variable
#>   Levels: Poor, Average, Excellent 
#>   Reference level: Poor
#>   Random - Normal distribution
#>     Average:
#>       Mean: 0.6
#>       SD:   0.1
#>     Excellent:
#>       Mean: 1.2
#>       SD:   0.1
#> 
#> Correlation Matrix:
#>                    price freshnessAverage freshnessExcellent
#> price                  1                0                  0
#> freshnessAverage       0                1                  0
#> freshnessExcellent     0                0                  1

```

--------------------------------

### Interaction Effects Example

Source: https://jhelvy.github.io/cbcTools/articles/priors.html

Demonstrates setting up priors with interaction effects between attributes using `int_spec()`.

```R
# Create priors with interaction effects
priors_interactions <- cbc_priors(
  profiles = profiles,
  price = -0.25,
  type = c("Fuji" = 0.5, "Honeycrisp" = 1.0),
  freshness = c("Average" = 0.6, "Excellent" = 1.2),
  interactions = list(
    # Price sensitivity varies by apple type
    int_spec(
      between = c("price", "type"),
      with_level = "Fuji",
      value = 0.1
    ),
    int_spec(
      between = c("price", "type"),
      with_level = "Honeycrisp",
      value = 0.2
    ),
    # Type preferences vary by freshness
    int_spec(
      between = c("type", "freshness"),
      level = "Honeycrisp",
      with_level = "Excellent",
      value = 0.3
    )
  )
)

priors_interactions
#> CBC Prior Specifications:
#> 
#> price:
#>   Continuous variable
#>   Levels: 1, 1.5, 2, 2.5, 3 
#>   Fixed parameter
#>     Coefficient: -0.25
#> 
#> type:
#>   Categorical variable
#>   Levels: Fuji, Gala, Honeycrisp 
#>   Reference level: Gala
#>   Fixed parameter
#>     Fuji: 0.5
#>     Honeycrisp: 1
#> 
#> freshness:
#>   Categorical variable
#>   Levels: Poor, Average, Excellent 
#>   Reference level: Poor
#>   Fixed parameter
#>     Average: 0.6
#>     Excellent: 1.2
#> 
#> Interactions:
#>   price × type[Fuji]: 0.1
#>   price × type[Honeycrisp]: 0.2
#>   type[Honeycrisp] × freshness[Excellent]: 0.3

```

--------------------------------

### Visualizing Power Curves

Source: https://jhelvy.github.io/cbcTools/articles/getting-started.html

This snippet shows how to use the `plot()` function to visualize the power curves generated by `cbc_power()`.

```R
plot(power, type = "power", power_threshold = 0.9)
```

--------------------------------

### Simulate Choices

Source: https://jhelvy.github.io/cbcTools/articles/getting-started.html

Generate realistic choice data using the `cbc_choices()` function. By default, random choices are made, but providing `priors` will simulate choices based on a utility model.

```R
# Simulate choices using our priors
choices <- cbc_choices(design, priors = priors)

choices
#> CBC Choice Data
#> ===============
#> Encoding: standard
#> Observations: 1800 choice tasks
#> Alternatives per task: 3
#> Respondents: 300
#> Questions per respondent: 6
#> Total choices made: 1800
#> 
#> Simulation method: utility_based
#> Original design D-error: 0.875074
#> Priors: Used for utility-based simulation
#> Simulated at: 2025-11-01 00:56:00
#> 
#> Choice rates by alternative:
#>   Alt 1: 32.9% (593 choices)
#>   Alt 2: 35.1% (632 choices)
#>   Alt 3: 31.9% (575 choices)
#> 
#> First few rows:
#>   profileID blockID respID qID altID obsID price       type freshness choice
#> 1         1       1      1   1     1     1     1       Fuji      Poor      0
#> 2        45       1      1   1     2     1     3 Honeycrisp Excellent      1
#> 3        21       1      1   1     3     1     1       Gala   Average      0
#> 4        31       1      1   2     1     2     1       Fuji Excellent      1
#> 5        20       1      1   2     2     2     3       Fuji   Average      0
#> 6        15       1      1   2     3     2     3 Honeycrisp      Poor      0
#> ... and 5394 more rows

```

```R
choices_cat <- choices

# Filter for the chosen rows only
choices_cat <- choices_cat[which(choices_cat$choice == 1), ]

```

--------------------------------

### Example 2: Small effect size suggestions

Source: https://jhelvy.github.io/cbcTools/reference/cbc_suggest_priors.html

This example shows how to obtain suggestions for a small effect size by specifying the 'effect_size' argument in the cbc_suggest_priors function.

```R
library(cbcTools)

# Create example profiles
profiles <- cbc_profiles(
  price = c(1, 1.5, 2, 2.5, 3),
  type = c('Fuji', 'Gala', 'Honeycrisp'),
  freshness = c('Poor', 'Average', 'Excellent')
)

# Get small effect size suggestions
cbc_suggest_priors(profiles, effect_size = "small")
```

--------------------------------

### Basic Setup for Choice Simulation

Source: https://jhelvy.github.io/cbcTools/articles/choices.html

Defines basic profiles and a random design using `cbcTools` functions.

```R
library(cbcTools)

profiles <- cbc_profiles(
  price = c(1, 1.5, 2, 2.5, 3),
  type = c('Fuji', 'Gala', 'Honeycrisp'),
  freshness = c('Poor', 'Average', 'Excellent')
)

design <- cbc_design(
  profiles = profiles,
  method = "random",
  n_alts = 2,
  n_q = 6,
  n_resp = 100
)

design
```

--------------------------------

### Example 2: Store results for later use

Source: https://jhelvy.github.io/cbcTools/reference/cbc_inspect.html

This example shows how to inspect only the 'balance' section of the design and store the results in a variable for later use. The stored results can then be printed.

```R
# Store results for later use
inspection <- cbc_inspect(design, sections = "balance")
inspection  # prints the same output
```

--------------------------------

### Inspect Design

Source: https://jhelvy.github.io/cbcTools/articles/getting-started.html

Use the `cbc_inspect()` function to evaluate the quality and properties of your design, looking at metrics like D-error, balance, overlap, and profile usage.

```R
cbc_inspect(design)
#> DESIGN SUMMARY
#> =========================
#> 
#> STRUCTURE
#> ================ 
#> Method: stochastic
#> Created: 2025-11-01 00:55:59
#> Respondents: 300
#> Questions per respondent: 6
#> Alternatives per question: 3
#> Total choice sets: 1800
#> Profile usage: 16/45 (35.6%)
#> 
#> SUMMARY METRICS
#> =================
#> D-error (with priors): 0.875074
#> D-error (null model): 0.827828
#> (Lower values indicate more efficient designs)
#> 
#> Overall balance score: 0.793 (higher is better)
#> Overall overlap score: 0.000 (lower is better)
#> 
#> VARIABLE ENCODING
#> =================
#> Format: Standard (categorical) (type, freshness)
#> 💡 Use cbc_encode() to convert to dummy or effects coding
#> 
#> ATTRIBUTE BALANCE
#> =================
#> Overall balance score: 0.793 (higher is better)
#> 
#> Individual attribute level counts:
#> 
#> price:
#> 
#>    1  1.5    2  2.5    3 
#> 1800  600  900  600 1500 
#>   Balance score: 0.665 (higher is better)
#> 
#> type:
#> 
#>       Fuji       Gala Honeycrisp 
#>       2100       1800       1500 
#>   Balance score: 0.857 (higher is better)
#> 
#> freshness:
#> 
#>      Poor   Average Excellent 
#>      2100      1500      1800 
#>   Balance score: 0.857 (higher is better)
#> 
#> ATTRIBUTE OVERLAP
#> =================
#> Overall overlap score: 0.000 (lower is better)
#> 
#> Counts of attribute overlap:
#> (# of questions with N unique levels)
#> 
#> price: Continuous variable
#>   Questions by # unique levels:
#>   1 (complete overlap):   0.0%  (0 / 1800 questions)
#>   2 (partial overlap):   33.3%  (600 / 1800 questions)
#>   3 (partial overlap):   66.7%  (1200 / 1800 questions)
#>   4 (partial overlap):    0.0%  (0 / 1800 questions)
#>   5 (no overlap):         0.0%  (0 / 1800 questions)
#>   Average unique levels per question: 2.67
#> 
#> type: Categorical variable
#>   Questions by # unique levels:
#>   1 (complete overlap):   0.0%  (0 / 1800 questions)
#>   2 (partial overlap):   50.0%  (900 / 1800 questions)
#>   3 (no overlap):        50.0%  (900 / 1800 questions)
#>   Average unique levels per question: 2.50
#> 
#> freshness: Categorical variable
#>   Questions by # unique levels:
#>   1 (complete overlap):   0.0%  (0 / 1800 questions)
#>   2 (partial overlap):   50.0%  (900 / 1800 questions)
#>   3 (no overlap):        50.0%  (900 / 1800 questions)
#>   Average unique levels per question: 2.50

```

--------------------------------

### Examples

Source: https://jhelvy.github.io/cbcTools/reference/cbc_encode.html

Example of creating profiles and a CBC design, then converting it to dummy coding.

```r
library(cbcTools)

# Create profiles with categorical variables
profiles <- cbc_profiles(
  price = c(10, 20, 30),
  quality = c("Low", "Medium", "High"),
  brand = c("A", "B")
)

# Create design (defaults to standard coding)
design <- cbc_design(
  profiles = profiles,
  n_alts = 2,
  n_q = 4
)

# Convert to dummy coding
design_dummy <- cbc_encode(design, coding = "dummy")
head(design_dummy)
#> Design method: random
#> Encoding: dummy
#> Structure: 100 respondents × 4 questions × 2 alternatives
#> Profile usage: 18/18 (100.0%)
#> 
#> 💡 Use cbc_inspect() for a more detailed summary
#> 💡 Use cbc_encode(design, 'standard') to view categorical format
#> 
#> First few rows of design:
#>   profileID respID qID altID obsID price qualityMedium qualityHigh brandB
#> 1        17      1   1     1     1    20             0           1      1
#> 2         8      1   1     2     1    20             0           1      0
#> 3         6      1   2     1     2    30             1           0      0
#> 4         5      1   2     2     2    20             1           0      0
#> 5         9      1   3     1     3    30             0           1      0
#> 6         3      1   3     2     3    30             0           0      0
```

```r
# Convert to effects coding
design_effects <- cbc_encode(design, coding = "effects")
head(design_effects)
#> Design method: random
#> Encoding: effects
#> Structure: 100 respondents × 4 questions × 2 alternatives
#> Profile usage: 18/18 (100.0%)
#> 
#> 💡 Use cbc_inspect() for a more detailed summary
#> 💡 Use cbc_encode(design, 'standard') to view categorical format
#> 
#> First few rows of design:
#>   profileID respID qID altID obsID price qualityMedium qualityHigh brandB
#> 1        17      1   1     1     1    20             0           1      1
#> 2         8      1   1     2     1    20             0           1     -1
#> 3         6      1   2     1     2    30             1           0     -1
#> 4         5      1   2     2     2    20             1           0     -1
#> 5         9      1   3     1     3    30             0           1     -1
#> 6         3      1   3     2     3    30            -1          -1     -1
```

```r
# Convert back to standard
design_standard <- cbc_encode(design_dummy, coding = "standard")
head(design_standard)
#> Design method: random
#> Encoding: standard
#> Structure: 100 respondents × 4 questions × 2 alternatives
#> Profile usage: 18/18 (100.0%)
#> 
#> 💡 Use cbc_inspect() for a more detailed summary
#> 
#> First few rows of design:
#>   profileID respID qID altID obsID price quality brand
#> 1        17      1   1     1     1    20    High     B
#> 2         8      1   1     2     1    20    High     A
#> 3         6      1   2     1     2    30  Medium     A
#> 4         5      1   2     2     2    20  Medium     A
#> 5         9      1   3     1     3    30    High     A
#> 6         3      1   3     2     3    30     Low     A
```

```r
# Custom reference levels with dummy coding
design_dummy2 <- cbc_encode(
  design,
  coding = "dummy",
  ref_levels = list(quality = "Medium", brand = "B")
)
head(design_dummy2)
#> Design method: random
#> Encoding: dummy
#> Structure: 100 respondents × 4 questions × 2 alternatives
#> Profile usage: 18/18 (100.0%)
#> 
#> 💡 Use cbc_inspect() for a more detailed summary
#> 💡 Use cbc_encode(design, 'standard') to view categorical format
#> 
#> First few rows of design:
#>   profileID respID qID altID obsID price qualityLow qualityHigh brandA
#> 1        17      1   1     1     1    20          0           1      0
#> 2         8      1   1     2     1    20          0           1      1
#> 3         6      1   2     1     2    30          0           0      1
#> 4         5      1   2     2     2    20          0           0      1
#> 5         9      1   3     1     3    30          0           1      1
#> 6         3      1   3     2     3    30          1           0      1
```

--------------------------------

### Install cbcTools from CRAN

Source: https://jhelvy.github.io/cbcTools/index.html

You can install the latest version of cbcTools from CRAN.

```r
install.packages("cbcTools")
```

--------------------------------

### Interactions Example

Source: https://jhelvy.github.io/cbcTools/articles/design.html

Example of creating priors with interaction effects and then generating a CBC design.

```r
# Create priors with interactions
priors_interactions <- cbc_priors(
  profiles = profiles,
  price = -0.25,
  type = c("Fuji" = 0.5, "Gala" = 1.0),
  freshness = c(0.6, 1.2),
  interactions = list(
    # Price is less negative (less price sensitive) for Fuji apples
    int_spec(
      between = c("price", "type"),
      with_level = "Fuji",
      value = 0.5
    ),
    # Price is slightly less negative for Gala apples
    int_spec(
      between = c("price", "type"),
      with_level = "Gala",
      value = 0.2
    )
    # Honeycrisp uses reference level (no additional interaction term)
  )
)

design_interactions <- cbc_design(
  profiles = profiles,
  n_alts = 2,
  n_q = 6,
  n_resp = 100,
  priors = priors_interactions,
  method = "stochastic"
)
```

--------------------------------

### Dominance Removal Example

Source: https://jhelvy.github.io/cbcTools/articles/design.html

Example of creating a CBC design with dominance removal enabled.

```r
design_no_dominance <- cbc_design(
  profiles = profiles,
  n_alts = 2,
  n_q = 6,
  n_resp = 100,
  priors = priors,
  method = "stochastic",
  remove_dominant = TRUE,
  dominance_types = c("total", "partial"),
  dominance_threshold = 0.8
)
```

--------------------------------

### Choice Data Format Example

Source: https://jhelvy.github.io/cbcTools/articles/choices.html

Demonstrates the structure of simulated choice data, including design columns and the 'choice' column.

```R
head(choices_utility)
#> CBC Choice Data
#> ===============
#> Encoding: standard
#> Observations: 3 choice tasks
#> Alternatives per task: 2
#> Total choices made: 3
#> 
#> Simulation method: utility_based
#> Priors: Used for utility-based simulation
#> Simulated at: 2025-11-01 00:55:32
#> 
#> Choice rates by alternative:
#>   Alt 1: 66.7% (2 choices)
#>   Alt 2: 33.3% (1 choices)
#> 
#> First few rows:
#>   profileID respID qID altID obsID price       type freshness choice
#> 1        31      1   1     1     1   1.0       Fuji Excellent      1
#> 2        15      1   1     2     1   3.0 Honeycrisp      Poor      0
#> 3        14      1   2     1     2   2.5 Honeycrisp      Poor      0
#> 4         3      1   2     2     2   2.0       Fuji      Poor      1
#> 5        42      1   3     1     3   1.5 Honeycrisp Excellent      1
#> 6        43      1   3     2     3   2.0 Honeycrisp Excellent      0
```

--------------------------------

### D-Optimal Methods Examples

Source: https://jhelvy.github.io/cbcTools/articles/design.html

Generates designs using 'stochastic', 'modfed', and 'cea' methods, including priors.

```r
design_stochastic <- cbc_design(
  profiles = profiles,
  method = "stochastic",
  n_alts = 2,
  n_q = 6,
  n_resp = 100,
  priors = priors,
  n_start = 1 # Number of random starting points
)

design_modfed <- cbc_design(
  profiles = profiles,
  n_alts = 2,
  n_q = 6,
  n_resp = 100,
  priors = priors,
  method = "modfed",
  n_start = 1
)

design_cea <- cbc_design(
  profiles = profiles,
  n_alts = 2,
  n_q = 6,
  n_resp = 100,
  priors = priors,
  method = "cea",
  n_start = 1
)
```
Tokens:
Raw