### Install Additional Required Packages

Source: https://github.com/bgreenwell/statlingua/blob/main/docs/articles/statlingua.html

Install necessary packages for the examples in the vignette, including ISLR2, MASS, and survival.

```R
install.packages(c("ISLR2", "jsonlite", "lme4", "MASS", "survival"))
```

--------------------------------

### Interactive Mode Notice Example

Source: https://github.com/bgreenwell/statlingua/blob/main/docs/LICENSE.html

A short notice to be displayed when a program starts in interactive mode, informing users about its version, copyright, warranty status, and redistribution conditions.

```text
Gnomovision version 69, Copyright (C) year name of author
Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
This is free software, and you are welcome to redistribute it
under certain conditions; type `show c' for details.
```

--------------------------------

### Install statlingua from GitHub

Source: https://github.com/bgreenwell/statlingua/blob/main/README.md

Install the development version of the statlingua package from GitHub. Ensure the 'remotes' package is installed first if it's not already present.

```r
if (!requireNamespace("remotes")) {
  install.packages("remotes")
}
remotes::install_github("bgreenwell/statlingua")
```

--------------------------------

### Run All Tinytest Tests (Robust)

Source: https://github.com/bgreenwell/statlingua/blob/main/AGENTS.md

Installs the package and then runs all tests defined in the 'inst/tinytest' directory for a thorough check.

```bash
Rscript -e 'tinytest::build_install_test()'
```

--------------------------------

### Load Package for Interactive Development

Source: https://github.com/bgreenwell/statlingua/blob/main/AGENTS.md

Simulates the installation of the package to make its functions available for interactive development and testing.

```bash
Rscript -e 'devtools::load_all()'
```

--------------------------------

### Install Development Dependencies

Source: https://github.com/bgreenwell/statlingua/blob/main/AGENTS.md

Installs essential development packages for the R project, including devtools, usethis, tinytest, roxygen2, and ellmer.

```bash
Rscript -e 'install.packages(c("devtools", "usethis", "tinytest", "roxygen2", "ellmer"))'
```

--------------------------------

### Example JSON for Documentation

Source: https://github.com/bgreenwell/statlingua/blob/main/inst/prompts/style/json.md

An example of a JSON object conforming to the schema, illustrating how to document a code snippet with its title, description, language, and code.

```json
{
  "page_title": "Example Page Title",
  "page_description": "A brief description of the example page.",
  "page_summary": "This page summarizes the example code snippets.",
  "codeSnippets": [
    {
      "title": "Example Code Snippet",
      "description": "This is a sample code snippet demonstrating a concept.",
      "language": "javascript",
      "codeList": [
        {
          "language": "javascript",
          "code": "function greet(name) {
  console.log(`Hello, ${name}!`);
}
greet('World');"
        }
      ]
    }
  ]
}
```

--------------------------------

### Install ellmer Package

Source: https://github.com/bgreenwell/statlingua/blob/main/docs/articles/statlingua.html

Install the ellmer package, which is required by statlingua for LLM communication.

```R
install.packages("ellmer")
```

--------------------------------

### Run Tinytest Tests (Quick Dev Cycle)

Source: https://github.com/bgreenwell/statlingua/blob/main/AGENTS.md

Quickly runs tests directly from the 'inst/tinytest' directory without a full package installation.

```bash
Rscript -e 'tinytest::run_test_dir("inst/tinytest")'
```

--------------------------------

### Explain Poisson Regression Output

Source: https://github.com/bgreenwell/statlingua/blob/main/docs/reference/explain.html

Explains the output of a Poisson regression model using Google Gemini. This example specifies the audience as 'student' and verbosity as 'detailed'.

```R
if (FALSE) { # \dontrun{
# 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
sm2 <- 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(sm2, client = client, audience = "student", verbosity = "detailed")
}

```

--------------------------------

### Statlingua System Prompt for JSON Output

Source: https://github.com/bgreenwell/statlingua/blob/main/docs/articles/statlingua.html

This is an example of a system prompt for Statlingua when the 'style' is set to 'json'. It details the expected JSON structure and content for explaining an lmerMod object.

```text
## Role

You are an expert statistician and R programmer, gifted at explaining complex concepts simply. Your primary function is to interpret statistical model outputs from R. You understand model nuances, underlying assumptions, and how results relate to real-world research questions.

