FTI.Statistics 1.1.2

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.2" />

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

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

Use Cases

Business Analytics

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

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.2 (Latest)

• Enhanced XML documentation with comprehensive examples and tooltips
• Improved code comments and developer experience
• Documentation improvements and clarity enhancements
• Better IntelliSense support with detailed parameter descriptions

Version 1.1.1

• Documentation improvements and usage examples

Version 1.1.0

• 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.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