Package {WMFM}

Environment for caching LLM results

Description

Internal cache for equations and explanations from fitted models.

Usage

.env_cache

Format

An object of class environment of length 0.

Add a derived variable to a data frame from a single assignment line

Description

Validates and evaluates a single assignment statement such as t = 1:nrow(data) or month = factor(rep(1:12, 12)). The RHS is evaluated in a safe environment created by makeSafeEvalEnv(), so only the data columns plus a small allowlist of base functions are available.

Usage

addDerivedVariableToData(data, txt, allowOverwrite = FALSE)

Arguments

Details

The derived variable is appended to the data frame as a new column. Scalars are recycled to the number of rows; otherwise the result must have length nrow(data).

Value

A list with elements:

• ok: logical, whether the operation succeeded.

• msg: character status message.

• data: the updated data frame (if ok), otherwise the original data.

• name: the new variable name (if ok).

• transformation: derived-variable metadata (if ok).

Examples

df = data.frame(passengers = 1:144)
res = addDerivedVariableToData(df, "t = 1:nrow(data)")
res$ok
names(res$data)

res2 = addDerivedVariableToData(res$data, "month = factor(rep(1:12, 12))")
table(res2$data$month)

Add the two-by-two interaction contrast for a factor-by-factor model

Description

Add the two-by-two interaction contrast for a factor-by-factor model

Usage

addFactorByFactorDifferenceOfDifferencesRow(
  model,
  mf,
  level,
  firstFactor,
  secondFactor,
  appendRow
)

Arguments

Value

Invisibly returns NULL.

Add simple factor-difference rows within levels of another factor

Description

Add simple factor-difference rows within levels of another factor

Usage

addFactorByFactorSimpleDifferenceRows(
  model,
  mf,
  level,
  focalFactor,
  conditioningFactor,
  appendRow
)

Arguments

Value

Invisibly returns NULL.

Add fitted-quantity CI rows for a single predictor setting

Description

Add fitted-quantity CI rows for a single predictor setting

Usage

addFittedQuantityRows(
  model,
  mf,
  familyObj,
  level,
  newData,
  labelContext,
  settings,
  numericReference,
  appendRow
)

Arguments

Value

Invisibly returns NULL.

Add a response-scale factor difference row for a linear model

Description

Add a response-scale factor difference row for a linear model

Usage

addLinearFactorDifferenceRow(
  model,
  mf,
  level,
  referenceData,
  comparisonData,
  focalFactor,
  referenceLevel,
  comparisonLevel,
  contextText,
  appendRow
)

Arguments

Value

Invisibly returns NULL.

Add a response-scale difference row for a two-level linear factor

Description

Adds the direct factor comparison for a two-level linear model without interactions. The fitted-value rows remain available, while this effect row gives the student-facing difference at the same reference settings.

Usage

addLinearTwoLevelFactorComparisonRow(
  model,
  mf,
  level,
  baseInfo,
  factorName,
  appendRow
)

Arguments

Value

Invisibly returns NULL.

Add conditional odds-ratio rows within levels of another factor

Description

Add conditional odds-ratio rows within levels of another factor

Usage

addLogisticFactorByFactorConditionalOddsRatioRows(
  model,
  mf,
  level,
  focalFactor,
  conditioningFactor,
  appendRow
)

Arguments

Value

Invisibly returns NULL.

Add the two-by-two ratio-of-odds-ratios row for a logistic interaction

Description

Add the two-by-two ratio-of-odds-ratios row for a logistic interaction

Usage

addLogisticFactorByFactorRatioOfOddsRatiosRow(
  model,
  mf,
  level,
  firstFactor,
  secondFactor,
  appendRow
)

Arguments

Value

Invisibly returns NULL.

Add an odds-ratio row for a two-level logistic factor comparison

Description

Adds a direct factor-comparison row for two-level binomial-logit models. Fitted values remain available on the probability scale, while this row gives the direct odds-ratio comparison needed to answer factor-comparison questions without reasoning from separate raw group odds or interval overlap.

Usage

addLogisticTwoLevelFactorComparisonRow(
  model,
  mf,
  familyObj,
  level,
  baseInfo,
  factorName,
  appendRow
)

Arguments

Value

Invisibly returns NULL.

Add a numeric-effect CI row

Description

Add a numeric-effect CI row

Usage

addNumericEffectRow(
  model,
  mf,
  familyObj,
  level,
  weights,
  numericName,
  factorLevelText,
  appendRow
)

Arguments

Value

Invisibly returns NULL.

Application server logic

Description

Defines the server-side logic for the Model Builder app. Handles data upload, variable assignment via buckets, model fitting, calls to the language model for fitted equations and explanations, and plotting of the fitted model when appropriate.

Usage

appServer(input, output, session)

Arguments

Value

No return value; called for its side effects.

Application user interface

Description

Constructs the Shiny user interface for the Model Builder app.

Usage

appUI()

Details

The interface is organised into the main teaching and analysis tabs:

• Load: upload a data set or choose an example from the s20x package.

• Model: assign variables to roles, choose the model type, specify the model formula, and fit/reset the model.

• Fitted Model: inspect the symbolic model equation, fitted equations from the language model, and the main regression outputs.

• Model Explanation: view the plain-language explanation, an optional tutor-style expansion, and the teaching accordions that explain how the explanation was constructed.

• Plot: view the observed data with the fitted model overlaid when there is a single numeric predictor.

Value

A Shiny UI definition created with fluidPage().

Build a pure LLM score record from parsed scores

Description

Validates a parsed LLM scoring response and returns a score record containing only judged fields, score summaries, and LLM scoring metadata.

Usage

applyWmfmLlmScoresToRecord(
  parsedScores,
  modelName = NA_character_,
  rawResponse = NA_character_
)

Arguments

Value

Named list containing only scoring fields.

Build simple arithmetic transformation information

Description

Build simple arithmetic transformation information

Usage

arithmeticTransformationInfo(funName, constant, variablePosition)

Arguments

Value

Transformation information.

Coerce a WMFM scores object to a data frame

Description

Flattens a wmfmScores object into a long or wide data frame for analysis, plotting, and comparison.

Usage

## S3 method for class 'wmfmScores'
as.data.frame(
  x,
  row.names = NULL,
  optional = FALSE,
  format = c("long", "wide"),
  ...
)

Arguments

Value

A data frame.

Attach response-transformation handling metadata to a fitted model

Description

Attach response-transformation handling metadata to a fitted model

Usage

attachResponseTransformationModeToModel(
  model,
  responseTransformationMode = "both"
)

Arguments

Value

The fitted model with a wmfm_response_transformation_mode attribute.

Attach derived-variable transformation metadata to a fitted model

Description

Attach derived-variable transformation metadata to a fitted model

Usage

attachVariableTransformationsToModel(
  model,
  formula,
  variableTransformations = NULL
)

Arguments

Value

The fitted model with a wmfm_variable_transformations attribute.

Audit whether bad explanations are being penalised by the current rubric

Description

Builds a compact audit summary around a set of already graded bad explanations, with optional comparison against a graded good explanation. This is intended as a lightweight helper for diagnosing adversarial or deliberately flawed explanations that may be slipping through the current deterministic rubric.

Usage

auditBadExplanationGrading(
  x,
  goodGrade = NULL,
  method = c("deterministic", "llm"),
  minExpectedDrop = 1,
  flaggedThreshold = 9,
  expectedMetrics = NULL,
  ...
)

Arguments

Value

An object of class wmfmBadExplanationAudit.

Examples

if (interactive()) {
badGrades = grade(modelObj, explanation = badVec, method = "deterministic")
goodGrade = grade(modelObj, explanation = modelObj$explanation, method = "deterministic")

audit = auditBadExplanationGrading(
  badGrades,
  goodGrade = goodGrade,
  expectedMetrics = list(
    effectDirectionError = c("factualScore"),
    wrongScaleError = c("factualScore", "clarityScore"),
    rSquaredOverclaim = c("factualScore", "calibrationScore"),
    logicalContradiction = c("factualScore", "clarityScore")
  )
)

print(audit)
}

Back-transform one transformed-scale difference row

Description

Back-transform one transformed-scale difference row

Usage

backTransformResponseDifferenceRow(row, responseRecord)

Arguments

Value

One-row data frame or NULL.

Back-transform transformed-scale differences where mathematically safe

Description

Back-transform transformed-scale differences where mathematically safe

Usage

backTransformResponseDifferenceValues(values, inverseType)

Arguments

Value

Numeric vector.

Back-transform one fitted-value row

Description

Back-transform one fitted-value row

Usage

backTransformResponseRow(row, responseRecord, rowMeaning)

Arguments

Value

One-row data frame or NULL.

Apply an inverse response transformation to fitted values

Description

Apply an inverse response transformation to fitted values

Usage

backTransformResponseValues(values, inverseType, parameters = list())

Arguments

Value

Numeric vector.

Wrap variable names in backticks for UI display

Description

Wrap variable names in backticks for UI display

Usage

backtickNames(x)

Arguments

Value

Character vector.

Build confirm label for add-derived-variable modal.

Description

Build confirm label for add-derived-variable modal.

Usage

buildAddDerivedVariableConfirmLabel()

Value

A character scalar button label.

Build help text for add-derived-variable modal.

Description

Build help text for add-derived-variable modal.

Usage

buildAddDerivedVariableHelpText()

Value

A character scalar help text.

Build placeholder for add-derived-variable expression input.

Description

Build placeholder for add-derived-variable expression input.

Usage

buildAddDerivedVariablePlaceholder()

Value

A character scalar placeholder.

Build title for add-derived-variable modal.

Description

Build title for add-derived-variable modal.

Usage

buildAddDerivedVariableTitle()

Value

A character scalar modal title.

Build deterministic explanation scaffold for adjustment workflows

Description

Build deterministic explanation scaffold for adjustment workflows

Usage

buildAdjustmentExplanationScaffold(model, mf = NULL)

Arguments

Value

A character scalar containing a deterministic scaffold, or an empty string when no adjustment variables are selected.

Build sanitized adjustment metadata for a fitted formula

Description

Restricts selected adjustment variables to non-empty predictors present in the fitted formula so downstream prompts and summaries do not receive stale adjustment state after UI invalidations or model-type switches.

Usage

buildAdjustmentMetadata(selectedVariables, formulaPredictors)

Arguments

Value

Character vector of sanitized adjustment-variable metadata.

Build adjustment-aware scoring context text

Description

Build adjustment-aware scoring context text

Usage

buildAdjustmentScoringContextBlock(runRecord, policy = NULL)

Arguments

Value

Character scalar containing adjustment scoring context.

Build adjustment-aware scoring policy metadata

Description

Build adjustment-aware scoring policy metadata

Usage

buildAdjustmentScoringPolicy(runRecord)

Arguments

Value

A list containing normalized role metadata for scoring prompts.

Build adjustment-aware rubric guidance text

Description

Build adjustment-aware rubric guidance text

Usage

buildAdjustmentScoringRubricGuidance()

Value

Character vector of field-specific adjustment scoring guidance lines.

Build adjustment-variable guidance for explanation prompts

Description

