Resample speedup

[t-brandt]

Partially resolves JP-3997
Resolves JP-4216
Resolves RCAL-1311

Closes spacetelescope/jwst#10115

This PR supersedes #485 and #367

The reproject functions and calc_pixmap and calc_gwcs_pixmap functions in alignment and outlier_detection are all removed in favor of a copy of the calc_pixmap function from drizzle which now lives in alignment. The rewritten calc_pixmap accepts two new inputs: stepsize (duplicating an argument in drizzlepac), which performs the full WCS pixel mapping only every stepsize pixels in each direction, and order, either 1 or 3, to perform either bilinear or bicubic interpolation in between. These parameters should be exposed at the top-level calls to outlier detection and resample.

Tasks

• update or add relevant tests
• update relevant docstrings and / or docs/ page
• Does this PR change any API used downstream? (if not, label with no-changelog-entry-needed)
  • write news fragment(s) in changes/: echo "changed something" > changes/<PR#>.<changetype>.rst (see changelog readme for instructions)
  • run regression tests with this branch installed ("git+https://github.com/<fork>/stcal@<branch>")
    • jwst regression test
    • romancal regression test

[codecov]

Codecov Report

❌ Patch coverage is 71.87500% with 27 lines in your changes missing coverage. Please review.
✅ Project coverage is 89.92%. Comparing base (6814765) to head (95dad49).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
src/stcal/alignment/resample_utils.py	53.06%	23 Missing ⚠️
src/stcal/resample/resample.py	87.50%	2 Missing ⚠️
tests/test_alignment.py	80.00%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #488      +/-   ##
==========================================
- Coverage   90.12%   89.92%   -0.21%     
==========================================
  Files          65       65              
  Lines       10180    10151      -29     
==========================================
- Hits         9175     9128      -47     
- Misses       1005     1023      +18     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[emolter]

The jwst repository calls gwcs_blot and the Resample class. So in order for this to be accessible to jwst, I think the two new parameters stepsize and order need to be propagated one more step and become optional inputs to those two.

For changelog fragments, you'll need a few different ones, something like the following:

• 488.alignment.rst: Rename calc_pixmap to calc_gwcs_pixmap, and add interpolation options to calc_gwcs_pixmap to speed up resample computations. (something about the amount of speedup here).
• 488.alignment.rst: Remove util.reproject method
• 488.outlier_detection.rst: Remove utils.reproject method. Remove utils.calc_gwcs_pixmap; use alignment.resample_utils.calc_gwcs_pixmap instead.
• 488.breaking.rst: Remove alignment.util.reproject, outlier_detection.utils.reproject, and outlier_detection.utils.calc_gwcs_pixmap. Rename alignment.util.calc_pixmap to alignment.util.calc_gwcs_pixmap

[t-brandt]

I added two changelog fragments attempting to match the current filenames and the spirit of your suggestions, I propagated stepsize and order up as needed, and I fixed the formatting. Tests are passing. This PR still needs unit tests of the interpolation aspect of calc_pixmap.

[emolter]

Thanks for doing so! It looks like I have what I need to ensure this looks good on multiple types of JWST data.

RE the changelog, what you have looks good. We are about to change some of the categories - this is part of what we were arguing about at hack day - so they unfortunatley may need to be renamed and split by step if #486 gets in before this does.

[zacharyburnett]

#486 is now merged so these two existing change log entries will probably need to be split into changes/488.alignment.rst and changes/488.resample.rst

[zacharyburnett]

