# HOW-TO Create a flat-field¶

## Flat-fielding¶

A basic step in calibrating raw science images is flat-fielding. A flat-field is the response of the telescope-camera system to a source of uniform radiation. Typically, a flat-field does not look flat. The flat-field is a multiplicative effect; the differences in attenuation of light over the field of view depend on exposure level. Science images are therefore divided by a flat-field normalized to 1. There are several ways of determining a flat-field. The attempt in the case of both dome and twilight flats (see the next sections) is to take approximately 5-10 images with an exposure level of around 20000-30000 ADU, combine and then normalize them. Flat-fields usually contain a large scale gradient, out-of-focus images of dust present on the filter and dewar window, as well as in focus features of dust on the CCDs or defects in the CCD. In other words, flat-fields contain anything that obstructs the light as it falls on the CCD(s).

In AWE, the flat-field image used to correct raw science images is called the MasterFlatFrame.

## Dome flat fields¶

A flat-field can be obtained by observing a screen on the inside of the dome of the telescope, which is illuminated by lights. This is called a domeflat in AWE. The advantage of dome flat-fields is that it is easy to repeatedly obtain a good signal to noise image of around 20000 ADU. Disadvantages are that the direction of entry of light in the telescope is different from that during the night, and that it is very difficult to illuminate a screen in such a way that it is a source of uniform radiation.

In AWE a flat-field made from a set of dome flats is called the DomeFlatFrame

## Twilight flat fields¶

Usually flat-fields are obtained by observing the sky during evening and/or morning twilight. During this time the sky better approximates uniform illumination than easily possible with dome flats, and light enters the telescope in much the same way as during the night. Disadvantages are that the brightness of the sky changes rapidly during twilight, and it can be difficult to obtain at least 5 good flat-fields of around 20000-30000 ADU. Time is always an issue. In addition, twilight flats taken in near-darkness can contain stars.

In AWE a flat-field made from a set of twilight flats is called the TwilightFlatFrame

## Night-sky (“super”) flats¶

Raw science images have a non-flat background, attributed to flat-field effects. Information about how to flat-field science images therefore is present in the science images themselves. It is possible to use a combination of approximately 10 or more science images as a flat-field. Any common structure can be attributed to flat-field effects and is stored in the NightSkyFlatFrame. In the Astro-WISE system, such flats are used as a correction on the other flats, and a new MasterFlatFrame must be derived incorporating the NightSkyFlatFrame.

In AWE a flat-field made from a set of (reduced) science frames is called the NightSkyFlatFrame

## Combining flats into a master flat¶

The procedure to go from raw dome flat fields and raw twilight flat fields to the master flat that is used to flat-field science images is as follows. First the raw dome flats are combined into a master dome flat. This is done by normalizing the raw flats to 1 and stacking them in a cube. Then, for the same pixel in the different input images, the average value is calculated, while rejecting any outliers. This value is the value of the master (dome/twilight) flat for that pixel. This procedure is applied when making the master dome, as well as the master twilight flat.

In the Astro-WISE system, master dome and master twilight flats are combined. Master twilight flats are used to obtain the large scale structure, while master dome flats are used to obtain the small scale structure. In addition a night-sky flat may be incorporated into the final master flat.

## Syntax, examples¶

To derive a master flat image, it is necessary to make a master dome flat as well as a master twilight flat.

Make a master dome flat. Note that it is necessary to specify the type of overscan correction (see HOW-TO Create a Bias) that you want to use, which should be the same as that was used in creating the master bias image:

awe> # Example using distributed processing
awe> dpu.run('DomeFlat', i='WFI', d='2000-04-28', f='#842', C=1)
awe> # Or specifying a different overscan correction method
awe> dpu.run('DomeFlat', i='WFI', d='2000-04-28', f='#842', oc=0, C=1)


Now make the master twilight flat:

awe> dpu.run('TwilightFlat', i='WFI', d='2000-04-28', f='#842', C=1)
awe> # Or specifying a different overscan correction method
awe> dpu.run('TwilightFlat', i='WFI', d='2000-04-28', f='#842', oc=0, C=1)


Finally, make the master flat:

awe> dpu.run('MasterFlat', i='WFI', d='2000-04-28', f='#842', C=1)


## Using the master dome or master twilight directly¶

When you explicitly do not want to combine the master dome flat and master twilight flat, for example because there simply are no raw dome flats available this is also possible. A parameter “ct” or “combine” needs to be specified in order to do this. The value of the “combine” parameter can be one of:

1. combine the master dome and master twilight flats (default)
2. use only the master dome flat
3. use only the master twilight flat

Syntax example:

awe> dpu.run('MasterFlat', i='WFI', d='2000-04-28', f='#842', ct=3, C=1)
awe> # or using the long option name
awe> dpu.run('MasterFlat', i='WFI', d='2000-04-28', f='#842', combine=3, C=1)


## Using night sky flats¶

In AWE, night sky flats are applied as a correction to the master flat, thereby creating an new master flat as the end-product. To use night sky flats, one must follow these steps:

1. Derive the master flat
2. Derive the night sky flat
3. Rederive the master flat, specifying that a query for night sky flats should be performed

Syntax example for step 2:

awe> dpu.run('NightSkyFlat', i='WFI', d='2000-04-28', f='#842', o='CDF4_?', C=1)


Syntax example for step 3:

awe> dpu.run('MasterFlat', i='WFI', d='2000-04-28', f='#842', nightsky=1,
combine=1, C=1)
# or using shorter options
awe> dpu.run('MasterFlat', i='WFI', d='2000-04-28', f='#842', n=1,
ct=1, C=1)