# HOW-TO Photometric pipeline(4): illumination correction¶

## Characterising the illumination variation¶

### Using a pre-cooked recipe¶

Deriving the characterisation of the illumination variation from the awe-prompt using a pre-cooked recipe is done thus:

 1 2 3 awe> from astro.recipes.IlluminationCorrectionVerify import IlluminationVerifyTask awe> task = IlluminationVerifyTask(raw='WFI.1999-06-18T06:02:14.059') awe> task.execute() 

awe> help(IlluminationVerifyTask)


which will, for example, show the parameters that can be passed to the constructor of the task.

### Using the basic building blocks¶

A more elaborate way of deriving the characterisation of the illumination variation is by using the basic building blocks of the photometric pipeline themselves. An illumination variation characterisation can be derived from the basic building blocks as follows:

  1 2 3 4 5 6 7 8 9 10 11 12 awe> from astro.main.IlluminationCorrection import IlluminationCorrection awe> from astro.main.PhotSrcCatalog import PhotSrcCatalog awe> from astro.main.RawFitsData import RawFitsData awe> raw = (RawFitsData.filename == 'WFI.1999-06-18T06:02:14.059.fits')[0] awe> query = (PhotSrcCatalog.date_obs == raw.DATE_OBS) & (PhotSrcCatalog.is_valid == 1) awe> len(query) 8 awe> photcats = [p for p in query] awe> illum = IlluminationCorrection() awe> illum.photcats = photcats awe> illum.make() awe> illum.commit() 

In lines (1)-(3) the relevant classes are imported, and in step (5) the necessary dependency is retrieved from the database. In this case, the dependeny consists of a list of photometric catalogs. Note that, in this example, the Python equivalent of a join is used to find these. In lines (9)-(11), an IlluminationCorrection object is instantiated, its dependency is set, and the make method is called. In step (12), the IlluminationCorrection object is committed to the database.

### Configuring the illumination correction¶

Any IlluminationCorrection object has a knob that allows the user to configure the behaviour of its make method. To get information about the available configuration options, just type:

awe> illum.process_params.info()


which will show the available configurable parameters, their meaning, and their default setting.

### Inspecting the characterisation result¶

To view the result of making an IlluminationCorrection object, simply invoke its inspect method:

awe> illum.inspect()


which will result in an output to screen that looks like the one shown in Figure 1. The inspect plot shows the result of the overall fit to the zeropoints as a function of their position on the complete detector block. Super-imposed on these are some relevant contours. The units on the contours are linear, as is the case for the fit shown on the background. The vertical and horizontal axes give the pixel position on the detector block. The inspect method of course also functions on IlluminationCorrection objects retrieved from the database.

### Inserting an illumination correction map into the system¶

To insert an external illumination correction map for a certain filter and instrument into the database, a simple tool is available. This tool is located in the ./awe/astro/toolbox/photometry/ directory and is called ingest_illuminationmap. To get information about how to use the tool just type:

awe \$AWEPIPE/astro/toolbox/photometry/ingest_illuminationmap.py


and a doc-string will appear on screen. The tool only accepts input for a filter/instrument combination that is actually present in the database. If a certain filter or instrument is not present, the tool refuses to comply. The external map provided should, of course, adhere to the mathematical structure used by the system.

## Creating an illumination correction frame¶

The illumination correction is applied to the pixel data in the image pipeline. This is done using an illumination correction frame that is derived from the illumination variation characterisation. This frame is represented in the system by the IlluminationCorrectionFrame class. The following sub-sections describe the two ways in which such frames can be produced from the awe-prompt.

### Using a pre-cooked recipe¶

Deriving an illumination correction frame from the awe-prompt using a pre-cooked recipe is done in the following way:

 1 2 3 awe> from astro.recipes.IlluminationCorrection import IlluminationTask awe> task = IlluminationTask(date='2003-02-11', chip='A5382-1-7', filter='220', instrument='WFC') awe> task.execute() 

awe> help(IlluminationTask)

  1 2 3 4 5 6 7 8 9 10 11 12 awe> from astro.main.IlluminationCorrectionFrame import IlluminationCorrectionFrame awe> from astro.main.IlluminationCorrection import IlluminationCorrection awe> from astro.main.Chip import Chip awe> illum = IlluminationCorrection.select(date='2003-02-11', filter='220', instrument='WFC') awe> chip = (Chip.name == 'A5506-4')[0] awe> illumframe = IlluminationCorrectionFrame() awe> illumframe.illuminationcorrection = illum awe> illumframe.chip = chip awe> illumframe.set_filename() awe> illumframe.make() awe> illumframe.store() awe> illumframe.commit()