statlingua (version 0.1.0)

explain: Explain statistical output

Description

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"),
  ...
)
# S3 method for default
explain(
  object,
  client,
  context = NULL,
  audience = "novice",
  verbosity = "moderate",
  style = "markdown",
  ...
)
# S3 method for htest
explain(
  object,
  client,
  context = NULL,
  audience = "novice",
  verbosity = "moderate",
  style = "markdown",
  ...
)
# S3 method for lm
explain(
  object,
  client,
  context = NULL,
  audience = "novice",
  verbosity = "moderate",
  style = "markdown",
  ...
)
# S3 method for glm
explain(
  object,
  client,
  context = NULL,
  audience = "novice",
  verbosity = "moderate",
  style = "markdown",
  ...
)
# S3 method for polr
explain(
  object,
  client,
  context = NULL,
  audience = "novice",
  verbosity = "moderate",
  style = "markdown",
  ...
)
# S3 method for lme
explain(
  object,
  client,
  context = NULL,
  audience = "novice",
  verbosity = "moderate",
  style = "markdown",
  ...
)
# S3 method for lmerMod
explain(
  object,
  client,
  context = NULL,
  audience = "novice",
  verbosity = "moderate",
  style = "markdown",
  ...
)
# S3 method for glmerMod
explain(
  object,
  client,
  context = NULL,
  audience = "novice",
  verbosity = "moderate",
  style = "markdown",
  ...
)
# S3 method for gam
explain(
  object,
  client,
  context = NULL,
  audience = "novice",
  verbosity = "moderate",
  style = "markdown",
  ...
)
# S3 method for survreg
explain(
  object,
  client,
  context = NULL,
  audience = "novice",
  verbosity = "moderate",
  style = "markdown",
  ...
)
# S3 method for coxph
explain(
  object,
  client,
  context = NULL,
  audience = "novice",
  verbosity = "moderate",
  style = "markdown",
  ...
)
# S3 method for rpart
explain(
  object,
  client,
  context = NULL,
  audience = "novice",
  verbosity = "moderate",
  style = "markdown",
  ...
)

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.

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

Examples

if (FALSE) {
# 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")
}