6.9. 2D skymaps (healpix_fits.h)

Galactic and extragalactic signals correspond to 2D skymaps. The file healpix_fits.h contains many tools to manipulate 2D skymaps in several formats, in particular to:

  • make use of the HEALPix pixelisation scheme on which to calculate the quantities of interest;
  • to add the contribution from single DM haloes (e.g. drawn subhaloes, or known DM haloes such as dSphs or other objects from a list).
  • to handle the FITS format input/output of 2D maps.


For 2D calculations, CLUMPY so far only treats cases where the spatial and spectral part of the indirect DM signal are separable, i.e., the morphology of the signal is not varying with energy.

When we calculate the J-factor for a 2D-skymap with a large number of pixels, we only calculate J for the continuum in fewer directions and interpolate the results for all the other directions (pixels) of the skymap. If the FOV does not encompass the halo centre, we use a simple linear interpolation grid. Towards the halo centre, J has a strong dependence on the position and a logarithmic step is used.

6.9.1. HEALPix pixelisation

Two-dimensional maps of \(J(\Delta\Omega_{\rm pix})\), \({\rm d}J/{\rm d}\Omega\), or of the \(\gamma\)-ray/\(\nu\) fluxes/intensities are drawn in the HEALPix pixelisation scheme. The HEALPix (Hierarchical Equal Area isoLatitude Pixelation) package provides a large set of routines for efficient manipulation and analysis of numerical data on the discretized sphere (Gorski et al., 2005).


