# 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
HEALPixpixelisation 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
FITSformat input/output of 2D maps.

Note

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).

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

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`

.

Note

- 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}\).

Note

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).

## 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).

### 6.9.3.1. 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:

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` |

Note

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 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.

Note

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.

### 6.9.3.2. 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.

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

### 6.9.3.3. 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 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.

### 6.9.3.4. 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.

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.

### 6.9.3.5. 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
```

```
$ 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
```

```
$ 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
```

Note

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¶

### 6.9.4.1. 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.Note

To get the right colour scale for part-sky maps in

**ds9**, go to (at the very bottom) and raise the lower limit to get an appropriate contrast.

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.

### 6.9.4.2. 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.

### 6.9.4.3. 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.

Note

The conversion into projected **FITS** images is degrading the original information.

### 6.9.4.4. 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`

.