SNAPGRID(1NEMO) manual page

HTML automatically generated with rman
Table of Contents

Name

snapgrid - grid a snapshot into a 2D or 3D image (cube), with optional moments

Synopsis

snapgrid in=snapshot out=image [parameter=value]

snapgrid grids three arbitrary bodytrans(3NEMO) expressions (default: x, y and -vz) of a snapshot into a 2D or 3D image(5NEMO) dataset, with optional astronomical projection for direct comparision with astronomical images.

The X and Y coordinates of the datacube can only be regularly gridded in histogram fashion (for spatial XY-smoothing see ccdsmooth(1NEMO) , for interpolating see also snapmap(1NEMO) ), however the Z coordinate has the property that it can take moments in this variable, pick a number of planes or planes with smoothing.

The output image is written in standard image(5NEMO) format, and can be accessed by various other programs for smoothing, display etc.

Although snapgrid(1NEMO) can grid datacubes (e.g. X-Y-Z), snapgridsmooth(1NEMO) is probably easier to use, since it does not integrate along any lines of sight, whereas this program is more suited for taking moments along the 3rd axis.

For images that require more accurate interpolation, instead of this histogramming approach, use snapmap(1NEMO) .

For a related program that creates images (and can create movies as well), see uns_2dplot(1NEMO) .

As of V6.0 the units in 3D cubes will be particle density. This ensures that programs such as ccdmom(1NEMO) and ccdstat(1NEMO) give the proper answer in their summed emission.

In the yt package such images are called phase plot, where a 2D grid in field1 (xvar=) and field2 (yvar=) is computed, with some statistic (mom=) on field3 (evar=).

Parameters

The following parameters are recognized:

in=in-file: input file, must be in snapshot(5NEMO) format. Multiple snapshots can be stacked uses the times= keyword: see stack= below. [no default].
out=out-file: output file, will be in image(5NEMO) format [no default].
times=t1:t2,t3,..: Selection of the times of snapshots to be selected for gridding. For stack=t all snapshots will be co-added into one image, however selecting stack=f or selecting multiple evar’s one can request multiple output images. [Default: all].
xrange=xb:xe: Range in xvar to bin, the coordinates are allowed to decrease as well as increase. [default: -2:2].
yrange=xb:xe: Range in yvar to bin [default: -2:2].
zrange=xb:xe: Range in zvar to bin, or take moments of [default: -infinity:infinity].
xvar=x-expression: The value of x-expression is gridded along the X axis. [default: x].
yvar=y-expression: The value of y-expression is gridded along the Y axis. [default: y].
zvar=z-expression: The value of z-expression is gridded along the Z axis (nz>1), or moments taken off (nz=1). [default: -vz].
evar=emissivity: Variable to denote emissivity per particle. You can select more than 1 expression, in which case different images will be written out (only in stack=f mode) [default: m].
tvar=tau: Variable to denote the optical depth of a particle. [Default: 0]
dvar=depth: Variable to denote the line of sight. [Default: z]
svar=smoothing: Variable to denote gaussian smoothing Note this is the gaussian sigma, not the FWHM (FMHW = 2.355 * sigma).
nx=x-pixels: Number of pixels along the X axis of the cube [default: 64].
ny=y-pixels: Number of pixels along the Y axis of the cube [default: 64].
nz=z-pixels: Number of pixels along the Z axis of the cube. If one pixel is choosen, moments can be taken (see below), else a simple gridding is used. [default: 1].
xlab=x-label: Text used to label the X-axis. By default the xvar expression is used. It may be useful in certain astronomical environment to label the axis with recognized labels like RA---TAN, DEC--SIN, GLON etc.
ylab=y-label: Same for the Y-axis.
zlab=z-label: Same for the Z-axis.
moment=number: Order of the Z-gridding. Most commonly choosen are: 0 (total intensity), 1 (velocity zvar weighted intensity) and 2 (velocity square weighted intensity), where ’intensity’ should really be read as surface density per square unit length. Special values of -1 and -2 can be used to directly compute the evar weighted mean and the dispersion from the mean. -3 and -4 are used to compute the gaussian-hermitian h3 and h4 moments (see e.g. van der Marel & Franx, 1993) [default: 0].
mean=t|f: Should the emission in a cell be averaged? This also controls the units of the gridding. For mean=f (the default) a surface-density is computed (emission per square length), whereas for mean=t the average per
pixel (or voxel) is computed of the units of emission. Another way of looking at this, mean=t is for interpolating maps (see also snapmap(1NEMO) ), where as mean=f is for splatting information as if this was observed. [Default: f].
stack=t|f: Should all snapshots from the input file be stacked, or write one image per selected (see times=) time? [default: f].
integrate=t|f: If selected, instead of summing points along the zvar, they are sorted and integrated along dvar. This is appropriate when emission represents something like a density, instead of a mass, and a total column density is needed. ** This option can only compute 2D moment=0 maps and also cannot handle stacked snapshots yet ** [default: f].
proj=: If a valid projection type (SIN, TAN, ARC, NCP, GLS, MER, AIT) but see also wcs(1NEMO) , the input coordinates are interpreted in angular degrees, and griddes with the appropriate sky projection. Default: no sky projection.

Examples

