Table Of Contents

Previous topic

2.5.1.1. Using Slices and “Subdata”

Next topic

4. AstroData Configuration Package Development Guide

This Page

3. ReductionContext Class Reference

The following is information about the ReductionContext class. When writing primitives the reduction context is passed into the primitive as the sole argument (generally named rc by Gemini conventions and in addition to the self argument). This object is used by the primitive to both get inputs and store outputs, as well as to communicate with subsystems like the calibration queries system or list keeping for stacking.

3.1. Parameter and Dictionary Features

3.1.1. The “in” operator: contains(..)

ReductionContext.__contains__(thing)
Parameters:thing (str) – A key to check for presence in the Reduction Context

The __contains__ function implements the Python in operator. The ReductionContext is a subclass of a dict, but it also has a secondary dict of “local parameters” which are available to the current primitive only, which are also tested by the __contains__(..) member. These parameters will generally be those passed in as arguments to a primitive call from a recipe.

3.2. Dataset Streams: Input and Output Datasets

3.2.1. get_inputs(..)

ReductionContext.get_inputs(style=None)
Parameters:style (string) – Controls the type of return value. Supported values are “AD” and “FN” for AstroData and string filenames respectively.
Returns:a list of AstroData instances or string filenames
Return type:list

get_inputs(..) gets the current input datasets from the current stream. You cannot choose the stream, use get_stream(..) for that. To report modified datasets back to the stream use report_output(..).

3.2.2. get_inputs_as_astrodata(..)

ReductionContext.get_inputs_as_astrodata()

This function is equivalent to:

get_inputs(style=”AD”)

3.2.3. get_inputs_as_filenames(..)

ReductionContext.get_inputs_as_filenames()

This function is equivalent for:

get_inputs(style=”FN”)

3.2.4. get_stream(..)

ReductionContext.get_stream(stream='main', empty=False, style=None)
Parameters:
  • stream (str) – A string name for the stream in question. To use the standard stream do not set.
  • empty (bool) – Controls if the stream is emptied, defaults to “False”.
  • style – controls the type of output. “AD” directs the function to return a list of AstroData instances. “FN” directs it to return a list of filenames. If left blank or set to None, the AstroDataRecord structures used by the Reduction Context will be returned.
Returns:

a list of AstroDataRecord objects, AstroData objects or filenames.

Return type:

list

get_stream returns a list of AstroData instances in the specified stream.

3.2.5. get_reference_image(..)

ReductionContext.get_reference_image()

This function returns the current reference image. At the moment this is simply the first dataset in the current inputs. However, use of this function allows us to evolve our concept of reference image for more complicated cases where the choice of a “reference” image may need to be different (e.g. require some data analysis to determine).

3.2.6. report_output(..)

ReductionContext.report_output(inp, stream=None, load=True)
Parameters:
  • inp (str, AstroData instance, or list) – The inputs to report (add to the given or current stream). Input can be a string (filename), an AstroData instance, or a list of strings and/or AstroData instances. Each individual dataset is wrapped in an AstroDataRecord and stored in the current stream.
  • stream (str) – If not specified the default (“main”) stream is used. When specified the named stream is created if necessary.
  • load – A boolean (default: True) which specifies whether string arguments (pathnames) should be loaded into AstroData instances or if it should be kept as a filename, unloaded. This argument has no effect when “report” AstroData instances already in memory.

This function, along with get_inputs(..) allows a primitive to interact with the datastream in which it was invoked (or access other streams).

3.2.7. switch_stream(..)

ReductionContext.switch_stream(switch_to=None)
Parameters:switch_to (str) – The string name of the stream to switch to. The named stream must already exist.
Note :This function is used by the infrastructure (in an application such as reduce and in the ReductionContext) to switch the stream being used. Reported output then goes to the specified stream.

3.3. ADCC Services

3.4. Calibrations

3.4.1. get_cal(..)

ReductionContext.get_cal(data, caltype)

Retrieve calibration.

Parameters:
  • data (string or AstroData instance) – File for which calibration must be retrieved.
  • caltype (string) – The type of calibration (ex.’bias’, ‘flat’).