Builds a prompt block that separates primary predictors from adjustment variables using Stage 20 adjustment metadata stored on the fitted model. The block instructs downstream explanation generation to interpret primary predictors substantively while mentioning adjustment variables only as adjusted-for controls.

Usage

buildAdjustmentVariablePromptBlock(model, mf = NULL)

Arguments

Value

A character scalar containing adjustment-variable guidance, or an empty string when no adjustment variables are present.

Build explanation-anchor audit metadata

Description

Build explanation-anchor audit metadata

Usage

buildAnchorAuditEntry(anchorInfo)

Arguments

Value

A named list suitable for audit or developer-feedback use.

Build anchored baseline fitted-value context for explanation prompts

Description

Uses the confidence-interval teaching helpers to compute baseline fitted values at the chosen numeric anchor, so the explanation prompt does not rely on the language model to derive anchored counts, odds, or means from the intercept alone.

Usage

buildAnchoredBaselinePromptBlock(model, mf = NULL, predictorNames = NULL)

Arguments

Value

A character scalar, or an empty string if no suitable anchored baseline summary is available.

Build app-side explanation text for a fitted model

Description

Build app-side explanation text for a fitted model

Usage

buildAppExplanation(model, chatProvider = NULL, useExplanationCache = TRUE)

Arguments

Value

A character string containing the generated explanation, or NULL if no explanation could be produced.

Build app-side explanation audit output for a fitted model

Description

Creates the deterministic audit trail used by the transparency panel in the app. This does not depend on an active chat provider.

Usage

buildAppExplanationAudit(model)

Arguments

Details

The returned object is expected to match the same contract used by buildModelExplanationAudit() so that later UI and teaching-summary helpers can rely on one stable audit structure.

Value

A wmfmExplanationAudit object or NULL if audit construction fails.

Build app-side equation and explanation outputs for a fitted model

Description

Centralises the logic used by the app after a model has been fitted. Deterministic equations are now the default app output. When explicitly requested, the older LLM equation path can still be used while keeping a deterministic fallback if the LLM equation request fails.

Usage

buildAppModelOutputs(
  model,
  chatProvider = NULL,
  useExplanationCache = TRUE,
  equationMethod = c("deterministic", "llm")
)

Arguments

Details

Explanations remain on the LLM path. If no chat provider is available, deterministic equations are still returned and the explanation remains empty.

The explanation audit is always built from the deterministic model-side audit helper rather than from separate app-specific audit logic.

Value

A named list with elements equations, explanation, explanationAudit, and equationMethodUsed.

Build user-facing progress text for fitted-model output generation

Description

Centralises app wording for the post-fit output pipeline so that the UI can reflect deterministic equation generation without using old LLM request language. Explanations may still be generated with a language model when one is available.

Usage

buildAppOutputMessages(
  equationMethod = c("deterministic", "llm"),
  explanationAvailable = FALSE,
  explanationRequested = FALSE
)

Arguments

Value

A named list of character strings for progress and notification text.

Build an optional tutor-style explanation of the explanation

Description

Build an optional tutor-style explanation of the explanation

Usage

buildAppTeachingTutorExplanation(
  teachingSummary,
  chatProvider = NULL,
  modelExplanation = NULL,
  researchQuestion = NULL
)

Arguments

Value

A character string or NULL.

Build message for empty average contrast groups.

Description

Build message for empty average contrast groups.

Usage

buildAverageContrastEmptyGroupMessage()

Value

A character scalar notification message.

Build message for invalid average contrast levels.

Description

Build message for invalid average contrast levels.

Usage

buildAverageContrastInvalidLevelMessage()

Value

A character scalar notification message.

Build message for overlapping average contrast levels.

Description

Build message for overlapping average contrast levels.

Usage

buildAverageContrastOverlappingLevelMessage()

Value

A character scalar notification message.

Build explanation-specific instructions for bad explanation generation

Description

Build explanation-specific instructions for bad explanation generation

Usage

buildBadExplanationInstructionBlock(plan)

Arguments

Value

A character scalar.

Build compact model context for bad explanation generation

Description

Build compact model context for bad explanation generation

Usage

buildBadExplanationModelContext(x)

Arguments

Value

A character scalar.

Build a bad explanation generation plan

Description

Build a bad explanation generation plan

Usage

buildBadExplanationPlan(
  x,
  type = "auto",
  severity = "moderate",
  n = 1,
  mixTypes = FALSE
)

Arguments

Value

A named list describing the requested generation plan.

Build an LLM prompt for generating bad explanations

Description

Build an LLM prompt for generating bad explanations

Usage

buildBadExplanationPrompt(x, baseExplanation, plan)

Arguments

Value

A character scalar containing the prompt text.

Build reference-level context for factor predictors

Description

Build reference-level context for factor predictors

Usage

buildBadExplanationReferenceLevels(x)

Arguments

Value

A character scalar describing factor predictors and their reference levels.

Build textual definitions for supported bad explanation types

Description

Build textual definitions for supported bad explanation types

Usage

buildBadExplanationTypeGuide()

Value

A character scalar.

Build message for a failed chat provider connection.

Description

Build message for a failed chat provider connection.

Usage

buildChatProviderConnectionFailedMessage(details)

Arguments

Value

A character scalar notification message.

Build the chat provider set confirmation message

Description

Build the chat provider set confirmation message

Usage

buildChatProviderSetMessage(backend, ollamaModel, ollamaThinkLow)

Arguments

Value

A character string for a notification.

Build the current chat provider status message

Description

Build the current chat provider status message

Usage

buildChatProviderStatus(backend, ollamaModel, ollamaThinkLow)

Arguments

Value

A character string for the chat provider status display.

Build message for missing example selection.

Description

Build message for missing example selection.

Usage

buildChooseExampleFirstMessage()

Value

A character scalar notification message.

Build a coefficient-only confidence-interval table

Description

Build a coefficient-only confidence-interval table

Usage

buildCoefficientOnlyConfidenceIntervalData(model, level = 0.95)

Arguments

Value

A list in the same format as buildModelConfidenceIntervalData().

Build factor-summary rows for comparison control

Description

Build factor-summary rows for comparison control

Usage

buildComparisonControlFactorSummary(mf, predictorTypes)

Arguments

Value

A data frame with one row per factor predictor.

Build comparison-control prompt text

Description

Builds deterministic prompt guidance that limits group or treatment comparisons to the scope implied by the model profile and the user-supplied research question. This keeps explanations from enumerating every pairwise comparison when a concise global summary is more appropriate.

Usage

buildComparisonControlPromptBlock(model, mf = NULL)

Arguments

Value

A character scalar containing comparison-control guidance, or an empty string if no comparison-control guidance is needed.

Build base-setting information for CI summaries

Description

Build base-setting information for CI summaries

Usage

buildConfidenceIntervalBaseInfo(mf, numericReference, predictorNames)

Arguments

Value

A list with base-row information.

Build CI notation labels for supported models

Description

Build CI notation labels for supported models

Usage

buildConfidenceIntervalNotation(model, mf)

Arguments

Value

A named list of notation labels.

Build a prediction and CI on the linear predictor scale

Description

Build a prediction and CI on the linear predictor scale

Usage

buildConfidenceIntervalPrediction(
  model,
  newData,
  level,
  numericReference = NULL
)

Arguments

Value

A list with fit, interval bounds, and non-zero weights.

Build a stable sort key for a CI display table

Description

Build a stable sort key for a CI display table

Usage

buildConfidenceIntervalSortKey(ciTable)

Arguments

Value

An integer vector.

Build a newdata grid for factor-only contrasts

Description

Constructs a newData data frame suitable for generating predictions or contrasts that vary one target factor across its levels while holding all other factor predictors constant at user-specified values.

Usage

buildContrastNewData(mf, factorPreds, targetFactor, condValues)

Arguments

Details

The function returns:

• newData: One row per level of targetFactor.

• targetLevels: The levels of targetFactor used in newData.

Value

A list with elements:

newData

A data frame with one row per level of targetFactor.

targetLevels

A character vector of the target factor levels.

Build message for too few non-zero custom contrast weights.

Description

Build message for too few non-zero custom contrast weights.

Usage

buildCustomContrastTooFewWeightsMessage()

Value

A character scalar notification message.

Build message for non-zero custom contrast weight sums.

Description

Build message for non-zero custom contrast weight sums.

Usage

buildCustomContrastWeightsMustSumToZeroMessage()

Value

A character scalar notification message.

Build message shown after clearing user data context.

Description

Build message shown after clearing user data context.

Usage

buildDataContextClearedMessage()

Value

A character scalar notification message.

Build message shown after saving user data context.

Description

Build message shown after saving user data context.

Usage

buildDataContextSavedMessage()

Value

A character scalar notification message.

Build title for the package data description modal.

Description

Build title for the package data description modal.

Usage

buildDataDescriptionTitle(datasetName = "")

Arguments

Value

A character scalar modal title.

Build message for a failed delimited file read.

Description

Build message for a failed delimited file read.

Usage

buildDelimitedFileReadFailedMessage()

Value

A character scalar notification message.

Build derived CI output for supported model structures

Description

Build derived CI output for supported model structures

Usage

buildDerivedConfidenceIntervalData(
  model,
  mf,
  level,
  numericReference,
  derivedPlan
)

Arguments

Value

A list in the same format as buildModelConfidenceIntervalData().

Build the default note for derived CI output

Description

Build the default note for derived CI output

Usage

buildDerivedModeNote(mf, numericReference)

Arguments

Value

A character scalar or NULL.

Build a deterministic equation table from a fitted model

Description

Runs the deterministic equation pipeline by building an equation specification, enumerating teaching cases, and rendering those cases into a tabular output suitable for printing or downstream storage.

Usage

buildDeterministicEquationTable(model, digits = 2)

Arguments

Details

The returned table includes a compatibility equation column containing the rendered scales collapsed into one text field, along with separate scale columns for later UI use.

Value

A data.frame with one row per displayed teaching case.

Build the incorrect developer mode password message

Description

Build the incorrect developer mode password message

Usage

buildDeveloperModeIncorrectPasswordMessage()

Value

A character string for the notification.

Build the developer mode locked message

Description

Build the developer mode locked message

Usage

buildDeveloperModeLockedMessage()

Value

A character string for the notification.

Build developer mode status text

Description

Build developer mode status text

Usage

buildDeveloperModeStatus(isUnlocked)

Arguments

Value

A character string for the developer mode status display.

Build the developer mode unlock error status text

Description

Build the developer mode unlock error status text

Usage

buildDeveloperModeUnlockErrorStatus(message)

Arguments

Value

A character string for the developer mode status display.

Build the developer mode unlocked message

Description

Build the developer mode unlocked message

Usage

buildDeveloperModeUnlockedMessage()

Value

A character string for the notification.

Build a compact developer repeated scoring export

Description

Build a compact developer repeated scoring export

Usage

buildDeveloperRepeatedScoringExport(repeatedResult, method = "deterministic")

Arguments

Value

A list suitable for JSON serialisation.

Build developer repeated scoring run table

Description

Build developer repeated scoring run table

Usage

buildDeveloperRepeatedScoringRunTable(repeatedResult)

Arguments

Value

A data frame suitable for renderTable().

Build developer repeated scoring summary table

Description

Build developer repeated scoring summary table

Usage

