Coadd
Purpose
Reduce resolution through combination of adjacent variables or samples.
Synopsis
- databin = coadd(data,binsize,options)
- databin = coadd(data,binsize,dim)
- databin = coadd(data,options)
Description
COADD is used to combine, or "bin", adjacent variables, samples, or slabs of a matrix. Unpaired values at the end of the matrix are padded with the least biased value to complete the bin. Unlike DERESOLV, COADD reduces the size of the data matrix by a factor of 1/binsize for the dimension defined by input (dim).
Inputs
- data = a data array to be "binned".
- binsize = the number of elements to combine together {default: 2}.
Optional Input
- dim = mode (dimension) to coadd (scalar integer {default = 2}).
- options = discussed below.
Outputs
- databin = the coadded / binned data.
- options = options structure that can be used to bin new data with the same settings.
Options
Options = structure array with the following fields:
- dim: dimension / mode in which to perform binning {default = 2},
- mode : [ 'sum' | {'mean'} | 'prod' ] method of binning. See algorithm notes for details of these modes.
- labels: [ {'all'} | 'first' | 'middle' | 'last' ] method of combining labels (if any exist). Each method labels a new object using one of the following rules:
- 'all' concatenates all labels for the combined items {the default}.
- 'first' uses only the label from the first object in each set of combined objects.
- 'middle': uses only the label from the "middle" object in each set of combined objects.
- 'last': uses only the label from the last object in each set of combined objects.
- binsize: [2] default binsize to use if no binsize is provided in the input.
- maxitems: [1000] maximum number of items to operate on at a time. Allows operating on much larger arrays without out-of-memory issues.
- Only this many rows/columns/etc will be co-added in one block. Set to inf to disable windowing and to zero to do one binsize at a time.
Algorithm
The input (options.mode) defines the type of binning to apply. The different types are described for (options.dim = 2) [i.e., for variables] as follows.
- 'sum' : groups of variables are added together and stored. The resulting values will be larger in magnitude than the original values by a factor on the order of the number of variables binned.
- 'mean' : groups of variables are added together and that sum is divided by the number of variables binned. The resulting values will be similar in magnitude to the original values.
- 'prod' : groups of variables are multiplied together.
Example
Given a matrix, (data), size 300 by 1000, the following coadds variables in groups of three:
- databin = coadd(data,3);
and the following coadds samples in groups of two:
- options.dim = 1;
- databin = coadd(data,2,options);
The following is equivalent to the previous two lines using the "shortcut" input of (dim).
- databin = coadd(data,2,1);