Masking

The masking function references the ESA’s Gaia database in order to mask known sources from our science images. This function masks both the base science images as well as the template (combined image), allowing a masked residual to be produced.

Science images are processed as normal through combine. If masking is called as an option when running the pipeline, the images will be masked before subtraction.

How the masking works:

-The template and aligned images are passed into Mask, where the template is processed first.

-Because the WCS (world coordinate system) information is not present in the template image, one must be created. The new WCS object is built by taking a weighted average of the WCS objects of the underlying science images. A weight is placed on the WCS of the underlying reference image (the original science image with the best SNR) since this was the image that the rest should have been aligned to. -The science images retain their WCS information through Align.

-A Gaia database search is then performed using the pointing coordinates of the base science image. The radius of the search is .3 degrees, meaning that it extends beyond the frame of the image so that all available sources in the frame can be masked. As a result, a masked array is created that is larger than the original image so there is no overflow later on. This mask is then cropped to the correct size at the end of the mask function. Some important information on using Gaia:

   -The Gaia dataset accessed on this search is the primary Gaia catalogue. This means there will likely not be data for every source in 
    the image, especially faint sources. Therefore, it is expected that not every source will be masked and programs like SExtractor will 
    probably detect more sources in an image than Gaia says there should be. The Gaia mission refines their final datasets to exclude 
    sources with higher than acceptable measurement errors or too few observations. 

-Since the Gaia probe can reliably see down to ~20th magnitude, a cutoff for masking is placed at 18th magnitude for our data (limitation of LCO). -The results of the Gaia search are also filtered by astrometric (ra & dec) error.

-The Ra & Dec of each source returned by Gaia is then turned into a Skycoord object to allow for easier access. This Skycoord object is then turned into a pixel value so that it can be matched to a source in the image.

-The Gaia search is made using the icrs frame. No transformations are made to the coordinate reference frame during this process. Using the positions provided by Gaia as a reference point, Photutils is then used to generate a more accurate centroid position for each source.

-In some instances, in the case of faint sources, Photutils fails to find a centroid position and returns a NaN value. In these cases, the centroid position is reverted to the one provided by Gaia.

-A radius for each source is then calculated by comparing pixel values to the average background value in a box around the source. The average background is first calculated and then a radius of 1 pixel is used as the starting point. If the value at that radius is larger than the average background, the value of the radius is increased. This proceeds until the pixel value at the radius is less than or equal to the background. This is repeated in four directions (up, down, left, right) and averaged to give a final radius value.

-Using the centroid positions and radii, each source is masked. After all sources have been masked, the masked array is cropped to the correct size.

-After all images have been masked (template + science images), the set is fed back into subtract.