buildDeveloperRepeatedScoringSummaryTable(repeatedResult)

Arguments

Value

A one-row data frame suitable for renderTable().

Build a compact developer scoring grade export

Description

Build a compact developer scoring grade export

Usage

buildDeveloperScoringGradeExport(gradeObj, method = "deterministic")

Arguments

Value

A list suitable for JSON serialisation.

Build developer scoring JSON export payload

Description

Build developer scoring JSON export payload

Usage

buildDeveloperScoringJsonPayload(
  model = NULL,
  rv = NULL,
  input = NULL,
  gradeObj = NULL,
  repeatedResult = NULL,
  method = "deterministic"
)

Arguments

Value

A list suitable for JSON serialisation.

Build developer scoring JSON export text

Description

Build developer scoring JSON export text

Usage

buildDeveloperScoringJsonText(payload)

Arguments

Value

A JSON character scalar.

Build developer scoring loss table

Description

Extracts a named feedback table from a scored wmfmGrade object.

Usage

buildDeveloperScoringLossTable(gradeObj, tableName, method = "deterministic")

Arguments

Value

A data frame suitable for renderTable().

Build developer scoring metric table

Description

Extracts the metric summary from a scored wmfmGrade object.

Usage

buildDeveloperScoringMetricTable(gradeObj, method = "deterministic")

Arguments

Value

A data frame suitable for renderTable().

Build developer scoring object text

Description

Captures the printed summary of a scored wmfmGrade object for developer inspection.

Usage

buildDeveloperScoringObjectText(gradeObj)

Arguments

Value

A character scalar.

Build developer scoring repeated-run progress text

Description

Build developer scoring repeated-run progress text

Usage

buildDeveloperScoringProgressText(completed, total, elapsedSeconds)

Arguments

Value

A character scalar.

Extracts semantic evidence diagnostics from a scored wmfmGrade object.

Description

Extracts semantic evidence diagnostics from a scored wmfmGrade object.

Usage

buildDeveloperScoringSemanticEvidenceTable(gradeObj, method = "deterministic")

Arguments

Value

A semantic evidence diagnostics data frame, or NULL.

Build developer scoring summary table

Description

Converts a scored wmfmGrade object into a compact one-row table for the developer scoring and grading panel.

Usage

buildDeveloperScoringSummaryTable(gradeObj, method = "deterministic")

Arguments

Value

A data frame suitable for renderTable().

Build a WMFM model object for developer scoring

Description

The app stores the current fitted model as a native fitted model object. The grading API is intentionally defined on wmfmModel, so this helper wraps the current app state in the same classed object before calling grade().

Usage

buildDeveloperScoringWmfmModel(model, rv, input, explanationText = NULL)

Arguments

Value

A wmfmModel object, or NULL when the current state is incomplete.

Build message for duplicate pairwise contrast requests.

Description

Build message for duplicate pairwise contrast requests.

Usage

buildDuplicateContrastPairMessage()

Value

A character scalar notification message.

Build eligible adjustment variables from predictor buckets

Description

Returns factor and numeric predictors that are currently eligible to be marked as adjustment variables. The response variable is always excluded.

Usage

buildEligibleAdjustmentVariables(
  responseVariable,
  factorVariables,
  continuousVariables
)

Arguments

Value

Character vector of eligible adjustment variables.

Build deterministic teaching cases from an equation specification

Description

Enumerates the displayed teaching cases implied by a deterministic equation specification. A case represents one condition to be shown later by the rendering layer, such as a general equation, one factor level, or one factor-level combination.

Usage

buildEquationCases(spec)

Arguments

Details

The current policy is intentionally simple:

• intercept-only and numeric-only models produce one general case

• models with one or more factor predictors produce one case per factor level combination

• numeric predictors are retained symbolically within each case rather than substituted

This helper decides which cases to show, but it does not render any algebra or response-scale expressions.

Value

A list of class "wmfmEquationCases" containing one element per displayed case.

Collapse coefficient components into a displayable expression term

Description

Builds one deterministic algebra term from one or more coefficient components. The result carries its own sign so later joining can avoid malformed patterns such as "+ (-1.23)".

Usage

buildEquationComponentText(values, variable = NULL, digits = 2)

Arguments

Value

A character scalar.

Build adjustment-role metadata for fitted equation display

Description

Creates metadata describing which predictors are primary versus adjustment variables while preserving the original fitted formula terms. This helper is display-focused only and does not alter model fitting, model matrices, or stored model objects.

Usage

buildEquationDisplayRoleMetadata(model)

Arguments

Value

A list containing predictor grouping metadata for equation display.

Build UI summary text for fitted equation role metadata

Description

Formats concise text describing which predictors are primary and which are adjustment variables so the fitted-equation display can label term roles without hiding any fitted terms.

Usage

buildEquationDisplayRoleSummary(roleMetadata)

Arguments

Value

Character vector of summary lines for display.

Build a deterministic equation specification from a fitted model

Description

Extracts the core structural information needed by a deterministic equation renderer. The returned specification is intended to separate model inspection from later case enumeration and string rendering.

Usage

buildEquationSpec(model)

Arguments

Details

The specification includes:

• model family and link

• response-variable name

• predictor metadata, including factor levels and reference levels

• coefficient estimates

• interaction metadata based on the fitted formula terms

This helper is intentionally conservative. It aims to describe the fitted model clearly, not to perform symbolic algebra.

Value

A list of class "wmfmEquationSpec".

Build the example ready status message

Description

Build the example ready status message

Usage

buildExampleReadyStatus()

Value

A character string for the example load status display.

Build a deterministic claim-to-evidence map for a model explanation

Description

Creates a student-safe, inspectable mapping from the final explanation text back to the deterministic evidence used to support it. The mapping is built from sentence-level units in the final explanation and links each sentence to evidence categories drawn from the explanation audit and teaching summary.

Usage

buildExplanationClaimEvidenceMap(
  explanationText,
  audit,
  teachingSummary = NULL,
  model = NULL
)

Arguments

Details

This object is intentionally not presented as hidden chain-of-thought. It is a transparent post hoc map showing which deterministic ingredients best match the visible explanation text.

The current implementation uses a tag-first hybrid approach:

• deterministic sentence-level claim tags from the audit and teaching summary

• lightweight sentence-level evidence matching against the final explanation text

• a derived legacy single-label claimType field kept for compatibility

Value

An object of class wmfmExplanationClaimEvidenceMap.

Build a combined plain-language support note for a mapped claim

Description

Build a combined plain-language support note for a mapped claim

Usage

buildExplanationClaimSupportNote(
  claimTags,
  matchedEvidence,
  supportNotes = NULL
)

Arguments

Value

A single character string.

Build plain-language support notes for a mapped claim

Description

Build plain-language support notes for a mapped claim

Usage

buildExplanationClaimSupportNotes(claimTags, matchedEvidence)

Arguments

Value

Character vector.

Build deterministic quality flags for a mapped explanation sentence

Description

Applies lightweight deterministic checks to a visible sentence. These flags are intended for developer feedback and validation. They do not change the explanation text and they do not replace the legacy claim-tag fields.

Usage

buildExplanationDeterministicQualityFlags(claimText, roles = character(0))

Arguments

Value

Character vector of quality-flag identifiers.

Build a deterministic evidence inventory for explanation mapping

Description

Build a deterministic evidence inventory for explanation mapping

Usage

buildExplanationEvidenceInventory(audit, teachingSummary = NULL, model = NULL)

Arguments

Value

A data frame.

Build deterministic quality flags for a claim-evidence map

Description

These map-level flags summarize omissions or structural problems across all mapped explanation sentences. They are deliberately conservative so Stage 9.6 adds developer-facing diagnostics without changing existing tagging behavior.

Usage

buildExplanationMapQualityFlags(claimsTable)

Arguments

Value

Character vector of quality-flag identifiers.

Build deterministic model-profile metadata for explanations

Description

Builds a compact model profile that can be shared by explanation prompts, deterministic formatting, auditing, validation, and developer feedback. The profile describes the fitted model structure without changing the existing explanation-audit or claim-evidence systems.

Usage

buildExplanationModelProfile(model, data = NULL, modelType = NULL)

Arguments

Value

A named list with deterministic model-profile metadata.

Build explanation provenance footer text

Description

Build explanation provenance footer text

Usage

buildExplanationProvenanceText(
  providerLabel,
  modelName = NULL,
  generatedAt = Sys.time()
)

Arguments

Value

Character scalar provenance text.

Build deterministic model-aware explanation rules

Description

Converts explanation model-profile metadata into a compact set of deterministic rules for later prompt construction, validation, and developer feedback. This function does not generate explanation text and does not call an LLM. It records the scale, comparison scope, skeleton, language guidance, avoided terms, and quality flags implied by the model profile.

Usage

buildExplanationRuleProfile(modelProfile)

Arguments

Value

A named list of deterministic model-aware explanation rules.

Build model-aware explanation skeleton text for prompt input

Description

Builds a deterministic prompt block from the Stage 9 model profile and rule profile. The block gives the language model an ordered explanation structure while leaving the wording of the student-facing explanation to the model.

Usage

buildExplanationSkeletonPromptBlock(model, mf = NULL)

Arguments

Value

A character scalar containing model-aware skeleton instructions, or an empty string if a skeleton cannot be built.

Build the starting-values teaching text

Description

Build the starting-values teaching text

Usage

buildExplanationTeachingBaselineChoice(
  audit,
  numericPredictors,
  factorPredictors
)

Arguments

Value

A single character string.

Build a plain-language description of the data used

Description

Build a plain-language description of the data used

Usage

buildExplanationTeachingDataDescription(
  model,
  responseName,
  numericPredictors,
  factorPredictors,
  outcomeLabel
)

Arguments

Value

A single character string.

Build the teaching evidence list

Description

Build the teaching evidence list

Usage

buildExplanationTeachingEvidenceTable(
  audit,
  responseName,
  outcomeLabel,
  numericPredictors,
  factorPredictors,
  researchQuestion,
  dataDescription
)

Arguments

Value

A data frame.

Build the interpretation teaching text

Description

Build the interpretation teaching text

Usage

buildExplanationTeachingInterpretationScale(audit, outcomeLabel)

Arguments

Value

A single character string.

Build the main-effect teaching text

Description

Build the main-effect teaching text

Usage

buildExplanationTeachingMainEffectDescription(
  audit,
  responseName,
  outcomeLabel,
  numericPredictors,
  factorPredictors
)

Arguments

Value

A single character string.

Format a teaching number for inline prose

Description

Format a teaching number for inline prose

Usage

buildExplanationTeachingNumber(x, digits = 2)

Arguments

Value

A single character string.

Build a student-friendly outcome label

Description

Build a student-friendly outcome label

Usage

buildExplanationTeachingOutcomeLabel(responseNounPhrase)

Arguments

Value

A single character string.

Build the research-question teaching text

Description

Build the research-question teaching text

Usage

buildExplanationTeachingResearchQuestionLink(
  researchQuestion,
  responseName,
  outcomeLabel
)

Arguments

Value

A single character string.

Build a student-facing teaching summary for a model explanation

Description

Derives a plain-language teaching summary from the deterministic explanation audit. The returned object is designed for student-facing display and avoids exposing raw prompt ingredients or developer-facing internal structures.