You are particularly skilled with **Linear Mixed-Effects Models** created using the `lmer()` function from the `lme4` package in R (producing `lmerMod` objects). You understand their estimation via REML or ML, the interpretation of fixed and random effects (including correlations), and the common practice of using packages like `lmerTest` for p-value estimation.


## Intended Audience and Verbosity

### Target Audience: Student
Assume the user is learning statistics. Explain concepts thoroughly but clearly, as if teaching. Define key terms as they arise and explain *why* certain statistics are important or what they indicate in the context of the analysis. Maintain an encouraging and educational tone.

### Level of Detail (Verbosity): Detailed
Give a comprehensive interpretation. Include nuances of the model output, a detailed breakdown of all relevant statistics, and a thorough discussion of assumptions and diagnostics. Be as thorough as possible, exploring various facets of the results.


## Response Format Specification (Style: Json)

Your response MUST be a valid JSON object that can be parsed directly into an R list.
The JSON object should have the following top-level keys, each containing a string with the relevant part of the explanation (formatted as plain text or simple Markdown within the string if appropriate for that section):
- "title": A concise title for the explanation.
- "model_overview": A general description of the model type and its purpose in this context.
- "coefficient_interpretation": Detailed interpretation of model coefficients/parameters.
- "significance_assessment": Discussion of p-values, confidence intervals, and statistical significance.
- "goodness_of_fit": Evaluation of model fit (e.g., R-squared, AIC, deviance).
- "assumptions_check": Comments on important model assumptions and how they might be checked.
- "key_findings": A bulleted list (as a single string with newlines `\n` for bullets) of the main conclusions.
- "warnings_limitations": Any warnings, limitations, or caveats regarding the model or its interpretation.

Example of expected JSON structure:
{
  "title": "Explanation of Linear Regression Model for Car Sales",
  "model_overview": "This is a linear regression model...",
  "coefficient_interpretation": "The coefficient for 'Price' is -0.10, suggesting that...",
  "significance_assessment": "The p-value for 'Price' is very small (< 0.001)...",
  "goodness_of_fit": "The R-squared value is 0.87, indicating...",
  "assumptions_check": "Assumptions such as linearity and homoscedasticity should be checked by examining residual plots.",
  "key_findings": "- Price is a significant negative predictor of sales.\n- Advertising has a positive impact on sales.",
  "warnings_limitations": "This model is based on simulated data and results should be interpreted with caution."
}

Ensure the entire output is ONLY the JSON object.
DO NOT wrap your entire response in JSON code fences (e.g., ```json ... ``` or ``` ... ```).
DO NOT include any conversational pleasantries or introductory/concluding phrases.


## Instructions

You are explaining a **Linear Mixed-Effects Model** (from `lme4::lmer()`, an `lmerMod` object).

**Core Concepts & Purpose:**
This model is used for data with hierarchical/nested structures or repeated measures, where observations are not independent. It models fixed effects (average effects of predictors) and random effects (variability between groups/subjects for intercepts and/or slopes). 

**Key Assumptions:**

```

--------------------------------

### Requesting JSON Output from Statlingua

Source: https://github.com/bgreenwell/statlingua/blob/main/docs/articles/statlingua.html

This example demonstrates how to request JSON output from Statlingua by setting the style parameter. This is useful for programmatic access to model results.

```r
style <- "json"
```

--------------------------------

### Explain Two-Sample T-Test Output

Source: https://github.com/bgreenwell/statlingua/blob/main/docs/articles/examples.html

This snippet demonstrates how to use the statlingua library to explain the output of a two-sample t-test. It includes defining context, creating a tibble for exam scores, running the t-test, initializing a chat client, and then using the explain function to get an LLM-generated explanation of the test results.

```R
library(statlingua)

# Define additional context to pass to `explain()`; this should include 
# any additional background information about the data and research question.
context <- "
An instructor wants to use two exams in her classes next year. This year, she gives both exams to the students. She wants to know if the exams are equally difficult and wants to check this by comparing the two sets of scores. Here is the data:

     student exam_1_score exam_2_score
         Bob           63           69
        Nina           65           65
         Tim           56           62
        Kate          100           91
      Alonzo           88           78
        Jose           83           87
      Nikhil           77           79
       Julia           92           88
       Tohru           90           85
     Michael           84           92
        Jean           68           69
       Indra           74           81
       Susan           87           84
       Allen           64           75
        Paul           71           84
      Edwina           88           82
"

