FTI.Statistics 1.1.0

FTI.Statistics- 🚦 Error Handling

• 🎯 Performance Considerations
• 💡 Best Practices & Common Patterns
• 📊 Use Cases
• 🔄 Version HistoryNuGet Version](https://www.nuget.org/packages/FTI.Statistics/)

A comprehensive, high-performance statistics library for .NET providing essential mathematical statistics functions for real-valued numerical data. FTI.Statistics offers robust statistical analysis capabilities with production-ready reliability, comprehensive input validation, and zero external dependencies.

📑 Table of Contents

• 🚀 Key Features
• 📦 Installation
• 🔧 Framework Support
• 📋 Quick Start Examples
• 📚 Complete Function Reference
• 🚦 Error Handling
• 🎯 Performance Considerations
• � Best Practices & Common Patterns
• �📊 Use Cases
• 🔄 Version History
• 📄 License
• 🤝 Contributing
• 📧 Contact & Support

🚀 Key Features

📊 Central Tendency & Descriptive Statistics

• Mean: Arithmetic, geometric, and harmonic means with optional weights
• Median: Standard median with robust median-low and median-high variants
• Mode: Single and multi-mode detection for discrete data
• Summary: Comprehensive statistical overview (count, mean, std, min, Q1, median, Q3, max)

📈 Dispersion & Variability Analysis

• Variance & Standard Deviation: Sample and population variants
• Range: Simple data range calculation (max - min)
• Interquartile Range (IQR): Robust dispersion measure (Q3 - Q1)
• Root Mean Square (RMS): For signal processing and quality metrics

📉 Distribution & Percentile Analysis

• Quantiles: Flexible n-quantile calculation with exclusive/inclusive methods
• Percentiles: Get values at any percentile (0-100) with linear interpolation
• Grouped Statistics: Median estimation for binned/grouped data

🔗 Relationships & Correlation

• Correlation: Pearson (linear) and Spearman (rank) correlation coefficients
• Covariance: Sample covariance for joint variability analysis
• Linear Regression: Ordinary least squares with proportional fitting option

🎯 Advanced Statistical Functions

• Kernel Density Estimation (KDE): Multiple kernel types with bandwidth control
• Normal Distribution: PDF, CDF calculations with error function approximation
• Combinatorial Functions: Binomial and multinomial coefficients
• Special Functions: Beta, Gamma, Polygamma, and Riemann Zeta functions

🛡️ Robust Design

• Comprehensive Input Validation: NaN, Infinity, and edge case handling
• Consistent Error Handling: Custom StatisticsError for clear error reporting
• Performance Optimized: Efficient algorithms with minimal memory allocation
• Zero Dependencies: Lightweight package with no external dependencies

📦 Installation

Package Manager Console

Install-Package FTI.Statistics

.NET CLI

dotnet add package FTI.Statistics

PackageReference

<PackageReference Include="FTI.Statistics" Version="1.1.0" />

🔧 Framework Support

• ✅ .NET Core 3.1
• ✅ .NET 6.0
• ✅ .NET 7.0
• ✅ .NET 8.0
• ✅ .NET 9.0

📋 Quick Start Examples

Basic Descriptive Statistics

using FTI.Statistics;

var data = new List<double> { 1.2, 2.5, 3.1, 4.7, 5.3, 6.8, 7.2, 8.9, 9.1, 10.5 };

// Central tendency
double mean = Stats.Mean(data);                    // 5.83
double median = Stats.Median(data);                // 6.05
double mode = Stats.Mode(new[] { 1, 2, 2, 3, 3, 3 }); // 3

// Dispersion
double range = Stats.Range(data);                  // 9.3
double iqr = Stats.InterquartileRange(data);       // 4.55
double stdev = Stats.Stdev(data);                  // 3.12

// Percentiles
double p25 = Stats.Percentile(data, 25);           // 25th percentile
double p75 = Stats.Percentile(data, 75);           // 75th percentile
double p90 = Stats.Percentile(data, 90);           // 90th percentile

Comprehensive Data Summary

var data = new List<double> { 12.5, 15.2, 18.7, 22.1, 25.8, 28.3, 31.9, 35.4, 38.7, 42.1 };

var summary = Stats.Summary(data);
Console.WriteLine(summary);
// Output: Count: 10, Mean: 27.0700, Std: 9.8234, Min: 12.5000, Q1: 19.4000, Median: 27.0500, Q3: 33.6500, Max: 42.1000

// Access individual properties
Console.WriteLine($"Dataset has {summary.Count} points");
Console.WriteLine($"Mean: {summary.Mean:F2}");
Console.WriteLine($"Standard Deviation: {summary.StandardDeviation:F2}");
Console.WriteLine($"Median: {summary.Median:F2}");

Correlation and Regression Analysis

var x = new List<double> { 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 };
var y = new List<double> { 2.1, 3.9, 6.2, 7.8, 10.1, 12.3, 14.2, 16.1, 18.3, 20.2 };

// Correlation analysis
double pearson = Stats.Correlation(x, y);                    // Pearson correlation
double spearman = Stats.Correlation(x, y, "ranked");         // Spearman correlation
double covariance = Stats.Covariance(x, y);                  // Sample covariance

// Linear regression
var (slope, intercept) = Stats.LinearRegression(x, y);
Console.WriteLine($"y = {slope:F3}x + {intercept:F3}");

Advanced Statistical Functions

var data = new double[] { 1.2, 2.3, 2.1, 3.4, 2.8, 3.9, 4.1, 3.7, 4.5, 5.2 };

// Kernel Density Estimation
var evalPoints = new double[] { 1.0, 2.0, 3.0, 4.0, 5.0 };
var kdeResult = Stats.Kde(data, evalPoints, h: 0.5, kernel: "normal");

// Normal distribution
var normalDist = new Stats.NormalDist(mu: 3.0, sigma: 1.5);
double pdf = normalDist.Pdf(2.5);    // Probability density at x=2.5
double cdf = normalDist.Cdf(2.5);    // Cumulative probability at x=2.5

// Combinatorial functions
long binomial = Stats.Binomial(10, 3);                       // 10 choose 3 = 120
long multinomial = Stats.Multinomial(10, new List<int> { 3, 3, 4 }); // Multinomial coefficient

Working with Different Data Types

// Works with various IEnumerable<double> sources
var array = new double[] { 1, 2, 3, 4, 5 };
var list = new List<double> { 1, 2, 3, 4, 5 };
var enumerable = Enumerable.Range(1, 5).Select(x => (double)x);

double arrayMean = Stats.Mean(array);        // All work the same
double listMean = Stats.Mean(list);
double enumerableMean = Stats.Mean(enumerable);

// Robust error handling
try 
{
    Stats.Mean(new double[] { });  // Empty data
}
catch (Stats.StatisticsError ex)
{
    Console.WriteLine($"Error: {ex.Message}");
}

📚 Complete Function Reference

Central Tendency

Dispersion & Spread

Distribution Analysis

Relationships & Correlation

Advanced Functions

🚦 Error Handling

FTI.Statistics uses a custom StatisticsError exception for all statistical errors:

try 
{
    var result = Stats.Mean(emptyData);
}
catch (Stats.StatisticsError ex)
{
    // Handle statistical errors (empty data, invalid parameters, etc.)
    Console.WriteLine($"Statistical Error: {ex.Message}");
}

Common error scenarios:

• Empty or null data sequences
• Insufficient data points (e.g., variance needs ≥2 points)
• Invalid parameters (e.g., negative percentiles)
• NaN or Infinity values in data
• Mismatched data lengths for paired functions

🎯 Performance Considerations

• Lazy Evaluation: Functions accept IEnumerable<double> for maximum flexibility
• Efficient Enumeration: Data is materialized only when necessary to minimize memory usage
• Memory Optimization: Minimal object allocation in hot paths for better GC performance
• Algorithm Efficiency: O(n) or O(n log n) complexity for most functions
• Single-Pass Processing: Most functions process data in a single enumeration where possible
• Input Validation: Comprehensive validation with minimal performance overhead
• Zero Dependencies: No external dependencies for lightweight deployment

Performance Tips

// ✅ Good: Use List<double> for multiple operations on the same data
var dataList = data.ToList();
var mean = Stats.Mean(dataList);
var stdev = Stats.Stdev(dataList);

// ⚠️ Avoid: Multiple enumerations of expensive IEnumerable
var expensiveData = database.GetValues(); // Expensive query
var mean = Stats.Mean(expensiveData);     // First enumeration
var stdev = Stats.Stdev(expensiveData);   // Second enumeration - BAD

📊 Use Cases

Business Analytics

var salesData = GetMonthlySales();
var summary = Stats.Summary(salesData);
var trend = Stats.LinearRegression(months, salesData);

💡 Best Practices & Common Patterns

Data Preparation

// Always validate and clean your data first
var rawData = GetRawData();
var cleanData = rawData.Where(x => !double.IsNaN(x) && !double.IsInfinity(x)).ToList();

// Use Summary() for initial data exploration
var summary = Stats.Summary(cleanData);
Console.WriteLine($"Data quality check: {summary}");

Efficient Data Processing

// Materialize expensive enumerables once
var data = expensiveQuery.ToList();

// Perform multiple analyses efficiently
var stats = new {
    Count = data.Count,
    Mean = Stats.Mean(data),
    Median = Stats.Median(data),
    StdDev = Stats.Stdev(data),
    Range = Stats.Range(data),
    IQR = Stats.InterquartileRange(data)
};

Robust Statistical Analysis

// Use IQR and median for robust statistics (less sensitive to outliers)
double robustCenter = Stats.Median(data);
double robustSpread = Stats.InterquartileRange(data);

// Combine with traditional statistics for comprehensive analysis
double traditionalCenter = Stats.Mean(data);
double traditionalSpread = Stats.Stdev(data);

// Detect potential outliers
var outlierThreshold = robustCenter + 1.5 * robustSpread;
var outliers = data.Where(x => Math.Abs(x - robustCenter) > outlierThreshold);

Quality Control

var measurements = GetProductMeasurements();
double mean = Stats.Mean(measurements);
double controlLimit = mean + 3 * Stats.Stdev(measurements);

Research & Data Science

var experimentData = GetExperimentResults();
var (slope, intercept) = Stats.LinearRegression(dosage, response);
double correlation = Stats.Correlation(treatment, outcome);

🔄 Version History

Version 1.1.0 (Latest)

• ✨ NEW: Range() - Calculate data range
• ✨ NEW: InterquartileRange() - Calculate IQR for robust dispersion
• ✨ NEW: Percentile() - Get values at any percentile with interpolation
• ✨ NEW: Summary() - Comprehensive descriptive statistics
• 🚀 Enhanced performance through optimized enumerable handling
• 🛡️ Improved input validation with NaN/Infinity checking
• 📚 Extensive XML documentation with examples
• 🧹 Removed unused dependencies for lighter package

Version 1.0.1

• 📖 Documentation improvements and usage examples

Version 1.0.0

• 🎉 Initial release with core statistical functions

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Contributing

Contributions are welcome! Whether you're fixing bugs, adding features, or improving documentation, your help is appreciated.

How to Contribute

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes with appropriate tests
4. Commit your changes (git commit -m 'Add amazing feature')
5. Push to the branch (git push origin feature/amazing-feature)
6. Open a Pull Request

Development Guidelines

• Follow existing code style and conventions
• Add comprehensive XML documentation for new functions
• Include unit tests for new functionality
• Ensure backward compatibility unless major version change
• Update README.md for new features

Reporting Issues

• Use the GitHub issue tracker
• Provide clear description and reproduction steps
• Include relevant error messages and stack traces
• Specify .NET version and environment details

📧 Contact & Support

• Author: Soumyadip Majumder
• NuGet Package: FTI.Statistics
• Issues: GitHub Issues
• Documentation: API Reference

Support

• 📖 Check the README and examples first
• 🔍 Search existing issues before creating new ones
• 💬 Use GitHub Discussions for questions and ideas
• 🐛 Report bugs with detailed reproduction steps

© 2025 Soumyadip Majumder, FTIRD. All rights reserved.

Made with ❤️ for the .NET community | Happy Coding! 🎉