---
title: "sgmean: Trimmed Mean Compatible with Statgraphics"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{sgmean: Trimmed Mean Compatible with Statgraphics}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>")
```

## Introduction

The `sgmean` package implements a trimmed mean method that replicates
the behavior of Statgraphics software. This method differs
fundamentally from R built-in mean(..., trim) in how it handles boundary values.

## Origin of this Package

During statistical analysis using both R and Statgraphics, a systematic
difference was observed between the trimmed mean results produced by each
software. Despite an extensive review of the Statgraphics documentation,
no explicit description of its trimmed mean algorithm was found.

Through systematic mathematical reverse engineering of Statgraphics output
using trial and error with multiple datasets, the underlying proportional
discount formula was identified and validated. This package makes that method
transparent, reproducible, and available to the R community for the first time.

## The Mathematical Difference

Given a sorted vector of n values and a trim fraction, both methods compute
k = trim x n. The key difference is:

- **R base**: truncates k to the nearest integer and completely removes that many values from each end.
- **sgmean**: applies a proportional discount of k to the boundary values, without removing them entirely.

## Practical Example

```{r example}
library(sgmean)
x <- c(10, 20, 30, 40, 50, 60, 70, 80, 90, 200)
result_r  <- mean(x, trim = 0.05)
result_sg <- sgmean(x, trim = 0.05)
cat("R base  (trim=0.05):", result_r,  "
")
cat("sgmean  (trim=0.05):", result_sg, "
")
cat("Difference:         ", abs(result_r - result_sg), "
")
```

## When Do Both Methods Agree?

```{r comparison}
x <- c(10, 20, 30, 40, 50, 60, 70, 80, 90, 200)
cat("trim=0.10 | R base:", mean(x, trim=0.10), "| sgmean:", sgmean(x, trim=0.10), "
")
cat("trim=0.05 | R base:", mean(x, trim=0.05), "| sgmean:", sgmean(x, trim=0.05), "
")
cat("trim=0.15 | R base:", mean(x, trim=0.15), "| sgmean:", sgmean(x, trim=0.15), "
")
```

## Conclusion

The sgmean method provides a continuous and mathematically consistent
trimmed mean for any trim fraction between 0 and 0.99, replicating the
behavior of Statgraphics software and avoiding the discontinuities
introduced by integer truncation in R built-in mean().