firmware-base/docs-c/core/xstatistics.md

title	description	keywords
XStatistics Class - Statistical Analysis Toolkit	A lightweight C++ class for statistical analysis, providing functionality for calculating mean, min/max, variance, and standard deviation of numerical datasets	ESP32 statistics C++ industrial standard deviation variance average

XStatistics

Path: src/modbus/xstatistics.h

Revision History: Initial documentation

The XStatistics module provides a lightweight statistical analysis toolkit for numerical datasets. It is designed for use in industrial applications on ESP32 platforms where standard C++ libraries might not be available. The Statistic class enables efficient calculation of basic statistical measures like average, minimum, maximum, variance, and standard deviations without requiring dynamic memory allocation.

REQUIREMENTS

• No specific hardware requirements
• C++ compiler supporting C++11 features
• Arduino core for ESP32

PROVIDES

• Statistic class for collecting and analyzing numerical datasets
• Template functions for basic operations (MIN, MAX, ABS)
• Conditional compilation for standard deviation functionality using the STAT_USE_STDEV flag

FEATURES

• Calculation of basic statistical measures (count, sum, min, max, average)
• Optional calculation of variance and standard deviation
• Memory-efficient implementation suitable for embedded systems
• No dynamic memory allocation required
• Incremental calculation methods that avoid storing the entire dataset

DEPENDENCIES

• Arduino.h
• math.h

graph TD
    XStatistics --> Arduino
    XStatistics --> Math

BEHAVIOUR

The Statistic class collects numerical data points one at a time and maintains running calculations of statistical measures.

graph TD
    Start[Create Statistic object] --> Clear[Initialize counters]
    Clear --> Add[Add data point]
    Add --> Calculate[Calculate statistics]
    Add --> |More data points| Add
    Calculate --> |mean/average| Mean
    Calculate --> |min/max| MinMax
    Calculate --> |count| Count
    Calculate --> |sum| Sum
    
    subgraph "Optional functionality"
    Calculate --> |STAT_USE_STDEV| Variance
    Variance --> PopStdev[Population standard deviation]
    Variance --> UnbiasedStdev[Unbiased standard deviation]
    end

TODOS

PERFORMANCE

• The code includes an optimization comment indicating a 10% faster calculation method for standard deviation, but it limits samples to 65K due to potential overflow. Consider implementing a version that handles larger datasets.
• For larger datasets, consider adding functionality to discard outliers or implement online algorithms that require less memory.

SECURITY

• No significant security concerns as this is a mathematical utility class without I/O operations.
• Consider adding bounds checking to prevent potential numerical overflows in extreme use cases.

COMPLIANCE

• The implementation follows standard computational formulas for statistical measures.
• The class might need additional methods like confidence intervals or hypothesis testing for compliance with specific industrial data analysis standards.

RECOMMENDATIONS

• Use this class when you need to monitor trends and statistics for sensor data or control variables.
• When using on systems with limited floating-point performance, consider monitoring the computational overhead.
• The optional standard deviation features can be disabled by removing the STAT_USE_STDEV definition to reduce code size and execution time.
• Consider extending the class with additional statistical functions like median, mode, or quartile calculations for more comprehensive analysis.