Generate SiGN Model Parameter List

A helper function that constructs a named list of parameters for behavioural choice predictions for the function SiGN(). Users can either select a predefined profile or specify custom values. The function includes built-in validation and recycling of arguments when lengths differ.

Usage

choice_params(
 profile = c("zentall", "kendall", "fantino"),
 il_dur_a = NULL, il_dur_b = NULL,
 tl_dur_a1 = NULL, tl_dur_a2 = NULL,
 tl_dur_b1 = NULL, tl_dur_b2 = NULL,
 tl_p_a1 = NULL, tl_p_a2 = NULL,
 tl_p_b1 = NULL, tl_p_b2 = NULL,
 tr_p_a1 = NULL, tr_p_a2 = NULL,
 tr_p_b1 = NULL, tr_p_b2 = NULL,
 il_sched_a = NULL, il_sched_b = NULL,
 s_delta = 1,
 beta_log = 10,
 beta_toggle = TRUE,
 display_params = FALSE
 )

Arguments

profile: A character string specifying a default parameter profile. Must be one of "zentall", "kendall", or "fantino". See details.
il_dur_a, il_dur_b: Numeric vector of initial link durations for alternatives A and B respectively.
tl_dur_a1, tl_dur_a2: Numeric vector of durations for two terminal links on alternative A.
tl_dur_b1, tl_dur_b2: Numeric vector of durations for two terminal links on alternative B.
tl_p_a1, tl_p_a2: Numeric vector of entry probabilities for two terminal links on alternative A.
tl_p_b1, tl_p_b2: Numeric vector of entry probabilities for two terminal links on alternative B.
tr_p_a1, tr_p_a2: Numeric vector of terminal reinforcement probabilities for two terminal links on alternative A.
tr_p_b1, tr_p_b2: Numeric vector of terminal reinforcement probabilities for two terminal links on alternative B.
il_sched_a, il_sched_b: Schedule type for each initial link. Must be either "VI" (variable-interval) or "FR" (fixed-ratio). Case-insensitive.
s_delta: Time required to perceive a stimulus that signals the absence of terminal reinforcement. Default is 1. See also s_delta().
beta_log: A positive real number specifying the base of the logarithm used for β. Defaults to 10.
beta_toggle: Logical defaulting to TRUE. Permits the model to adjust the balance of conditional and primary reinforcement for signalled alternatives according to Equation 6 of Dunn et al. (2024). See also beta_sig().
display_params: Logical. If TRUE, prints the parameter list as a data frame.

Value

A named list of validated and possibly recycled parameters suitable for input into the SiGN() function.

Details

Default Profiles:

Three default profiles are available to streamline argument selection: "zentall" (based on Stagner & Zentall, 2010), "kendall" (based on Kendall, 1985), and "fantino" (based on Fantino, 1969). Notably, the " fantino" profile reflects a single terminal link procedure, consistent with the design used in Fantino’s original study.

Default profile values can be overridden by specifying the corresponding arguments directly.

If argument lengths differ, values are recycled to the maximum length, with a message.

Temporal Units:

The SiGN model is temporally relative, meaning it allows initial and terminal link durations to be treated as any unit of time (e.g., seconds, minutes, hours, etc.). However, units need to be consistent across all link durations.

s_delta

Conventionally, concurrent-chains paradigms have measured time in seconds with very easily discriminable stimuli. The default value of s_delta reflects this convention. However, if shorter or longer temporal units are used, or the stimuli takes considerable time to be discriminated, it may be prudent to adjust s_delta accordingly.

Signal Discrimination:

A choice alternative is treated by the SiGN() function as signalled if both terminal link durations are non-zero and either the durations or the reinforcement probabilities differ between the terminal links.

This definition assumes that differences in duration or reinforcement probability imply discriminability between the stimuli associated with each terminal link. For example, if one terminal link lasts 10 seconds and the other 20 seconds, and both have a reinforcement probability of 1, it is assumed that the organism can fully discriminate between them—e.g., the terminal links may be visually distinct (such as different colours) and thus are recognisable from the moment of onset.

The SiGN model assumes that the (behavioural) function of terminal link stimuli remains fixed across the entire duration of the terminal link—that is, the probability of terminal reinforcement does not change partway through the terminal link. Procedures that depart from this assumption may not be appropriately handled by the model.

Schedule Selection:

Setting the initial link schedules as "FR" is most suitable for cases involving an FR 1 schedule or when a single timer is employed in the initial links of long VI schedules. This is because the "FR" setting does not take into account the switching behaviour present with concurrent schedules using independent timers. For example, if a single timer is used for two concurrent VI 30 schedules, setting the Initial Link Schedule as an FR is preferable because the time spent in the initial links is controlled by one timer, not two independent timers operating concurrently. However, if independent timers are used for each initial link, the model requires this setting to be VI .

Note that the SiGN model does not directly compute predictions for ratio schedules. Instead, it represents the ratio as a duration with an individual reinforcement rate, rather than a common/shared one.

References

Dunn, R. M., Pisklak, J. M., McDevitt, M. A., & Spetch, M. L. (2024). Suboptimal choice: A review and quantification of the signal for good news (SiGN) model. Psychological Review. 131(1), 58-78. https://doi.org/10.1037/rev0000416

Fantino, E. (1969). Choice and rate of reinforcement. Journal of the Experimental Analysis of Behavior, 12(5), 723–730. https://doi.org/10.1901/jeab.1969.12-723

Kendall, S. B. (1985). A further study of choice and percentage reinforcement. Behavioural Processes, 10(4), 399–413. https://doi.org/10.1016/0376-6357(85)90040-3

Stagner, J. P., & Zentall, T. R. (2010). Suboptimal choice behavior by pigeons. Psychonomic Bulletin & Review, 17(3), 412–416. https://doi.org/10.3758/PBR.17.3.412

Examples

# Use default Zentall profile
z <- choice_params("zentall", display_params = TRUE)
#>   il_dur_a il_dur_b tl_dur_a1 tl_dur_a2 tl_dur_b1 tl_dur_b2 tl_p_a1 tl_p_a2
#> 1        1        1        10        10        10        10     0.2     0.8
#>   tl_p_b1 tl_p_b2 tr_p_a1 tr_p_a2 tr_p_b1 tr_p_b2 il_sched_a il_sched_b s_delta
#> 1     0.2     0.8       1       0     0.5     0.5         FR         FR       1
#>   beta_log beta_toggle
#> 1       10        TRUE

# Custom specification with minimal values
k <- choice_params(
  profile = "kendall",
  tr_p_b1 = c(1, 0.5), tr_p_b2 = c(1, 0.5),
  display_params = TRUE
)
#>   il_dur_a il_dur_b tl_dur_a1 tl_dur_a2 tl_dur_b1 tl_dur_b2 tl_p_a1 tl_p_a2
#> 1        1        1        15        15        15        15     0.5     0.5
#> 2        1        1        15        15        15        15     0.5     0.5
#>   tl_p_b1 tl_p_b2 tr_p_a1 tr_p_a2 tr_p_b1 tr_p_b2 il_sched_a il_sched_b s_delta
#> 1     0.5     0.5       1       0     1.0     1.0         FR         FR       1
#> 2     0.5     0.5       1       0     0.5     0.5         FR         FR       1
#>   beta_log beta_toggle
#> 1       10        TRUE
#> 2       10        TRUE