(see https://github.com/spacetelescope/stcal/tree/main/changes#news-fragment-change-types for instructions)

[emolter]

FWIW I think my original suggestion was tailored to the new way of doing things, so that may be helpful again.

[t-brandt]

Please check if my changes are sufficient. I think it just needs a proper unit test or two.

[emolter]

I think they look good. Maybe we should also add a fragment for Resample, something like "Add options to interpolate pixel map...something something" since the resample step is the most highly affected one? But I'm happy as-is.

[emolter]

@t-brandt I started testing this by hooking it into the jwst repository (see this early PR draft). I think I found a small bug, which is that the output pixel map seems to be the wrong shape for non-square data.

For example, for the unit test jwst.outlier_detection.tests.test_outlier_step_no_outliers, the input data shape is (21,20), and this gets passed into calc_pixmap properly (data and shape parameters are consistent) but the output has shape (20,21,2) when it should be (21,20,2).

Changing the last line of calc_pixmap to have some transposes, i.e. pixmap = np.dstack([x.T, y.T]), allows the test to pass. (I didn't check if this was the mathematically correct fix.)

[t-brandt]

Thanks, @emolter -- the x and y order were reversed in one call. It didn't matter if they were the same as for a square array. I think it should be fixed now.

[emolter]

Fix looks like it works, thanks. I'm still testing this on different jwst datasets, will update when that's done.

[emolter]

I've now tested this on all jwst imaging regression test data. Things are looking excellent- the differences in output data are almost all smaller than our tolerances, and those that aren't are still small enough that I'm not worried. I've also confirmed that the runtime improvements can be substantial for large JWST mosaics. See comments on spacetelescope/jwst#10137 for details.

I'm ready to approve this pending two things:

• Regression tests against jwst main. Although I don't anticipate differences, we did consolidate calc_pixmap into one function, and the now-removed stcal version did have some small differences with the current version. I've kicked those off here: https://github.com/spacetelescope/RegressionTests/actions/runs/21004645391
• Additional unit test coverage, which I think is already on Tim's radar.

[emolter]

There are three failures in the regression tests (https://github.com/spacetelescope/RegressionTests/actions/runs/21004645391) pointing to jwst/main and this PR branch.

They look small so I'm not super worried, but we didn't expect any changes at all, so I think it'd be worth at least understanding where they are coming from. I presume it is indeed related to some difference between the old stcal calc_gwcs_pixmap and the new calc_pixmap.

test_nirspec_mos_spec3[v000000056-crf] had just one pixel in one of several sci extensions flip from a real value to NaN.
test_nirspec_mos_spec3[v000000056-s2d] had just four pixels change value, but some of those changes look large.
test_nirspec_fs_spec3_moving_target[crf] had 21 pixels flip from real values to NaN (also in just one extension), which is still only around 0.1% of pixels

Does anyone have insight here?

edit with more details:
For the failing SlitModel in test_nirspec_mos_spec3[v000000056-s2d], there's some noise at the numerical precision level. The plot below shows the diff between the science data in the PR branch vs our truth file. The green/yellow highlighted points are the 10 largest differences. These are:

Difference statistics:
  Shape: (31, 1291) (spatial x wavelength)
  Max absolute difference: 1.032e+00
  RMS difference: 6.677e-03

  Top 10 largest differences:
    1. [y= 29, x= 200]: -1.032e+00
    2. [y= 29, x= 199]: -5.989e-01
    3. [y= 28, x= 200]: -2.680e-01
    4. [y= 28, x= 199]: -1.142e-01
    5. [y=  5, x= 552]: +6.104e-05
    6. [y=  9, x= 553]: +3.052e-05
    7. [y= 10, x= 552]: -1.526e-05
    8. [y=  8, x= 553]: +7.629e-06
    9. [y=  9, x= 554]: +3.815e-06
    10. [y=  5, x= 554]: -3.815e-06

So the four points the regtest flagged (the four in the upper left) are indeed substantially larger differences than the rest. Still unclear to me what caused this.

For the failing second exposure in the MultiExposureModel in test_nirspec_fs_spec3_moving_target[crf], it looks like the newly-NaN pixels are all along one edge; see below, where I'm plotting the diff between the PR branch and the truth file and coloring the newly-NaN pixels in magenta.

[emolter]

Looking again at the analysis I did above, I think it's fine to chalk it up to just small numerical differences between the old and new calc_pixmap. I got an opinion from Melanie and she agrees. So I'm fine ok-ifying these whenever the PR goes in.