3. What are Recipes and Recipe Libraries

A DRAGONS recipe is a set of instructions, called primitives, that processes data in a certain way. Depending on the recipe, the input data can be in any state of processing. Most often though, people will want to process Gemini raw data into a master calibration or a processed calibrated output.

A recipe library is a collection of recipes. The recipes in a library have one thing in common: they all apply to the same type of data. When DRAGONS search for a matching recipe for some input data, it searches for a recipe library. In each library, one recipe is set as the default recipe. To use the others, the user needs to specify the name of the non-default recipes.

Let’s look at examples and tools.

3.1. Recipes

This is what a recipe looks like:

def reduce(p):
   p.prepare()
   p.addDQ()
   p.removeFirstFrame()
   p.ADUToElectrons()
   p.addVAR(read_noise=True, poisson_noise=True)
   p.nonlinearityCorrect()
   p.darkCorrect()
   p.flatCorrect()
   p.separateSky()
   p.associateSky(stream='sky')
   p.skyCorrect(instream='sky', mask_objects=False, outstream='skysub')
   p.detectSources(stream='skysub')
   p.transferAttribute(stream='sky', source='skysub', attribute='OBJMASK')
   p.clearStream(stream='skysub')
   p.associateSky()
   p.skyCorrect(mask_objects=True)
   p.detectSources()
   p.adjustWCSToReference()
   p.resampleToCommonFrame()
   p.stackFrames()
   p.writeOutputs()

A recipe is a Python function that calls “primitives” sequentially. The user does not need to know Python to understand more or less what is being done to the data when the recipe is run. From the recipe above, we can read that the data will be corrected for dark current, for flat field effects, the sky background will be subtracted and the frames will be stacked. The p argument is the primitive set that matches the input. We will talk about that in the next chapter.

3.1.1. Exploring recipes

showrecipes can be used to see which recipe DRAGONS with run by default given the input data. The tool’s basic usage signature is:

showrecipes fitsfile_name.fits

To see more options, try showrecipes -h.

Exercise - Recipes 1

The file N20160102S0373.fits, in the playdata/example1 directory, is a raw “lamp-on” flat.

  • Get the default recipe for a NIRI flat displayed on the terminal

  • Find the name of the default recipe.

[Solution]

3.2. Recipe libraries

Recipes are stored in recipe libraries, or in Python language, a module. A recipe library can have one or more recipes in them. One recipe is identified as the default recipe.

When DRAGONS searches for a recipe, it is actually searching for a matching recipe library. Once found, it will run the default recipe, unless instructed otherwise by the user.

The recipe libraries are associated with the input files by matching astrodata tags (Astrodata User Manual). The tags are qualifiers like “NIRI”, “IMAGE”, “FLAT”. The tags of the first file in the list of inputs are used by the matching algorithm. Each recipe library is assigned a set of tags that defines which type of data this library is for.

Exercise - Recipes 2

The file N20160102S0423.fits in the playdata/example1 directory is a raw dark.

  • Find the location of the recipe library on your disk.

  • What are the tags assigned to the input file?

  • What are the tags assigned to that recipe library?

[Solution]

As mentioned above, a recipe library can have more than one recipe. To see the list of recipes, showrecipes has the option --all. Then, to see the sequence of primitives for one of those recipes, there’s the option -r.

DRAGONS has the concept of “reduction mode”. There are three modes: the science quality mode, “sq”, the quicklook mode, “ql”, and the quality assessment mode, “qa”. You can safely ignore the “qa” mode, it is used exclusively at the observatory, at night, to help with the assessment of the sky conditions and the resulting quality of the data. The mode can be specified in showrecipes with the -m flag. The default is “sq”.

To see all the flags and option, showrecipes -h.

Exercise - Recipes 3

For the file N20160102S0270.fits in the playdata/example1 directory:

  • List all matching recipes. Note the “sq”, and the “qa” recipes.

  • Show the makeSkyFlat recipe. (“sq” is the default.)

  • Show the reduce recipe for “qa” mode.

[Solution]