Fig. 6.17 Illustration of the HEALPix pixelisation of the sphere. The displayed HEALPix resolutions are (clockwise from top left): \(N_{\rm side}=1,\,2,\,4,\,8\). If the uppermost pixel in the light grey base pixel is \(\#1\), then the Galactic centre is located in the centre of the dark grey base pixel.
Figure credit: Gorski et al. (2005).

The HEALPix scheme discretises the full sphere into \(N_{\rm pix} = 12\,N_{\rm side}^2\) equal-area quadrilateral pixels. It is

(6.16)\[\Delta\Omega_{\rm pix} = \frac{\pi}{3\,N_{\rm side}^2}\,{\rm sr}\quad \Rightarrow \quad d_{\rm pix} \approx \frac{58.6^{\circ}}{N_{\rm side}}\,,\]

with \(d_{\rm pix}\) the approximate edge-length of each pixel, assuming that the pixels are quadratic (which they are not) and \(\Delta\Omega_{\rm pix} \ll \pi\).

\(N_{\rm side}\) is a resolution parameter and allowed to take any integer value, \(N_{\rm side}\geq 1\) in CLUMPY via the parameter gSIM_HEALPIX_NSIDE.


  • While gSIM_HEALPIX_NSIDE is allowed to take any integer value, it is recommended, especially for large or high-resolution skymaps, to choose \(N_{\rm side} = 2^n, \,n\in \mathbb{N}^+\). This choice allows a more efficient storage of the data in the HEALPix NESTED scheme with faster I/O and handling by FITS viewers (which may not be able to deal with \(N_{\rm side} \neq 2^n\) maps).

  • The current HEALPix version allows only \(N_{\rm side} \leq 2^{13} = 8192\), which determines the maximum resolution for 2D skymaps in CLUMPY. However, with correspondingly \(d_{\rm pix} \gtrsim 0.007^{\circ} = 26''\), this is well below the instrumental resolution of current \(\gamma\)-ray or \(\nu\) instruments.

In CLUMPY, the HEALPix grid is always initialised in Galactic coordinates. I.e., in the RING ordering scheme (gSIM_HEALPIX_SCHEME = RING), the Galactic north pole lies at the intersections of the pixels \(\#1\), \(\#2\), \(\#3\), and \(\#4\), and the Galactic south pole between the pixels \(\#N_{\rm pix}-3\), \(\#N_{\rm pix}-2\), \(\#N_{\rm pix}-1\), and \(\#N_{\rm pix}\). The Galactic anti-center, \((\psi,\theta)_\oplus = (\pi,0)_\oplus\) is found where the pixels \(\#N_{\rm pix}/2\), and \(\#N_{\rm pix}/2 + 1\) touch. For \(N_{\rm side} = 2^n\), CLUMPY choses the storage-efficient NESTED scheme (gSIM_HEALPIX_SCHEME = NESTED) by default, if not explicitly overwritten by the user. Here, the pixel ordering scheme is more intricate, and the reader is referred to the HEALPix documentation for further information.

6.9.2. Oversampled averaging

In the FITS files, CLUMPY provides the J-factor values with respect to the pixels’ sizes in the map, \(\Delta\Omega_{\rm pix}\) according to Eq. (6.16). However, the value of \(J(\Delta\Omega_{\rm pix})\) is based on an circular “oversampled averaging” over a region slightly larger than the pixel surface, as illustrated in Fig. 6.18. This approach is much faster than calculating the exact signal contained in a quadrilateral HEALPix pixel (for the expense of some accuracy) while it is more accurate, especially for very steep DM profiles, than simply calculating the line-of-sight integral at a single direction (e.g., the pixel center) and multiplying it with \(\Delta\Omega_{\rm pix}\).


The \(\mathrm{d}J/\mathrm{d}\Omega\) values given in the FITS output rely on the same approach as decribed above and are effectively an averaged \(\langle\mathrm{d}J/\mathrm{d}\Omega\rangle\) over the circular regions in Fig. 6.18. They are not simply the line-of-sight integral towards the pixel centers (blue points in Fig. 6.18).


Fig. 6.18 Illustration of the HEALPix grid and CLUMPY’s minimal oversampling in the HEALPix scheme. Blue: pixel centers, pink: pixel boundaries, green: Integration area adapted to the HEALPix resolution.

6.9.3. Field of view choices

For 2D maps, different FOV shapes or masking shapes can be chosen. Either rectangular shapes (limited by great circles, i.e., the shortest connection between four given points on the sphere, “rectangular mode”), circular ones (“disk mode”) and, for FOV centred in latitude in the Galactic plane, also limited by lines in constant longitude and latitude (“strip mode”). All figures below show skymaps of the Galactic DM emission obtained with the -g5 option (i.e., no drawn substructures). Rectangular field of view

For a standard rectangular field of view, the centre of the field of view and its dimensions in diameter are specified via the parameters listed in Table 6.9:

Table 6.9 Parameters to define a 2D field of view
Quantities Parameter names
Field of view center, \(\psi_0\) or \(l_0\), \(\rm [deg]\) gSIM_PSI_OBS_DEG
Field of view centre , \(\theta_0\) or \(b_0\), \(\rm [deg]\) gSI_THETA_OBS_DEG
Field of view diameter \(\Delta\theta_\perp\) in \(\theta_\perp\) direction, \(\rm [deg]\) gSIM_THETA_ORTH_SIZE_DEG
Field of view diameter \(\Delta\theta\) in \(\theta\) direction, \(\rm [deg]\) gSIM_THETA_SIZE_DEG


The field of view diameter \(\Delta\theta_\perp\) only falls together with some \(\Delta\psi\) for \(\theta_0 = 0^{\circ}\).

In the rectangular mode, the field of view is limited by great circles. By this, \(\Delta\theta\) corresponds to the field of view diameter in latitudinal direction between the corners, while \(\Delta\theta_\perp\) is the distance (orthogonal to the latitudinal direction) through the skymap centre between the the field of view edges:


Fig. 6.19 Rectangular field of view, limited by great circles, of dimension \(\,60^{\circ}\times 40^{\circ}\) around the Galactic centre.

Fig. 6.19 is obtained with:

$ clumpy -g5 --gSIM_PSI_OBS_DEG=0 --gSIM_THETA_OBS_DEG=0 --gSIM_THETA_ORTH_SIZE_DEG=60 --gSIM_THETA_SIZE_DEG=40 -i all_other_parameters.txt

Note that the user has to create the all_other_parameters.txt file with e.g. the -D. For further infos about how to create a figure like Fig. 6.19 from the CLUMPY output, see Section 6.9.4 below.


For \(\Delta\theta_\perp=\Delta\theta \rightarrow 180^{\circ}\), the field of view in rectangular mode approaches a half-sphere (as shown in Fig. 6.21). It is not possible to draw a rectangular field of view larger than a half-sphere. Strip mode

The strip mode is a variant of the rectangular mode, in which the northern and southern field of view limits are given by lines of constant latitude. It is only available for field of views symmetric w.r.t. the Galactic equator (\(\theta_0 \equiv 0^{\circ}\)) and triggered by setting gSI_THETA_OBS_DEG = s. In contrast, the central position in longitudinal coordinates, \(\psi_0\), can be freely chosen. For example,

$ clumpy -g5 --gSIM_PSI_OBS_DEG=0 --gSIM_THETA_OBS_DEG=s --gSIM_THETA_ORTH_SIZE_DEG=60 --gSIM_THETA_SIZE_DEG=40 -i all_other_parameters.txt

creates a skymap in a field of view as shown in Fig. 6.20.


Fig. 6.20 Strip-mode field of view of dimension \(\,60^{\circ}\times 40^{\circ}\) around the Galactic centre.

The strip mode can be used to draw maps of the full sky, see Fullsky maps. Circular field of view

By setting gSIM_THETA_ORTH_SIZE_DEG = d, a circular/disk-shaped field of view is chosen, and the parameter gSIM_THETA_SIZE_DEG now corressponds to the diameter of the field of view. For example, Fig. 6.21 shows a circular field of view with gSIM_THETA_SIZE_DEG = 180:


Fig. 6.21 Circular field of view around the Galactic centre with diameter of \(180^{\circ}\). Note that this is also the limit of a rectangular field of view on the sphere and its diameters approaching \(180^{\circ}\).

Fig. 6.21 is obtained with the command:

$ clumpy -g5 --gSIM_PSI_OBS_DEG=0 --gSIM_THETA_OBS_DEG=0 --gSIM_THETA_ORTH_SIZE_DEG=d --gSIM_THETA_SIZE_DEG=180 -i all_other_parameters.txt

The circular field of view diameter can be as large as the full sky, see Fullsky maps. Fullsky maps

To compute a fullsky map, either the disk mode d or the strip mode s can be used. Both options yield the same result. For example:

$ clumpy -g5 --gSIM_PSI_OBS_DEG=0 --gSIM_THETA_OBS_DEG=0 --gSIM_THETA_ORTH_SIZE_DEG=d --gSIM_THETA_SIZE_DEG=360 -i all_other_parameters.txt

results into a fullsky map, as shown in Fig. 6.22.


Fig. 6.22 Fullsky map of the Galactic DM halo.

For such a fullsky field of view, the \((l,b)\) position of the field-of-view centre is irrelevant (any choices results into the exactly same skymap). The fullsky mode can also be triggered with the strip mode :

$ clumpy -g5 --gSIM_PSI_OBS_DEG=0 --gSIM_THETA_OBS_DEG=s --gSIM_THETA_ORTH_SIZE_DEG=360 --gSIM_THETA_SIZE_DEG=180 -i all_other_parameters.txt

Again, for a fullsky field of view, the longitudinal position of the field of view centre is irrelevant. Masking

CLUMPY accepts negative values for the field of view dimensions to trigger masking. Negative values result in subtraction of this field of view from a fullsky map. In the following, we give in short some command examples with the resulting skymaps:

$ clumpy -g5 --gSIM_PSI_OBS_DEG=0 --gSIM_THETA_OBS_DEG=s --gSIM_THETA_ORTH_SIZE_DEG=360 --gSIM_THETA_SIZE_DEG=-30 -i all_other_parameters.txt

Fig. 6.23 Masking the Galactic plane with the strip mode.

$ clumpy -g5 --gSIM_PSI_OBS_DEG=0 --gSIM_THETA_OBS_DEG=s --gSIM_THETA_ORTH_SIZE_DEG=60 --gSIM_THETA_SIZE_DEG=-40 -i all_other_parameters.txt

Fig. 6.24 Masking the Galactic centre with the strip mode.

$ clumpy -g5 --gSIM_PSI_OBS_DEG=0 --gSIM_THETA_OBS_DEG=0 --gSIM_THETA_ORTH_SIZE_DEG=d --gSIM_THETA_SIZE_DEG=-30 -i all_other_parameters.txt

Fig. 6.25 Masking the Galactic centre with a circular mask.


Masking is worth to speed up the computation time, as CLUMPY calculates only the pixel values outside the mask. However, choosing a mask smaller than a half-sphere increases the output file size, as explicit HEALPix pixel labeling must be done to define the location of the unmasked pixels on the sphere.

6.9.4. Accessing the FITS output Viewing the FITS files

CLUMPY’s 2D skymaps are stored in the FITS (Flexible Image Transport System) file format (Pence et al., 2010). This format allows to clearly and efficiently store several maps as binary tables in one single file, and to append extensive meta information in the FITS headers of the output file. Both fullsky (implicit HEALPix pixel labeling) and part-sky maps (explicit pixel labeling) are handled in the FITS format.

CLUMPY skymap FITS files are composed of several extensions (J-factor skymaps, smoothed J-factor skymaps, intensities,…; see also clumpy executable: options and plots, Add flux extensions: \tt -f -f for CLUMPY’s feature of adding extra extensions to a FITS file), each containing various columns (e.g., \(J_{\rm sm}\), \(J_{\rm subs}\), \(J_{\rm cross-prod}\), etc.). Each extension possesses its own FITS header, containing the relevant input parameters of the performed simulation.

The following two programs are able to directly read and display these FITS files (however, only for \(N_{\rm side} = 2^n\)):

  • Aladin sky atlas

    The Aladin sky atlas is a nice viewer which comes with a lot of neat features: Switch between various interactive projections, switch coordinate systems, overlay various maps from different files. It has an interface to various survey skymaps along the electromagnetic spectrum (DSS, XMM Newton, Fermi) to easily overlay with your input skymap. See the Picture gallery for some example.

  • The Python module healpy (part of the HEALPix package) is able to directly read any column of any extension in the FITS output into numpy arrays with simple one-line commands

Other FITS viewers are also able to display skymaps stored in FITS files and HEALPix pixelisation format, but only for fullsky maps in single extension, single column files. CLUMPY comes with an internal postprocessing module to extract single columns from a FITS extension (e.g. “the integrated intensity of Galactic DM of only resolved substructure”) and to store them in a fullsky HEALPix-FITS file. This is explained in clumpy executable: options and plots, Section 7.5, using the -o2 option.

The following two viewers are supported to display single-extension 2D fullsky maps in the HEALPix scheme (including the aforementioned viewers):

  • ds9 supports HEALPix format from version 7 on.

    In ds9, you can switch coordinate systems and display horizontal and vertical 1D-profiles.


    To get the right colour scale for part-sky maps in ds9, go to Scale ‣ Scale Parameters (at the very bottom) and raise the lower limit to get an appropriate contrast.

  • Lambda skyviewer.

In addition to those FITS viewers,

can be used to browse the extensions, columns, and their numeric data of a FITS file and to display the FITS headers. fv is also able to delete extensions from a file, which may be useful after the procedure from clumpy executable: options and plots, Add flux extensions: \tt -f -f has been applied to add various intensity extensions to a file. Conversion to ASCII

Also, FITS extensions can be converted into ASCII files. This is further explained in clumpy executable: options and plots, Section 7.5, using the -o1 option. Conversion to projected FITS images

CLUMPY comes with a Python script which, based on (and requiring) healpy and astropy, converts the skymaps saved in the HEALPix pixelisation scheme into projected FITS images. These images can also be displayed with all above FITS viewers (including fv).

The conversion to FITS images is further explained in the Detector-related interfaces section.


The conversion into projected FITS images is degrading the original information. Restoring an input parameter file out of the FITS metadata

The -o3 option can be used to generate back the CLUMPY input parameter file out of the header of an output FITS file extension:

$ clumpy -o3 -i results.fits 1

creates an input parameter file out of the metadata stored in the header of the first extension of the file results.fits.