Distribution from Weighted Samples

Name

UxHwDoubleDistFromWeightedSamples, UxHwFloatDistFromWeightedSamples — Create a distributional value from an array of weighted samples.

Synopsis

#include <stddef.h>
#include <uxhw.h>

double  UxHwDoubleDistFromWeightedSamples(WeightedDoubleSample *  samples, size_t sampleCount, size_t unweightedSampleCount));
float   UxHwFloatDistFromWeightedSamples(WeightedFloatSample *  samples, size_t sampleCount, size_t unweightedSampleCount));

Description

The UxHwDoubleDistFromWeightedSamples() function returns a floating-point value which is the mean of a distribution based on weighted samples from samples array. The samples array must have been created by using a collection of unweighted samples. The number of unweighted samples used to create the weighted samples is represented by unweightedSampleCount parameter. On architectures that associate distributional information with floating-point values, UxHwDoubleDistFromWeightedSamples() creates a distributional value that follows the empirical distribution of the first sampleCount elements of the array samples, taking into account the number of the original unweighted samples unweightedSampleCount. On such architectures, the return value is associated, at the architecture level, with the distributional value created and it is equal to the mean of the distribution.

Parameters

• samples — The pointer to the array of weighted samples. The samples parameter is either WeightedDoubleSample or WeightedFloatSample struct, based on the function. These structs, are specified in uxhw.h as:

typedef struct {
    double sample;
    double sampleWeight;
} WeightedDoubleSample;

typedef struct {
    float sample;
    float sampleWeight;
} WeightedFloatSample;

The samples value stores the arithmetic value of the Weighted sample, while the sampleWeight stores its weight.

• sampleCount — The number of elements of the samples array that is going to be used for the calculation of the distributional value and its mean.
• unweightedSampleCount — The number of the original unweighted samples that were used to calculate the array of samples.

Return Values

The UxHwDoubleDistFromWeightedSamples() function returns the weighted mean value of the first sampleCount elements of the samples array. If sampleCount is equal to 0, the function returns NaN.

✏️   Examples

#include <stddef.h>
#include <uxhw.h>
#include <stdio.h>

enum
{
    N = 3,
};

int
main(void)
{
    double                  a;
    size_t                  unweightedSampleCount;
    WeightedDoubleSample    samples[N] =
                            {
                                {.sample = 1.0, .sampleWeight = 1.0},
                                {.sample = 2.0, .sampleWeight = 2.0},
                                {.sample = 3.0, .sampleWeight = 3.0}
                            };

    /*
     *  Weighted samples can be created by any number of unweighted original samples greater.
     *  than sampleCount. It is up to the user to know how many unweighted samples have been
     *  used for the weighted samples.
     */
    unweightedSampleCount = 100;

    a = UxHwDoubleDistFromWeightedSamples(samples, N, unweightedSampleCount);

    printf("a = %lf\n", a);

    return 0;
}