5.6 Scoring Quick Reference

This section provides a compact overview of the CBA ItemBuilder’s scoring system. For detailed descriptions, refer to the sections referenced above.

5.6.1 Scoring Structure

Scoring in the CBA ItemBuilder is defined per Task (see section 3.6) using Hit- and Miss-conditions that evaluate to true or false. Conditions are grouped into Classes, which serve as scoring variables in the result data.

Hit-Condition Syntax:
  component1 and component2                  (selected components)
  component1 and not component3              (with negation)
  matches(input1, "^correct answer$")        (text matching)
  result_text(input1)                        (capture text response)

Key Concepts:

Hit: A condition that evaluates to true when a desired response pattern is detected.
Miss: A condition that evaluates to true when an undesired response pattern is detected.
Class: A scoring variable that groups related Hit- or Miss-conditions. Each class produces one value in the result data.
Result-Text: Additional text output attached to a class, typically used to capture open text or numeric responses via the result_text() operator.
Result-Label: Additional label attached to a class via the result_label() operator.
Sequential Evaluation: When Use first active hit/miss per class is enabled (recommended), the first matching condition within a class determines the result.

5.6.2 Scoring Condition Operators

TABLE 5.1: Operators available in *Hit*- and *Miss*-conditions (see appendix B.2 for the complete listing).
Operator	Syntax	Description
Component state	`checkbox1`	`true` if component is selected
Negation	`not checkbox1`	`true` if component is not selected
Logical AND/OR	`A and B`, `A or B`	Combine conditions
`matches()`	`matches(input1, "^regex$")`	Text matches regular expression
`matches()`	`matches(cell1, "^regex$", "formula")`	Match formula text in spreadsheet cells
`integer_value()`	`integer_value(input1, "half_up", 0)`	Parse text as integer (with rounding mode and default)
`highlighted()`	`highlighted(text1, "#FFFF00")`	`true` if text is highlighted (optionally with specific color)
`complete()`	`complete(sel1, sel2)`	`true` if all listed selections are active
`partial()`	`partial(sel1, sel2)`	`true` if at least one selection is active
`variable_in()`	`variable_in(V_ans, 1, 2)`	`true` if variable has one of the listed values
`current_page()`	`current_page(page2)`	`true` if page is currently displayed
`bookmarked()`	`bookmarked(webPage1)`	`true` if page is bookmarked
`panel_position_range()`	`panel_position_range(p, 10, 100, 10, 100, true, comp1)`	`true` if component is within coordinate range
`panel_distance_range()`	`panel_distance_range(p, 5, 50, true, c1, c2)`	`true` if components are within distance range
`elapsedTime()`	`elapsedTime() > 5000`	Elapsed time in milliseconds
`user_interactions()`	`user_interactions() > 0`	Number of user interactions

5.6.3 Scoring Result Operators

TABLE 5.2: Operators for capturing results in *Hit*- and *Miss*-conditions.
Operator	Syntax	Description
`result_text()`	`result_text(input1)`	Copy component text to Result-Text
`result_text()`	`result_text("Answer: %1$s", input1)`	Template-based Result-Text
`result_label()`	`result_label("Category A")`	Set Result-Label for the condition
`result_label()`	`result_label("Score: %1$s", input1)`	Template-based Result-Label
`trace_text()`	`trace_text("scored")`	Write to trace log
`trace_snapshot()`	`trace_snapshot("scoring")`	Write to trace log with task snapshot

All result operators always return true and can be combined with other conditions using and.

5.6.4 FSM-Related Scoring Operators

TABLE 5.3: Operators for scoring based on *Finite-State Machine* states and events.
Operator	Syntax	Description
`raised_events()`	`raised_events(ev1)`	Number of times event was raised
`raised_nb_events()`	`raised_nb_events(ev1, ev2)`	Number of specified events raised
`raised_all_events()`	`raised_all_events(ev1, ev2)`	`true` if all listed events were raised
`raised_nb_events_in_state()`	`raised_nb_events_in_state(S1, ev1)`	Events raised while in specific state
`raised_all_events_in_state()`	`raised_all_events_in_state(S1, ev1, ev2)`	`true` if all events raised in state
`visited_nb_states()`	`visited_nb_states(S1, S2)`	Number of listed states visited
`visited_all_states()`	`visited_all_states(S1, S2)`	`true` if all listed states were visited
`is_last_state()`	`is_last_state(S1)`	`true` if last state matches
`visited_all_values_of_variable()`	`visited_all_values_of_variable(V, 1, 2, 3)`	`true` if variable had all listed values

5.6.5 Tree Scoring Operators

TABLE 5.4: Operators for scoring `Tree` components (see section 3.9.9).
Operator	Syntax	Description
`current_node()`	`current_node(tree1, "^nodePattern$")`	`true` if current node matches pattern
`exists_nodes()`	`exists_nodes(tree1, "pattern1", "pattern2")`	Number of nodes matching patterns
`visited_nodes()`	`visited_nodes(tree1, "pattern1")`	Number of visited nodes matching pattern
`matches_nodes()`	`matches_nodes(tree1, "nodeId", "col1", "col2")`	Nodes matching ID and column patterns

5.6.6 Scoring with `getItemScore()`

The getItemScore() operator can be used within the Finite-State Machine to query scoring results at runtime (e.g., for adaptive feedback):

getItemScore(TaskName, Calculation)

TABLE 5.5: Available `Calculation` values for `getItemScore()`.
Calculation	Returns	Description
`result`	`0` or `1`	Overall result (1 if minimum hits reached and no active misses)
`nb_hits`	Integer	Number of active hits
`hit_weight`	Integer	Total weight of active hits
`nb_misses`	Integer	Number of active misses
`miss_weight`	Integer	Total weight of active misses
`credit_class`	String	Name of the class with highest weight
`credit_weight`	Integer	Weight of the highest-weighted class
`nbInteractions`	Integer	User interactions in current execution
`execTime`	Integer (ms)	Time since task start
`reactionTime`	Integer (ms)	Time to first interaction