Assess neuroscientific consistency between IDPs and performance domains

Queries a language model API to evaluate the neuroscientific relationship between imaging-derived phenotypes (IDPs) and a performance domain.

assess_idp_consistency(
  df,
  Perf.Dom,
  idp_cols,
  prompt = generate_idp_interpretation_prompt(),
  backend = c("groq", "openrouter"),
  api_key_env = NULL,
  model = NULL,
  required_fields = c("consistency", "justification", "plausibility"),
  max_retries = 5,
  retry_delay_base = 2,
  jitter = TRUE,
  temperature = 0.1,
  user_input_prompt = "Assess neuroscientific consistency and return JSON.",
  collapse_fn = function(x) paste(na.omit(x), collapse = ", "),
  parallel = FALSE,
  .options_furrr = furrr::furrr_options(),
  cache_dir = NULL,
  verbose = TRUE,
  skip_api_key_check = FALSE
)

Arguments

df

A data frame with at least one performance domain column and IDP columns.

Perf.Dom

Character, name of the column containing the performance domain.

idp_cols

Character vector of column names containing IDPs.

prompt

Character, system prompt. Default: see generate_idp_interpretation_prompt.

backend

Character, API backend ("groq", "openrouter"). Default: "groq".

api_key_env

Character, environment variable storing the API key. Default: NULL.

model

Character, model name. Default: NULL (uses backend default).

required_fields

Character vector, fields expected in API response. Default: c("consistency", "justification", "plausibility").

max_retries

Integer, maximum API retry attempts. Default: 5.

retry_delay_base

Numeric, base delay (seconds) for exponential backoff. Default: 2.

jitter

Logical, add jitter to retry delays. Default: TRUE.

temperature

Numeric, sampling temperature (0–1). Default: 0.1.

user_input_prompt

Character, additional user prompt text. Default: "Assess neuroscientific consistency and return JSON."

collapse_fn

Function, how to collapse IDPs into a string. Default: function(x) paste(na.omit(x), collapse = ", ").

parallel

Logical, use parallel processing with furrr::future_map. Default: FALSE.

.options_furrr

List, options for furrr::future_map. Default: furrr::furrr_options().

cache_dir

Character, directory for caching API responses. Default: NULL.

verbose

Logical, print debug information. Default: TRUE.

skip_api_key_check

Logical, if TRUE, skip API key validation (useful for testing). Default: FALSE.

Value

A data frame with original data plus columns for consistency, justification, and plausibility.