README

[English] | Español

StatGuard is a robust statistical analysis suite for PHP focused on scientific precision and data integrity. It compares classic statistics against robust statistics to detect bias, noise, and measurement anomalies in a fully automated way.

Why StatGuard

Outliers are inevitable in telemetry, finance, sports tracking, and lab measurements. A single extreme value can pull the arithmetic mean far from the central mass, which biases decisions that depend on it. StatGuard provides robust estimators (median, MAD, trimmed and winsorized means, Huber M-estimator) that stay stable under contamination so you can trust summaries even when the data is messy.

Highlights

• ClassicStats: Full classic descriptive statistics implementation.
• StatsComparator: The analysis core that evaluates data fidelity and issues a verdict.
• ExportableTrait: First-class CSV and JSON exports for every stats class.
• Traits + Interfaces: Built-in data validation and extensible architecture.
• Independent engines: QuantileEngine and CentralTendencyEngine keep core math isolated and reusable.
• R parity: Quantiles and robust means are validated against R outputs.

Features

• 9 R-compatible quantile types (Hyndman & Fan 1-9).
• Robust means: Huber, winsorized, and trimmed.

Installation

Install via Composer:

composer require cjuol/statguard

Interactive Demo

An Outlier Playground is shipped in web/public/. It renders a dataset, injects synthetic outliers on demand, and shows classic vs. robust estimators (mean, median, Huber, trimmed, winsorized) side by side with a histogram overlay and the StatsComparator verdict.

# Local dev (native PHP, falls back to docker run if PHP not installed):
./scripts/serve-demo.sh                # http://127.0.0.1:8080

# Or with docker compose (VPS / long-running):
docker compose up -d                   # binds 127.0.0.1:8080 by default

docker compose up -d brings up only the demo service (PHP built-in server on web/public/). Override the bind with STATGUARD_DEMO_BIND=0.0.0.0 STATGUARD_DEMO_PORT=8080 docker compose up -d if you are not fronting it with a reverse proxy. The legacy Apache service is kept under the apache profile (docker compose --profile apache up web).

The UI calls POST /api.php with {"data": [...], "huberK": 1.345, "trimPercent": 0.1} and returns the full summary as JSON, making it a usable backend endpoint on its own.

Usage

Robust Estimators (Quick Start)

use Cjuol\StatGuard\RobustStats;

$stats = new RobustStats();
$data = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 1000];

$huber = $stats->getHuberMean($data);
$winsorized = $stats->getWinsorizedMean($data, 0.1);
$iqr = $stats->getIqr($data, RobustStats::TYPE_R_DEFAULT);

Robust estimators stay stable even with extreme outliers:

Example: Huber Mean

use Cjuol\StatGuard\RobustStats;

$robust = new RobustStats();
$data = [10, 12, 11, 15, 10, 1000];

$huber = $robust->getHuberMean($data, 1.345, 50, 0.001);

Example: Winsorized Mean (R-Compatible Quantile Type)

use Cjuol\StatGuard\RobustStats;

$robust = new RobustStats();
$data = [10, 12, 11, 15, 10, 1000];

// Type 7 matches R's default quantile() behavior.
$winsorized = $robust->getWinsorizedMean($data, 0.1, 7);

Comparator (Bias Detection)

use Cjuol\StatGuard\StatsComparator;

$comparator = new StatsComparator();
$data = [10, 12, 11, 15, 10, 1000];

$analysis = $comparator->analyze($data);

echo $analysis['verdict'];
// ALERT: Data is highly influenced by outliers. Use robust metrics.

Instant Export

use Cjuol\StatGuard\RobustStats;

$robust = new RobustStats();

file_put_contents('report.csv', $robust->toCsv($data));
echo $robust->toJson($data);

Summary Keys (Classic vs Robust)

Classic summary keys:

[
	'mean',
	'median',
	'stdDev',
	'sampleVariance',
	'cv',
	'outliersZScore',
	'count'
]

Robust summary keys:

[
	'mean',
	'median',
	'robustDeviation',
	'robustVariance',
	'robustCv',
	'iqr',
	'mad',
	'outliers',
	'confidenceIntervals',
	'count'
]

Metrics Comparison

R Quantile Types (1-9)

StatGuard matches R v4.x quantile definitions. The table below summarizes the nine Hyndman & Fan (1996) types supported by quantile().

Implemented Methods

ClassicStats

• getMean(array $data): float
• getMedian(array $data): float
• getDeviation(array $data): float
• getStandardDeviation(array $data): float
• getCoefficientOfVariation(array $data): float
• getSampleVariance(array $data): float
• getPopulationVariance(array $data): float
• getOutliers(array $data): array
• getSummary(array $data, bool $sort = true, int $decimals = 2): array
• toJson(array $data, int $options = JSON_PRETTY_PRINT): string
• toCsv(array $data, string $delimiter = ","): string

RobustStats

• getMean(array $data): float
• getMedian(array $data): float
• getDeviation(array $data): float
• getCoefficientOfVariation(array $data): float
• getRobustDeviation(array $data): float
• getRobustCv(array $data): float
• getRobustVariance(array $data): float
• getIqr(array $data): float
• getMad(array $data): float
• getOutliers(array $data): array
• getConfidenceIntervals(array $data): array
• getTrimmedMean(array $data, float $trimPercentage = 0.1): float
• getWinsorizedMean(array $data, float $trimPercentage = 0.1, int $type = 7): float
• getHuberMean(array $data, float $k = 1.345, int $maxIterations = 50, float $tolerance = 0.001): float
• getSummary(array $data, bool $sort = true, int $decimals = 2): array
• toJson(array $data, int $options = JSON_PRETTY_PRINT): string
• toCsv(array $data, string $delimiter = ","): string

StatsComparator

• __construct(?RobustStats $robust = null, ?ClassicStats $classic = null)
• analyze(array $data, int $decimals = 2): array

Mathematical Basis

Scaled Robust Deviation

To keep comparisons fair, MAD is scaled to be comparable to standard deviation under normal distributions:

$$\sigma_{robust} = MAD \times 1.4826$$

Robust Coefficient of Variation ($CV_r$)

Calculated over the median to avoid a single extreme value inflating volatility:

$$CV_r = \left( \frac{\sigma_{robust}}{|\tilde{x}|} \right) \times 100$$

R Compatibility & Accuracy

Every public statistic is tested against R v4.x outputs to ensure scientific accuracy. Quantile calculations use Type 7 by default (the same default as quantile() in R), and robust central tendency methods (trimmed mean, winsorized mean, Huber M-estimator) are verified via R comparison scripts in the repository.

Docker Profiles (Optional R Validation)

StatGuard does not require R for normal usage. The default container is lightweight and focused on PHP development. For scientific auditing, you can enable the r-validation profile to run the R comparison script.

# Default dev container (no R runtime)
docker compose up -d

# Run tests in the default container
composer run test

# Run R validation in the heavy profile
composer run validate-r

Performance Benchmarks (StatGuard vs MathPHP vs R)

Up to 5x faster than MathPHP in median calculations.

20x faster than MathPHP in robust mean estimation.

Dataset: 100,000 random floats. Benchmarks executed in the Docker performance profile using docker compose --profile performance run --rm benchmark report. R timings use system.time() and only measure computation (file load excluded).

Use json only when you need the shield data output (it does not update the markdown tables).

Scientific Parity (vs R)

Status shows ✅ when the absolute difference between StatGuard and R is below 0.0001.

Generate or refresh the table with php tests/BenchmarkStatGuard.php report.

Precision check (Huber): $\Delta = 0.0056111266$ for $n = 100000$ (warning threshold $10^{-10}$). Smaller datasets showed higher deltas, which are reported by the benchmark warnings.

Consistent results with R core within 0.01% tolerance on the benchmark scale (0-1000).

Tests and Quality

Validated with PHPUnit for full coverage of calculations and data validation.

./vendor/bin/phpunit tests

License

This project is licensed under the MIT License. See LICENSE for details.

Built with ❤️ by cjuol.