Usage

buildExplanationTeachingSummary(audit, model, researchQuestion = NULL)

Arguments

Value

An object of class wmfmExplanationTeachingSummary.

Build the uncertainty teaching text

Description

Build the uncertainty teaching text

Usage

buildExplanationTeachingUncertaintySummary(audit, outcomeLabel)

Arguments

Value

A single character string.

Build the derived-variable transformation teaching text

Description

Build the derived-variable transformation teaching text

Usage

buildExplanationTeachingVariableTransformationSummary(audit)

Arguments

Value

A single character string.

Build the x-change teaching text

Description

Build the x-change teaching text

Usage

buildExplanationTeachingXChangeDescription(
  numericPredictors,
  factorPredictors,
  outcomeLabel
)

Arguments

Value

A single character string.

Build a constrained tutor-style prompt for explaining the explanation

Description

Uses the deterministic teaching summary as the main source of truth for an optional, more conversational explanation of how the model explanation was constructed. This avoids exposing raw audit internals and constrains the language model to the information already shown in the app.

Usage

buildExplanationTutorPrompt(
  teachingSummary,
  modelExplanation = NULL,
  researchQuestion = NULL
)

Arguments

Value

A single character string prompt.

Build CI rows for two-factor linear-model interactions

Description

Build CI rows for two-factor linear-model interactions

Usage

buildFactorByFactorInteractionConfidenceIntervalRows(
  model,
  mf,
  familyObj,
  level,
  baseInfo,
  factorNames,
  appendRow
)

Arguments

Value

Invisibly returns NULL.

Build new-data rows for a two-factor comparison

Description

Build new-data rows for a two-factor comparison

Usage

buildFactorByFactorNewData(
  mf,
  focalFactor,
  focalLevel,
  conditioningFactor,
  conditioningLevel
)

Arguments

Value

A one-row data frame.

Build fitted-equation content UI

Description

Renders fitted-equation content for supported equation output structures while consistently prepending the predictor-role summary when available.

Usage

buildFittedEquationContentUi(eq, roleSummaryUi = NULL)

Arguments

Value

A shiny.tag or shiny.tag.list object.

Build fitted-equation role summary UI

Description

Builds the predictor-role summary block used above fitted equations when adjustment-variable metadata is present.

Usage

buildFittedEquationRoleSummaryUi(roleSummary)

Arguments

Value

A shiny.tag object, or NULL when no summary should be shown.

Build a fitted-quantity label

Description

Build a fitted-quantity label

Usage

buildFittedQuantityLabel(labelContext, notation, quantityType = NULL)

Arguments

Value

A character scalar.

Build formatted explanation quantities for prompt input

Description

Builds a student-ready prompt block from deterministic confidence-interval evidence. Raw coefficients and raw confidence-interval matrices should stay in audit/developer metadata; this block is for the language model prompt.

Usage

buildFormattedPromptQuantityBlock(model, mf = NULL, predictorNames = NULL)

Arguments

Value

A character scalar containing formatted prompt quantities, or an empty string if no deterministic quantity table can be built.

Build student-facing notation for GLM teaching output

Description

Creates a small bundle of notation strings used in equations and confidence interval output for common GLM families.

Usage

buildGlmTeachingNotation(model)

Arguments

Details

For binomial models, the helper extracts the response-variable name and the two observed outcome levels from the model response and returns labels such as "Pr(outcome = success)" and "Odds(outcome = success)". The second level is treated as the success level to match R's usual treatment coding for a two-level factor response.

For Poisson models, the helper returns labels based on the response-variable name, such as "E[count]".

Value

A named list of notation strings.

Build the default example load status message

Description

Build the default example load status message

Usage

buildInitialExampleLoadStatus()

Value

A character string for the example load status display.

Build the initial package scan status message

Description

Build the initial package scan status message

Usage

buildInitialPackageScanStatus(initialPackageChoices)

Arguments

Value

A character string for the package scan status display.

Build interpretation-mode banner text for adjustment workflows

Description

Returns a compact interpretation-mode label shown near explanation surfaces when adjustment variables are selected.

Usage

buildInterpretationModeLabel(adjustmentVariables)

Arguments

Value

Character scalar banner text, or NULL when no adjustment variables are selected.

Build message for invalid custom contrast weights.

Description

Build message for invalid custom contrast weights.

Usage

buildInvalidCustomContrastWeightMessage()

Value

A character scalar notification message.

Build a CI for a linear combination of coefficients

Description

Build a CI for a linear combination of coefficients

Usage

buildLinearCombinationInterval(model, weights, level)

Arguments

Value

A list with estimate, bounds, and weights.

Build readable text for a linear combination of coefficients

Description

Build readable text for a linear combination of coefficients

Usage

buildLinearCombinationText(nonZero)

Arguments

Value

A character scalar.

Build readable variance text for a linear combination

Description

Build readable variance text for a linear combination

Usage

buildLinearCombinationVarianceText(nonZero)

Arguments

Value

A character scalar.

Build message for recoding a binary factor response for linear regression.

Description

Build message for recoding a binary factor response for linear regression.

Usage

buildLinearModelBinaryFactorRecodingMessage(responseName, levels)

Arguments

Value

A character scalar notification message.

Build cache key for plain-language explanation generation

Description

Build cache key for plain-language explanation generation

Usage

buildLmExplanationCacheKey(
  formulaStr,
  coefStr,
  numericAnchorCacheKey,
  researchQuestion,
  followupQuestion = "",
  adjustmentVariables = character(0)
)

Arguments

Value

Character scalar cache key.

Build term-evidence guidance for explanation prompts

Description

Uses the linear-model ANOVA table as internal guidance for which additive or interaction terms deserve emphasis in the student-facing explanation. The block is prompt-side guidance only: explanations should not report p-values or ANOVA mechanics directly to students.

Usage

buildLmTermEvidencePromptBlock(model, mf = NULL, alpha = 0.05)

Arguments

Value

A character scalar containing prompt guidance, or an empty string when term-level evidence is unavailable or not applicable.

Build message shown when data is required before opening model help.

Description

Build message shown when data is required before opening model help.

Usage

buildLoadDataFirstMessage()

Value

A character scalar notification message.

Build status text for a successfully loaded example.

Description

Build status text for a successfully loaded example.

Usage

buildLoadedExampleStatus(exampleName)

Arguments

Value

A character scalar status message.

Build the loading examples choice label

Description

Build the loading examples choice label

Usage

buildLoadingExampleChoice()

Value

A named character vector for the temporary example selector choice.

Build message for non-binary character logistic responses.

Description

Build message for non-binary character logistic responses.

Usage

buildLogisticCharacterResponseMessage(responseName, nValues)

Arguments

Value

A character scalar notification message.

Build message for non-binary factor logistic responses.

Description

Build message for non-binary factor logistic responses.

Usage

buildLogisticFactorResponseMessage(responseName, nLevels)

Arguments

Value

A character scalar notification message.

Build message for numeric logistic responses with values other than 0/1.

Description

Build message for numeric logistic responses with values other than 0/1.

Usage

buildLogisticNumericResponseMessage(responseName, values)

Arguments

Value

A character scalar notification message.

Build message for unsupported logistic response types.

Description

Build message for unsupported logistic response types.

Usage

buildLogisticUnsupportedResponseMessage()

Value

A character scalar notification message.

Build summary statistics for metric diagnosis

Description

Internal helper for diagnose().

Usage

buildMetricDiagnosisSummary(metricDf, metric)

Arguments

Value

A one-row data frame.

Build metric-specific evidence summary for diagnosis

Description

Internal helper for diagnose() that creates a compact, metric-aware evidence summary from the run-level diagnosis data.

Usage

buildMetricEvidenceSummary(metricDf, metric)

Arguments

Details

The initial implementation focuses on fields that are especially useful for diagnosing disagreement on numericExpressionAdequate. For other metrics, the function returns a lighter generic summary.

Value

A one-row data frame containing metric-specific summary fields.

Build startup guidance for missing provider configuration

Description

Build startup guidance for missing provider configuration

Usage

buildMissingProviderStartupMessage()

Value

Character scalar.

Build message for a missing custom text separator.

Description

Build message for a missing custom text separator.

Usage

buildMissingSeparatorMessage()

Value

A character scalar notification message.

Build interpretable confidence-interval output for a fitted model

Description

Creates a compact table of confidence intervals for quantities that are easier for students to interpret than a raw coefficient table. For supported models, the helper prefers derived teaching rows such as fitted quantities at simple reference settings and one-unit covariate effects on the most natural teaching scale. When the model structure is too complex for a stable derived summary, the helper falls back to a coefficient table.

Usage

buildModelConfidenceIntervalData(
  model,
  level = 0.95,
  numericReference = c("mean", "zero")
)

Arguments

Details

Derived mode currently supports:

• models with no interaction terms

• models with exactly one factor predictor, one numeric predictor, and one interaction term between them

All other interaction structures fall back to coefficient mode.

Value

A list with components:

table

A data frame ready for display in the confidence-interval tab.

details

A list of labelled derivation records for drill-down display.

note

Optional explanatory note for the UI.

teachingNote

Optional short teaching note about variance and covariance.

vcovTable

The variance-covariance matrix rounded for display.

mode

Either "derived" or "coefficient".

Build choices for the confidence-interval row selector

Description

Build choices for the confidence-interval row selector

Usage

buildModelConfidenceIntervalRowChoices(ciData)

Arguments

Value

A named character vector suitable for selectInput().

Build a short teaching note for confidence-interval drill-down

Description

Build a short teaching note for confidence-interval drill-down

Usage

buildModelConfidenceIntervalTeachingNote(model)

Arguments

Value

A character scalar.

Build a deterministic audit trail for a model explanation

Description

Creates a structured, student-facing summary of the deterministic inputs, interpretation choices, and supporting model quantities used when WMFM asks the language model to write a plain-language explanation.

Usage

buildModelExplanationAudit(model)

Arguments

Details

This audit is intentionally not presented as hidden reasoning or private chain-of-thought. Instead, it records inspectable ingredients such as prompt rules, interpretation scale, numeric anchors, reference levels, and confidence-interval evidence.

The returned object is expected to follow a stable top-level contract with sections for overview metadata, prompt inputs, prompt rules, interpretation-scale metadata, numeric anchors, reference levels, confidence-interval summary, baseline and effect evidence, coefficient data, and raw prompt ingredients.

Value

An object of class wmfmExplanationAudit.

Build a model coefficient table while muffling known perfect-fit warnings

Description

Build a model coefficient table while muffling known perfect-fit warnings

Usage

buildModelExplanationAuditCoefficientTable(model)

Arguments

Value

A data frame of coefficient summaries.

Build explanation-audit confidence-interval summary

Description

Build explanation-audit confidence-interval summary

Usage

buildModelExplanationAuditConfidenceIntervals(ciData)

Arguments

Value

A named list.

Build explanation-audit evidence table for CI sections

Description

Build explanation-audit evidence table for CI sections

Usage

buildModelExplanationAuditEvidenceTable(ciData, section)

Arguments

Value

A data frame.

Build explanation-audit numeric-anchor summary

Description

Build explanation-audit numeric-anchor summary

