manual offsets

doc/coadd3d.rst

@@ -268,15 +268,48 @@ cubes covering different wavelength range, but it can coadd
 multiple spec2D files into a single datacube if the wavelength
 setup overlaps, and the spatial positions are very similar.
 
-Difficulties with combining multiple datacubes
-==============================================
+Combining multiple datacubes
+============================
 
 PypeIt is able to combine standard star frames for flux calibration, and
 should not have any difficulty with this. If your science observations are
 designed so that there is very little overlap between exposures, you should
-not expect the automatic combination algorithm to perform well. Instead, you
-should output individual data cubes and manually combine the cubes with some
-other purpose-built software.
+not assume that the automatic combination algorithm will perform well. Instead,
+you may prefer to output individual data cubes and manually combine the cubes
+with some other purpose-built software. If you know the relative offsets very
+well, then you can specify these, and PypeIt can combine all frames into a
+single combined datacube. This is the recommended approach, provided that you
+know the relative offsets of each frame. In the following example, the first
+cube is assumed to be the reference cube (0.0 offset in both RA and Dec), and
+the second science frame is offset relative to the first by:
+
+.. code-block:: ini
+
+    Delta RA x cos(Dec) = 1.0" W
+    Delta Dec = 1.0" S
+
+The offset convention used in PypeIt is that positive offsets translate the RA and Dec
+of a frame to higher RA (i.e. more East) and higher Dec (i.e. more North). In the above
+example, the coadd3d file looks like the following:
+
+.. code-block:: ini
+
+    # User-defined execution parameters
+    [rdx]
+        spectrograph = keck_kcwi
+        detnum = 1
+    [reduce]
+        [[cube]]
+            combine = True
+            output_filename = BB1245p4238_datacube.fits
+            align = True
+
+    # Read in the data
+    spec2d read
+                               filename  |  ra_offset | dec_offset
+    Science/spec2d_scienceframe_01.fits  |  0.0       | 0.0
+    Science/spec2d_scienceframe_02.fits  |  1.0       | -1.0
+    spec2d end
 
 .. _coadd3d_datamodel:
 

pypeit/core/datacube.py

@@ -2154,8 +2154,11 @@ def coadd_cube(files, opts, spectrograph=None, parset=None, overwrite=False):
         if opts['ra_offset'] is not None:
             for ff in range(numfiles):
                 # Apply the shift
-                all_ra[all_idx == ff] += opts['ra_offset'][ff]
-                all_dec[all_idx == ff] += opts['dec_offset'][ff]
+                all_ra[all_idx == ff] += opts['ra_offset'][ff]/3600.0
+                all_dec[all_idx == ff] += opts['dec_offset'][ff]/3600.0
+                msgs.info("Spatial shift of cube #{0:d}: RA, DEC (arcsec) = {1:+0.3f}, {2:+0.3f}".format(ff + 1,
+                                                                                                         opts['ra_offset'][ff],
+                                                                                                         opts['dec_offset'][ff]))
         else:
             # Find the wavelength range where all frames overlap
             min_wl, max_wl = get_whitelight_range(np.max(mnmx_wv[:, :, 0]),  # The max blue wavelength

pypeit/par/pypeitpar.py

@@ -1397,7 +1397,9 @@ def __init__(self, slit_spec=None, relative_weights=None, align=None, combine=No
         dtypes['align'] = [bool]
         descr['align'] = 'If set to True, the input frames will be spatially aligned by cross-correlating the ' \
                          'whitelight images with either a reference image (see `reference_image`) or the whitelight ' \
-                         'image that is generated using the first spec2d listed in the coadd3d file.'
+                         'image that is generated using the first spec2d listed in the coadd3d file. Alternatively, ' \
+                         'the user can specify the offsets (i.e. Delta RA x cos(dec) and Delta Dec, both in arcsec) ' \
+                         'in the spec2d block of the coadd3d file. See the documentation for examples of this usage.'
 
         defaults['combine'] = False
         dtypes['combine'] = [bool]