StsJS

A comprehensive JavaScript library for statistical analysis with automatic insight generation. Transform CSV data into deep statistical analysis with natural language interpretations.

🚀 Key Features

• 📊 Complete Descriptive Statistics - Central tendency, dispersion, position, and shape measures
• 🔬 Inferential Statistics - Hypothesis testing, confidence intervals, and normality tests
• 🔗 Multivariate Analysis - Correlations, regressions, and relationship analysis
• 🧠 Automatic Insights - Intelligent pattern detection and natural language interpretation
• 📈 Pattern Detection - Trends, seasonality, outliers, clusters, and anomalies
• 💬 Natural Language Reports - Plain English explanations of statistical results
• 🎯 Smart Recommendations - Context-aware suggestions based on analysis results
• ✅ Robust Validation - Comprehensive data quality checks and assumption testing

📦 Installation

npm install stsjs

🏃 Quick Start

import StsJS from 'stsjs';

const stats = new StsJS();

// Load your CSV data
const data = stats.loadCSV('data.csv');

// Get comprehensive analysis
const summary = stats.generateSummaryReport(data);
console.log(summary);

// Detect patterns automatically
const patterns = stats.identifyPatterns(data);
console.log(patterns);

// Analyze specific relationships
const correlation = stats.correlationPearson(data.column1, data.column2);
const interpretation = stats.interpretResults(correlation);
console.log(interpretation.plainLanguage);

📊 Core Modules

Data Loading & Validation

// Load and clean CSV data
const dataset = stats.loadCSV('data.csv', {
    delimiter: ',',
    header: true,
    skipEmptyLines: true
});

// Validate data quality
const validation = stats.validateData(dataset);
console.log(validation);

// Get dataset information
const info = stats.getDataInfo(dataset);

Descriptive Statistics

const column = stats.dataLoader.getColumn(dataset, 'sales');

// Central tendency
const mean = stats.mean(column);
const median = stats.median(column);
const mode = stats.mode(column);

// Dispersion
const stdDev = stats.standardDeviation(column);
const variance = stats.variance(column);
const range = stats.range(column);

// Position
const quartiles = stats.quartiles(column);
const percentile90 = stats.percentile(column, 90);

// Shape
const skewness = stats.skewness(column);
const kurtosis = stats.kurtosis(column);

Inferential Statistics

// Hypothesis Testing
const tTestResult = stats.tTest(sample1, sample2, 'two-sample');
const anovaResult = stats.anovaTest([group1, group2, group3]);
const chiSquareResult = stats.chiSquareTest(category1, category2);

// Confidence Intervals
const meanCI = stats.confidenceInterval(sample, 0.95);
const proportionCI = stats.proportion(successes, total, 0.95);

// Normality Tests
const shapiroTest = stats.shapiroWilkTest(sample);
const normalityBatch = stats.normalityTests.batchNormalityTest(sample);

Correlation Analysis

// Different correlation methods
const pearson = stats.correlationPearson(x, y);
const spearman = stats.correlationSpearman(x, y);
const kendall = stats.kendall(x, y);

// Correlation matrix for multiple variables
const corrMatrix = stats.correlationMatrix(dataset, 'pearson');
console.log(corrMatrix.strongCorrelations);

Regression Analysis

// Linear regression
const linearReg = stats.linearRegression(x, y);
console.log(linearReg.equation); // y = 2.34 + 1.56x
console.log(linearReg.rSquared); // 0.78

// Multiple regression
const multipleReg = stats.multiple(dataset, 'target', ['feature1', 'feature2']);
console.log(multipleReg.coefficients);

// Polynomial regression
const polyReg = stats.polynomial(x, y, 2);

// Cross-validation
const cvResults = stats.crossValidation(x, y, 'linear', 5);

Pattern Detection

const patterns = stats.identifyPatterns(dataset);

// Access specific patterns
console.log(patterns.trends);        // Increasing/decreasing trends
console.log(patterns.seasonality);   // Seasonal patterns in time series
console.log(patterns.outliers);      // Statistical outliers
console.log(patterns.correlations);  // Strong relationships
console.log(patterns.clustering);    // Natural data clusters