# Create the data set
exam_scores <- tibble::tribble(
  ~student,  ~exam_1_score, ~exam_2_score,
  "Bob",     63,
            69,
  "Nina",    65,
            65,
  "Tim",     56,
            62,
  "Kate",    100,
           91,
  "Alonzo",  88,
            78,
  "Jose",    83,
            87,
  "Nikhil",  77,
            79,
  "Julia",   92,
            88,
  "Tohru",   90,
            85,
  "Michael", 84,
            92,
  "Jean",    68,
            69,
  "Indra",   74,
            81,
  "Susan",   87,
            84,
  "Allen",   64,
            75,
  "Paul",    71,
            84,
  "Edwina",  88,
            82
)

# Run a two-sample t-test
(tt <- t.test(exam_scores$exam_1_score, y = exam_scores$exam_2_score))

# Inititalize client
client <- ellmer::chat_google_gemini(echo = "none")
ex <- explain(tt, client = client, context = context)
cat(ex)

```

--------------------------------

### Summarize t-test output

Source: https://github.com/bgreenwell/statlingua/blob/main/docs/reference/summarize.html

Demonstrates how to use the summarize function with a t-test object. The first example shows the raw character string output, while the second uses `cat` for more readable formatting.

```R
tt <- t.test(1:10, y = c(7:20))
summarize(tt)  # prints output as a character string
#> [1] "\n\tWelch Two Sample t-test\n\ndata:  1:10 and c(7:20)\nt = -5.4349, df = 21.982, p-value = 1.855e-05\nalternative hypothesis: true difference in means is not equal to 0\n95 percent confidence interval:\n -11.052802  -4.947198\nsample estimates:\nmean of x mean of y 
      5.5      13.5 
"
```

```R
cat(summarize(tt))  # more useful for reading
#> 
#> 	Welch Two Sample t-test
#> 
#> data:  1:10 and c(7:20)
#> t = -5.4349, df = 21.982, p-value = 1.855e-05
#> alternative hypothesis: true difference in means is not equal to 0
#> 95 percent confidence interval:
#>  -11.052802  -4.947198
#> sample estimates:
#> mean of x mean of y 
#>       5.5      13.5 
```

--------------------------------

### Requesting JSON Explanation of a Model

Source: https://github.com/bgreenwell/statlingua/blob/main/docs/articles/statlingua.html

This snippet shows how to use the `explain` function with `style = "json"` to get a structured JSON explanation of a statistical model. It requires initializing a client and specifying the model, context, audience, verbosity, and style. The resulting JSON is stored in the `text` component of the output object and can be prettified using `jsonlite::prettify`.

```R
client <- ellmer::chat_google_gemini(echo = "none")
ex <- explain(fm_sleep, client = client, context = sleepstudy_context,
              audience = "student", verbosity = "detailed", style = "json")

# The 'text' component of the statlingua_explanation object now holds a JSON
# string which can be parsed using the jsonlite package
jsonlite::prettify(ex$text)
```

--------------------------------

### Basic explain() Usage

Source: https://github.com/bgreenwell/statlingua/blob/main/docs/articles/statlingua.html

Demonstrates the fundamental usage of the explain() function with a statistical object and an ellmer client. Requires an initialized ellmer client.

```R
library(statlingua)
library(ellmer)

# Assume 'my_model' is a statistical object (e.g., an lm model)
# Assume 'my_client' is an initialized ellmer client (e.g., chat_google_gemini())

explanation <- explain(my_model, client = my_client)

```

--------------------------------

### Initialize Statlingua Client and Explain Model

Source: https://github.com/bgreenwell/statlingua/blob/main/docs/articles/statlingua.html

Establishes a client connection to a language model (Google Gemini) and then uses the 'explain' function from Statlingua to generate an explanation of a fitted logistic regression model ('fm_pima'). The explanation is tailored for a 'researcher' audience with 'moderate' verbosity, using the provided 'pima_context'.

```r
# Establish fresh client connection
client <- ellmer::chat_google_gemini(echo = "none")
#> Using model = "gemini-2.0-flash".

explain(fm_pima, client = client, context = pima_context,
        audience = "researcher", verbosity = "moderate")
```

--------------------------------

### Explain Linear Model with Context and Follow-up

Source: https://github.com/bgreenwell/statlingua/blob/main/README.md

This snippet demonstrates how to fit a linear model, provide context, establish an LLM connection using 'ellmer', and then explain the model. It also shows how to ask a follow-up question to the LLM.

```r
# Ensure you have an appropriate API key set up first!
# Sys.setenv(GEMINI_API_KEY = "<YOUR_API_KEY_HERE>") 

