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);
- databin = coadd(data); %user is prompted for settings to use
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. Missing data (NaN) and excluded data are also replaced with the least-biased value. 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);