Improved representation of geometric distortion

[stscijgbot-jp]

Issue JP-3168 was created on JIRA by Anton Koekemoer:

This ticket is intended as a high-level ticket to track work related to proposed improvements in the JWST pipeline for how geometric distortions are represented for imaging modes.

Currently, polynomial representations are used to describe the instrument distortion. For imaging modes with MIRI, NIRISS and NIRCam, these polynomials generally account for distortion to an accuracy of a few milliarcseconds, which is sufficient to enable initial science to be carried out. However, on milliarcsecond scales there are generally distortion residual patterns across the detector (either because polynomials might not exactly match the functional form of the distortion, or due to other effects such as detector lithographics, etc).

The proposed solution to this is to capture these 2D residual distortion patterns in additional reference files that can be applied, together with the polynomial files, to reduce the distortion residuals by significant amounts, important for enabling additional science to be carried out. This solution is similar to that used on HST, where distortions are also represented by polynomials along with 2D residual files that capture all the remaining differences, and which has worked very successfully for both ACS and WFC3.

So this ticket is aimed at introducing the idea and serving as a forum for additional discussion (join the ticket watchlist to participate, and use the comments for discussion), to arrive at an eventual path to propose this to the MO and SPB for inclusion in the overall priorization process for pipeline improvements.

[stscijgbot-jp]

Comment by Anton Koekemoer on JIRA:

This was discussed in JWST Cal WG Meeting 2023-04-04

Example plots from Mattia Libralato showing the improvement for NIRISS, with just the current polynomial representation on the left (which is what's currently in the pipeline), vs the proposed polynomial + 2D residual correction on the right:

!image-2023-04-05-15-04-13-530.png|width=579,height=324!

[stscijgbot-jp]

Comment by Alicia Canipe on JIRA:

Just for ease of tracking, copying the path forward from the CalWG meeting:

Path forward:

• Conclusion from today's meeting: There is enough scientific benefit for this to be worth proceeding with implementation: polynomials are good to a few mas, but pushing further to sub-mas accuracy can enable new science (Mattia's presentation today in fact came from the scientific side initially) Today's presentation focussed on MIRI and NIRISS, but NIRCam has similarities as well (Armin and Vera are in fact reporting on this at the NIRCam CAO review after this meeting), ie the polynomial solution is generally good to a few mas, but with the potential to reach sub-mas accuracy if a 2d residual approach was to be implemented Will initially consider implementing this for imaging modes: MIRI, NIRISS, NIRCam Will continue discussion offline, to develop an approach for implementation that can be proposed to the MO (and include in prioritization process with MO/DMD/SPB, with eventual involvement from DMS as this proceeds further)

[stscijgbot-jp]

Comment by Anton Koekemoer on JIRA:

thanks Alicia Canipe! Also, we'll be resuming this discussion at our next JWST CalWG meeting (2023 Jun 13) when Armin Rest  and Vera Platais  will present the corresponding discussion for NIRCam geometric distortions, and this should provide the context for determining the next steps in a path forward for implementation.

[stscijgbot-jp]

Comment by Anton Koekemoer on JIRA:

Armin Rest  Bryan Hilbert  (CalWG NIRCam reps) would you be able to assign this ticket please the NIRCam team's assessment of an "Urgency" rating (1 though 4) and associated text in the "Criticality Rationale" field?

[stscijgbot-jp]

Comment by Howard Bushouse on JIRA:

I believe the next step in the implementation process for this would be to have the stakeholders agree on format and content for a new type of reference file for the 2D residual information, e.g. something like the HST "DGEO" ref file? Anyone with ideas along these lines, please chime in here.

[stscijgbot-jp]

Comment by Anton Koekemoer on JIRA:

To follow up on Howard's question, tagging some relevant folks here if you could chime in please (but anyone else welcome too of course): Mattia Libralato  Vera Platais  Armin Rest  Mario Gennaro  Kevin Volk  Rosa Diaz 

[stscijgbot-jp]

Comment by Kevin Volk on JIRA:

Mattia and Tony are the point people for this, I think.  I have pinged Tony about it, although he is on vacation through today.

 

