1D Wavelength Calibration and 2D tilt correction

CHANGES.rst

@@ -6,6 +6,9 @@ New Features
 
 - Added a ``disp_bounds`` argument to ``tracing.FitTrace``. The argument allows for adjusting the
   dispersion-axis window from which the trace peaks are estimated.
+- Added a new ``specreduce.wavecal1d.WavelengthCalibration1D`` class for one-dimensional wavelength
+  calibration. The old ``specreduce.wavelength_calibration.WavelengthCalibration1D`` is
+  deprecated and will be removed in v. 2.0.
 
 1.6.0 (2025-06-18)
 ------------------

docs/api.rst

@@ -21,6 +21,9 @@ API Index
 .. automodapi:: specreduce.extract
     :no-inheritance-diagram:
 
+.. automodapi:: specreduce.wavecal1d
+    :no-inheritance-diagram:
+
 .. automodapi:: specreduce.calibration_data
     :no-inheritance-diagram:
     :include-all-objects:

docs/conf.py

@@ -156,6 +156,7 @@
 man_pages = [('index', project.lower(), project + u' Documentation',
               [author], 1)]
 
+extensions.append('nbsphinx')
 
 # -- Options for the edit_on_github extension ---------------------------------
 

docs/index.rst

@@ -50,7 +50,8 @@ Calibration
 .. toctree::
     :maxdepth: 1
 
-    wavelength_calibration.rst
+    tilt_correction/tilt_correction.rst
+    wavelength_calibration/wavelength_calibration.rst
     extinction.rst
     specphot_standards.rst
     mask_treatment/mask_treatment.rst

docs/tilt_correction/common.py

@@ -0,0 +1,19 @@
+from pathlib import Path
+
+from astropy import units as u
+from astropy.io import fits as pf
+from astropy.nddata import CCDData, VarianceUncertainty
+
+
+def read_file(fname, bias):
+    d = pf.getdata(fname).astype('d')
+    return CCDData(d - bias, unit=u.dn, uncertainty=VarianceUncertainty(d))
+
+
+def read_data():
+    bias = pf.getdata('gtc_osiris_example/osiris_bias.fits.bz2').astype('d')
+    obj = read_file('gtc_osiris_example/osiris_tres_3b.fits.bz2', bias)
+    lamps = 'HgAr', 'Ne', 'Xe'
+    arc_files = sorted(Path('gtc_osiris_example').glob('*arc*'))
+    arcs = [read_file(f, bias) for f in arc_files]
+    return arcs, lamps, obj

docs/tilt_correction/tilt_correction.rst

@@ -0,0 +1,40 @@
+Tilt Correction
+===============
+
+In astronomical spectroscopy, tilt correction is a calibration step that addresses optical
+distortions and misalignments in spectroscopic instruments. These distortions cause wavelength
+to vary along the cross-dispersion (spatial) axis, resulting in spectral features appearing
+tilted or curved across the detector rather than being perfectly aligned with detector columns.
+
+Tilt correction is performed by modeling a two-dimensional tilt function that describes how
+wavelength positions shift across the spatial axis. This function can be determined empirically
+from arc lamp calibration spectra by measuring how the centroids of emission lines vary along
+the cross-dispersion axis.
+
+Once characterized, the tilt function enables transformation of two-dimensional spectroscopic
+images so that wavelengths become aligned along straight lines parallel to the detector axes (a
+process known as 2D rectification). This alignment is essential for achieving accurate
+wavelength calibration and performing robust sky subtraction.
+
+In the `specreduce` package, the tilt function is represented as a 2D polynomial using an
+``~astropy.modeling.models.Polynomial2D`` instance of a specified degree. The
+``~specreduce.tilt_correction.TiltCorrection`` class implements this correction through several
+steps:
+
+1. Identifying emission lines in one or more arc lamp calibration spectra for a given number of
+   cross-dispersion sample positions
+2. Fitting a 2D polynomial model to characterize the geometric distortion
+3. Computing a transformation that maps the tilted features to straight lines
+4. Applying this transformation to rectify the observed frames
+
+
+Tutorials
+---------
+
+The following tutorial provides hands-on examples demonstrating the usage of the
+``~specreduce.tilt_correction.TiltCorrection`` class.
+
+.. toctree::
+   :maxdepth: 1
+
+   osiris_example.ipynb