Next Previous Up Contents
Next: tgroup: Calculates aggregate functions on groups of rows
Up: tgridmap: Calculates N-dimensional density maps
Previous: Usage

### B.37.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.

Next Previous Up Contents
Next: tgroup: Calculates aggregate functions on groups of rows
Up: tgridmap: Calculates N-dimensional density maps
Previous: Usage

STILTS - Starlink Tables Infrastructure Library Tool Set
Starlink User Note256
STILTS web page: http://www.starlink.ac.uk/stilts/
Author email: m.b.taylor@bristol.ac.uk
Mailing list: topcat-user@jiscmail.ac.uk