build_blueprint_blocks: Build Forced-Choice Blocks from a Custom Blueprint

In autoFC: Automatic Toolkit for Construction, Optimization, Scoring and Simulation of Forced-Choice Tests

Build Forced-Choice Blocks from a Custom Blueprint

Description

Constructs an initial set of forced-choice blocks that strictly adhere to a user-specified blueprint (e.g., exact trait and keying combinations for every block). It utilizes a fast random-search heuristic to simultaneously optimize a specified matching criterion (e.g., minimizing within-block difficulty variance).

This function acts as an excellent "Smart Initializer" before passing the resulting blocks into assemble_blocks() for further global optimization.

Usage

build_blueprint_blocks(
  item_chars,
  blueprint,
  bp_block_col = "block",
  bp_trait_col = "trait",
  bp_sign_col = "sign",
  bp_crit_col = NULL,
  df_id_col = "item_num",
  df_trait_col = "trait",
  df_sign_col = "sign",
  df_crit_col = NULL,
  optim_func = NULL,
  adjust_factor = 1.1,
  max_comb_attempts = 100,
  max_adjust_attempts = 5
)

Arguments

item_chars	A data frame containing the item pool characteristics. Each row represents a single item.
blueprint	A data frame detailing the exact structural requirements for every block. Must contain columns mapping to the block ID, required trait, and required keying direction.
bp_block_col	Character string. The column name in blueprint identifying the block ID. Defaults to "block".
bp_trait_col	Character string. The column name in blueprint identifying the required trait. Defaults to "trait".
bp_sign_col	Character string. The column name in blueprint identifying the required keying sign. Defaults to "sign".
bp_crit_col	Character string. Optional. The column name in blueprint defining the initial numerical target for the matching criterion (e.g., maximum allowed difference). Defaults to NULL.
df_id_col	Character string. The column name in item_chars containing item number.
df_trait_col	Character string. The column name in item_chars containing the items' traits. Defaults to "trait".
df_sign_col	Character string. The column name in item_chars containing the items' keying signs. Defaults to "sign".
df_crit_col	Character string. Optional. The column name in item_chars containing the numerical values to be optimized (e.g., item difficulty). Defaults to NULL.
optim_func	Character string or function object. Optional. The function used to evaluate the items within a block (e.g., "var" or a custom function). The result is compared against the target in bp_crit_col. Defaults to NULL.
adjust_factor	Numeric value > 1. The multiplier used to relax the matching criterion target if a valid combination cannot be found. For example, 1.1 increases the allowed variance by 10 percents per failure. Defaults to 1.1.
max_comb_attempts	Integer. The maximum number of random combinations to generate and test against the matching criterion before relaxing the target. Defaults to 100.
max_adjust_attempts	Integer. The maximum number of times to relax the target criterion using adjust_factor before giving up on the block. Defaults to 5.

Value

A data frame containing the successfully matched items. The data frame will include all original columns from item_chars, plus tracking columns N_adjusts, final_criteria, and block_id. If the algorithm fails to construct a block due to depleted inventory or overly strict criteria, it returns the partially built scale up to the point of failure.

autoFC documentation built on July 14, 2026, 5:07 p.m.