Usage

buildModelExplanationAuditNumericAnchor(
  model,
  mf,
  predictorNames,
  numericAnchorInfo
)

Arguments

Value

A named list.

Build explanation-audit overview metadata

Description

Build explanation-audit overview metadata

Usage

buildModelExplanationAuditOverview(model, mf, predictorNames, responseName)

Arguments

Value

A named list.

Build explanation-audit prompt-input metadata

Description

Build explanation-audit prompt-input metadata

Usage

buildModelExplanationAuditPromptInputs(model, mf, predictorNames, responseName)

Arguments

Value

A named list.

Build explanation-audit prompt-rule summary

Description

Build explanation-audit prompt-rule summary

Usage

buildModelExplanationAuditPromptRules(model)

Arguments

Value

A character vector of concise prompt-side rules.

Build explanation-audit reference-level summary

Description

Build explanation-audit reference-level summary

Usage

buildModelExplanationAuditReferenceLevels(mf, predictorNames)

Arguments

Value

A data frame.

Build explanation-audit interpretation-scale metadata

Description

Build explanation-audit interpretation-scale metadata

Usage

buildModelExplanationAuditScaleInfo(model)

Arguments

Value

A named list.

Build explanation-audit rows for derived-variable transformations

Description

Converts fitted-model transformation records into a compact data frame for the explanation audit. This is intentionally descriptive only; it does not perform numerical back-transformation.

Usage

buildModelExplanationAuditVariableTransformations(model)

Arguments

Value

A data frame with one row per fitted derived-variable transformation.

Build bounded follow-up model-question block for explanation prompts

Description

Build bounded follow-up model-question block for explanation prompts

Usage

buildModelFollowupPromptBlock(followupPayload = NULL, followupQuestion = NULL)

Arguments

Value

Character scalar prompt block. Empty when no follow-up question is provided.

Build numeric-anchor metadata for model prompts and cache keys

Description

Summarises the observed range and the chosen teaching anchor for each numeric predictor so prompt builders can avoid interpreting model quantities at meaningless values such as 0 when 0 lies well outside the data.

Usage

buildModelNumericAnchorInfo(model = NULL, mf = NULL, predictorNames = NULL)

Arguments

Value

A list with elements numericReference, promptText, and cacheKey.

Build deterministic model-plot data

Description

Build deterministic model-plot data

Usage

buildModelPlotData(model, plotType = c("observedFitted", "residualFitted"))

Arguments

Value

A list containing plot metadata and a data frame.

Build a file name for exported model plots

Description

Build a file name for exported model plots

Usage

buildModelPlotDownloadFilename(
  plotType = c("observedFitted", "residualFitted", "unsupported")
)

Arguments

Value

A PNG file name for the selected model plot.

Build model-plot axis labels

Description

Build model-plot axis labels

Usage

buildModelPlotLabels(responseName, plotFamily, plotType, residualType)

Arguments

Value

A named list of plot labels.

Build a short model-plot summary sentence

Description

Build a short model-plot summary sentence

Usage

buildModelPlotSummaryText(
  model,
  plotType = c("observedFitted", "residualFitted", "unsupported")
)

Arguments

Value

A single character string for the Model plots UI.

Build a short teaching note for a model plot

Description

Build a short teaching note for a model plot

Usage

buildModelPlotTeachingNote(
  model,
  plotType = c("observedFitted", "residualFitted")
)

Arguments

Value

A named list with short explanatory strings.

Build available model-plot choices

Description

Build available model-plot choices

Usage

buildModelPlotTypeChoices(model)

Arguments

Value

A named character vector suitable for selectInput().

Build coefficient weights for a difference between two new-data rows

Description

Build coefficient weights for a difference between two new-data rows

Usage

buildNewDataDifferenceWeights(model, referenceData, comparisonData)

Arguments

Value

A named numeric vector of non-zero coefficient weights.

Build message for missing pairwise contrast entries.

Description

Build message for missing pairwise contrast entries.

Usage

buildNoContrastPairsMessage()

Value

A character scalar notification message.

Build message for missing contrast removal selection.

Description

Build message for missing contrast removal selection.

Usage

buildNoContrastSelectionMessage()

Value

A character scalar notification message.

Build message for an RDA or RData file without a data frame.

Description

Build message for an RDA or RData file without a data frame.

Usage

buildNoDataFrameInRdaMessage()

Value

A character scalar notification message.

Build CI rows for models without interactions

Description

Build CI rows for models without interactions

Usage

buildNoInteractionConfidenceIntervalRows(
  model,
  mf,
  familyObj,
  level,
  baseInfo,
  appendRow
)

Arguments

Value

Invisibly returns NULL.

Build message for missing language model fallback.

Description

Build message for missing language model fallback.

Usage

buildNoLanguageModelAvailableMessage()

Value

A character scalar notification message.

Build the no package datasets status message

Description

Build the no package datasets status message

Usage

buildNoPackageDatasetsStatus()

Value

A character string for the package dataset status display.

Build a short UI note about numeric interpretation anchors

Description

Returns a concise note for student-facing UI sections when a fitted model has numeric predictors. The note explains whether baseline fitted values are being described at 0 or at sample means.

Usage

buildNumericAnchorUiNote(model = NULL, mf = NULL, predictorNames = NULL)

Arguments

Value

A character scalar. Returns "" when no numeric predictors are present.

Build cancel label for numeric-as-factor confirmation modal.

Description

Build cancel label for numeric-as-factor confirmation modal.

Usage

buildNumericFactorCancelLabel()

Value

A character scalar button label.

Build confirm label for numeric-as-factor confirmation modal.

Description

Build confirm label for numeric-as-factor confirmation modal.

Usage

buildNumericFactorConfirmLabel()

Value

A character scalar button label.

Build body text for numeric-as-factor confirmation modal.

Description

Build body text for numeric-as-factor confirmation modal.

Usage

buildNumericFactorConfirmMessage(variableName)

Arguments

Value

A character scalar modal body.

Build title for numeric-as-factor confirmation modal.

Description

Build title for numeric-as-factor confirmation modal.

Usage

buildNumericFactorConfirmTitle()

Value

A character scalar modal title.

Build text describing other predictors at base settings

Description

Build text describing other predictors at base settings

Usage

buildOtherBaseSettingsText(
  mf,
  baseRow,
  excludeVarName = NULL,
  numericReference
)

Arguments

Value

A character scalar.

Build the package dataset checking status message

Description

Build the package dataset checking status message

Usage

buildPackageDatasetCheckingStatus(packageName)

Arguments

Value

A character string for the package dataset status display.

Build the default package dataset status message

Description

Build the default package dataset status message

Usage

buildPackageDatasetChoiceStatus()

Value

A character string for the package dataset status display.

Build the package dataset empty choice label

Description

Build the package dataset empty choice label

Usage

buildPackageDatasetEmptyChoiceLabel()

Value

A character string for the disabled dataset choice label.

Build the package dataset empty status message

Description

Build the package dataset empty status message

Usage

buildPackageDatasetEmptyStatus(packageName)

Arguments

Value

A character string for the package dataset status display.

Build the package dataset loading notification message

Description

Build the package dataset loading notification message

Usage

buildPackageDatasetFindingMessage(packageName)

Arguments

Value

A character string for the package dataset loading notification.

Build the package dataset found status message

Description

Build the package dataset found status message

Usage

buildPackageDatasetFoundStatus(packageName, datasetNames)

Arguments

Value

A character string for the package dataset status display.

Build message for a package dataset loading failure.

Description

Build message for a package dataset loading failure.

Usage

buildPackageDatasetLoadFailedMessage(datasetName, packageName)

Arguments

Value

A character scalar notification message.

Build the startup package dataset pending status message

Description

Build the startup package dataset pending status message

Usage

buildPackageDatasetPendingScanStatus()

Value

A character string for the package dataset status display.

Build the package list updating status message

Description

Build the package list updating status message

Usage

buildPackageListUpdatingStatus()

Value

A character string for the package scan status display.

Build the package scan completion status message

Description

Build the package scan completion status message

Usage

buildPackageScanCompleteStatus(packageNames, initialPackageChoices)

Arguments

Value

A character string, or NULL when no status message is needed.

Build message for Poisson response warnings.

Description

Build message for Poisson response warnings.

Usage

buildPoissonResponseWarningMessage()

Value

A character scalar notification message.

Build validation-guard prompt guidance

Description

Builds deterministic prompt guidance from the Stage 9 validation targets. The guard is deliberately prompt-side and diagnostic only: it asks the language model to avoid known failure modes, while leaving automatic regeneration for a later stage.

Usage

buildPromptValidationGuardBlock(model, mf = NULL)

Arguments

Value

A character scalar containing validation-guard prompt guidance.

Build validation-guard target rows

Description

Build validation-guard target rows

Usage

buildPromptValidationGuardTargets(modelProfile = NULL, ruleProfile = NULL)

Arguments

Value

A data frame with flag and label columns.

Build help text for the user data context modal.

Description

Build help text for the user data context modal.

Usage

buildProvideDataContextHelpText()

Value

A character scalar help text.

Build placeholder text for the user data context modal.

Description

Build placeholder text for the user data context modal.

Usage

buildProvideDataContextPlaceholder()

Value

A character scalar placeholder text.

Build title for the user data context modal.

Description

Build title for the user data context modal.

Usage

buildProvideDataContextTitle()

Value

A character scalar modal title.

Build provider credential guidance text for settings

Description

Build provider credential guidance text for settings

Usage

buildProviderCredentialGuidance(provider)

Arguments

Value

Character vector of concise guidance lines for the selected provider.

Build provider credential status lines for settings

Description

Build provider credential status lines for settings

Usage

buildProviderCredentialStatusLines(provider)

Arguments

Value

Character vector describing whether credentials are detected and where they are expected.

Build provider settings UI state

Description

Build provider settings UI state

Usage

buildProviderSettingsState()

Value

Named list containing config-location details, provider status, and the resolved non-secret provider config values used by the settings UI.

Build provider settings status text lines

Description

Build provider settings status text lines

Usage

buildProviderSettingsStatusLines(settingsState)

Arguments

Value

Character vector of status lines for display in the settings UI.

Build a response back-transformation availability note

Description

Build a response back-transformation availability note

Usage

buildResponseBackTransformationAvailabilityNote(responseRecord, rows)

Arguments

Value

Character scalar.

Build response back-transformation mode guidance

Description

Build response back-transformation mode guidance

Usage

buildResponseBackTransformationModeGuidance(payload)

Arguments

Value

Character vector of prompt guidance lines.

Build deterministic response back-transformation metadata

Description

Uses recorded derived-variable metadata to construct conservative prompt payloads for models where the response variable itself was user-created from another variable. The helper only reports quantities WMFM can compute deterministically; it does not ask the language model to infer an inverse.

Usage

buildResponseBackTransformationPayload(model, mf = NULL, predictorNames = NULL)

Arguments

Value

A list describing availability and any original-response-scale rows.

Build response back-transformation prompt guidance

Description

Build response back-transformation prompt guidance

Usage

buildResponseBackTransformationPromptBlock(
  model,
  mf = NULL,
  predictorNames = NULL,
  payload = NULL
)

Arguments