The following example makes three moment images from an N-body snapshot, then smooths and combines them into an ’intensity’ (int), ’mean velocity’ (vel) and ’velocity dispersion’ (sig) map using a CCD math operator.

Note that the moment maps must be smoothed before they can be combined to the proper velocity and dispersion maps.

   % snapgrid in=nbody.dat out=map0 moment=0
   % snapgrid in=nbody.dat out=map1 moment=1
   % snapgrid in=nbody.dat out=map2 moment=2
   % ccdsmooth in=map0 out=map00 gauss=0.1
   % ccdsmooth in=map1 out=map11 gauss=0.1
   % ccdsmooth in=map2 out=map22 gauss=0.1
   % mv map00 int
   % ccdmath in=int,map11     out=vel  fie=%2/%1
   % ccdmath in=int,vel,map22 out=sig  fie="sqrt(%3/%1-%2*%2)"
   % rm map11 map22

Alternatively, with the option of using negative moments, one can also use (assuming no smoothing implemented):

    % snapgrid in=nbody.dat out=int moment=0
    % snapgrid in=nbody.dat out=vel moment=-1
    % snapgrid in=nbody.dat out=sig moment=-2

Consider now the situation where a coordinate is regularly sampled, with N values between A and B. In order to grid these, one would normally use a range=A-dx/2:B+dx/2, where dx=(B-A)/(N-1). One can also make a grid with N cells with emission, and K blank cells between each valued cell (K would be typically small, perhaps 1 or 2). With NK=(K+1)N-K and dx=(B-A)/(NK-1), a range=A-dx/2:B+dx/2 is used. If this is done in both the X and Y dimension, the program ccdintpol(1NEMO) can be used to create a bi-linearly interpolated grid with more pixels for a seemingly higher sampled map. Most likely the option mean=t will have to be used to conserve units between runs with different values of K.

Here is an example of making a gridded map of ungridded data. Both unweighted, and weighted. Suppose the snapshot has the weights stored in the Aux field, and we use these as weights (i.e. sum(mass*Aux)/sum(Aux) would be the quantity of interest). The unweighted average uses the mean=t key:

    snapgrid ... out=map0 evar=m mean=t

but the weighted average computes the two maps seperately and uses ccdmath(1NEMO) to divide them to get the desired result:

    snapgrid ... out=map1 evar=’m*aux’ 
    snapgrid ... out=map2 evar=’aux’ 
    ccdmath in=map1,map2 out=map3 fie="ifeq(%2,0,0,%1/%2)"

with an additional safeguard to set cells to 0 if no emission with found in them.

Kinemetry

Krajnovic et al. (2006) popularized kinemetry, a description of line of sight velocities in terms of the first four moments (v, sigma, h3 and h4). The following example shows how to create these maps with snapgrid:

  % snapgrid ...

Units

Units are maintained in the same way as in snapshots, they don’t have a specific name, but carry their normal meaning ’length’, ’velocity’ and ’mass’. Since snapgrid calculates (surface/space) densities, its units are formally ’mass’ per square ’length’ times ’velocity’ to the power moment. Notice the mean= keyword, which prevents division by the cellsize.

When channel maps are produced (moment=0), the data are not normalized w.r.t. the convolving velocity beam. For a rectangular beam (vrange=vmin:vmax) the data should formally be divided by (vmax-vmin), for a gaussian beam (vrange=vmean,vsig) by vsig*sqrt(2*pi). Also remember that a gaussian beam has FWHM = 2.355*sigma.

Although snapscale(1NEMO) can also be used, after a snapshot has been gridded into a map/cube, ccdsky(1NEMO) can optionally be used to rescale a cube in astronomical units (degrees and m/s) such that exported FITS files can be compared directly with model generated FITS files.

Bugs

Combinations of large snapshots and large images may run into memory problems since both the snapshot and the image(s) must fit into memory to obtain turbo speeds. Use non-negative moments to avoid having to allocate one or two extra images in addition to the snapshot and the image.

Sky projections do not guarantee flux conservation.

Author

Peter Teuben

Files

src/nbody/image      snapgrid.c

Update History

19-jan-89    V1.0: Created    PJT
12-mar-89    V1.1: added emisitivity evar    PJT
2-nov-90    V2.0: allow stacked snapshots    PJT
21-oct-91    V3.0: moment -1,-2 implemented    PJT
12-jun-92    V3.1: added times=    PJT
18-jul-92    V3.2: fixed bug when moment<0 and stacked snapshots    PJT
30-jul-93    V4.0: allow multiple  evar’s - default is now stack=f    PJT
18-jun-98    V4.4: added xlab/ylab/zlab and allow range[0]>range[1]    PJT
8-may-04    V5.0: added proj= to optionallaly allow sky projections    PJT
7-feb-06    V5.1: added integrate=t to deal with 3D density points    PJT
2-mar-11    V5.3: moment -3,-4 implemented    PJT
18-may-12    V5.4: added smoothing in VZ (szvar)
14-feb-13    V6.0: units changed on a cube (now xyz-density instead of xy-surface
brightness)    PJT

Table of Contents

Name
Synopsis
Description
Parameters
Examples
Kinemetry
Units
Bugs
See Also
Author
Files
Update History