[stscijgbot-jp]

Comment by Nadia Dencheva on JIRA:

If I remember correctly there was no agreement at the time of the presentation where this correction should be applied - before or after the polynomial correction. This will need to be clarified as well.

[stscijgbot-jp]

Comment by Anton Koekemoer on JIRA:

thanks Nadia Dencheva  I think the proposed paradigm would have it done in the same order as it currently done for HST, but Vera Platais  may be well placed to confirm this or whether it should be done differently.

[stscijgbot-jp]

Comment by Rosa Diaz on JIRA:

For HST the "DGEO" file was replaced by three files NPOLFILE, D2IMFILE, ICDTAB

In this case the the NPOLFILE is a 2-D look up table that contains the non-polynomial filter-dependent part of the distortion correction. You can check this info (for HST) along with the format in  subsection 11.2.11  in https://newcdbs.stsci.edu/doc/Section11.html     |http://example.com/]|

[stscijgbot-jp]

Comment by Tony Sohn on JIRA:

As Rosa Diaz pointed out above, HST's NPOL files are the ones that Mattia and I had in mind. So, these would be applied AFTER the IDCTAB has been applied when correcting for distortion (i.e., from Science X,Y to Ideal X, Y).

[stscijgbot-jp]

Comment by Nadia Dencheva on JIRA:

Just a reminder that the polynomial distortion for JWST transforms from Science X,Y  to V2V3, not Ideal X,Y.

Also all WCS related reference files are in ASDF format. We should consider using it for this distortion component as well.

[stscijgbot-jp]

Comment by Tony Sohn on JIRA:

Nadia Dencheva Hmm... as far as I know, the polynomials in the reference files are from SciX,Y to IdlX,Y, at least for NIRCam and NIRISS (columns are thus named Sci2IdlX/Y and Idl2SciX/Y). The conversion to V2, V3 are then done using SIAF alignment parameters.

[stscijgbot-jp]

Comment by Nadia Dencheva on JIRA:

Tony Sohn Are you thinking about the SIAF?  The "distortion" reference files in CRDS go to V2V3. Then the pipeline applies rotations to go to a standard celestial system. If I evaluate the Nircam distortion model I get values in arcsec

ddist.model(1024, 1024)
Out[58]: (118.43896987798297, -487.32104731855975) ```

[stscijgbot-jp]

Comment by Tony Sohn on JIRA:

Nadia Dencheva Okay, I see what you mean. The end results are in the V2, V3 system in arcsec from DMS pixels. However, the distortion reference files (asdf) have the polynomial coefficients which brings science (X, Y) pixels to ideal (X, Y) arcsec first. Then, simple offsets in V2, V3, and the Y rotation about V3 are applied to bring everything into the V2, V3 system. The NPOL-style lookup table would have to be applied right after the polynomial corrections since it is meant to correct for non-linear components in the detector distortion. This means, some code changes may be required to make the jwst pipeline handle things in the current HST way when it comes to distortion corrections.

[stscijgbot-jp]

Comment by Nadia Dencheva on JIRA:

Tony Sohn Here're the transforms in the reference file:

print(d)
Model: CompoundModel
Inputs: ('x0', 'x1')
Outputs: ('y0', 'y1')
Model set size: 1
Expression: [0] & [1] | [2] & [3] | [4] | [5] & [6] | [7] | [8] & [9] | [10] & [11]
Components: 
    [0]: <Shift(offset=1.)>
    [1]: <Shift(offset=1.)>
    [2]: <Shift(offset=-1024.5)>
    [3]: <Shift(offset=-1024.5)>
    [4]: <Mapping((0, 1, 0, 1))>
    [5]: <Polynomial2D(5, c0_0=0., c1_0=0.03089057, c2_0=0.00000001, c3_0=0., c4_0=-0., c5_0=-0., c0_1=0., c0_2=-0.00000003, c0_3=0., c0_4=-0., c0_5=-0., c1_1=-0.00000015, c1_2=0., c1_3=0., c1_4=0., c2_1=-0., c2_2=-0., c2_3=0., c3_1=0., c3_2=-0., c4_1=-0.)>
    [6]: <Polynomial2D(5, c0_0=0., c1_0=-0.0001116, c2_0=0.00000011, c3_0=-0., c4_0=-0., c5_0=0., c0_1=0.03089632, c0_2=-0.00000005, c0_3=0., c0_4=-0., c0_5=0., c1_1=0.00000004, c1_2=-0., c1_3=-0., c1_4=0., c2_1=0., c2_2=-0., c2_3=0., c3_1=-0., c3_2=0., c4_1=-0.)>
    [7]: <Mapping((0, 1, 0, 1))>
    [8]: <Polynomial2D(1, c0_0=0., c1_0=-0.99998323, c0_1=-0.0057911)>
    [9]: <Polynomial2D(1, c0_0=0., c1_0=-0.0057911, c0_1=0.99998323)>
    [10]: <Shift(offset=118.454504)>
    [11]: <Shift(offset=-487.33635)> ```
 

