ReBin.h File Reference

#include "Stroika/Foundation/StroikaPreComp.h"
#include "Stroika/Foundation/Containers/Sequence.h"
#include "Stroika/Foundation/Containers/Set.h"
#include "Stroika/Foundation/Traversal/DiscreteRange.h"
#include "Stroika/Foundation/Traversal/Range.h"
#include "ReBin.inl"

Go to the source code of this file.

Classes
class	Stroika::Foundation::Math::ReBin::BasicDataDescriptor< X_TYPE, VALUE_TYPE >
class	Stroika::Foundation::Math::ReBin::UpdatableDataDescriptor< X_TYPE, VALUE_TYPE >

Namespaces
namespace	Stroika::Foundation

Functions
template<typename SRC_DATA_DESCRIPTOR , typename TRG_DATA_DESCRIPTOR >
void	Stroika::Foundation::Math::ReBin::ReBin (const SRC_DATA_DESCRIPTOR &srcData, TRG_DATA_DESCRIPTOR *trgData)

Detailed Description

Note

Code-Status: Alpha

@todo   Clearly DOCUMENT and CHECK assumption in this code that X-value is non-decreasingly a function of bucket#
        In debug build, could do a pre-pass to assert this (if its not otherwise easy to test/verify)

        PROBABLY FALSE: INSTEAD TRY THIS STATEMENT AFTER I TEST/REIVEW:
            There is no requirement about how the X-values vary with the bucket numbers (though typically
            they increase monotonically with bucket number).

            The only requirement is that the buckets form a partition of some domain (so in other words, they
            don't overlap, but have no 'holes' in the middle. So they can be parition Range<XType> (some minx/maxx).

@todo   Consider adding an x-offset, so that we logically re-bin, plus shift along the x-axis by
        a (given) offset (in units of src-bin widths).

Definition in file ReBin.h.

Function Documentation

ReBin()

template<typename SRC_DATA_DESCRIPTOR , typename TRG_DATA_DESCRIPTOR >

void Stroika::Foundation::Math::ReBin::ReBin	(	const SRC_DATA_DESCRIPTOR &	srcData,
		TRG_DATA_DESCRIPTOR *	trgData
	)

Take one array of counts (buckets/samples) - and stretch them (rebin them) to another number of buckets.

Logically, think of a 2D graph, x versus y. The source buckets represent an approximation of a real curve (y=f(x)). The buckets represent equally spaced measurements along the x-axis and the corresponding y-axis value.

Re-binning means selecting a different (could be larger or smaller) bin count, and inferring the curve from the source bins, and producing target bins that match that curve as best as possible.

The new bins could also - have been offset slightly versus the new bins (that is the zeroth bin of the new set of bins need not start at the same x-value as the original set of bins).

Classically - this assumes the curve was fairly linear across the new set original set of bins. As a future exercise, we may want to experiment with different assumptions (like linear up/down according to prev and successive bins?).

Note

The bucket index really doesn't mean much of anything (if you use the SRC_DATA_DESCRIPTOR variant of the API), except that its used to address (name) buckets. Buckets underlying X-Range need not vary monotonically with bucket index (though beware that BasicDataDescriptor assumes this).

The only requirement ReBin() makes is that each bucket represents a Range, and that these ranges are contiguous and non-overlapping (a partition).

Note

When calling the simple ReBin() overload (with no source description) - the target data is all automatically zeroed.

But for the more ReBin() template variant with the SOURCE_DESCRIPTION, the caller must clear if desired. The reason to NOT clear (null) the target in this variant is that the caller may want to accumulate sereral ReBin sources into one.

Example Usage

uint32_t srcBinData[] = { 3, 5, 19, 2, 0, 0, 0 };
double  resultData[4];
ReBin (begin (srcBinData), end (srcBinData), begin (resultData), end (resultData));
EXPECT_TRUE (NearlyEquals ((3 + (5 * ((7.0 / 4.0) - 1))), resultData[0]));
EXPECT_TRUE (0 == resultData[3]);

Example Usage

uint32_t srcBinData[] = { 3, 5, 19, 2 };
double  resultData[8];
ReBin (begin (srcBinData), end (srcBinData), begin (resultData), end (resultData));
EXPECT_TRUE (NearlyEquals (1.5, resultData[0]));
EXPECT_TRUE (NearlyEquals (1.5, resultData[1]));
EXPECT_TRUE (NearlyEquals (2.5, resultData[2]));
EXPECT_TRUE (NearlyEquals (2.5, resultData[3]));

Example Usage

// Shifting by partial bin (1/10 of 4, or by 2/5)
uint32_t srcBinData[] = { 3, 5, 19, 2 };
double  resultData[4];
using   SRC_DATA_DESCRIPTOR     =   BasicDataDescriptor<double, uint32_t>;
using   TRG_DATA_DESCRIPTOR     =   UpdatableDataDescriptor<double, double>;
SRC_DATA_DESCRIPTOR srcData (srcStart, srcEnd, 0, 10);
TRG_DATA_DESCRIPTOR trgData (trgStart, trgEnd, 1, 11);
ReBin (srcData, &trgData);
 
// In src, srcBinData[0] extends from 0 .. 10/4 (ie 0..2.5), and srcBinData[1] extends from 2.5 to 5.0
// In target, resultData[0] extends from 1 to (11-1)/4 + 1, or 1 to 3.5
// SO... resultData[0] = 3 * (pct of src bucket 0) + 5 * (pct of src bucket 1)
//                     = 3 * (1.5/2.5) + 5 * (1/2.5) = 1.8 + 2
EXPECT_TRUE (NearlyEquals (3.8, resultData[0]));

Definition at line 160 of file ReBin.inl.