library(statlingua)

# Fit a polynomial regression model
fm_cars <- lm(dist ~ poly(speed, degree = 2), data = cars)
summary(fm_cars)

# Define some context (highly recommended!)
cars_context <- "
This model analyzes the 'cars' dataset from the 1920s. Variables include:
  * 'dist' - The distance (in feet) taken to stop.
  * 'speed' - The speed of the car (in mph).
We want to understand how speed affects stopping distance in the model.
"

# Establish connection to an LLM provider (in this case, Google Gemini)
client <- ellmer::chat_google_gemini(echo = "none")  # defaults to gemini-2.0-flash

# Get an explanation
explain(
  fm_cars,                 # model for LLM to interpret/explain
  client = client,         # connection to LLM provider
  context = cars_context,  # additional context for LLM to consider
  audience = "student",    # target audience
  verbosity = "detailed",  # level of detail
  style = "markdown"       # output style
)

# Ask a follow-up question
client$chat(
  "How can I construct confidence intervals for each coefficient in the model?"
)
```

--------------------------------

### Install ellmer package

Source: https://github.com/bgreenwell/statlingua/blob/main/README.md

Install the 'ellmer' package from CRAN, which is a dependency for statlingua. Ensure you have version 0.2.0 or higher.

```r
install.packages("ellmer")  # >= 0.2.0
```

--------------------------------

### explain() with Context and Audience

Source: https://github.com/bgreenwell/statlingua/blob/main/docs/articles/statlingua.html

Shows how to provide additional context about the data and specify the target audience for the explanation. This enhances the relevance and clarity of the output.

```R
library(statlingua)
library(ellmer)

# Assume 'my_model' is a statistical object
# Assume 'my_client' is an initialized ellmer client

research_context <- "This model analyzes factors affecting penguin bill length (mm) based on data from the Palmer Archipelago. We aim to understand dietary adaptations."

explanation <- explain(my_model, 
                       client = my_client,
                       context = research_context,
                       audience = "researcher")

```

--------------------------------

### explain() with Verbosity and Style

Source: https://github.com/bgreenwell/statlingua/blob/main/docs/articles/statlingua.html

Illustrates controlling the detail level ('verbosity') and output format ('style') of the explanation. Supports styles like markdown, html, json, text, and latex.

```R
library(statlingua)
library(ellmer)

# Assume 'my_model' is a statistical object
# Assume 'my_client' is an initialized ellmer client

explanation <- explain(my_model, 
                       client = my_client,
                       verbosity = "detailed",
                       style = "json")

```

--------------------------------

### Standard License Header for New Programs

Source: https://github.com/bgreenwell/statlingua/blob/main/docs/LICENSE.html

This is a standard header to include at the beginning of each source file to convey the exclusion of warranty and terms of redistribution. It should include the program's name, copyright information, and a pointer to the full license.

```text
<one line to give the program's name and a brief idea of what it does.>
Copyright (C) <year>  <name of author>

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
```

--------------------------------

### JSON Schema for Style Prompts

Source: https://github.com/bgreenwell/statlingua/blob/main/inst/prompts/style/json.md

This schema defines the structure for a JSON object used to document code snippets, including page details and individual code examples.

```json
{
  "page_title": "string",
  "page_description": "string",
  "page_summary": "string",
  "codeSnippets": [
    {
      "title": "string",
      "description": "string",
      "language": "string",
      "codeList": [
        {
          "language": "string",
          "code": "string"
        }
      ]
    }
  ]
}
```

--------------------------------

### Create a New R File

Source: https://github.com/bgreenwell/statlingua/blob/main/AGENTS.md

Automates the creation of a new R script file within the package structure using the usethis package.

```bash
Rscript -e 'usethis::use_r("file_name")'
```

--------------------------------

### Querying R-squared Explanation

Source: https://github.com/bgreenwell/statlingua/blob/main/docs/articles/statlingua.html

Use the client$chat() method to get a simplified explanation of R-squared values for a specific model. This method remembers previous interactions to provide context-aware responses.

```R
query <- paste("Could you explain the R-squared values (Multiple R-squared and",
               "Adjusted R-squared) in simpler terms for this car seat sales",
               "model? What does it practically mean for predicting sales?")
