soxspipe.recipes.base_recipe

The base recipe class which all other recipes inherit

Author

David Young & Marco Landoni

Date Created

January 22, 2020

Module Contents

Classes

base_recipe

The base recipe class which all other recipes inherit

API

class soxspipe.recipes.base_recipe.base_recipe(log, settings=False, inputFrames=False, verbose=False, overwrite=False, recipeName=False, command=False, debug=False, turnOffMP=False)

Bases: object

The base recipe class which all other recipes inherit

Key Arguments:

• log – logger

• settings – the settings dictionary

• inputFrames – input fits frames. Can be a directory, a set-of-files (SOF) file or a list of fits frame paths.

• verbose – verbose. True or False. Default False

• overwrite – overwrite the product file if it already exists. Default False

• recipeName – name of the recipe as it appears in the settings dictionary. Default False

• command – the command called to run the recipe

• debug – debug mode. True or False. Default False

• turnOffMP – turn off multiprocessing. True or False. Default False

Usage

To use this base recipe to create a new soxspipe recipe, have a look at the code for one of the simpler recipes (e.g. soxs_mbias) - copy and modify the code.

Initialization

clean_up(forceFail=False)

update product status in DB and remove intermediate files once recipe is complete

Key Arguments:

• forceFail – force the recipe to be marked as failed in the DB

Usage

recipe.clean_up(forceFail=True)

clip_and_stack(frames, recipe, ignore_input_masks=False, post_stack_clipping=True)

mean combine input frames after sigma-clipping outlying pixels using a median value with median absolute deviation (mad) as the deviation function

Key Arguments:

• frames – an ImageFileCollection of the frames to stack or a list of CCDData objects

• recipe – the name of recipe needed to read the correct settings from the yaml files

• ignore_input_masks – ignore the input masks during clip and stacking?

• post_stack_clipping – allow cross-plane clipping on combined frame. Clipping settings in setting file. Default True.

Return:

• combined_frame – the combined master frame (with updated bad-pixel and uncertainty maps)

Usage:

This snippet can be used within the recipe code to combine individual (using bias frames as an example):

combined_bias_mean = self.clip_and_stack(
    frames=self.inputFrames, recipe="soxs_mbias", ignore_input_masks=False, post_stack_clipping=True)

detrend(inputFrame, master_bias=False, dark=False, master_flat=False, order_table=False)

subtract calibration frames from an input frame

Key Arguments:

• inputFrame – the input frame to have calibrations subtracted. CCDData object.

• master_bias – the master bias frame to be subtracted. CCDData object. Default False.

• dark – a dark frame to be subtracted. CCDData object. Default False.

• master_flat – divided input frame by this master flat frame. CCDData object. Default False.

• order_table – order table with order edges defined. Used to subtract scattered light background from frames. Default False.

Return:

• calibration_subtracted_frame – the input frame with the calibration frame(s) subtracted. CCDData object.

Usage:

Within a soxspipe recipe use detrend like so:

myCalibratedFrame = self.detrend(
    inputFrame=inputFrameCCDObject, master_bias=masterBiasCCDObject, dark=darkCCDObject)

flag_poor_data()

a method to flag data as ‘poor’ quality based on QC values exceeding thresholds defined in the settings file

Usage:

self.flag_poor_data()

get_recipe_settings()

get the recipe and arm specific settings

Return:

• recipeSettings – the recipe specific settings

Usage:

usage code

prepare_frames(save=False)

prepare raw frames by converting pixel data from ADU to electrons and adding mask and uncertainty extensions

Key Arguments:

• save – save out the prepared frame to the intermediate products directory. Default False.

Return:

• preframes – the new image collection containing the prepared frames

Usage

Usually called within a recipe class once the input frames have been selected and verified (see soxs_mbias code for example):

self.inputFrames = self.prepare_frames(
    save=self.settings["save-intermediate-products"])

qc_median_flux_level(frame, frameType='MBIAS', frameName='master bias', medianFlux=False)

calculate the median flux level in the frame, excluding masked pixels

Key Arguments:

• frame – the frame (CCDData object) to determine the median level.

• frameType – the type of the frame for reporting QC values Default “MBIAS”

• frameName – the name of the frame in human readable words. Default “master bias”

• medianFlux – if serendipitously calculated elsewhere don’t recalculate. Default False

Return:

• medianFlux – median flux level in electrons

Usage:

medianFlux = self.qc_median_flux_level(
    frame=myFrame,
    frameType="MBIAS",
    frameName="master bias")

qc_ron(frameType=False, frameName=False, masterFrame=False, rawRon=False, masterRon=False)

calculate the read-out-noise from bias/dark frames

Key Arguments:

• frameType – the type of the frame for reporting QC values. Default False

• frameName – the name of the frame in human readable words. Default False

• masterFrame – the master frame (only makes sense to measure RON on master bias). Default False

• rawRon – if serendipitously calculated elsewhere don’t recalculate. Default False

• masterRon – if serendipitously calculated elsewhere don’t recalculate. Default False

Return:

• rawRon – raw read-out-noise in electrons

• masterRon – combined read-out-noise in mbias

Usage:

rawRon, mbiasRon = self.qc_ron(
    frameType="MBIAS",
    frameName="master bias",
    masterFrame=masterFrame
)

report_output(rformat='stdout')

a method to report QC values alongside intermediate and final products

Key Arguments:

• rformat – the format to outout reports as. Default stdout. [stdout|…]

Usage:

self.report_output(rformat="stdout")

subtract_mean_flux_level(rawFrame)

iteratively median sigma-clip raw bias data frames before calculating and removing the mean bias level

Key Arguments:

• rawFrame – the raw bias frame

Return:

• meanFluxLevel – the frame mean bias level

• fluxStd – the standard deviation of the flux distribution (RON)

• noiseFrame – the raw bias frame with mean bias level removed

Usage:

meanFluxLevel, fluxStd, noiseFrame = self.subtract_mean_flux_level(rawFrame)

update_fits_keywords(frame, rawFrames=False)

update fits keywords to comply with ESO Phase 3 standards

Key Arguments:

• frame – the frame to update

• rawFrames – limit the raw frames to be listed in the fits header to only these frames (list)

Return:

• None

Usage:

usage code

Todo

- add usage info
- create a sublime snippet for usage
- write a command-line tool for this method
- update package tutorial with command-line tool info if needed

xsh2soxs(frame)

perform some massaging of the xshooter data so it more closely resembles soxs data - this function can be removed once code is production ready

Key Arguments:

• frame – the CCDDate frame to manipulate

Return:

• frame – the manipulated soxspipe-ready frame

Usage:

frame = self.xsh2soxs(frame)