Generate a Prompt for IDP–Outcome Plausibility Scoring — idp_outcome_priors

This function creates a structured prompt that instructs a large language model (LLM) to produce a table of plausibility scores (0–1) relating imaging-derived phenotypes (IDPs) to behavioral or cognitive outcomes. The scoring framework is based on expert neuroscience principles: structure–function specificity, network-level alignment, disease alignment, reproducibility, and measurement fidelity.

idp_outcome_priors_prompt(
  idps = c("CA1", "Dentate Gyrus/CA3", "Anterolateral Entorhinal Cortex",
    "Posteromedial Entorhinal Cortex", "Parahippocampal Gyrus", "Perirhinal Cortex",
    "Medial Temporal Lobe", "Unknown Core: hier medullabrainstem",
    "Unknown Core: hier midbrainbrainstem", "Unknown Core: hier ponsbrainstem",
    "Caudal Anterior Cingulate", "Caudal Middle Frontal Gyrus", "Cuneus",
    "Entorhinal Cortex", "Fusiform Gyrus", "Inferior Parietal Lobule",
    "Inferior Temporal Gyrus", "Insula", "Isthmus Cingulate", "Lateral Occipital Cortex",
    
     "Lateral Orbitofrontal Cortex", "Lingual Gyrus", "Medial Orbitofrontal Cortex",
    "Middle Temporal Gyrus", "Paracentral Cortex", "Pars Opercularis", "Pars Orbitalis",
    "Pars Triangularis", "Pericalcarine Cortex", "Postcentral Gyrus",
    "Posterior Cingulate", "Precentral Gyrus", "Precuneus", "Rostral Anterior Cingulate",
    "Rostral Middle Frontal Gyrus", "Superior Frontal Gyrus", "Superior Parietal Lobule",
    "Superior Temporal Gyrus", "Supramarginal Gyrus", "Transverse Temporal Gyrus",
    "Basal Forebrain Ch13", 
     "Nucleus Basalis of Meynert Anterior",
    "Nucleus Basalis of Meynert Middle", "Nucleus Basalis of Meynert Posterior",
    "Globus Pallidus External", "Globus Pallidus Internal", "Caudate Nucleus", "Putamen",
    "Red Nucleus", "Substantia Nigra Compacta"),
  outcomes = c("verbal.learning.recall", "recall.delayed", "recall.total",
    "verbal.comprehension", "focus.and.control", "working.memory", "executive.function",
    "processing.speed", "episodic.memory", "reading.ability", "fluid.intelligence",
    "crystallized.intelligence", "cognitive.health", "cognitive.development", "MMSE",
    "CDRSB", "ADAS13", "ADASQ4", "mPACCdigit", "mPACCtrailsB", "FAQ", "EcogPtTotal",
    "EcogSPTotal", "moca", "updrs_totscore", "updrs1_score", "updrs2_score",
    "updrs3_score", "pigd", "rem"),
  domains = c("episodic memory", "working memory", "executive control",
    "processing speed", "language/semantic", "visuospatial", "global cognition",
    "activities of daily living", "subjective cognition", "motor (parkinsonian)",
    "sleep/REM"),
  call_llm = FALSE,
  llm_fun = NULL
)

Arguments

idps: A character vector of imaging-derived phenotypes (IDPs). Defaults to a curated set of T1-MRI derived regions including hippocampal subfields, medial temporal lobe structures, frontal, parietal, occipital, cingulate, basal ganglia, basal forebrain, and brainstem nuclei.
outcomes: A character vector of behavioral or cognitive outcomes. Defaults to neuropsychological, global cognition, daily functioning, and Parkinson’s measures commonly used in ADNI and related studies.
domains: A character vector of functional domains used internally in the protocol (episodic memory, working memory, executive control, etc.). Defaults to the protocol’s 10+ canonical domains.
call_llm: Logical; if TRUE, the function will attempt to send the generated prompt to an LLM endpoint. Requires llm_fun. Default is FALSE.
llm_fun: Optional function of the form function(prompt) -> character. This can be a wrapper around GROQ, OpenAI, or other APIs. Required if call_llm = TRUE.

Value

If call_llm = FALSE, a character string containing the full prompt. If call_llm = TRUE, the output of the provided llm_fun.

Details

The function supports either (1) returning only the prompt text (default), or (2) sending the prompt to an LLM such as GROQ to obtain the scored table.

Examples

# Get the prompt text only
p <- idp_outcome_priors_prompt()
cat(substr(p, 1, 500))
#> You are an expert neuroscientist and brain mapper.
#> For each Imaging Derived Phenotype (IDP) × outcome pair, assign a plausibility score on a 0–1 scale, where:
#>  - 0 = no or contradictory support
#>  - 0.5 = mixed evidence (equal support and null findings)
#>  - 1 = very strong convergent support.
#> Intermediate values (e.g., 0.25, 0.7, 0.85) reflect gradient strength of evidence.
#> 
#> Scoring must follow these five evidence pillars:
#> 1. Anatomy→Function specificity (CA1/EC ↔ episodic/delayed recall; IFG/tempo

# Example with an LLM call (user must provide llm_fun)
# out <- idp_outcome_priors_prompt(call_llm = TRUE, llm_fun = my_groq_wrapper)