BUCKETIZE

framework bucketize gts bucketizer

Configuration parameters

```
warpscript.maxbuckets
```
```
warpscript.maxbuckets.hard
```

The BUCKETIZE framework allow to realign datapoints:

A bucket is a time interval which spans a certain number of time units called the bucketspan
BUCKETIZE sort the geotimeserie input, starts by computing the last bucket defined by lastbucket, always going backward in time.
BUCKETIZE ends when there is no more ticks to compute, or when bucketcount is reached.

The bucketizer is a function that aggregates all the datapoints that falls into the bucket. It means their timestamp belongs to range ](bucketEnd - bucketspan);bucketEnd]. If there is no datapoint in the bucket range, there is no aggregate output for the bucket, and BUCKETIZE jumps to the next non empty bucket.

Parameters

last bucket	bucket span	bucket count
0	span	0	`BUCKETIZE` will choose last bucket as multiple of the bucket span, and will adjust bucketcount to cover all the input time range. This is the most straightforward way to use `BUCKETIZE`. As last bucket is a multiple of bucket span, results will be aligned.
lastbucket	span	0	`BUCKETIZE` will adjust bucketcount to cover all the input time range. As lastbucket is fixed, results will be aligned.
0	span	count	`BUCKETIZE` will choose the GTS last tick as last bucket, and stop computation as soon as bucket count is reached. Results may not be aligned.
0	0	count	`BUCKETIZE` will choose the GTS last tick as last bucket, and will adjust bucket span to `(last bucket - first tick of gts + 1) / bucket count`. Results may not be aligned.
0	-1	count	`BUCKETIZE` will choose the GTS last tick as last bucket, and will adjust bucket span to `(last bucket - first tick of gts) / (bucket count - 1)`. Results may not be aligned.

All the output will be bucketized. The bucket span and last bucket can be retrieved with BUCKETSPAN and BUCKETCOUNT.

Up to bucketization, the other WarpLib functions will process the series differently. Empty buckets will be considered as values. You may need to remove the bucketized property from a GTS, with UNBUCKETIZE function.

Aggregators

You can use BUCKETIZE with 3 different type of aggregators:

The WarpLib aggregators: they are all named bucketizer.xxx, you will find them in the bucketizer section.
A macro: for each bucket, BUCKETIZE will push a new sub Geo Time Series™ which will contain the ticks and values that falls in current bucket, then execute the macro. The macro can process the GTS, and let the aggregation result on the stack.
A MACROBUCKETIZER: see MACROBUCKETIZER documentation.

If the bucketizer argument is NULL, then BUCKETIZE do not create any new Geo Time Series™ but instead sets the lastbucket, bucketspan and bucketcount of its inputs without processing their data.

BUCKETIZE output is always a list of GTS, even if the input is a single GTS.

BUCKETIZE is available since version 1.0.0.

Examples

// the simplest way to realign data, keeping the last datapoint every second. NEWGTS 'gts1' RENAME [ 0 28 ] ADDVALUE [ 1 s 29 ] ADDVALUE [ 3 s 27 ] ADDVALUE 'gts1' STORE NEWGTS 'gts2' RENAME [ 0 33 ] ADDVALUE [ 1.1 s 34 ] ADDVALUE [ 2.0 s 35 ] ADDVALUE [ 2.9 s 35 ] ADDVALUE 'gts2' STORE [ [ $gts1 $gts2 ] bucketizer.mean // aggregator = mean 0 // lastbucket 1 s // bucketspan 0 // bucketcount ] BUCKETIZE SORT

// Use your own aggregator with MACROBUCKETIZER NEWGTS 'gts1' RENAME [ 0 28 ] ADDVALUE [ 1 s 29 ] ADDVALUE [ 3 s 27 ] ADDVALUE 'gts1' STORE NEWGTS 'gts2' RENAME [ 0 33 ] ADDVALUE [ 1.1 s 34 ] ADDVALUE [ 2.0 s 35 ] ADDVALUE [ 2.9 s 35 ] ADDVALUE 'gts2' STORE [ [ $gts1 $gts2 ] <% // [tick_of_computation,[gts_classes],[label_bucketize],[ticks] // ,[latitudes],[longitudes],[elevations],[values]] //STOP // insert stop here to understand what BUCKETIZE presents 'i' STORE // return the number of datapoints in the bucket [ $i 7 GET SIZE ] %> MACROBUCKETIZER // this custom aggregator can be replaced by bucketizer.count 0 // lastbucket 1 s // bucketspan 0 // bucketcount ] BUCKETIZE SORT