Value

Character scalar prompt block.

Build safe response back-transformation rows

Description

Build safe response back-transformation rows

Usage

buildResponseBackTransformationRows(ciTable, responseRecord)

Arguments

Value

Data frame of back-transformed rows.

Build response-scale control guidance for explanation prompts

Description

Builds deterministic prompt guidance from the Stage 9 model profile and rule profile so the language model explains the fitted model on the intended student-facing scale rather than on the raw coefficient or link-function scale.

Usage

buildResponseScaleControlPromptBlock(model, mf = NULL)

Arguments

Value

A character scalar containing response-scale prompt guidance, or an empty string if the profile cannot be built.

Build the missing s20x package dataset choice label

Description

Build the missing s20x package dataset choice label

Usage

buildS20xPackageMissingChoiceLabel()

Value

A character string for the disabled dataset choice label.

Build the missing s20x package dataset status message

Description

Build the missing s20x package dataset status message

Usage

buildS20xPackageMissingStatus()

Value

A character string for the package dataset status display.

Build message for identical pairwise contrast levels.

Description

Build message for identical pairwise contrast levels.

Usage

buildSameContrastLevelsMessage()

Value

A character scalar notification message.

Generate language rules for interpreting a linear contrast

Description

This helper constructs a short, deterministic set of language constraints to guide natural-language interpretation of a contrast. The rules are designed to enforce wording that is consistent with the model scale (identity, log, logit, etc.) and any transformation applied to the response in an lm() model.

Usage

buildScalePhrasingRules(
  isGlm,
  effectiveScale,
  respTransform,
  nounPhrase = NULL
)

Arguments

Details

The returned text is intended to be embedded verbatim in an LLM prompt to prevent inconsistent phrasing (e.g., additive vs multiplicative language).

Value

A single character string containing bullet-point language rules. The text is suitable for direct inclusion in an LLM prompt.

Examples

buildScalePhrasingRules(
  isGlm = FALSE,
  effectiveScale = "identity",
  respTransform = "none"
)

buildScalePhrasingRules(
  isGlm = TRUE,
  effectiveScale = "logit",
  respTransform = "none",
  nounPhrase = "disease status"
)

Build secondary-scale columns for a CI table

Description

Build secondary-scale columns for a CI table

Usage

buildSecondaryConfidenceIntervalColumns(modelFramework, ciTable)

Arguments

Value

A list of numeric vectors.

Build message for a selected object that is not a data frame.

Description

Build message for a selected object that is not a data frame.

Usage

buildSelectedObjectNotDataFrameMessage()

Value

A character scalar notification message.

Build CI rows for supported simple interactions

Description

Build CI rows for supported simple interactions

Usage

buildSimpleInteractionConfidenceIntervalRows(
  model,
  mf,
  familyObj,
  level,
  baseInfo,
  factorName,
  numericName,
  appendRow
)

Arguments

Value

Invisibly returns NULL.

Build coefficient weights for a simple interaction slope

Description

Build coefficient weights for a simple interaction slope

Usage

buildSimpleInteractionSlopeWeights(model, factorName, factorLevel, numericName)

Arguments

Value

A named numeric vector.

Build the startup notification message

Description

Build the startup notification message

Usage

buildStartupDataChoicesMessage()

Value

A character string for the startup notification.

Build message for too many predictors in the fitted model formula.

Description

Build message for too many predictors in the fitted model formula.

Usage

buildTooManyPredictorsMessage(predictorNames)

Arguments

Value

A character scalar notification message.

Build the unknown chat provider message

Description

Build the unknown chat provider message

Usage

buildUnknownChatProviderMessage()

Value

A character string for an error notification.

Build message for unknown model type errors.

Description

Build message for unknown model type errors.

Usage

buildUnknownModelTypeMessage()

Value

A character scalar notification message.

Build message for an unsupported upload file type.

Description

Build message for an unsupported upload file type.

Usage

buildUnsupportedUploadFileTypeMessage()

Value

A character scalar notification message.

Build a per-variable summary for a data frame

Description

Creates a compact summary of each column in a data frame, intended for display in a Shiny "data help" panel. For each variable, the summary includes its name, class, number of missing values, and a short "details" string:

• Factors: levels (up to maxLevels)

• Numeric/integer: range (min to max) computed on non-missing values

• Character/logical: a small sample of unique non-missing values (up to maxUnique)

• Other types: a brief note based on class

Usage

buildVarSummary(df, maxLevels = 30, maxUnique = 12)

Arguments

Value

A data frame with one row per column of df and columns:

var

Variable name.

class

First class label (e.g., "numeric", "factor").

missing

Count of NA values.

details

A short human-readable summary string.

Build a prompt block describing fitted derived-variable transformations

Description

Build a prompt block describing fitted derived-variable transformations

Usage

buildVariableTransformationPromptBlock(variableTransformations = NULL)

Arguments

Value

Character scalar prompt block.

Build run-level paired comparison data for WMFM scores

Description

Creates run-level paired data for all metrics in the registry that are present in two score data frames. The returned object is intended to support downstream summaries and plotting.

Usage

buildWmfmComparisonPairs(leftDf, rightDf, registry, leftMethod, rightMethod)

Arguments

Value

A data frame of run-level paired values.

Build downstream support notes for a deterministic explanation audit

Description

Summarises how later rebuild streams can safely use each top-level section of a wmfmExplanationAudit object. This keeps the handoff guidance close to the code and provides a deterministic reference for later teaching-summary, claim-evidence, and UI work.

Usage

buildWmfmExplanationAuditSupportNotes(audit)

Arguments

Value

A data frame describing section purpose and downstream usage.

Build the shared language contract for WMFM explanations

Description

Central shared rules used by both overall model summaries and contrasts. Only the opening context lines vary; the core rules stay identical.

Usage

buildWmfmLanguageContractText(context = c("summary", "contrast"))

Arguments

Value

A character scalar containing the shared language contract text.

Build a compact WMFM LLM scoring cache key

Description

Builds a short cache key for a scoring prompt. The full prompt can exceed R's maximum environment binding-name length, so the cache stores responses under a hash rather than the literal prompt text.

Usage

buildWmfmLlmScoringCacheKey(prompt)

Arguments

Value

Character scalar cache key.

Build the system prompt for WMFM explanation scoring

Description

Creates the fixed system prompt used when asking a language model to score a plain-language model explanation against the WMFM scoring schema.

Creates the fixed system prompt used when asking a language model to score a plain-language model explanation against the WMFM scoring schema.

Usage

buildWmfmLlmScoringSystemPrompt()

buildWmfmLlmScoringSystemPrompt()

Value

A character scalar containing the system prompt.

A character scalar containing the system prompt.

Build a user prompt for WMFM explanation scoring

Description

Given a single run record produced by buildWmfmRunRecord(), construct a prompt asking a language model to score the explanation and return strict JSON matching the WMFM scoring schema.

Given a single run record produced by buildWmfmRunRecord(), construct a prompt asking a language model to score the explanation and return strict JSON matching the WMFM scoring schema.

Usage

buildWmfmLlmScoringUserPrompt(runRecord)

buildWmfmLlmScoringUserPrompt(runRecord)

Arguments

Details

This prompt includes field-specific rubric guidance so that the language model applies the WMFM scoring dimensions consistently rather than inferring its own definitions of what counts as adequate, clear, or appropriate.

This prompt includes field-specific rubric guidance so that the language model applies the WMFM scoring dimensions consistently rather than inferring its own definitions of what counts as adequate, clear, or appropriate.

Value

A character scalar containing the prompt text.

A character scalar containing the prompt text.

Build a user-facing provider model label

Description

Build a user-facing provider model label

Usage

buildWmfmProviderModelLabel(
  profile,
  providerConfig = resolveWmfmProviderConfig()
)

Arguments

Value

Character scalar model label.

Build a user-facing provider readiness label

Description

Build a user-facing provider readiness label

Usage

buildWmfmProviderReadinessLabel(
  profile,
  providerConfig = resolveWmfmProviderConfig()
)

Arguments

Value

Character scalar readiness label.

Build provider registry rows for the settings UI

Description

Build provider registry rows for the settings UI

Usage

buildWmfmProviderRegistryRows(
  profiles = readWmfmProviderProfiles(),
  providerConfig = resolveWmfmProviderConfig()
)

Arguments

Value

Data frame with user-facing provider registry rows.

Build provider setup policy text

Description

Build provider setup policy text

Usage

buildWmfmProviderSetupPolicyText()

Value

Character vector describing who controls provider setup in the current runtime context.

Build a single WMFM repeated-run record

Description

Creates a structured record for one repeated WMFM run using a schema that separates:

1. metadata and model context,

2. raw explanation text and text summaries, and

3. extracted semantic claims.

Usage

buildWmfmRunRecord(
  runId,
  exampleName,
  package,
  modelType,
  formula,
  equationsText,
  explanationText,
  researchQuestion = "",
  errorMessage = NA_character_,
  interactionTerms = character(0),
  interactionMinPValue = NA_real_,
  interactionAlpha = 0.05,
  hasFactorPredictors = FALSE,
  adjustmentVariables = character(0),
  primaryVariables = character(0),
  followupScoringContext = NULL
)

Arguments

Details

This function is intentionally limited to describing what happened during a run and what the explanation appeared to say. It does not create any judged scoring fields or aggregate score placeholders. Scoring is handled later by downstream functions such as score() and scoreWmfmRepeatedRuns(), which should operate on the raw run record rather than being partially embedded in it.

Output schema

The returned named list contains the following groups of fields.

Metadata and model context

runId

Integer run identifier.

timestamp

Character timestamp created at record build time.

exampleName

Example identifier.

package

Package name.

modelType

High-level model class.

modelFamily

Optional model family. Initialised to NA.

linkFunction

Optional link function. Initialised to NA.

formula

Model formula as character.

equationsText

Fitted-equation text.

interactionTerms

Pipe-separated interaction-term names.

hasInteractionTerms

Logical. Whether the fitted model includes interactions.

nInteractionTerms

Integer count of interaction terms.

interactionMinPValue

Minimum interaction-term p-value, or NA.

interactionAlpha

Stored interaction threshold metadata from the run.

hasError

Logical. Whether an error was recorded for the run.

errorMessage

Run error message, or NA.

Raw explanation text and summaries

explanationText

Raw explanation text.

normalizedExplanation

Normalised explanation used for duplicate detection.

explanationPresent

Logical. Whether a non-empty explanation is present.

wordCount

Approximate word count.

sentenceCount

Approximate sentence count.

Extracted claim variables

ciMention

Logical. Whether a confidence or credible interval is mentioned.

percentLanguageMention

Logical. Whether percent language is used.

referenceGroupMention

Logical. Whether reference/baseline framing is mentioned.

interactionMention

Logical. Whether interaction or differential-pattern language is mentioned.

uncertaintyMention

Logical. Whether uncertainty or evidential caution is mentioned.

usesInferentialLanguage

Logical. Whether inferential wording is present.

usesDescriptiveOnlyLanguage

Logical. Whether wording is descriptive only.

overclaimDetected

Logical. Whether overstrong language is detected.

underclaimDetected

Logical. Whether unusually weak language is detected.

conditionalLanguageMention