Automatic Interpretation

// Get plain English interpretation of any statistical test
const testResult = stats.tTest(group1, group2);
const interpretation = stats.interpretResults(testResult);

console.log(interpretation.plainLanguage);
// "✓ SIGNIFICANT RESULT: Found a meaningful difference between groups..."

console.log(interpretation.recommendations);
// ["Examine practical significance of the finding", "Consider replicating with independent data"]

Comprehensive Reports

// Generate complete analysis report
const report = stats.generateSummaryReport(dataset);

console.log(report.keyInsights);
console.log(report.dataQuality);
console.log(report.recommendations);

// Export in different formats
const textReport = stats.reportGenerator.exportSummary(report, 'text');
const csvReport = stats.reportGenerator.exportSummary(report, 'csv');

🎯 Advanced Usage

Custom Analysis Pipeline

// 1. Load and validate data
const data = stats.loadCSV('sales_data.csv');
const cleaned = stats.cleanData(data);

// 2. Exploratory analysis
const summary = stats.generateSummaryReport(cleaned);
const patterns = stats.identifyPatterns(cleaned);

// 3. Hypothesis testing
const groups = stats.utils.groupBy(cleaned, 'category', { revenue: 'mean' });
const anovaResult = stats.anovaTest(Object.values(groups).map(g => g.revenue_mean));

// 4. Regression modeling
const model = stats.multiple(cleaned, 'revenue', ['marketing', 'seasonality', 'competition']);

// 5. Interpret and report
const interpretation = stats.interpretResults(model);
console.log(interpretation.formatForReport());

Working with Time Series

// Detect temporal patterns
const timePatterns = stats.patternDetector.detectTemporalPatterns(dataset);

// Analyze seasonality
const seasonal = stats.patternDetector.detectSeasonality(dataset);

// Trend analysis
const trends = stats.patternDetector.detectTrends(dataset);

Data Quality Assessment

const quality = stats.reportGenerator.assessDataQuality(dataset);

console.log(`Overall Quality Score: ${quality.overallScore}/100`);
console.log(`Completeness: ${quality.completenessScore}%`);
console.log(`Issues found: ${quality.issues.length}`);

🧪 Supported Statistical Tests

Hypothesis Tests

• t-tests (one-sample, two-sample, paired)
• z-tests (one-sample, two-sample)
• ANOVA (one-way analysis of variance)
• Chi-square (independence, goodness of fit)
• Mann-Whitney U (non-parametric)
• Wilcoxon (paired non-parametric)

Normality Tests

• Shapiro-Wilk (recommended for n < 50)
• Anderson-Darling (sensitive to tails)
• Kolmogorov-Smirnov (general purpose)
• Jarque-Bera (based on skewness and kurtosis)
• D'Agostino K-squared (large samples)
• Lilliefors (variant of KS test)

Correlation Methods

• Pearson (linear relationships)
• Spearman (monotonic relationships)
• Kendall Tau (robust to outliers)
• Partial correlation (controlling for third variables)

Regression Types

• Simple Linear (y = a + bx)
• Multiple Linear (multiple predictors)
• Polynomial (non-linear relationships)
• Logistic (binary outcomes)
• Stepwise Selection (automated feature selection)

📈 Pattern Detection Capabilities

Trend Analysis

• Linear and non-linear trends
• Change point detection
• Trend strength classification
• Statistical significance testing

Seasonality Detection

• Automatic period identification
• Seasonal strength measurement
• Peak and valley detection
• Multiple seasonal components

Outlier Detection

• IQR method (interquartile range)
• Z-score method
• Modified Z-score (robust)
• Contextual anomaly detection

Clustering Analysis

• K-means clustering
• Silhouette analysis
• Cluster quality assessment
• Natural grouping identification

🔧 Configuration Options

CSV Loading Options

