Teareduce: Python for Educational Astronomy

• Teareduce is a Python tool for teaching astronomical image reduction with educational utilities and simple, modifiable APIs.
• It builds on Astropy and ccdproc to provide slice-aware indexing, interactive cosmic-ray removal, and adaptive spline fitting for calibration workflows.
• The package supports practical learning through Jupyter notebooks and real telescope data, emphasizing transparency over full pipeline automation.

Searching arXiv for the teareduce paper and closely related astronomy software references. Teareduce is a Python package developed to support teaching activities related to the reduction of astronomical data. It serves as instructional material for practical classes on the processing of astronomical images acquired with various instruments and telescopes, specifically within the course Experimental Techniques in Astrophysics in the Master’s Degree in Astrophysics at the Complutense University of Madrid. The package is publicly available on GitHub and is accompanied by a documentation site with Jupyter notebooks demonstrating its classes and functions. Its design is explicitly pedagogical rather than pipeline-oriented: it complements established libraries such as Astropy and ccdproc with narrowly scoped utilities that students can inspect, modify, and extend during practical classes (Cardiel et al., 28 Jan 2026).

1. Institutional setting and pedagogical role

Teareduce is embedded in the teaching workflow of the “Experimental Techniques in Astrophysics” (TEA) master’s course at the Universidad Complutense de Madrid. In that course, students prepare observing proposals, observe with the CAFOS instrument at the Calar Alto 2.2 m telescope, and then reduce images and spectra and analyze the results in practical classes. The package was created to support that practical component by supplying concrete utilities for operations that are not covered, or are less convenient, in more general packages (Cardiel et al., 28 Jan 2026).

The package’s pedagogical orientation is central to its identity. Its APIs and abstractions are intentionally simple enough to inspect, alter, and extend in a classroom setting. Interactive utilities make reduction steps visible and understandable, and alternative approaches are introduced where they are effective for instruction, such as adaptive spline fitting without predefined knot positions. This suggests that teareduce is best understood not as an attempt to replace professional astronomical software ecosystems, but as a didactic layer built around them.

2. Software stack, data model, and scope

Teareduce is built atop the mainstream scientific Python stack: Astropy provides FITS I/O, WCS handling, and CCDData containers; ccdproc provides CCD processing primitives such as bias, dark, and flat calibration operations; NumPy and SciPy provide array operations, optimization, and splines; and Matplotlib provides visualization (Cardiel et al., 28 Jan 2026).

Its workflows center on FITS images, and one of its explicit design choices is to address common pitfalls in FITS indexing and slicing by providing convention-aware slicing classes. The package integrates with Astropy CCDData objects and preserves headers and uncertainties where relevant. For WCS it relies on Astropy; photometric workflows are typically carried out with Astropy-affiliated packages such as Photutils alongside teareduce tools; plotting uses Matplotlib. In scope, teareduce is intentionally limited. It is not a full-featured, general-purpose reduction pipeline, is not optimized for large-scale high-throughput reductions, and does not attempt to provide comprehensive photometric or astrometric suites. Those functions remain the responsibility of Astropy-affiliated packages or other domain tools.

A common misconception is to treat teareduce as a self-sufficient reduction environment. The documented scope is narrower: it is a classroom-oriented package that supports specific operations, especially where transparency and modifiability are more important than completeness.

3. Core modules and algorithmic components

The package organizes its distinctive functionality around a small set of teaching-oriented classes and utilities (Cardiel et al., 28 Jan 2026).

Component	Purpose	Principal use
SliceRegion1D, SliceRegion2D, SliceRegion3D	Define slice regions in FITS or Python indexing conventions	Explicit sub-image extraction and indexing instruction
TeaWaveCalibration	Wavelength calibration and correction of “C-distortion” in 2D spectroscopic images	Interactive arc-line identification, peak detection, polynomial fitting
AdaptiveLSQUnivariateSpline	Smooth curve fitting without predefining knot locations	Background or continuum modeling
tea-cleanest	Interactive cosmic-ray detection and correction in single exposures	L.A. Cosmic-based masking with manual refinement
cr2images	Automatic cosmic-ray removal from two equivalent exposures	Pixel replacement using the paired exposure