Returns:

The URI of the currently stored calibration or None.

Return type:

string or None

3.4.2. rq_cal(..)

ReductionContext.rq_cal(caltype, inputs=None, source='all')

Create calibration requests based on raw inputs.

Parameters:
  • caltype (str) – The type of calibration. For example, ‘bias’ and ‘flat’.
  • inputs (list of AstroData instances) – The datasets for which to find calibrations, if not present or None current “inputs” are used.
  • source – Directs what calibration service to contact, for future compatibility, currently only “all” is supported.

3.5. Stacking

3.5.1. rq_stack_get(..)

ReductionContext.rq_stack_get(purpose='')
Parameters:purpose (string) – The purpose is a string prepended to the stackingID used to identify the list (see get_list(..)).

The stackingID (see IDFactory module) is used to identify the list. The first input in the rc.inputs list is used as the reference image to generate the stackingID portion of the list identifier.

The stackingID function in IDFactory is meant to produce identical stacking identifiers for different images which can/should be stacked together, e.g. based on program ID and/or other details. Again, see IDFactory for the particular algorithm in use.

Note :a versioning system is latent within the code, and is added to the id to allow adaptation in the future if identifer construction methods change.

3.5.2. rq_stack_update(..)

ReductionContext.rq_stack_update(purpose=None)
Parameters:purpose (str) – The purpose argument is a string prefixed to the generated stackingID. This allows two images which would produce identical stackingIDs to go in different lists, i.e. such as a fringe frame which might be prepended with “fringe” as the purpose.

This function creates requests to update a stack list with the files in the current rc.inputs list. Each will go in a stack based on its own stackingID (prepended with “purpose”).

Note :this function places a message on an outbound message queue which will not be sent until the next “yield”, allowing the ReductionObject command clause to execute.

3.6. Lists

3.6.1. list_append(..)

ReductionContext.list_append(id, files, cachefile=None)
Parameters:
  • id (string) – A string that identifies to which list to append the filenames.
  • files (list of strings) – A list of filenames to add to the list.
  • cachefile (string) – Filename to use to store the list.

The caller is expected to supply cachefile, which in principle a value of “None” could mean the “default cachefile” this is not supported by the adcc as of yet. The desired behavior is for reduce instances running in the same directory to cooperate, and those running in separate directories be kept separate, and this is implemented by providing an argument for cachefile which is in a generated subdirectory (hidden) based on the startup directory for the reduce process.

The adcc will negotiate all contention and race conditions regarding multiple applications manipulating a list simultaneously in separate process.

3.6.2. get_list(..)

ReductionContext.get_list(id)
Parameters:id (str) – Lists are associated with arbitrary identifiers, passed as strings. See IDFactory for IDs built from standard astrodata characteristics.

The list functionality allows storing dataset names in a list which is shared by all instances of reduce running in a given directory. The list is kept by an adcc instance in charge of that sub-directory. The get_list(..) function retrieves a list that has already been requested via rq_stack_get(..) which initiates the interprocess request.

This function does not block, and if the stack was not requested prior to a yeild, prior to this call, then None or an out of date version of this list will be retrieved.

Note :“get_stack” calls get_list but takes a “purpose” to which it adds a stackingID as a suffix to the list identifier.

3.7. Utility

3.7.1. prepend_names(..)

ReductionContext.prepend_names(prepend, current_dir=True, filepaths=None)
Parameters:
  • prepend (string) – The string to be put at the front of the file.
  • current_dir (boolean) – Used if the filename (astrodata filename) is in the current working directory.
  • filepaths – If present, these file paths will be modified, otherwise the current inputs are modified.
Returns:

List of new prepended paths.

Return type:

list

Prepends a prefix string to either the inputs or the given list of filenames.

3.7.2. run(..)

ReductionContext.run(stepname)
Parameters:stepname – The primitive or recipe name to run. Note: this is
actually compiled as a recipe. Proxy recipe names may appear
in the logs.

The run(..) function allows a primitive to use the reduction context to execute another recipe or primitive.