Chapter 7
Regridding your Data

 7.1 Running Makecube
  7.1.1 Reducing multiple observations
 7.2 Makecube options
  7.2.1 Specifying spectral bounds
  7.2.2 Masking receptors
  7.2.3 Including/excluding receptors
  7.2.4 Defining an output grid
  7.2.5 Data-regridding options
  7.2.6 Generating a variance map
  7.2.7 Sparse grid
  7.2.8 Creating a catalogue of receptor positions
  7.2.9 Tile dimensions

If you prefer to reduce your data manually, regridding your data is the best place to start. (See Appendix D for an explanation of what regridding is.)

To convert your raw time-series cubes with spectral channel number, receptor index, time-slices axes into a spatial cube with RA, Dec (or Galactic longitude, Galactic latitude) and spectral axes use the Smurf application makecube. In this chapter we will show an example of processing data using makecube, discuss what to look out for and introduce the various parameters with which to tailor your reduction.

7.1 Running Makecube

The Smurf application used for regridding your raw data is makecube.

  % makecube in=a20070505_00041_01_0001.sdf out=cube autogrid
  Processing data from instrument ’HARP’ for object ’W49’ from the following
  observation  :
     20070505 #41 grid/pssw
     Projection parameters used:
        CRPIX1 = 0
        CRPIX2 = 0
        CRVAL1 = 287.555875 ( RA = 19:10:13.410 )
        CRVAL2 = 9.10386111111111 ( Dec = 9:06:13.90 )
        CDELT1 = -0.00166666666666667 ( -6 arcsec )
        CDELT2 = 0.00166666666666667 ( 6 arcsec )
        CROTA2 = 0
     Output cube pixel bounds: ( -8:11, -8:11, -1024:1023 )
     Output cube WCS bounds:
          Right ascension: 19:10:09.156 -> 19:10:17.259
          Declination: 9:05:16.90 -> 9:07:16.90
          Radio velocity (LSB): -443.8134 -> 464.2568 km/s

The autogrid option allows the software to determine the optimal projection parameters for regridding. This is usually fine for stares and jiggles but is not so good for raster maps. See Section 7.2.5 for more discussion.

The screen report generated by makecube includes the input files, instrument, source, UT date and observation number, and observing mode. The pixel size can be checked in the projection parameters section, while the bounding box of the resulting cube (RA, Dec and velocity) is reported in the output section.

You can visualise your map by opening it with Gaia—see Figure 7.1.

Figure 7.1: The regridded cube displayed with Gaia. The 5×5 jiggle pattern is evident in the map as is the missing receptor in the top-left corner. The smaller window shows the spectrum for the pixel selected by the blue cross on the map.

7.1.1 Reducing multiple observations

You can supply makecube a group in a text file containing a list of all the raw files you want reduced. These filenames should include the full path if they are not in the local directory.

When you pass such group files to makecube (and any Starlink command) you should prefix the filename with an up-caret ( ̂).

  % makecube in=^filelist.txt

Alternatively you can use wild cards. The example below reads in all the raw files for observation 10.

  % makecube in=rawdata/a20140101_00010\*

7.2 Makecube options

7.2.1 Specifying spectral bounds

To save disk space and processing time you can specify the region of the spectra to be processed with SPECBOUNDS. If you know your line lies close to 0 km s1, you may chose to process only the central 100 km s1 as in the example below.

  %  makecube rawfile specbounds=\"-50.0 50.0\"

7.2.2 Masking receptors

When combining several maps with masked bad receptors one can use the BADMASK parameter of makecube. This option determines the way in which bad pixels are propagated from input to output. The one that produces the best map is badmask=and, which uses all the data so an output pixel will be bad only if all the input pixels that contribute to it are bad. This generates an output map with the lowest noise and fewest bad pixels. However, for large datasets the memory requirements may be excessive.

Other options are badmask=or (default) and badmask=first. Or means that an output pixel will be bad if any of the input pixels that contribute to it are bad and is the default. The flag first means that the decisions on which pixels will be flagged as bad will be made with the first input spectrum while the rest are ignored.

7.2.3 Including/excluding receptors

To make a cube with only certain receptors you can use the detectors option on the command line. This allows you to either include or exclude specific receptors without the need for masking. The example below makes a HARP map using all HARP receptors except H04 and H11.

  % makecube in=rawfile autogrid out=map detectors=‘"-H04,H11"’

This alternative example makes a map using only receptor H10. Maps made with single receptors may be used to evaluate the receptor-to-receptor flat-field.

  % makecube in=rawfile autogrid out=map detectors=‘"H10"’

