Add plane fitting to level_match_step.py

Also adds in metadata about background offset times at the lv2 stage

Also adds in option to combine the NIRCam short chips before any mosaic level matching

CHANGES.rst

@@ -1,6 +1,17 @@
 1.1.1 (Unreleased)
 ==================
 
+- Added ``combine_nircam_short`` option in ``level_match_step``, which will match levels
+  between the four NIRCam short imaging chips before doing matching between mosaic tiles
+- ``lv2_step`` will now propagate through individual exposure offset times from backgrounds,
+  which is necessary for selecting a reference image in ``level_match_step``
+- Added ``fit_type`` option to ``level_match_step`` for every option, which allows for
+  plane fitting in the level matching in a modular way
+- ``level_match_step`` fitting method has been changed to resemble the iterative Montage method,
+  which is necessary for plane fitting
+- ``reproject_image`` in ``utils`` can now also reproject error arrays
+- ``make_stacked_image`` in ``utils`` can now also reproject the error and readnoise maps
+- Exposed ``auto_rotate`` in ``make_stacked_image`` in ``utils``
 - Added ``recombine_lyot`` option to ``level_match_step``, which allows for recombining
   the lyot coronagraph into the main MIRI science chip before matching between mosaic tiles
 - Tidied up ``level_match_step`` to make more modular and functional

docs/steps/level_match.rst

@@ -4,14 +4,27 @@ LevelMatchStep
 
 This step matches relative levels between tiles, using an algorithm very similar to
 `Montage <http://montage.ipac.caltech.edu/>`_. We reproject tiles to a common astrometric grid, and then for each
-overlapping pair find the median per-pixel difference, and minimize for that. We do this in a two-pass process, firstly
-for dithers within a mosaic tile, and then for all mosaic tiles (creating stacked images). This maximises overlaps
-between mosaic tiles and produces better results from our testing.
+overlapping pair find the median per-pixel difference, and minimize for that. We do this in a two (or three)-pass
+process, firstly for dithers within a mosaic tile, then optionally for main science chip and lyot coronagraph,
+optionally between the four NIRCam short chips, and then for all mosaic tiles (creating stacked images). This maximises
+overlaps between mosaic tiles and produces better results from our testing.
 
 For MIRI imaging, there is an optional ``recombine_lyot`` parameter. If you've used the ``lyot_separate`` step then
 this will match the coronagraph and main science chip and recombine them before any potential matching between
 different tiles in the mosaic.
 
+For NIRCam short imaging, there is an optional ``combine_nircam_short`` parameter. This will match levels between the
+four NIRCam short chips and then will treat as one single image going into the final mosaic level matching stage.
+
+For each of these three stages, you can match either with a simple constant offset ("level") or with a plane
+("level+match"). This can be controlled separately for each stage (``fit_type_dithers``, ``fit_type_recombine_lyot``,
+``fit_type_combine_nircam_short``, ``fit_type_mosaic_tiles``). By default, everything will just fit a constant offset.
+
+When matching between mosaic tiles, we select a reference image that we deem to be the most flat, and will adjust any
+corrections relative to that. If you are using observations with dedicated backgrounds (as defined by
+:doc:`Lv2Step <lv2>`, then it will select the image closest in time to the backgrounds. If not, it will use the image
+with the most overlapping image pairs.
+
 N.B. This should be run once you have good local astrometry, and before you do
 :doc:`MultiTileDestripeStep <multi_tile_destripe>`.