I think what you are saying is (correct me if I'm wrong) that we will have to split this file in two after transform #&#x2060;6, or perhaps transform #&#x2060;9, apply the non-polynomial distortion, then apply the rest of the transforms from the current reference file.
If this is what you mean, this will require changes to the reference file, as well as code changes, if the non-polynomial corrections are to be kept in separate files. Alternatively, if they are inserted at the right place in the current chain of transforms then this means only delivering new reference files and no code changes. The drawback is they are kept together with the polynomials and when there's a need to update them the entire file will have to be redelivered. This may be a good thing though, it may be easier to test.

[stscijgbot-jp]

Comment by Tony Sohn on JIRA:

Correct, the non-poly distortion will be applied right after the poly distortion. I think it'll be after #⁠6 in your example above (#⁠8 and #⁠9 looks to be the Y angle about V3). The non-poly component is a NxM look-up tables (32x32 in the case of NIRISS) which provides the corrections to be applied (deltaX and deltaY, i.e., two separate tables) for given science X and Y positions via interpolation. It may be possible to embed this look-up table in the distortion asdf file or keep it separate as you mentioned. In the calibration point of view, the poly and non-poly components will most likely have to be updated together if there is a change in distortions, so I don't think it really matters which way we decide to go.

[stscijgbot-jp]

Comment by Mario Gennaro on JIRA:

I agree with Tony's interpretation of all of this.

I have a question: can the compound model construct handle a 2D look up table? I think "applying" the table implies finding the 4 (x,y) locations in the table around the desired (X0,Y0) point, do a bilinear (or other type of) interpolation and thus obtain (X0',Y0')?

If not we'd have to apply the lookup table AFTER step 11 above and outside this part of the code, which in turn would imply that the lookup table itself needs to be mapped to (V2,V3), which is not hard/impossible, just needs the right bookkeeping.

[stscijgbot-jp]

Comment by Nadia Dencheva on JIRA:

Mario Gennaro Yes, an astropy.modeling.Tabular2D model, containing the lookup tables can be inserted in the right place in the chain of models. I can work with those who create the reference files to help with the script if necessary.

Doing it that way also allows the reference files to be delivered and the correction to be enabled at any time, because there won't be any software changes. So as soon as the reference files are ready and tested the change can become "live" in OPS.

[stscijgbot-jp]

Comment by Vera Platais on JIRA:

Mario Gennaro in NIRCam the max vector of the residuals after the polynomial solution is very small < 1mas, or 0.6mas. I believe that for general NIRCam users it is really insignificant. Here are 2-D looks residuals map for NRCB and NRCA in F201M filter after the polynomial solution. The largest structure are in NRCA4 & NRCB4 and related to epoxy. Since it is some-kind manufacture effect i.e.  effecting  the pixel itself 2-Dlook up table should be used before polynomial solution, as I did for WFC3/UVIS and ACS/WFC and as it is implemented in the HST pipe-line.

 

[^NRCBresids_smooth_3or.f210m.pdf][^NRCBresids_smooth_3or.f210m.pdf]