When reduced by makecube—either by hand or through the pipeline—it is possible to find out which good receptors contributed to the reduced cube by inspecting that file’s FITS header. This can be done using fitslist or fitsval to examine the RECPUSED parameter. Here are examples for Ūū and HARP respectively.

  % fitsval a20200808_00084_01_reduced001 RECPUSED
  % fitsval ga20210520_60_1_reduced001 RECPUSED
  H12 H13 H04 H03 H11

7.2.4 Defining an output grid

You can use the REF option to specify a reference NDF that defines an output grid. This NDF can have only two spatial dimensions, even though your data may be in three dimensions.

  % makecube in=rawfile ref=myreffile

If you do not supply a reference file makecube will revert to the AUTOGRID option.

If autogrid=true, the output grid is determined automatically so that as many data samples as possible fall close to the centre of pixels in the output cube.

If autogrid=false, REFLON and REFLAT are set to the first pointing BASE position, CROTA2 is set to the MAP_PA value in the FITS header (converted to the requested sky co-ordinate system), PIXSIZE is set to 6 arcseconds, and REFPIX1 and REFPIX2 are both set to zero. See SUN/258 for a full description of each of these parameters.

7.2.5 Data-regridding options

There are several regridding options available to you through the makecube command. These are specified with the SPREAD parameter on the command line. For instance,

  % makecube in=rawfile spread=sincsinc params="[6,9]"

The default method is Nearest, which assigns the input pixel completely to the nearest output pixel. This is the fastest method available but is not optimal. In particular it may result in blank pixels in HARP maps due to missing receptors (see Figure 7.2).

We recommend you select one of the other methods available which spread the emission to neighbouring pixels. These include Gauss and SincSinc which are the most common, although the latter sometimes gives noisy edges with negative values in some pixels. SincCos will give neater edges. For each of these you will need to provide the size of the convolution function through the params option as in the example above. See SUN/258 for more details.

pdfpict pdfpict pdfpict
Figure 7.2: Raster map regridded with makecube and spread = nearest (left), Gauss (centre) and SincSinc (right). Blank pixels are coloured blue. You can see the Nearest option has resulted in multiple blank pixels throughout the map.

7.2.6 Generating a variance map

The option GENVAR can be used to generate a variance array for your cube. This is important if you are adding multiple maps with different variances as it allows them to be accurately weighted. There are three options for GENVAR:

Spread The output variance values are based on the spread of input data values contributing to each output pixel. Note that this option is not available if parameter SPARSE is set true. If the BADMASK value is or or first, then a single variance value will be produced for each output spectrum. However, when BADMASK is and, an independent variance value is calculated for each channel in each output spectrum.
Tsys The output variance values are based on the system noise temperature values supplied in the input NDFs. Since each input spectrum is characterised by a single Tsys value, each output spectrum will have a constant variance value (i.e. all channels in an output spectrum will have the same variance value). [Default].
None No output variance values are created.

7.2.7 Sparse grid

If one has observed a number of offset positions which are not on a regular grid or are widely spaced, it is of little use to make a normal cube with makecube, which then would have a large size and which would be mostly empty. Then one can use the makecube parameter SPARSE. When sparse=true a one-dimensional array is created which stacks spectra in the order in which they were observed (from left to right when viewed with Gaia).

  % smurfhelp makecube param sparse

This is generates a one-dimensional array where spectra are displayed by Gaia in the order where they were observed (from left to right).

7.2.8 Creating a catalogue of receptor positions

You can use the option OUTCAT to generate a catalogue of the spatial positions of the receptors used to make your final cube. The label associated with each row in the catalogue is the detector name. The detector positions in the catalogue are ordered as follows: all the positions for the first input NDF come first, followed by those for the second input NDF, etc. Within the group of positions associated with a single input NDF, the positions for the first time slice come first, followed by the positions for the second time slice, and so on.

  % makecube in=rawfiles outcat=cat

The catalogue produced will be in FITS format. In the example above a file called cat.FIT is created. When viewing your map with Gaia this catalogue can be overlaid to identify the receptors contributing to each pixel (see Figure 7.3).

Figure 7.3: The receptor positions overlaid on a regridded cube of a HARP stare observation. This is viewed in Gaia by selecting Data-Servers > Local Catalogs and selecting your OUTCAT filename (here cat.FITS). Notice that dead receptors are excluded from the list.

7.2.9 Tile dimensions

For large data sets, it may be beneficial to break the output array up into a number of smaller rectangular tiles. This can be controlled by the TILEDIMS parameter. The files can be stitched together later using the Kappa application paste which may be used any time the tiles to be abutted have the same pixel co-ordinates. Each tile may also have a rim of extra data to allow for future co-adding, the width of which is set by the TILEBORDER parameter.