Logical. Whether conditional wording such as "depends on" or subgroup-conditioned interpretation is present.

comparisonLanguageMention

Logical. Whether explicit or implicit comparison wording is present.

outcomeMention

Logical. Placeholder for whether the response is clearly named. Initialised conservatively.

predictorMention

Logical. Placeholder for whether the focal predictor is clearly named. Initialised conservatively.

effectDirectionClaim

Character. One of increase, decrease, mixed_or_both, not_stated.

effectScaleClaim

Character. One of additive, multiplicative, probability_or_odds, mixed_or_unclear, not_stated.

interactionSubstantiveClaim

Character. One of difference_claimed_strongly, difference_claimed_cautiously, no_clear_difference, not_mentioned, unclear, not_applicable.

inferentialRegister

Character. One of inferential, descriptive_only, overclaiming, unclear.

uncertaintyTypeClaim

Character. One of none, generic_uncertainty, confidence_interval, mixed, unclear.

Value

Named list containing one structured raw run record.

Build a wmfmScoreComparison object

Description

Internal helper that constructs agreement summaries and run-level paired data for two score data frames.

Usage

buildWmfmScoreComparison(
  leftDf,
  rightDf,
  leftMethod,
  rightMethod,
  sourceLabel,
  registry = getWmfmMetricRegistry()
)

Arguments

Value

An object of class wmfmScoreComparison.

Choose deterministic explanation anchors for numeric predictors

Description

Builds auditable anchor metadata for student-facing explanations. These anchors are intended for explanation and prompt inputs, not for changing the fitted model. The raw anchor value is kept separately from the displayed value so explanations can use readable numbers while calculations remain traceable.

Usage

chooseExplanationAnchor(
  model = NULL,
  mf = NULL,
  predictorNames = NULL,
  userAnchors = NULL,
  meaningfulAnchors = NULL,
  defaultSource = c("median", "mean")
)

Arguments

Value

A named list containing anchor metadata, prompt text, and a cache key.

Choose fitted-means table layout for 1–3 factor predictors

Description

Implements the layout rules for displaying fitted means when all predictors are factors:

• 1 factor: one-way table (single column of fitted means).

• 2 factors: two-way table with the factor having the most levels on rows.

• 3 factors: a set of two-way tables split by the factor with the fewest levels. Within each two-way table, the factor with the most levels is on rows and the remaining factor is on columns.

Usage

chooseFactorLayout(mf, predictors)

Arguments

Value

A list describing the layout:

type

One of "oneWay", "twoWay", "threeWay", or "other".

rowVar

Row factor name (for "oneWay" and "twoWay" and "threeWay").

colVar

Column factor name (for "twoWay" and "threeWay").

splitVar

Split factor name (for "threeWay" only).

Examples

df = data.frame(
  y = rnorm(24),
  A = factor(rep(c("a1","a2"), each = 12)),
  B = factor(rep(paste0("b", 1:4), times = 6)),
  C = factor(rep(paste0("c", 1:6), times = 4))
)
mod = lm(y ~ A * B * C, data = df)
mf = model.frame(mod)
chooseFactorLayout(mf, c("A","B","C"))

Choose the numeric reference used for teaching summaries

Description

Selects whether numeric predictors should be anchored at 0 or at their sample means when building teaching-oriented summaries such as fitted-value confidence-interval rows. The current rule is intentionally simple: if every numeric predictor has an observed range that includes 0, use 0; otherwise use the sample mean.

Usage

chooseModelNumericReference(model = NULL, mf = NULL, predictorNames = NULL)

Arguments

Value

A single string, either "zero" or "mean".

Choose a point alpha for model plots

Description

Choose a point alpha for model plots

Usage

chooseModelPlotPointAlpha(observationCount)

Arguments

Value

A numeric alpha value between 0 and 1.

Classify the effect scale described in a WMFM explanation

Description

Uses simple text heuristics to classify the scale on which the explanation describes the main effect. The intent is to identify the dominant scale used for coefficient interpretation, rather than unrelated numeric summaries such as model-fit percentages.

Usage

classifyEffectScaleClaim(text)

Arguments

Details

The classifier is deliberately conservative about assigning "mixed_or_unclear". In particular, generic percentage language such as an R^2 statement should not by itself force a multiplicative label when the coefficient interpretation is otherwise clearly additive.

Value

One of "additive", "multiplicative", "probability_or_odds", "mixed_or_unclear", or "not_stated".

Classify a sentence-level explanation claim for legacy compatibility

Description

This helper now derives the legacy single-label claimType value from the multi-tag detector output used by the claim-mapping pipeline. New code should prefer detectExplanationClaimTags() and treat claimType as a compatibility field only.

Usage

classifyExplanationClaimType(
  claimText,
  audit,
  teachingSummary = NULL,
  model = NULL,
  sentenceIndex = NA_integer_,
  totalClaims = NA_integer_,
  claimTags = NULL
)

Arguments

Value

A single character string.

Classify likely source of metric disagreement

Description

Internal heuristic classifier for diagnose().

Usage

classifyMetricDisagreement(summaryDf)

Arguments

Value

A single character string describing the likely disagreement class.

Classify CI output mode for a fitted model

Description

Classify CI output mode for a fitted model

Usage

classifyModelConfidenceIntervalPlan(model, mf)

Arguments

Value

A list describing the chosen mode.

Classify the fitted model for model plots

Description

Classify the fitted model for model plots

Usage

classifyModelPlotFamily(model)

Arguments

Value

A single character string describing the supported plot family.

Classify run-level score disagreement for heatmap plotting

Description

Converts paired run-level values from buildWmfmComparisonPairs() into a categorical disagreement label that can be used for a heatmap.

Usage

classifyWmfmScoreDisagreement(
  x,
  includeContinuous = FALSE,
  continuousBreaks = c(0.1, 0.35, 0.75)
)

Arguments

Details

Classification rules are:

• binary metrics: "exact" or "different";

• ordinal metrics: "exact", "adjacent", "moderate", or "large";

• continuous metrics: excluded by default in the heatmap and returned as NA unless includeContinuous = TRUE, in which case they are binned as "exact", "small", "moderate", or "large" using absolute differences.

For ordinal metrics, ordered levels are taken from the registry stored on the comparison object.

Value

A data frame like x$pairData with an added disagreementClass column.

Clean generated explanation text before deterministic processing

Description

Removes simple LLM formatting artifacts that can leak into the visible explanation, such as leading Answer, ⁠Answer:⁠, or ⁠Answer -⁠ tokens. This is a deterministic surface cleanup step. It does not rewrite the statistical content of the explanation.

Usage

cleanExplanationText(text)

Arguments

Value

A character vector with formatting artifacts removed.

Finish a WMFM progress tracker

Description

Internal helper that closes the text progress bar and returns timing summaries.

Usage

closeWmfmProgressTracker(tracker)

Arguments

Value

A list with elapsed, average, and iteration timing summaries.

Build a natural language list from names

Description

Build a natural language list from names

Usage

collapseTeachingNames(x)

Arguments

Value

A single character string.

Compare WMFM objects

Description

Generic for comparing WMFM objects.

Usage

compare(x, y = NULL, ...)

Arguments

Value

Method specific comparison object.

Compare grading results for wmfmGrade objects

Description

Compares deterministic and llm grading either within a single wmfmGrade object that contains both methods, or across two separate wmfmGrade objects.

Usage

## S3 method for class 'wmfmGrade'
compare(x, y = NULL, methods = c("deterministic", "llm"), ...)

Arguments

Value

An object of class wmfmGradeComparison.

Compare WMFM score results

Description

Compares score results either:

• within a single wmfmScores object containing two methods, or

• between two wmfmScores objects.

Usage

## S3 method for class 'wmfmScores'
compare(
  x,
  y = NULL,
  xMethod = NULL,
  yMethod = NULL,
  registry = getWmfmMetricRegistry(),
  ...
)

Arguments

Details

The comparison summarizes agreement separately for binary, ordinal, and continuous score fields using the WMFM metric registry.

Value

An object of class wmfmScoreComparison.

Complete one-row newdata for CI predictions

Description

Ensures that all predictors referenced by the fitted model are present in the one-row newData passed to predict(), filling any omitted columns from simple base settings taken from the model frame. This keeps the CI builder robust when a row constructor only changes the focal predictors for a teaching quantity.

Usage

completeConfidenceIntervalNewData(
  model,
  newData,
  numericReference = NULL,
  mf = NULL,
  predictorNames = NULL
)

Arguments

Value

A completed one-row data frame.

Assemble a WMFM prompt from common pieces

Description

Assemble a WMFM prompt from common pieces

Usage

composeWmfmPrompt(
  context = c("summary", "contrast"),
  contextPayload,
  scaleRules = NULL
)

Arguments

Value

A character scalar prompt.

Compute a priority score for metric diagnosis

Description

Internal helper that ranks metrics for follow-up. Higher values indicate more systematic and potentially more important disagreement.

Usage

computeDiagnosisPriorityScore(summaryTable)

Arguments

Value

A numeric vector of priority scores.

Compute a single contrast for factor-only models

Description

Computes an estimate and 95% confidence interval for a user-specified contrast in a factor-only model, optionally using robust (sandwich) variance estimators.

Usage

computeFactorOnlyContrast(
  model,
  newData,
  weights,
  ciType = c("standard", "sandwich"),
  hcType = c("HC0", "HC3"),
  level = 0.95
)

Arguments

Details

The contrast is defined through a set of weights applied to the rows of newData. For example, a pairwise contrast between level A and level B can be represented with weights c(1, -1, 0, ..., 0).

For GLMs, inference is carried out on the linear predictor (link) scale and then back-transformed for interpretation when possible:

• Poisson (log link): reports a mean ratio exp(contrast).

• Binomial (logit link): reports an odds ratio exp(contrast).

Value

A list with estimates and confidence intervals on the link scale and (when applicable) an interpreted scale.

Compute confidence intervals for fitted mean responses

Description

Computes pointwise confidence intervals for the fitted mean response evaluated at newData. These are confidence intervals for the conditional mean (i.e., the fitted line), not prediction intervals.

Usage

computeMeanCi(
  model,
  newData,
  ciType = "standard",
  hcType = "HC0",
  level = 0.95
)

Arguments

Details

For generalized linear models, intervals are computed on the link scale and transformed back to the response scale.

Robust (sandwich) confidence intervals are supported via vcovHC().

Value

A data frame containing newData plus columns fit, lower, and upper.

Compute quadratic weighted kappa for ordinal values

Description

Computes quadratic weighted kappa for two ordinal vectors that have already been converted to integer scores.

Usage

computeWeightedKappa(leftVec, rightVec)

Arguments

Value

A numeric scalar, or NA_real_ if it cannot be computed.

Compute the number of WMFM LLM grading jobs

Description

Internal helper for estimating how many LLM grading calls a request would make.

Usage

computeWmfmLlmJobCount(nExplanations, method, nLlm = 1L)

Arguments

Value

Integer scalar.

Convert a model response to a plotting response

Description

Convert a model response to a plotting response

Usage

convertModelPlotResponse(response, plotFamily)

Arguments

Value

A list with values, breaks, and labels.

Count sentences in text

Description

Count sentences in text

