Configuration-selection aid

Once you've picked a methodology mode via methodology_decision_aid(), this function helps you set config.yaml knobs based on your corpus shape. It encodes the empirical evidence from re-validation: three Mode 2 runs at different scales (40, 47, 157 codes) and different research-focus breadths produced 6, 10, and 7 themes respectively – all in the publication-quality 4-10 range with 0% single-code themes.

Usage

configuration_selection_aid(
  mode,
  corpus_size,
  estimated_codebook_size = NULL,
  focus_shape = c("narrow_intersection", "single_focal", "broad")
)

Arguments

mode

One of "reflexive_scaffold" (M1), "codebook_collaborative" (M2), "framework_applied" (M3). Get this from methodology_decision_aid() first.

corpus_size

Integer; approximate number of entries in the corpus. Used to estimate codebook scale.

estimated_codebook_size

Integer; approximate number of codes you expect after saturation. If NULL, the function estimates from corpus_size (typical ratio: 1 code per 1.5-4 entries depending on focus breadth, e.g. 40 codes from 60 coded entries up to 157 codes from 140 coded entries).

focus_shape

One of "narrow_intersection" (e.g., "remote work x burnout x retention"), "single_focal" (e.g., "remote-work satisfaction"), or "broad" (e.g., "emotional experiences"). Narrow foci produce fewer codes per coded entry.

Value

A list with elements expected_themes, expected_passes, recommended_review_points, expected_wall_time_min, expected_api_spend_usd, and notes.

Details

The function returns a list with: expected_themes (range), expected_passes (clustering passes; v2 only), and recommended_review_points (whether the post-coding or post-themes researcher review pause should be enabled).

Examples

# A 250-entry corpus on a narrow remote-work x burnout question:
configuration_selection_aid(
  mode = "codebook_collaborative",
  corpus_size = 250,
  focus_shape = "narrow_intersection"
)
#> $mode
#> [1] "codebook_collaborative"
#> 
#> $expected_themes
#> [1] 5 8
#> 
#> $expected_passes
#> [1] 1
#> 
#> $recommended_review_points
#> $recommended_review_points$after_coding
#> [1] TRUE
#> 
#> $recommended_review_points$after_themes
#> [1] FALSE
#> 
#> 
#> $expected_wall_time_min
#> [1] 11
#> 
#> $expected_api_spend_usd
#> [1] 3
#> 
#> $notes
#> [1] "Estimated codebook (46 codes) is within the empirically-validated bracket (40-157 codes). Expect 1 substantive clustering pass(es) before AI-declared convergence."
#> 

# A larger 1000-entry corpus with a broad focus:
configuration_selection_aid(
  mode = "codebook_collaborative",
  corpus_size = 1000,
  focus_shape = "broad"
)
#> $mode
#> [1] "codebook_collaborative"
#> 
#> $expected_themes
#> [1]  6 10
#> 
#> $expected_passes
#> [1] 3
#> 
#> $recommended_review_points
#> $recommended_review_points$after_coding
#> [1] TRUE
#> 
#> $recommended_review_points$after_themes
#> [1] FALSE
#> 
#> 
#> $expected_wall_time_min
#> [1] 41
#> 
#> $expected_api_spend_usd
#> [1] 10.5
#> 
#> $notes
#> [1] "Estimated codebook (660 codes) is above the empirically-validated bracket (tested up to 157 codes). v2's single-call-per-pass should scale to ~500 codes within OpenAI gpt-4o's context window, but quality at that scale is unknown; smoke first."
#>