The slicing classes are primarily pedagogical safeguards. SliceRegion1D, SliceRegion2D, and SliceRegion3D let students define regions in either FITS or Python indexing conventions and then access the equivalent representation in the other convention through .fits or .python. Their main value is to make indexing explicit and thereby reduce off-by-one and axis-ordering errors when extracting calibration regions, apertures, or areas to clean.

TeaWaveCalibration addresses 2D spectroscopic calibration. Its workflow includes interactive identification of arc lines, automatic detection of line peaks across all spectra in a 2D image, polynomial correction for C-distortion, and wavelength-solution fitting and application. The C-distortion correction is expressed as

$y' = y + \sum_{k=0}^{m} c_k x^k,$

and the wavelength solution as

$\lambda(x) = \sum_{k=0}^{n} a_k x^k,$

fit by least squares using identified arc-line centroids. In the classroom context, this combines visual interaction with automated propagation across the spatial dimension.

AdaptiveLSQUnivariateSpline is intended for smooth curve fitting when polynomials are insufficient and knot locations should not be predefined. It takes $x,y$ data together with the number of intermediate knots and smoothing or tolerance parameters, and returns a univariate spline fit whose knot positions are optimized by numerical minimization. The paper describes it as based on an adaptive least-squares strategy and cites Cardiel 2009 as background.

Cosmic-ray treatment is split between interactive and automatic modes. tea-cleanest is an auxiliary interactive program for single exposures. It uses L.A. Cosmic to flag suspicious pixels, then allows manual selection or deselection of pixels to be interpolated; the corrected image marks both interpolated pixels and interpolation neighbors. cr2images instead assumes two equivalent aligned exposures and replaces cosmic-ray pixels in one exposure with the signal from the other, with user-defined inclusive or exclusive regions controlling where cleaning is performed. Additional algorithms—PyCosmic, deepCR, and Cosmic-CoNN—are being incorporated.

4. Reduction workflows taught with teareduce

Teareduce is used together with Astropy, ccdproc, and affiliated packages to cover the canonical reduction workflow presented in class (Cardiel et al., 28 Jan 2026). The package is purposefully scoped, so these workflows combine teareduce-specific utilities with standard CCD-reduction operations.

Bias correction is introduced through construction of a master bias, for example

$B_{\mathrm{master}} = \mathrm{median}(B_i),$

followed by subtraction from the raw frame. Dark correction is taught via scaled master dark frames,

$$D_{\mathrm{master},t} = \left(\frac{t}{t_0}\right) D_{\mathrm{master},t_0},$$

which are then subtracted from the bias-corrected image. Flat-fielding proceeds by normalizing the flat,

$F_{\mathrm{norm}} = \frac{F}{\langle F \rangle},$

and dividing the image by the normalized flat.

Bad-pixel masks and cosmic-ray rejection are discussed both conceptually and operationally. Masks can be created via thresholding, known defect maps, or detection algorithms. Cosmic-ray detection includes sigma-clipping on local residuals or Laplacian edge detection through L.A. Cosmic; teareduce contributes tea-cleanest for interactive cleaning and cr2images for two-exposure replacement. Combination statistics for master-frame construction and stacking include the mean,

$\bar{x} = \frac{1}{N}\sum_i x_i,$

the median, and the sigma-clipped mean.

Sky-background estimation and subtraction are taught using robust sigma-clipping in annuli or global background regions, as well as 1D or 2D spline fitting; AdaptiveLSQUnivariateSpline is specifically noted as useful for modeling smooth backgrounds without fixed knots. Image alignment and stacking are typically handled through WCS alignment or feature-based registration using Astropy APIs, while teareduce remains focused on complementary tasks.

The package is also situated within a broader framework of uncertainty propagation. A typical variance model in electrons is presented as

$$\sigma^2 = \frac{S}{g} + N_{\mathrm{pix}}\,\sigma_{\mathrm{read}}^2 + \frac{B}{g} + \frac{D\,t}{g},$$

with signal-to-noise ratio

$$\mathrm{SNR} = \frac{S}{\sqrt{S + N_{\mathrm{pix}}\left(B + D\,t + \sigma_{\mathrm{read}}^2\right)}}.$$

In practice, students are shown how Astropy CCDData supports uncertainty arrays and how subtraction and division propagate uncertainties.