Usage

countWmfmSentences(x)

Arguments

Value

Integer.

Count words in text

Description

Count words in text

Usage

countWmfmWords(x)

Arguments

Value

Integer.

Create app server observer dependencies

Description

Create app server observer dependencies

Usage

createAppServerObserverDependencies(input, session, rv, modelFit)

Arguments

Value

A list of helper functions used by observer registration code.

Create app server reactive state

Description

Create app server reactive state

Usage

createAppServerReactiveState()

Value

A list containing the app server reactive values and reactive holders.

Create derived-variable transformation metadata

Description

Records the expression used to create a derived variable without changing how the expression is evaluated. The metadata is intentionally conservative: it preserves the original expression and only labels transformations that WMFM can recognise safely for later explanation and back-transformation work.

Usage

createVariableTransformationRecord(
  variable,
  rhs,
  data = NULL,
  expressionText = NULL,
  sourceVariables = NULL,
  transformationType = NULL,
  inverseType = NULL,
  transformationParameters = NULL,
  createdFrom = "addDerivedVariable"
)

Arguments

Value

A list with class wmfmVariableTransformation.

Deparse an expression to one line

Description

Deparse an expression to one line

Usage

deparseOneLine(expr)

Arguments

Value

Character scalar.

Derive paired metric comparison data directly from wmfmScores

Description

Internal helper that reconstructs run-level paired deterministic and LLM scores for a single metric from a wmfmScores object.

Usage

deriveMetricComparisonDataFromScores(scores, metric)

Arguments

Value

A data frame with columns runId, detValue, and llmValue.

Describe a field for a WMFM object

Description

S3 generic for describing fields stored in WMFM objects.

Usage

describeField(x, field, ...)

Arguments

Value

Method-specific description output.

Describe a field for a WMFM runs object

Description

Describes a field that is present in a wmfmRuns object. The method accepts canonical field names, recognised aliases, and supported pretty plot labels. It validates that the resolved canonical field is actually stored in the raw run records before delegating to describeWmfmField().

Usage

## S3 method for class 'wmfmRuns'
describeField(
  x,
  field,
  format = c("text", "list", "data.frame"),
  includeExamples = TRUE,
  includeAliases = TRUE,
  ...
)

Arguments

Value

The result of describeWmfmField() in the requested format. This is a character scalar for format = "text", a named list for format = "list", or a one-row data.frame for format = "data.frame".

Describe a field for a WMFM scores object

Description

Describes a field that is present in a wmfmScores object. The method accepts canonical field names, recognised aliases, and supported pretty plot labels. It validates that the resolved canonical field is actually stored in the scored records before delegating to describeWmfmField().

Usage

## S3 method for class 'wmfmScores'
describeField(
  x,
  field,
  format = c("text", "list", "data.frame"),
  includeExamples = TRUE,
  includeAliases = TRUE,
  ...
)

Arguments

Value

The result of describeWmfmField() in the requested format. This is a character scalar for format = "text", a named list for format = "list", or a one-row data.frame for format = "data.frame".

Describe WMFM config location status

Description

Returns path and accessibility metadata for the local WMFM non-secret configuration file.

Usage

describeWmfmConfigLocation()

Value

Named list containing config file location details.

Describe a WMFM field

Description

Prints a human-readable description of a field used in the WMFM workflow. This is intended to help interpret the raw run fields, judged fields, and aggregate score fields that appear in WMFM objects and related plots.

Usage

describeWmfmField(
  field,
  format = c("text", "list", "data.frame"),
  includeExamples = TRUE,
  includeAliases = TRUE
)

Arguments

Details

The function accepts:

• current schema names such as interactionEvidenceAppropriate,

• older aliases such as interactionInference, and

• the pretty x-axis labels used by plotWmfmExplanationClaimHeatmap(), such as "Direction claim", "Scale claim", or "CI mention".

By default the function prints a formatted explanation to the console using cat() and returns the underlying character vector invisibly. This makes it convenient for interactive use while still allowing the text to be captured programmatically when needed.

For judged fields scored on a 0/1/2 scale, the usual interpretation is:

0

Poor, missing, inappropriate, or clearly problematic.

1

Partly adequate, weak, borderline, or unclear.

2

Appropriate, clear, or well handled.

Value

If format = "text", a formatted character vector returned invisibly after being printed to the console. Otherwise a named list or a one-row data frame describing the requested field.

Examples

describeWmfmField("interactionEvidenceAppropriate")
describeWmfmField("Direction claim")
describeWmfmField("CI mention")
describeWmfmField("overallScore", format = "list")

Describe WMFM provider status

Description

Returns deterministic, printable provider metadata and credential status without including secret values.

Usage

describeWmfmProviderStatus()

Value

Named list with providers and configuredProviders entries.

Detect the teaching framework for CI display metadata

Description

Detect the teaching framework for CI display metadata

Usage

detectConfidenceIntervalModelFramework(model)

Arguments

Value

A character scalar.

Detect whether a model contains factor predictors

Description

Detect whether a model contains factor predictors

Usage

detectDeveloperScoringFactorPredictors(model)

Arguments

Value

Logical scalar.

Detect whether a developer scoring model has interaction terms

Description

Detect whether a developer scoring model has interaction terms

Usage

detectDeveloperScoringInteractionTerms(model)

Arguments

Value

Logical scalar.

Detect implicit comparison language in WMFM explanations

Description

Detects comparison structure that may not use explicit phrases such as "compared with" or "relative to", but still clearly expresses a contrast between groups or conditions.

Usage

detectImplicitComparison(text)

Arguments

Details

This helper is intended to support extraction in buildWmfmRunRecord(), especially for explanations that use constructions such as:

• "higher ... than those who did not"

• "more ... than students who did not attend"

• "lower ... than those without ..."

The function looks for comparative wording together with at least one structural cue indicating contrast or grouping.

Value

Logical scalar. TRUE if implicit comparison language is detected, otherwise FALSE.

Detect numeric range expressions (implicit uncertainty)

Description

Detects expressions like "from 3.0 to 4.0" or "between 3.8 and 12.2", which indicate uncertainty without explicitly mentioning confidence intervals.

Usage

detectRangeExpression(text)

Arguments

Value

Logical

Detect a response transformation from an expression string

Description

Attempts to detect a common response transformation from a text expression. This is intended for lightweight UI labeling (e.g., "log", "sqrt") rather than for full parsing of arbitrary R code.

Usage

detectRespTransform(expr)

Arguments

Details

Recognised transformations (returned values):

• "log" for expressions starting with log(

• "log1p" for expressions starting with log1p(

• "sqrt" for expressions starting with sqrt(

If no recognised transformation is detected, returns NULL.

Value

A single character string naming the detected transformation, or NULL if none is detected.

Detect pattern in text

Description

Detect pattern in text

Usage

detectWmfmPattern(x, pattern)

Arguments

Value

Logical.

Diagnose scoring disagreement

Description

S3 generic for diagnosing disagreement between deterministic and LLM scoring outputs.

Usage

diagnose(x, ...)

Arguments

Value

Method-specific diagnosis output.

Diagnose disagreement for a WMFM scores object

Description

Diagnoses disagreement between deterministic and LLM scoring for either a single metric or all available metrics.

Usage

## S3 method for class 'wmfmScores'
diagnose(x, metric = NULL, runs = NULL, cmp = NULL, maxExamples = 5, ...)

Arguments

Details

When metric is supplied, the function returns a wmfmMetricDiagnosis object. When metric = NULL, it returns a wmfmScoresDiagnosis object summarising all metrics that can be compared.

Value

A wmfmMetricDiagnosis or wmfmScoresDiagnosis object.

Diagnose deterministic explanation surface processing

Description

Runs the deterministic explanation surface processor in debug mode and records surface-language issues before and after processing. This helper is intended for developer review and tests. It does not change the explanation pipeline and it does not make statistical claims.

Usage

diagnoseExplanationSurfaceProcessing(text, audit = NULL)

Arguments

Value

A list with original text, processed text, applied rule names, detected issues before processing, detected issues after processing, and the number of unresolved issues.

Examples

diagnoseExplanationSurfaceProcessing(
  "A one-unit rise multiplies the expected count by 0.21."
)

Draw the fitted-model plot (data + fitted line / fitted means)

Description

Extracts the plotting logic from the Shiny renderPlot() block and returns either:

• a ggplot object (most models), or

• the result of makeFactorOnlyPlot() for factor-only models, or

• draws a base-graphics message and returns invisible() when a plot is not applicable.

Usage

drawModelPlot(
  model,
  ciType = "standard",
  hcType = "HC0",
  showCi = FALSE,
  level = 0.95
)

Arguments

Details

This function expects the helper functions isFactorOnlyModel() and makeFactorOnlyPlot() to exist in your app codebase (as they do in your current server implementation).

If the model contains exactly one numeric predictor, the function draws the raw data and a fitted line. Optionally, it can add confidence bands around the fitted line(s). Bands can be computed using either the model-based standard errors or sandwich/robust standard errors.

Value

A ggplot object when a numeric-predictor plot is available, or whatever makeFactorOnlyPlot() returns for factor-only models. In cases where plotting is not applicable, the function draws an informative message using base graphics and returns invisible().

Edit the WMFM local configuration file

Description

Opens the WMFM user configuration file in the default R editor. If the configuration directory or file does not yet exist, they are created first.

Usage

editWmfmConfig(editor = utils::file.edit)

Arguments

Value

Invisibly returns the path to the configuration file.

Build an empty response back-transformation payload

Description

Build an empty response back-transformation payload

Usage

emptyResponseBackTransformationPayload(
  mode,
  status,
  responseVariable = "",
  originalVariable = "",
  transformationType = "",
  inverseType = "",
  note = ""
)

Arguments

Value

A named list.

Build an empty response back-transformation table

Description

Build an empty response back-transformation table

Usage

emptyResponseBackTransformationTable()

Value

A zero-row data frame with stable columns.

Build an empty variable-transformation audit table

Description

Build an empty variable-transformation audit table

Usage

emptyVariableTransformationAuditTable()

Value

A zero-row data frame with the stable audit columns.

Enforce the WMFM LLM grading job guard

Description

Internal helper that prevents unexpectedly large LLM grading requests unless the user explicitly opts in.

Usage

enforceWmfmLlmJobGuard(
  totalLlmCalls,
  nExplanations,
  nLlm,
  confirmLargeLlmJob = FALSE,
  maxLlmJobsWithoutConfirmation = 20L
)

Arguments

Value

Invisibly returns TRUE when the request is allowed.

Enrich a CI table with framework-aware display metadata

Description

Adds internal columns that the app can use to filter and present confidence-interval rows by model framework, teaching role, and display scale. This keeps the calculation layer stable while making the returned table easier to drive from UI controls.

Usage

enrichConfidenceIntervalDisplayTable(model, ciTable)

Arguments

Value

A data frame with additional metadata columns.

Ensure anchored factor comparisons appear in explanation text

Description

Adds a deterministic anchored factor-comparison sentence when a fitted linear model contains both a factor predictor and a numeric predictor, but the LLM explanation omitted the anchored fitted values needed for a student-facing interpretation.

Usage

ensureAnchoredFactorComparisonText(text, model)

Arguments