client$chat(query)
```

--------------------------------

### Generate Detailed Explanation for Novice Audience

Source: https://github.com/bgreenwell/statlingua/blob/main/docs/articles/statlingua.html

Uses the explain function from statlingua to generate a detailed explanation of the linear model output for a novice audience, leveraging the provided context and Google Gemini client.

```R
explain(fm_carseats, client = client, context = carseats_context,
        audience = "novice", verbosity = "detailed")
```

--------------------------------

### Define Context for LLM Explanation

Source: https://github.com/bgreenwell/statlingua/blob/main/docs/articles/statlingua.html

Provides detailed context about the Carseats dataset, including variable descriptions, the model's goal, and included interaction terms, to guide the LLM's explanation.

```R
carseats_context <- "
The model uses a data set on child car seat sales (in thousands of units) at 400 different stores.
The goal is to identify factors associated with sales.
The variables are:
  * Sales: Unit sales (in thousands) at each location (the response variable).
  * CompPrice: Price charged by competitor at each location.
  * Income: Community income level (in thousands of dollars).
  * Advertising: Local advertising budget for the company at each location (in thousands of dollars).
  * Population: Population size in the region (in thousands).
  * Price: Price the company charges for car seats at each site.
  * ShelveLoc: A factor with levels 'Bad', 'Good', and 'Medium' indicating the quality of the shelving location for the car seats. ('Bad' is the reference level).
  * Age: Average age of the local population.
  * Education: Education level at each location.
  * Urban: A factor ('No', 'Yes') indicating if the store is in an urban or rural location. ('No' is the reference level).
  * US: A factor ('No', 'Yes') indicating if the store is in the US or not. ('No' is the reference level).
Interaction terms `Income:Advertising` and `Price:Age` are also included.
The data set is simulated. We want to understand key drivers of sales and how to interpret the interaction terms.
"
```

--------------------------------

### Parsing JSON Output from explain()

Source: https://github.com/bgreenwell/statlingua/blob/main/docs/articles/statlingua.html

Demonstrates how to parse the JSON output from explain() into an R list for further programmatic use. This is useful when the 'style' argument is set to 'json'.

```R
library(statlingua)
library(jsonlite)

# Assume 'json_explanation' is the string output from explain(..., style = "json")

parsed_explanation <- fromJSON(json_explanation)

```

--------------------------------

### Request Plain Text Output from Statlingua

Source: https://github.com/bgreenwell/statlingua/blob/main/docs/articles/statlingua.html

Use the `style = "text"` argument to get a plain text explanation of a statistical model. Specify the target audience and verbosity level.

```R
explain(fm_sleep, client = client, context = sleepstudy_context,
        audience = "researcher", verbosity = "moderate", style = "text")
```

--------------------------------

### Define Context for Model Explanation

Source: https://github.com/bgreenwell/statlingua/blob/main/docs/articles/statlingua.html

Defines a string variable containing contextual information about the Pima Indians diabetes dataset and the logistic regression model. This context is used to guide the explanation generated by Statlingua.

```r
pima_context <- "
This logistic regression model attempts to predict the likelihood of a Pima
Indian woman testing positive for diabetes. The data is from a study on women of
Pima Indian heritage, aged 21 years or older, living near Phoenix, Arizona. The
response variable 'type' is binary: 'Yes' (tests positive for diabetes) or 'No'.

Predictor variables include:
  - npreg: Number of pregnancies.
  - glu: Plasma glucose concentration in an oral glucose tolerance test.
  - bp: Diastolic blood pressure (mm Hg).
  - skin: Triceps skin fold thickness (mm).
  - bmi: Body mass index (weight in kg / (height in m)^2).
  - ped: Diabetes pedigree function (a measure of genetic predisposition).
  - age: Age in years.

The goal is to understand which of these factors are significantly associated
with an increased or decreased odds of having diabetes. We are particularly
interested in interpreting coefficients as odds ratios.
"
```

--------------------------------

### Load statlingua and Connect to Google Gemini

Source: https://github.com/bgreenwell/statlingua/blob/main/docs/articles/statlingua.html

Loads the statlingua package and establishes a connection to a Google Gemini model for generating explanations. The 'echo = "none"' argument suppresses model output.

```R
library(statlingua)

# Establish client connection
client <- ellmer::chat_google_gemini(echo = "none")
```