Decide how to provide aperture correction reference files

[stscijgbot]

Issue JP-613 was created by Alicia Canipe:

The flux calibration factors will be applied by the calibration pipeline assuming they are for an infinite aperture, so the pipeline will need to apply an aperture correction in the extract_1d and source_catalog code to account for the finite aperture used.

 

We need to decide how the aperture corrections will be provided:

• scalar? vector of wavelength-dependent values?
• what reference file will they be in, and can we use the photom reference file format? in the photom reference file for imaging, this is already a table where each row corresponds to a given optical mode (e.g., filter), and there is a single scalar flux conversion factor given in that row the table could be expanded to include one or more columns giving additional scalars, such as the sizes of the source and bkg apertures and the aperture correction factor in the photom reference file for spectroscopy, this is a table with one row per mode (e.g., grating) and a 1D vector of wavelength-dependent flux calibration factors the table could be expanded to include additional columns of aperture sizes and aperture correction factors (either scalar or 1D) that go with each disperer mode ** Note: this could work if we have a single aperture, correction factor, etc. for each unique filter/wavelength, but it may be the case in the future where we need corrections for different apertures depending on knowledge of the source type (or we may want to support offline use of the pipeline where the user might want a different extraction aperture, e.g., faint sources may benefit from smaller apertures than brighter sources)

 

+Information to include for imaging+

• at minimum, files will have a line for each filter with the specified apertures and background annuli and multiplicative aperture correction to infinite aperture

 

+Information to include for spectroscopy+

• at minimum, files will need to include a vector as a function of wavelength for the extraction aperture, background regions, and correction to infinite extraction window (aperture)

 

Related documentation:

• [https://outerspace.stsci.edu/display/JWSTCC/Vanilla+Point+Source+Catalog]
• [https://outerspace.stsci.edu/display/JWSTCC/Vanilla+Spectral+1D+Extraction]
• [https://outerspace.stsci.edu/display/JWSTCC/Vanilla+Spectral+Extraction]
• [https://outerspace.stsci.edu/display/JWSTCC/Vanilla+Imaging+Flux+Calibration]
• [https://outerspace.stsci.edu/display/JWSTCC/Vanilla+Spectral+Flux+Calibration]

[stscijgbot]

Comment by Megan Sosey: I saw this ticket go by and I'd like to make a suggestion: consider moving this reference file to ASDF instead of FITS. This will allow some greater flexibility in clarity in the file itself, the values you are trying to define, and those you may need to define in the future.

I've attached a couple asdf files as examples. I used the information from the nircam imaging mode photom reference file here: [https://jwst-crds.stsci.edu/browse/jwst_nircam_photom_0031.fits] as a guide and simply added extra information as discussed above. More can be added of course, but I've saved the files with the data in ascii format so that you can either open with asdf, or just page through it to get an idea.

These are examples of how the data might be saved and accessed, but there are other ways to do it as well

 

The first file, [^imaging_photom.asdf], (right click on the link for a quick view) is a simple organization where arrays assuming similar indexing

To open the file that's been included:

{{photom = asdf.open('imaging_photom.asdf')}}

list the attributes:

{{photom.keys() returns:}} {quote}dict_keys(['filter', 'pupil', 'photmjsr', 'nelem', 'wavelength', 'relresponse', 'uncertainty', 'asdf_library', 'history', 'fixed_aperture_correction', 'fixed_apertures']) {quote} These are some attributes in the provided file (i.e. dictionary keys in the file):

filter = list of available filters

['F070W', 'F090W', 'F115W', 'F140M', 'F150W', 'F150W2', 'F182M', 'F187N', 'F200W', 'F210M', 'F212N', 'WL3', 'F150W', 'F150W2', 'F150W2']

fixed_apertures= list of fixed apertures

[0.0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7,  0.8, 0.9, 1.0, 1.1, 1.2, 1.3, 1.4]

fixed_aperture_correction = a nested list by filter and aperture, such that fixed_aperture_correction[filter][aperture] returns the correction. You can get at this programmatically like so:

{{my_filter = photom['filter'].index('F115W')}}

{{my_aperture = photom['fixed_apertures'].index(0.8) # 0.8 is the aperture you want}}

{{correction = photom['fixed_aperture_correction'][my_filter][my_aperture]}}

 

Another way to organize the information is to logically organize everything by filter, this is in [^imaging_photom_logical.asdf].

{{photom = asdf.open('imaging_photom_logical.asdf')}}

{{photom.keys() returns:}} {quote}dict_keys(['F070W', 'F090W', 'F115W', 'F140M', 'F150W', 'F150W2', 'F182M', 'F187N', 'F200W', 'F210M', 'F212N', 'WL3', 'asdf_library', 'history']) {quote} Visually, this file would have the data organized by filter, such that just paging the asdf file you would see the following and infer that the fixed apertures and corrections were specific to each filter: {quote}F115W:

  fixed_aperture_correction: [0.0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0,

    1.1, 1.2, 1.3, 1.4]

  fixed_apertures: [0.5, 0.6, 0.7, 0.8, 0.9, 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7,

    1.8, 1.9]

F140M:

  fixed_aperture_correction: [0.0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0,

    1.1, 1.2, 1.3, 1.4]

  fixed_apertures: [0.5, 0.6, 0.7, 0.8, 0.9, 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7,

    1.8, 1.9] {quote}  The access of the data would be similar to above:

{{my_aperture = photom}}['F115W']['fixed_apertures'].index(0.8)       

correction = photom['F115W']['fixed_aperture_correction'][my_aperture]

 

The second method is a little clearer, and allows for flexible numbers of fixed apertures (or other items)  per filter. More pedantic type information can be added to each filter too, such as:

photom['F070W']['aperture_correction_for_source_size_0.5_arcseconds'] = 1.24

photom['F070W']['infinite_aperture_correction'] = 1.8

or make the above a list of source_sizes and a list of source_size_aperture_corrections ... lots of options here :) 

 

 

[stscijgbot]

Comment by James Davies: Agree with [~sosey]'s suggestion to use ASDF for the photom reference file.  It would make the photom reference files much more flexible.  And easier to create for the instrument teams.  Great suggestion.

[stscijgbot]

Comment by Alicia Canipe: The instrument teams seem to be in favor of moving to ASDF format for the photom files, so I will track that work in a separate Jira ticket.

[stscijgbot]

Comment by Alicia Canipe: The instrument teams seem to be in favor of moving to ASDF format for the photom files, so I will track the work to submit updated photom reference files in a separate ticket (or tickets).

[stscijgbot]

Comment by Alicia Canipe: {color:#172b4d}[~kgordon]  [~koekemoe]  [~whitmore]  [~lbradley]   Just a reminder about this ticket, since I think many were busy with Hubble proposals when I created it. We will need to add extraction aperture and aperture correction information to either the photom reference file or a separate reference file, because of recent pipeline updates to the photometric correction step (imaging and spec pipelines). {color}

[stscijgbot]

Comment by Alicia Canipe: Initial versions were delivered.