const data = stats.loadCSV('data.csv', {
    delimiter: ',',        // Field separator
    header: true,          // First row contains headers
    skipEmptyLines: true,  // Skip empty rows
    encoding: 'utf8'       // File encoding
});

Statistical Test Parameters

// Customize significance levels
const result = stats.tTest(sample1, sample2, 'two-sample', 0.01); // α = 0.01

// Confidence intervals
const ci = stats.confidenceInterval(sample, 0.99); // 99% confidence

// Bootstrap settings
const bootstrap = stats.utils.bootstrap(sample, 'mean', 2000); // 2000 iterations

📋 Data Requirements

Supported Data Types

• Numeric: integers, floats, scientific notation
• Categorical: strings, booleans
• Temporal: ISO dates, common date formats
• Missing Values: null, undefined, empty strings, "NaN"

CSV Format Requirements

• UTF-8 encoding recommended
• Headers in first row (optional)
• Consistent field separators
• Proper handling of quotes and escapes

🚨 Error Handling

StsJS provides comprehensive error handling and validation:

try {
    const result = stats.tTest(sample1, sample2);
    console.log(result);
} catch (error) {
    console.error('Statistical test failed:', error.message);
    // "Sample size too small" or "Data contains non-numeric values"
}

Common validation errors:

• Insufficient sample size
• Non-numeric data in numeric operations
• Missing required columns
• Assumption violations
• Invalid parameter ranges

🎨 Example Output

Statistical Test Result

{
    "statistic": 2.847,
    "pValue": 0.0067,
    "significant": true,
    "confidenceInterval": { "lower": 1.23, "upper": 4.56 },
    "interpretation": "Strong evidence of difference between groups",
    "plainLanguage": "✓ SIGNIFICANT: Found meaningful difference between groups (p = 0.007)"
}

Pattern Detection Result

{
    "trends": [
        {
            "column": "sales",
            "direction": "increasing",
            "strength": "strong",
            "rSquared": 0.84
        }
    ],
    "insights": [
        {
            "type": "trend",
            "importance": "high",
            "message": "Found 1 strong trend(s) in your data"
        }
    ]
}

Comprehensive Report

{
    "title": "Statistical Summary Report",
    "basicInfo": {
        "totalRows": 1000,
        "totalColumns": 8,
        "memoryFootprint": "2.3 MB"
    },
    "dataQuality": {
        "overallScore": 87.3,
        "recommendation": "Good data quality - minor cleaning recommended"
    },
    "keyInsights": [
        "Strong positive correlation between marketing and sales",
        "Significant seasonal pattern detected in revenue",
        "3% outliers detected - investigate for data quality"
    ],
    "recommendations": [
        {
            "priority": "high",
            "title": "Investigate Strong Correlations",
            "description": "Perform regression analysis on highly correlated variables"
        }
    ]
}

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

git clone https://github.com/your-repo/stsjs.git
cd stsjs
npm install
npm test

Running Tests

npm test              # Run all tests
npm run test:watch    # Watch mode
npm run test:coverage # Coverage report

📚 Documentation

• API Documentation
• Statistical Methods Guide
• Examples and Tutorials
• Troubleshooting

🔬 Statistical Accuracy

StsJS implements well-established statistical algorithms with:

• Proper handling of edge cases
• Numerical stability considerations
• Standard statistical approximations
• Comprehensive assumption checking

All implementations follow standard statistical references and are validated against established statistical software.

⚡ Performance

• Optimized for datasets up to 100k rows
• Memory-efficient algorithms
• Lazy evaluation where appropriate
• Configurable precision vs. speed tradeoffs

📄 License

MIT License - see LICENSE file for details.

🏷️ Version History

• v1.0.0 - Initial release with core statistical functions
• v1.1.0 - Added pattern detection and automatic insights
• v1.2.0 - Enhanced interpretation and reporting capabilities

🆘 Support

• 📧 Email: [email protected]
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📖 Wiki: Project Wiki

StsJS - Making statistical analysis accessible through intelligent automation and natural language interpretation.