For photometric calibration, the teaching context introduces instrumental magnitudes,

$$m_{\mathrm{inst}} = -2.5\log_{10}\!\left(\frac{F}{t_{\mathrm{exp}}}\right),$$

and the transformation to standard magnitudes,

$\lambda(x) = \sum_{k=0}^{n} a_k x^k,$0

where $\lambda(x) = \sum_{k=0}^{n} a_k x^k,$1 is the zero point, $\lambda(x) = \sum_{k=0}^{n} a_k x^k,$2 the extinction coefficient, $\lambda(x) = \sum_{k=0}^{n} a_k x^k,$3 the airmass, and $\lambda(x) = \sum_{k=0}^{n} a_k x^k,$4 the color term. Teareduce does not itself perform photometry; aperture photometry is typically done with packages such as Photutils. Likewise, astrometric calibration and plate solutions are handled via Astropy WCS, with teareduce supporting upstream preparation such as slicing, calibration setup, and cosmic-ray cleaning.

5. Documentation, notebooks, and classroom use

The documentation site hosts Jupyter notebooks that demonstrate teareduce’s classes and functions in practical contexts. The documented notebook topics include introduction to the package and its role in the TEA course; image slicing with SliceRegion1D/2D/3D; wavelength calibration and C-distortion correction with TeaWaveCalibration; adaptive spline fitting with AdaptiveLSQUnivariateSpline; and cosmic-ray cleaning with both tea-cleanest and cr2images (Cardiel et al., 28 Jan 2026).

These notebooks are intended to produce three explicit learning outcomes: understanding each calibration step and its mathematical or algorithmic underpinning; developing practical skills in inspecting, modifying, and validating reduction code; and gaining familiarity with tools and conventions used in professional astronomical data reduction, especially FITS, WCS, and CCDData. In that sense, the notebooks are not merely usage examples. They are an instructional interface to reduction methodology itself.

The package is used in TEA practicals in which students reduce real CAFOS observations. The figures described in the paper reinforce that practical framing: the Calar Alto 2.2 m telescope and CAFOS, students working in the control room, the stepwise TeaWaveCalibration workflow, and the detection and correction sequence in tea-cleanest. A plausible implication is that teareduce’s principal validation is pedagogical and operational rather than benchmark-driven: its success is measured by whether students can execute and understand real reductions.

6. Limitations, comparisons, and future development

Teareduce is explicitly defined against the alternative of relying solely on Astropy and ccdproc. Its rationale is that it adds instructional utilities not present in ccdproc, including convention-aware slicing classes, interactive cosmic-ray cleaning, adaptive knots in spline fitting, and specific C-distortion workflows for long-slit 2D spectra. It simplifies abstractions for classroom clarity and encourages exploration through code inspection and modification (Cardiel et al., 28 Jan 2026).

At the same time, the package’s limitations are clearly stated. It is not a full-featured, general-purpose pipeline. Its examples and classroom use emphasize CAFOS data from Calar Alto, although the utilities are generic in the sense that they are FITS- and CCDData-based. Performance is adequate for classroom use rather than large-scale reduction campaigns. End-to-end reduction of all modalities, as well as comprehensive photometric and astrometric suites, are missing by design and are expected to be handled elsewhere. The paper does not specify a license and directs readers to the GitHub repository for licensing details.

Its closest software relationships are complementary rather than competitive. Astropy and ccdproc provide foundational FITS, CCD, and WCS functionality; Photutils and SEP are commonly used for photometry and source extraction; existing cosmic-ray tools such as L.A. Cosmic, PyCosmic, deepCR, and Cosmic-CoNN provide algorithmic foundations or external methods that teareduce wraps or integrates into interactive, didactic workflows. This suggests that teareduce occupies a narrow but distinctive niche: it is an educational augmentation layer within the broader Python astronomy ecosystem.

The roadmap described in the paper is correspondingly incremental. Future work includes incorporation of additional cosmic-ray detection methods beyond L.A. Cosmic—specifically PyCosmic, deepCR, and Cosmic-CoNN—continued development of teaching utilities addressing gaps in existing packages, and expansion of notebooks and examples to cover more instruments and scenarios as course needs evolve.