Healpix map2gif options

I’m doing a lot of work with CMB maps at the moment, most of which are pixelised using Healpix. It’s good to be able to visualise the maps, and the Healpix distribution comes with a utility to do just that: map2gif. Unfortunately, map2gif has somewhat sparse documentation – there are a few options that aren’t documented and that sort of thing. I ended up poking through the source code to find some options, so I figured I should share them here to make other peoples’ lives a little easier.

Rough full-sky map of the Sunyaev-Zel'dovich effect, extracted from WMAP data.

Rough full-sky map of the Sunyaev-Zel’dovich effect, extracted from WMAP data.

(You can access much of this information by typing map2gif -hlp to print usage instructions, but they’re quite basic.)

Basic usage

At its simplest, you need to supply filenames for an input FITS file (in the Healpix format) and an output GIF:

$ map2gif -inp input.fits -out map.gif

If you have a CMB map, you’re probably most interested in seeing the CMB anisotropies. Unfortunately, residual foregrounds can mess up the scaling of the map, so you have to add a scale yourself. For a map in units of micro-Kelvin, the following scale should produce good results for the anisotropies:

$ map2gif -inp input.fits -out map.gif -min -300 -max 300

For most uses, you probably want a colour scale to be displayed on the output image too. Use the -bar option for this (it’s a boolean value, so specify True):

$ map2gif -inp input.fits -out map.gif -bar True

A rough map of the Sunyaev-Zel'dovich effect around the Virgo cluster, extracted from WMAP

A rough (Gnomonic-projected) map of the Sunyaev-Zel’dovich effect centred around the Virgo cluster, extracted from WMAP data.

Projection and centering

For a lot of applications, you’ll be wanting to zoom in on some region of the map rather than seeing the full sky. Healpix supports the Mollweide (default) and Gnomonic projections, which you can switch between using the -proj switch. You only need to type the first three letters of each projection. If you want to zoom in on some specific area, use Gnomonic and specify a different map origin using the (FITS file coordinate system-dependent) -lat and -lon switches:

$ map2gif -inp input.fits -out map.gif -proj gno -lat 45 -lon 87

By default this will look quite zoomed-in, so you might want to use the resolution (-res) switch to zoom out a little (higher numbers zoom out more):

$ map2gif -inp inp.fits -out map.gif -proj gno -lat 45 -lon 87 -res 4

Presentation (colours, labels, image size)

There are a number of switches for controlling the presentation of the output image, most of which are explained sufficiently well in the Healpix documentation. For example, you can add a title to the plot (-ttl), increase its width in pixels (-xsz; the aspect ratio is kept the same) or use a different colormap (-col; try different numbers to get different colour maps).

Other options

There are a few other options that are a bit more specialised; for example, you can scale the signal by arcsinh (-ash) for some reason. A particularly interesting one for CMB applications is the map selection option (-sig); it’s typical to include maps for several Stokes parameters (I, Q, and U) inside a single FITS file for experiments that do polarisation mapping, so you can use this switch to select between them. For example, to pick the Q map out of a WMAP IQU map, use:

$ map2gif -inp input.fits -out map.gif -sig 2

There are also some basic rescaling operations that you can apply using the addition (-add) and multiplication (-mul) switches. Read more about those in the Healpix docs.

Listing of command line options

Here’s a full listing of command-line options to map2gif, taken directly from the output of the -hlp switch:

usage: MAP2GIF
[-inp input_file]
[-out output_file]
[-max usermax] [-min usermin]
[-add offset] [-mul factor]
[-pro projection] [-res gridresn]
[-lon lon0] [-lat lat0]
[-col color_table] [-sig signal]
[-xsz xsize] [-log logflg]
[-ash ashflg]
[-bar add color bar] [-ttl title]


About Phil Bull

I'm a theoretical cosmologist, currently working as a NASA NPP fellow at JPL/Caltech in Pasadena, CA. My research focuses on the effects of inhomogeneities on the evolution of the Universe and how we measure it. I'm also keen on stochastic processes, scientific computing, the philosophy of science, and open source stuff. View all posts by Phil Bull

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s

%d bloggers like this: