Explain statistical output

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"),
  ...
)

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

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

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

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

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

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

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

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

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

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

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

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

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.

...

Additional optional arguments. (Currently ignored.)

Value

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

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

• model_type - Character string giving the model type (e.g., "lm" or "coxph").

• 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.

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)

# Poisson regression example from ?stats::glm
counts <- c(18,17,15,20,10,20,25,13,12)
outcome <- gl(3,1,9)
treatment <- gl(3,3)
data.frame(treatment, outcome, counts) # showing data
fm2 <- glm(counts ~ outcome + treatment, family = poisson())

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