README.md

libincstats

incstats is a C library for efficiently computing running statistics, such as mean, variance, skewness, kurtosis, central moments, and finding the maximum and minimum values in a dataset. The library is designed to handle weighted data points, making it suitable for a wide range of applications.

Status

Features

• Compute running mean, variance, skewness, and kurtosis.
• Calculate central moments up to a specified order.
• Calculate standardized central moments up to a specified order.
• Track maximum and minimum values.
• Designed for efficiency and simplicity.
• Handles weighted data points.

Installation

To build and install the library, you will need CMake version 3.0 or higher. Follow the steps below:

1. Clone the repository:

   git clone https://github.com/borchehq/incstats.git
   cd incstats

2. Create a build directory and navigate into it:

    mkdir build
    cd build

3. Configure the project using CMake:

    cmake ..

4. Build the project:

    make

5. Run the tests (optional):

    make test

6. Install the library:

    sudo make install

Usage

Include the incstats header files in your project to use the library functions. Here is a brief overview of the available functions:

Running Mean

inline void incstats_mean(double x, double w, double *buffer);
inline void incstats_mean_finalize(double *mean, double *buffer);

Running Variance

inline void incstats_variance(double x, double w, double *buffer);
inline void incstats_variance_finalize(double *results, double *buffer);

Running Skewness

inline void incstats_skewness(double x, double w, double *buffer);
inline void incstats_skewness_finalize(double *results, double *buffer);

Running Kurtosis

inline void incstats_kurtosis(double x, double w, double *buffer);
inline void incstats_kurtosis_finalize(double *results, double *buffer);

Central Moments

inline void incstats_central_moment(double x, double w, double *buffer, uint64_t p);
inline void incstats_central_moment_finalize(double *results, double *buffer, uint64_t p, bool standardize);

Maximum and Minimum

inline void incstats_max(double x, double *max);
inline void incstats_min(double x, double *min);

Important Note All functions for higher moments (e.g., kurtosis) will also compute all lower moments (e.g., skewness, variance, and mean) in a single pass. This feature enhances performance and reduces computational overhead, making it efficient to obtain all necessary statistical measures with minimal passes through the data.

Example Usage in C

#include <stdio.h>
#include "incstats.h"

int main() {
    double buffer[5] = {0}; // Initialize buffer for mean, variance, skewness, kurtosis
    double data[20] = {5.0, 3.2, 4.1, 2.9, 6.5, 4.3, 5.1, 3.8, 4.6, 2.7, 
                       3.3, 5.7, 4.9, 2.4, 3.6, 5.8, 4.0, 6.2, 3.4, 5.3};
    double w = 1.0;

    // Update statistics with new values
    for (int i = 0; i < 20; ++i) {
        incstats_kurtosis(data[i], w, buffer);  // This will also update mean, variance, and skewness
    }

    // Finalize and get results
    double results[4];
    incstats_kurtosis_finalize(results, buffer);

    printf("Mean: %f\n", results[0]);
    printf("Variance: %f\n", results[1]);
    printf("Skewness: %f\n", results[2]);
    printf("Kurtosis: %f\n", results[3]);

    return 0;
}

Example Usage in C++

#include <iostream> // Use C++ iostream for printing

// Include the C header file with extern "C"
extern "C" {
#include "incstats.h"
}

int main() {
    double buffer[5] = {0}; // Initialize buffer for mean, variance, skewness, kurtosis
    double data[20] = {5.0, 3.2, 4.1, 2.9, 6.5, 4.3, 5.1, 3.8, 4.6, 2.7, 
                       3.3, 5.7, 4.9, 2.4, 3.6, 5.8, 4.0, 6.2, 3.4, 5.3};
    double w = 1.0;

    // Update statistics with new values
    for (int i = 0; i < 20; ++i) {
        incstats_kurtosis(data[i], w, buffer);  // This will also update mean, variance, and skewness
    }

    // Finalize and get results
    double results[4];
    incstats_kurtosis_finalize(results, buffer);

    std::cout << "Mean: " << results[0] << std::endl;
    std::cout << "Variance: " << results[1] << std::endl;
    std::cout << "Skewness: " << results[2] << std::endl;
    std::cout << "Kurtosis: " << results[3] << std::endl;

    return 0;
}

License

This project is licensed under the Apache License, Version 2.0. You may obtain a copy of the License at:

http://www.apache.org/licenses/LICENSE-2.0

The full text of the license is available in the LICENSE.txt file in this repository.