Background subtraction error propagation

.readthedocs.yaml

@@ -5,7 +5,7 @@ build:
   apt_packages:
     - graphviz
   tools:
-    python: "3.13"
+    python: "3.14"
 
 sphinx:
   builder: html

CHANGES.rst

@@ -6,6 +6,14 @@ New Features
 
 - Added uncertainty propagation to ``specreduce.extract.BoxcarExtract`` and
   ``specreduce.extract.HorneExtract``. The extracted spectra have now proper uncertainties.
+- Added uncertainty propagation to ``specreduce.background.Background``. The
+  ``bkg_image()``, ``bkg_spectrum()``, ``sub_image()``, and ``sub_spectrum()`` methods
+  now return spectra with proper uncertainties. When input image has uncertainty, it is
+  propagated using variance formulas appropriate for the chosen statistic. When no
+  uncertainty is provided, it is estimated from the flux values in the background region.
+- Added optional ``sigma`` parameter to ``specreduce.background.Background`` for sigma
+  clipping outlier rejection in background estimation. Default is 5.0; set to ``None``
+  to disable.
 
 Other changes
 ^^^^^^^^^^^^^

docs/background.rst

@@ -31,4 +31,41 @@ and the background-subtracted image via `~specreduce.background.Background.sub_i
 (or ``image - bg``).
 
 The background and trace steps can be done iteratively, to refine an automated
-trace using the background-subtracted image as input.
+trace using the background-subtracted image as input.
+
+Outlier rejection
+-----------------
+
+The background estimation supports sigma clipping for outlier rejection, which is useful
+for removing cosmic rays and other artifacts from the background region. The ``sigma``
+parameter controls the number of standard deviations used for clipping (default is 5.0).
+Set ``sigma=None`` to disable sigma clipping.
+
+.. code-block:: python
+
+  # Use tighter sigma clipping for aggressive outlier rejection
+  bg = Background.two_sided(image, trace, separation=5, width=4, sigma=3.0)
+
+  # Disable sigma clipping
+  bg = Background.two_sided(image, trace, separation=5, width=4, sigma=None)
+
+Uncertainty propagation
+-----------------------
+
+The `~specreduce.background.Background` class propagates uncertainties through
+background subtraction. When the input image is an `~astropy.nddata.NDData` object
+with ``image.uncertainty`` provided, the uncertainties are propagated using variance
+formulas appropriate for the chosen statistic (``average`` or ``median``). When no
+uncertainty is provided, it is estimated from the variance of flux values in the
+background region.
+
+The background image, background spectrum, and background-subtracted outputs all
+include proper uncertainties:
+
+.. code-block:: python
+
+  bg = Background.two_sided(image, trace, separation=5, width=4)
+
+  # Access background with uncertainty
+  bkg_spec = bg.bkg_spectrum()
+  print(bkg_spec.uncertainty)

docs/conf.py

@@ -207,6 +207,17 @@
 # ArrayLike from numpy.typing is not properly resolved by intersphinx
 nitpick_ignore = [
     ("py:class", "ArrayLike"),
+    ("py:class", "numpy._typing.ArrayLike"),
+    ("py:class", "specutils.spectra.spectrum1d.Spectrum1D"),
+]
+
+# Ignore complex type annotations that can't be cross-referenced
+# These come from autodoc processing dataclass fields with Literal, Union, and generic types
+nitpick_ignore_regex = [
+    (r"py:obj", r"typing\.Literal\[.*"),      # Literal types with string values
+    (r"py:class", r"tuple\[.*"),               # Generic tuple types
+    (r"py:class", r"None \| dict\[.*"),        # Union types with dict
+    (r"py:class", r"dict\[.*"),                # Generic dict types
 ]
 
 # -- Options for linkcheck output -------------------------------------------

docs/extraction.rst

@@ -44,6 +44,33 @@ flux is scaled according to the effective number of unmasked pixels. When using
 options (``filter`` or ``omit``), the non-finite values may be propagated or treated
 differently as documented in the API.
 
+Uncertainty propagation
+-----------------------
+
+Both `~specreduce.extract.BoxcarExtract` and `~specreduce.extract.HorneExtract`
+propagate uncertainties from the input image to the extracted 1D spectrum.
+
+For the input image, uncertainties can be provided in two ways:
+
+1. As part of an `~astropy.nddata.NDData` object via ``image.uncertainty``
+2. Via the ``variance`` parameter (for HorneExtract)
+
+The extracted spectrum includes the propagated uncertainty, which can be accessed via
+the ``uncertainty`` attribute:
+
+.. code-block:: python
+
+  extract = BoxcarExtract(image, trace, width=5)
+  spectrum = extract.spectrum
+  print(spectrum.uncertainty)
+
+For `~specreduce.extract.BoxcarExtract`, the uncertainty is propagated through the
+weighted sum over the extraction aperture. For `~specreduce.extract.HorneExtract`,
+the optimal extraction algorithm naturally produces properly weighted uncertainties.
+
+Calling the extraction methods
+------------------------------
+
 The previous examples in this section show how to initialize the BoxcarExtract
 or HorneExtract objects with their required parameters. To extract the 1D
 spectrum

environment-dev.yml

@@ -12,4 +12,8 @@ dependencies:
   - photutils
   - tox
   - sphinx-astropy
+  - sphinx-copybutton
+  - sphinx-design
+  - nbsphinx
+  - pydata-sphinx-theme
   - synphot