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 weightedSampleCount);
float   UxHwFloatDistFromWeightedSamples(WeightedFloatSample *  samples, size_t weightedSampleCount);

Description

The UxHwDoubleDistFromWeightedSamples() function returns a floating-point value which is the mean of a distribution based on weighted samples from samples array. Weighted samples is a collection of samples and corresponding weights. Weights can be arbitrary non-negative floating-point values representing the relative frequency of samples. On architectures that associate distributional information with floating-point values, UxHwDoubleDistFromWeightedSamples() creates a distributional value that follows the empirical distribution of the first weightedSampleCount elements of the array samples. 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 a pointer to WeightedDoubleSample or to WeightedFloatSample struct, based on the function signature. We specify these structs as part of the UxHw API as:

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

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

The sample field stores the arithmetic value of the weighted sample, while the sampleWeight stores its weight.

• weightedSampleCount — The count of elements of the samples array, that the Signaloid compute engine will convert to a distributional value and calculate its mean.

Return Values

The UxHwDoubleDistFromWeightedSamples() function returns the weighted mean value of the first weightedSampleCount elements of the samples array. If weightedSampleCount 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;
    WeightedDoubleSample    samples[N] =
                            {
                                {.sample = 1.0, .sampleWeight = 1.0},
                                {.sample = 2.0, .sampleWeight = 2.0},
                                {.sample = 3.0, .sampleWeight = 3.0}
                            };

    a = UxHwDoubleDistFromWeightedSamples(samples, N);

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

    return 0;
}