B.36.2 Examples

Here are some examples of using tgridmap:

stilts tgridmap in=ravedr4.fits coords=HRV nbins=20

Calculates a simple 1-dimensional unweighted histogram of the HRV column from the input table ravedr4.fits. The output is a table with columns HRV, giving the central value of each bin, and COUNT, giving the number of input rows with HRV values in that bin; additional columns HRV_lo and HRV_hi give the lower and upper bounds of the bin. The bin size is determined from the actual range of the HRV values in the input table, combined with the requested bin count of 20; however, the bin size will be chosen as some round number, so the bin count (number of rows in the output table) may not be exactly as requested.

stilts tgridmap in=ravedr4.fits coords=HRV
                binsizes=100 bounds=-450:450 sparse=false

Produces a similar histogram to the previous example, but the bin dimensions, ranges and alignments are specified explicitly rather than being worked out from the data. There will be 9 output bins, [-450,-350), [-350,-250), ..., [350,450); any values outside of these bins will be ignored. The sparse=false parameter means that rows will be output for all 9 bins, even if some of them are empty. Note supplying bin geometry in this way allows control of bin boundaries; in this case HRV=0 is in the middle of a bin not at a bin boundary. This will also be faster, since no initial scan to determine actual data ranges has to be performed.

stilts tgridmap in=edr3-local.fits
                icmd='addcol nobs astrometric_n_good_obs_al'
                icmd='addcol g_abs phot_g_mean_mag+5*log10(parallax*0.01)'
                coords='bp_rp g_abs'
                binsizes='0.125 0.5' bounds='-1:6 -5:20'
                cols='1;count;NUM nobs;sum;SUM_NOBS nobs;mean;MEAN_NOBS'
                out=grid-stats.vot sparse=false

This assembles a table containing three weighted histograms on a 2-d colour vs. absolute-magnitude grid. The output table contains columns giving bp_rp and g_abs coordinate values for each grid point, as well as columns NUM containing source density, and columns SUM_NOBS and MEAN_NOBS containing respectively the sum and mean of the nobs column in each grid cell. Since sparse=false the number and arrangement of output rows is determined by the binsizes and bounds (57*51 rows) independent of the input data, and could be compared with similar runs on different input tables. The icmd=addcol... parameters prepare values for accumulation ahead of the actual gridding step for convenience though this isn't essential, the relevant expressions could be used directly in the coords and cols parameters if preferred.