How To Use PyReduce¶

PyReduce offers two ways to run reductions: the command-line interface (CLI) and the Python API.

Image Coordinate Convention¶

PyReduce uses the convention that dispersion runs horizontally (along x-axis) and cross-dispersion runs vertically (along y-axis). The clipnflip() function rotates and flips raw images from each instrument to ensure this standard orientation.

This means:

Columns (x) = wavelength/dispersion direction
Rows (y) = spatial/cross-dispersion direction
Traces are polynomial functions of x, giving y-position
extraction_height is the extraction aperture size (fraction of order separation, or pixels if >1.5)

Mask Convention¶

PyReduce uses the numpy masked array convention for bad pixel masks:

1 = bad (masked/excluded)
0 = good (valid data)

This applies to:

Bad pixel mask files (mask_*.fits.gz)
The mask array passed between pipeline steps
Masks returned from extraction (indicating rejected pixels)

Command Line Interface¶

The CLI is the simplest way to run reductions. See CLI Reference for full details.

Quick start:

# Download sample data
uv run reduce download UVES

# Run full pipeline
uv run reduce run UVES -t HD132205 --steps bias,flat,trace,science

# Run individual steps
uv run reduce bias UVES -t HD132205
uv run reduce trace UVES -t HD132205

# List available steps
uv run reduce list-steps

Python API¶

The recommended Python entry point is Pipeline.from_instrument():

from pyreduce.pipeline import Pipeline

result = Pipeline.from_instrument(
    instrument="UVES",
    target="HD132205",
    night="2010-04-01",
    channel="middle",
    steps=("bias", "flat", "trace", "science"),
    plot=1,
).run()

This handles:

Loading the instrument configuration
Finding and sorting input files
Setting up output directories
Running the requested steps

For more control, construct a Pipeline manually:

from pyreduce.pipeline import Pipeline

pipe = Pipeline(
    instrument="UVES",
    output_dir="/data/reduced",
    channel="middle",
)
pipe.bias(bias_files)
pipe.flat(flat_files)
pipe.trace()
pipe.extract(science_files)
result = pipe.run()

Environment Variables¶

Variable	Description
`REDUCE_DATA`	Base data directory (default: `~/REDUCE_DATA`)
`PYREDUCE_PLOT`	Override plot level (0=off, 1=basic, 2=detailed)
`PYREDUCE_PLOT_DIR`	Save plots to directory as PNG files
`PYREDUCE_PLOT_SHOW`	Display mode: `block` (default), `defer`, or `off`
`PYREDUCE_PLOT_ANIMATION_SPEED`	Frame delay in seconds for extraction animation (default: 0.3)
`PYREDUCE_USE_CHARSLIT`	Use charslit extraction backend (default: 0)
`PYREDUCE_USE_DELTAS`	Enable slitdelta correction with charslit backend (default: 1)

Plot Modes¶

PyReduce supports three plot display modes via PYREDUCE_PLOT_SHOW:

Mode	Description
`block`	Show each plot interactively, blocking until closed (default)
`defer`	Accumulate all plots, show together at end of pipeline
`off`	Don’t display plots (useful with `PYREDUCE_PLOT_DIR` to save only)

Save and display are independent—you can save to files AND display:

# Save only (headless/CI)
PYREDUCE_PLOT=1 PYREDUCE_PLOT_DIR=/tmp/plots PYREDUCE_PLOT_SHOW=off uv run ...

# Show all at end (useful with webagg backend for browser viewing)
MPLBACKEND=webagg PYREDUCE_PLOT=1 PYREDUCE_PLOT_SHOW=defer uv run ...

# Save AND show all at end
PYREDUCE_PLOT=1 PYREDUCE_PLOT_DIR=/tmp/plots PYREDUCE_PLOT_SHOW=defer uv run ...

Note: Plot level 2 (interactive progress plots during extraction) only works with block mode.

Extraction Animation¶

When plot=2, extraction shows an animated progress plot with the current swath, slit function fit, and residuals. Interactive controls are available:

Pause/Resume button - pause animation to examine current state
Step button - advance one swath at a time (when paused)
Speed slider - adjust animation frame rate

Set PYREDUCE_PLOT_ANIMATION_SPEED to control the default frame delay (in seconds). A value of 0 shows swaths as fast as possible.

Pipeline Steps¶

Steps are run in dependency order. Available steps:

Step	Description
`bias`	Combine bias frames
`flat`	Combine flat frames
`trace`	Trace echelle orders on flat
`curvature`	Measure slit curvature
`scatter`	Model inter-order background
`norm_flat`	Normalize flat, extract blaze
`wavecal_master`	Extract wavelength calibration spectrum
`wavecal_init`	Initial line identification
`wavecal`	Refine wavelength solution
`freq_comb_master`	Extract frequency comb spectrum
`freq_comb`	Apply frequency comb calibration
`science`	Optimally extract science spectra
`continuum`	Normalize continuum
`finalize`	Write final output

Steps not explicitly requested but required as dependencies will be loaded from previous runs if available, or executed automatically.