How to Plug In A User-Generated Module¶
Jwst_reffiles is simply a framework upon which reference file generation modules can be built. In order to add functionality for creating and averaging/combining reference files, users will need to plug-in their code to the jwst_reffiles framework. This page describes how to plug an existing module into jwst_reffiles. An example is provided in jwst_reffiles/example, where we have plugged in example_readnoise_module.py by creating mkref_example_readnoise_module.py following the steps below.
Assume you have a python script that creates a gain reference file. It takes as input several fits files containing dark current and flat field exposures, as well as optional arguments, and produces a CRDS-formatted gain reference file which is saved as a fits file. For this example, we will call this script my_gain_module.py.
Plug-in Steps¶
The steps needed to plug my_gain_module.py into jwst_reffiles are:
- Make a copy of jwst_reffiles/templates/plugin_template.py and rename it to the name of your module with mkref_ prepended. (e.g. mkref_my_gain_module.py). This is your plug-in module.
- Make your plug-in module executable. (e.g.
chmod ugo+x mkref_my_gain_module.py
). This is necessary so that the plug-in module can be called via the command line without prependingpython
to the call. This is helpful for cases where commands are being sent to Condor. - Add the appropriate parameters and a call to your script (e.g. my_gain_module.py). Details on edits are given in the edits list below.
- Add the appropriate parameters for your script to a new section towards the bottom (see for example the block for
example_readnoise_module
) of the main config file. An example of what to add is shown in the Config File Update section below.
Plug-in Wrapper Edits¶
Within your plug-in module, make the following edits:
- Add an import statement for your script. e.g.
from my_package.gain import my_gain_module
- In
__init__
, set the reflabel and reftype. The reflabel is simply the name of your script. (e.g. my_gain_module) The reftype is the jwst_reffiles shorthand for the type of reference file that your script produces. (e.g. gain) The list of allowed reftypes is in ???? - In the
extra_optional_arguments
function, add any parameters for your script that you may want to call via the command line. These parameters will be available during command line calls to mkrefs.py. Parameters set via the command line will override the values set in the config file. - Within the
callalgorithm
function, create a call to your script (e.g. my_gain_module.py) When creating the call to your module, you should have access to all necessary information. The names of input fits files for a single run of your script will be in a list inself.inputimages['output_name']
. Similarly, the output name of the reference file to be created will be inself.args.outputreffilename
. Any additional parameters (as defined in the config file and/or on the command line) will be available in theself.parameters
dictionary.
Config File Update¶
You may add any parameters for your module to the mkrefs config file. This is done in a block under the name of your module.
In this example, let’s assume that mkref_my_gain_module.py takes two arguments:
- num_boxes: The detector will be divided up into a num_boxes*x*num_boxes grid of squares
- max_signal: The maximum signal value to use in the calculation of the gain
Add a section to the config file containing the arguments and corresponding values.
my_gain_module:
num_boxes: 16
max_signal: 20000
The values for these parameters will then be read in from the config file when mkrefs.py is called. Keep in mind that if you have added these parameters to extra_optional_arguments
function, then you can override the values in the config file via the command line.