4 Customising Recipes

If you wish to write your own data-reduction recipes, you should consult the Orac-dr Programmer’s Guide (SUN/233). However, for most purposes, observers wishing to modify existing scripts can get by without this document.

A easier-to-use tailoring system to control parameters and primitive arguments from the command line and ‘personal’ style files is under consideration.

4.1 Search paths

Orac-dr allows you to create your own recipes and primitives, or modify those provided as part of the package. In either case you must tell Orac-dr where your recipes and/or primitives are stored. This is achieved through two environment variables. $ORAC_RECIPE_DIR should equate to the directory containing your recipes. $ORAC_PRIMITIVE_DIR specifies the directory containing your primitives. Here’s an example.

Once these environment variables are defined, Orac-dr first looks in $ORAC_RECIPE_DIR or $ORAC_PRIMITIVE_DIR to find a recipe or primitive respectively. If the script is absent, Orac-dr looks in the standard $ORAC_DIR directories.

4.2 Anatomy of an imaging recipe

There are documentation modules—a Starlink style between #+ and #- delimiters at the head, and a Perl POD (Plain Old Documentation) at the foot. Between these is the code. This consists of calls to primitives, sometimes with arguments. Primitives have uppercase names preceded and terminated by underscores, such as _DIVIDE_BY_FLAT_.

4.2.1 Hello primitives

The first of these primitives is _IMAGING_HELLO_. It contains instrument-specific code and initialisation. It is best left alone. See

Section 3.1.2 for a description of what this primitive does for each instrument.

Second there is a recipe-specific primitive such as _JITTER_SELF_FLAT_HELLO_. This sets up Ccdpack, sets directives when to perform certain operations, optionally create variances, removes any bias, and edits the FITS headers.

Two things you might wish to change in the recipe _HELLO script are listed below.

• Change the extent of the images. If there is an instrumental defect in some peripheral rows you might not want to use the full bounds as given by headers ORAC_X_LOWER_BOUND, ORAC_X_UPPER_BOUND, ORAC_Y_LOWER_BOUND, ORAC_Y_UPPER_BOUND. Suppose you wanted to trim off the top three rows you could change the line.
        my $y2 = $Frm->uhdr( "ORAC_Y_UPPER_BOUND" );

  to

        my $y2 = $Frm->uhdr( "ORAC_Y_UPPER_BOUND" ) -3;
• Switch on error propagation. To save time at the telescope, the pipeline does not keep track of the errors per pixel (except for the polarimetry recipes with names starting “POL” and the NOD_CHOP series). If you wish to know realistic errors for your data, in the recipe switch on the USEVAR argument for the recipe’s _HELLO primitive. Here is an example for the BRIGHT_POINT_SOURCE recipe.
        _BRIGHT_POINT_SOURCE_HELLO_ USEVAR=1

4.2.2 Steering primitive

Within a recipe’s _HELLO primitive, a ‘steering’ primitive is invoked. These are best left well alone. They control when the various operations are performed. See

Appendix F.2 for more details. What you can safely adjust are the configurable steering parameters listed in the recipe documentation. In the main these parameters set the number of frames processed in a cycle through the recipe. The parameters are passed by argument through the recipe’s _HELLO script to the steering primitive.

Suppose that for some reason an observation of a nine-point jitter self flat was aborted after seven positions. If you try the recipe stored in the headers some processing will occur, but it will not include mosaic creation. The final steps inclusing mosaic creation occur once all nine frames are dark subtracted. Now there are no seven-point recipes to substitute on the command line. You could make your own seven-point recipe to reduce those data. First make a new recipe by copying the standard one.

Next edit JITTER7_SELF_FLAT and alter the line

to become

The recipe will then generate the self flat, flat field and make the mosaic once the seventh frame is dark-subtracted.

Recipes are stored in $ORAC_DIR/recipes/imaging; and for a few instrument-specific recipes in $ORAC_DIR/recipes/$<$instrument$>$, where $<$instrument$>$ is IRCAM, MICHELLE, UFTI. IRIS2, ISAAC, or INGRID. See

Appendix E for some details.

4.2.3 Recipe primitives

After the steering primitive we come to the recipe-specific scripts that actually perform the recipe. The most likely and easiest things you would change are to add arguments or modify argument values of the primitives in the recipes. For instance, you might wish to change the aperture diameter for the aperture photometry. To alter to a 4-arcsecond aperture, change the APERTURE argument’s value of the _APHOT_MAG_ primitive like below.

To obtain details of a primitive’s arguments, use the oracman or perldoc command. Thus

will display the documentation for primitive _MAKE_MOSAIC_. Space does not permit inclusion of the documentation of the many primitives in this manual. Most of primitives’ source code is stored in $ORAC_DIR/primitives/imaging; the instrument-specific ones are situated within $ORAC_DIR/primitives/$<$instrument$>$, where $<$instrument$>$ is UFTI, UIST, MICHELLE, IRCAM, IRIS2, ISAAC, or INGRID; and there are a few general scripts in

$ORAC_DIR/primitives/general.

While the simplest primitives just invoke a Starlink task, and updates just that and are amenable to customisation, some are quite complex especially for the registration. They may invoke other primitives, manipulate parameters and small data files so that the various tasks connect to cope with a variety of circumstances. The most likely change you will want to make is to change the parameter values of a Starlink task. Armed with the reference documentation for the application, say with a findme $<$application$>$, it is easy to change values or append further parameters.

Here is an example. Let us suppose you wanted to combine frames to make a self flat, not with the median, since you have heard that a mean trimmed of the most-extreme tenth of the values gives better results. First copy _MAKE_FLAT_FROM_GROUP_ to your primitives directory.

Using an editor, find the first line in your copy of _MAKE_FLAT_FROM_GROUP_ commencing $hidden. It should be as follows.

Change this to

to effect the change of statistic. There is in fact a second line assigning variable $hidden depending on argument CLEAN, and you should make the same alteration there too.

If there is demand, additional arguments could be provided for primitives, to simplify control. Please contact the author if you have suggestions for arguments and new recipes, or need help customising your Orac-dr scripts.

4.3 Index files

Once the pipeline has run for a bit you will find text files in $ORAC_DATA_OUT called index.flat, index.dark amongst others. These list the calibration frames. Orac-dr uses these to find the most-recent, appropriate calibration. For example, a flat requires that the filter of the flat matches that of the frame being flat fielded, and a dark must have the same exposure time as the target frame; and both must have been taken in the same instrument mode.

Here is an example of a flat index.

The first line contains the column headings. ORACTIME is the UT in decimal hours, and WPLANGLE is the polarisation waveplate angle.

In general you should not manipulate these files. Mis-editing can lead to the calibration system breaking down. If you must edit this file, say to exclude a poor dark or an uneven flat, restrict yourself deleting the line corresponding to that calibration file. It’s safer to remove the calibration file and recreate a new one with the calibration frames you want by running the pipeline.

If you want to nominate specific calibration frames, overriding those selected from the calibration indices, there is a -calib option for the oracdr command to do this. See the section on calibration options in SUN/230 for examples.