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

``bash
npm install stsjs
`

🏃 Quick Start

`javascript
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

$3


`javascript
// 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);
`

$3


`javascript
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);
`

$3


`javascript
// 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);
`

$3


`javascript
// 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);
`

$3


`javascript
// 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);
`

$3


`javascript
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
`

$3


`javascript
// 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"]
`

$3


`javascript
// 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

$3


`javascript
// 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());
`

$3


`javascript
// 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);
`

$3


`javascript
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

$3

- 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)

$3

- 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)

$3

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

$3

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

📈 Pattern Detection Capabilities

$3

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

$3

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

$3

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

$3

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

🔧 Configuration Options

$3

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

$3

`javascript
// 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

$3

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

$3

- 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:

`javascript
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

$3


`javascript
{
"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)"
}
`

$3

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

$3

`javascript
{
"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.

$3

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

$3

`bash
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: support@stsjs.com
- 🐛 Issues: GitHub Issues
- 💬 Discussions: GitHub Discussions
- 📖 Wiki: Project Wiki

---

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