tpmjs/packages/tools/official/STATISTICS_TOOLS.md

Statistics Tools Implementation Summary

Successfully implemented 3 statistical analysis tools for the TPMJS official tools collection.

Tools Implemented

1. Permutation Test (@tpmjs/tools-permutation-test)

Path: /Users/ajaxdavis/repos/tpmjs/tpmjs/packages/tools/official/permutation-test

Purpose: Performs a permutation test to assess the statistical significance of the difference in means between two groups.

Features:

• Non-parametric hypothesis testing
• Configurable iterations (100-100,000)
• Returns p-value, observed difference, significance status
• No assumptions about distribution

Example:

const result = await permutationTestTool.execute({
  group1: [23, 25, 27, 29, 31],
  group2: [18, 20, 22, 24, 26],
  iterations: 10000
});
// Returns: pValue, observedDiff, significant, metadata

2. Multiple Testing Adjustment (@tpmjs/tools-multiple-testing-adjust)

Path: /Users/ajaxdavis/repos/tpmjs/tpmjs/packages/tools/official/multiple-testing-adjust

Purpose: Adjusts p-values for multiple comparisons using Bonferroni, Benjamini-Hochberg (BH), or Holm methods.

Features:

• Three adjustment methods:
  • Bonferroni: Most conservative, controls FWER
  • Benjamini-Hochberg (BH): Controls FDR, less conservative
  • Holm: Step-down procedure, more powerful than Bonferroni
• Returns adjusted p-values and indices of significant tests
• Handles monotonicity constraints correctly

Example:

const result = await multipleTestingAdjustTool.execute({
  pValues: [0.001, 0.02, 0.03, 0.15, 0.8],
  method: 'bh',
  alpha: 0.05
});
// Returns: adjusted[], significant[], method, alpha, metadata

3. Linear Regression OLS (@tpmjs/tools-linear-regression-ols)

Path: /Users/ajaxdavis/repos/tpmjs/tpmjs/packages/tools/official/linear-regression-ols

Purpose: Performs simple linear regression using Ordinary Least Squares (OLS) method.

Features:

• Calculates slope and intercept
• Computes R-squared (coefficient of determination)
• Returns residuals and predictions
• Handles edge cases (identical x or y values)

Example:

const result = await linearRegressionOLSTool.execute({
  x: [1, 2, 3, 4, 5],
  y: [2, 4, 5, 4, 5]
});
// Returns: slope, intercept, rSquared, residuals[], predictions[], metadata

Implementation Details

Architecture

• Each tool follows the TPMJS pattern using AI SDK v6
• Uses import { tool, jsonSchema } from 'ai'
• TypeScript with strict type checking
• No external statistical libraries - implemented from scratch
• Comprehensive input validation

File Structure (each tool)

tool-name/
├── src/
│   └── index.ts          # Main implementation
├── dist/                 # Built output (ESM + TypeScript declarations)
│   ├── index.js
│   └── index.d.ts
├── package.json          # Package configuration with tpmjs metadata
├── tsconfig.json         # TypeScript configuration
├── tsup.config.ts        # Build configuration
└── README.md            # Documentation with examples

Build Status

✅ All tools build successfully ✅ All tools pass TypeScript type-check ✅ All tools tested and working correctly

Statistical Algorithms Implemented

Permutation Test:

• Fisher-Yates shuffle algorithm
• Monte Carlo permutation sampling
• Two-tailed p-value calculation

Multiple Testing Adjustment:

• Bonferroni correction: p_adj = min(1, p × n)
• Benjamini-Hochberg: Monotonic FDR control
• Holm step-down: Sequential rejection procedure

Linear Regression:

• OLS slope: β₁ = Σ((x-x̄)(y-ȳ)) / Σ((x-x̄)²)
• OLS intercept: β₀ = ȳ - β₁x̄
• R-squared: R² = 1 - (SSE/SST)

Package Metadata

Each tool includes proper tpmjs metadata in package.json:

• Category: statistics
• Framework: vercel-ai
• Tool documentation with parameters and returns
• Published to npm under @tpmjs scope

Testing Results

All three tools have been tested and verified working:

✅ Permutation Test: Correctly identifies significance with p-values
✅ Multiple Testing Adjust: Properly adjusts p-values with BH method
✅ Linear Regression: Accurately calculates slope, intercept, and R²

Next Steps

The tools are ready to be:

1. Added to blocks.yml (to be done by user)
2. Published to npm
3. Documented on tpmjs.com

Dependencies

• ai: ^6.0.0-beta.124 (AI SDK v6)
• No external statistical libraries required
• All algorithms implemented from scratch for transparency and control