Skip to contents

Explain statistical output

Source: R/explain.R
explain.Rd

Use an LLM to explain the output from various statistical objects using straightforward, understandable, and context-aware natural language descriptions.

Usage

explain(
  object,
  client,
  context = NULL,
  audience = c("novice", "student", "researcher", "manager", "domain_expert"),
  verbosity = c("moderate", "brief", "detailed"),
  style = c("markdown", "html", "json", "text", "latex"),
  language = NULL,
  prompt_dir = NULL,
  ...
)

# Default S3 method
explain(
  object,
  client,
  context = NULL,
  audience = "novice",
  verbosity = "moderate",
  style = "markdown",
  language = NULL,
  prompt_dir = NULL,
  ...
)

# S3 method for class 'htest'
explain(
  object,
  client,
  context = NULL,
  audience = "novice",
  verbosity = "moderate",
  style = "markdown",
  language = NULL,
  prompt_dir = NULL,
  ...
)

# S3 method for class 'lm'
explain(
  object,
  client,
  context = NULL,
  audience = "novice",
  verbosity = "moderate",
  style = "markdown",
  language = NULL,
  prompt_dir = NULL,
  ...
)

# S3 method for class 'glm'
explain(
  object,
  client,
  context = NULL,
  audience = "novice",
  verbosity = "moderate",
  style = "markdown",
  language = NULL,
  prompt_dir = NULL,
  ...
)

# S3 method for class 'polr'
explain(
  object,
  client,
  context = NULL,
  audience = "novice",
  verbosity = "moderate",
  style = "markdown",
  language = NULL,
  prompt_dir = NULL,
  ...
)

# S3 method for class 'lme'
explain(
  object,
  client,
  context = NULL,
  audience = "novice",
  verbosity = "moderate",
  style = "markdown",
  language = NULL,
  prompt_dir = NULL,
  ...
)

# S3 method for class 'lmerMod'
explain(
  object,
  client,
  context = NULL,
  audience = "novice",
  verbosity = "moderate",
  style = "markdown",
  language = NULL,
  prompt_dir = NULL,
  ...
)

# S3 method for class 'glmerMod'
explain(
  object,
  client,
  context = NULL,
  audience = "novice",
  verbosity = "moderate",
  style = "markdown",
  language = NULL,
  prompt_dir = NULL,
  ...
)

# S3 method for class 'gam'
explain(
  object,
  client,
  context = NULL,
  audience = "novice",
  verbosity = "moderate",
  style = "markdown",
  language = NULL,
  prompt_dir = NULL,
  ...
)

# S3 method for class 'survreg'
explain(
  object,
  client,
  context = NULL,
  audience = "novice",
  verbosity = "moderate",
  style = "markdown",
  language = NULL,
  prompt_dir = NULL,
  ...
)

# S3 method for class 'coxph'
explain(
  object,
  client,
  context = NULL,
  audience = "novice",
  verbosity = "moderate",
  style = "markdown",
  language = NULL,
  prompt_dir = NULL,
  ...
)

# S3 method for class 'rpart'
explain(
  object,
  client,
  context = NULL,
  audience = "novice",
  verbosity = "moderate",
  style = "markdown",
  language = NULL,
  prompt_dir = NULL,
  ...
)

Arguments

object

An appropriate statistical object. For example, object can be the output from calling t.test() or glm().

client

A Chat object (e.g., from calling chat_openai() or [chat_gemini()][ellmer::chat_gemini)]).

[ellmer::chat_gemini)]: R:ellmer::chat_gemini)

context

Optional character string providing additional context, such as background on the research question and information about the data.

audience

Character string indicating the target audience:

  • "novice" - Assumes the user has a limited statistics background (default).

  • "student" - Assumes the user is learning statistics.

  • "researcher" - Assumes the user has a strong statistical background and is familiar with common methodologies.

  • "manager" - Assumes the user needs high-level insights for decision-making.

  • "domain_expert" - Assumes the user is an expert in their own field but not necessarily in statistics.

verbosity

Character string indicating the desired verbosity:

  • "moderate" - Offers a balanced explanation (default).

  • "brief" - Offers a high-level summary.

  • "detailed" - Offers a comprehensive interpretation.

style

Character string indicating the desired output style:

  • "markdown" (default) - Output formatted as plain Markdown.

  • "html" - Output formatted as an HTML fragment.

  • "json" - Output structured as a JSON string parseable into an R list.

  • "text" - Output as plain text.

  • "latex" - Output as a LaTeX fragment.

language

Character string specifying the language the explanation should be written in (e.g. "Spanish", "French", "Mandarin Chinese"). If NULL (the default), no language constraint is added and the LLM will typically respond in the same language as the input/context or its default language.

prompt_dir

Optional character string specifying a custom directory containing custom prompt templates to override or overlay the package's default templates.

...

Additional optional arguments. (Currently ignored.)

Value

An object of class "statlingo_explanation". Essentially a list with the following components:

  • text - Character string representation of the LLM's response.

  • model_type - Character string giving the internal prompt model type (e.g., "linear_model" or "cox_proportional_hazards").

  • audience - Character string specifying the level or intended audience for the explanations.

  • verbosity - Character string specifying the level of verbosity or level of detail of the provided explanation.

Details

The following models and package classes are supported:

  • stats (Base R):

  • MASS:

    • polr (Proportional odds logistic regression via polr())

  • nlme:

    • lme (Linear mixed-effects models via lme())

  • lme4:

    • lmerMod (Linear mixed-effects models via lmer())

    • glmerMod (Generalized linear mixed-effects models via glmer())

  • mgcv:

    • gam (Generalized additive models via gam())

  • survival:

    • survreg (Parametric survival regression via survreg())

    • coxph (Cox proportional hazards models via coxph())

  • rpart:

    • rpart (Recursive partitioning decision trees via rpart())

Examples

if (FALSE) { # \dontrun{
# Polynomial regression
fm1 <- lm(dist ~ poly(speed, degree = 2), data = cars)
context <- "
The data give the speed of cars (mph) and the distances taken to stop (ft).
Note that the data were recorded in the 1920s!
"
# Use Google Gemini to explain the output; requires an API key; see
# ?ellmer::chat_google_gemini for details
client <- ellmer::chat_google_gemini(echo = "none")
ex <- explain(fm1, client = client, context = context)
explain(fm1, client = client, context = context, language = "Spanish")

# Poisson regression example using the bike sharing data from ISLR2
Bikeshare <- ISLR2::Bikeshare

# Fit a Poisson regression model to the bike sharing data set
fm2 <- glm(bikers ~ mnth + hr + workingday + temp + weathersit,
           data = Bikeshare, family = poisson)

# Additional context for the LLM to consider when explaining the model's
# output
context <- "
The data contain the hourly and daily count of rental bikes between years
2011 and 2012 in Capital bikeshare system, along with weather and seasonal
information. The variables in the model include:

* bikers - Total number of bikers.
* mnth - Month of the year, coded as a factor.
* hr - Hour of the day, coded as a factor from 0 to 23.
* workingday - Is it a work day? Yes=1, No=0.
* temp - Normalized temperature in Celsius. The values are derived via
  (t-t_min)/(t_max-t_min), t_min=-8, t_max=+39.
* weathersit - Weather, coded as a factor.
"

# Use Google Gemini to explain the output; requires an API key; see
# ?ellmer::chat_google_gemini for details
client <- ellmer::chat_google_gemini(echo = "none")
explain(fm2, client = client, context = context, audience = "student",
        verbosity = "brief", style = "text")
} # }