From an input product to the executed modules

Table 12, Table 13 and Table 14 describe product routing, fallback criteria and IFU branch selection.

PyAPS first identifies product geometry and then determines the scientific route for each target. These decisions are independent: a cube can contain stars, galaxies and quasars, and a MOS observation can contain several of those classes at once.

Product recognition and first decision

The first decision is made from FITS headers and array dimensionality rather than from a filename. l1_fileinfo identifies the observing form, resolution, camera, binning and calibration metadata. A two-dimensional fibre-level product follows the MOS-like path, including legacy MOS-formatted IFU inputs. A three-dimensional LIFU or MIFU cube follows the IFU preparation path. Two arms may be supplied and joined where the selected module requires it; the standard IFU input is a pair of stacked Blue and Red cubes. A run that uses one arm or another non-standard input records that choice in its provenance.

Classification is a ranked routing operation

Rank retention, class inference and target filters

Redrock produces a ranked set of candidate solutions rather than only one number. Each retained rank carries a class, redshift, uncertainty, warning bits and fit information. The number of retained ranks is configurable; the IFU preparation baseline requests three, while lower-level MOS entry points can request a different ntop. A reproducible workflow must fix this value and store all retained ranks in the classification product.

The class used for routing is derived with an explicit metadata priority. If available, TARGCLASS is interpreted first; otherwise the code falls back to TARGPROG, then TARGSRVY. Keyword groups map these fields to the survey classes STAR, QSO or GALAXY. This inferred survey class is used both to interpret Redrock candidates and to decide which downstream worker should receive a target. A command-line targclass filter is a separate selection constraint: it limits which targets are processed and does not rewrite the measured spectrum.

Foreground-extinction preparation for Redrock

For configured Redrock runs, PyAPS can correct the target spectrum for Milky Way foreground extinction before classification. It obtains the line-of-sight
$E(B-V)$

from the SFD map (Schlegel, Finkbeiner & Davis, 1998) at each target’s coordinates and evaluates the wavelength-dependent transmission with the Fitzpatrick (1999) law at
$R_V=3.1$

through desiutil.dust. The flux is divided by the transmission and the inverse variance is multiplied by its square. This step follows the Level-1 sensitivity-function calibration and precedes the Redrock fit.

The correction is an opt-in classification preparation, not a change to the archived flux calibration. Its scale is configurable because SFD measures the total line-of-sight dust column, whereas a foreground Galactic star may lie within that column. In one 765-target GA-LRDISC observing block, full-SFD correction increased agreement with the stellar targeting class from 513 (67.1 per cent) to 660 targets (86.3 per cent); 165 targets changed to agreement and 18 changed to disagreement. Targeting metadata are not independent spectroscopic truth, so these fractions measure catalogue agreement, not classification accuracy. This result motivates the option but does not establish a universal setting for every survey and target class.

Target-class representation in the retained ranks

After the initial ranked table is formed, the classifier checks whether the requested target class is represented among the retained ranks. If, for example, the target metadata imply STAR but all three retained candidates are GALAXY/QSO, the code searches the full fit table for the best matching STAR candidate and replaces only the last retained slot when a valid candidate is available. The best two existing ranks are preserved. This makes ambiguity visible while ensuring that a requested class is not silently absent from the candidate set. If no matching rank exists, the table is left unchanged and the condition is recorded for review.

PCA-archetype fallback

The current Redrock integration can use both coarse/PCA and archetype fits. The coarse scan supplies a redshift/class reference over the search space; archetypes provide a more detailed coefficient representation. The archetype result is checked when it changes class relative to the coarse result, has a substantially worse
${\chi }^2$

ratio, or moves the best minimum in redshift within the same class. These triggers are qualified by fit quality and targeting metadata. In particular, an archetype class supported by TARGCLASS, TARGPROG or TARGSRVY is not discarded only because the coarse scan selected another class. A PCA reliability check determines whether the refined PCA redshift confirms the coarse solution. When fallback is triggered, PyAPS selects a same-class candidate near the trusted reference, swaps its fit information into the primary rank where appropriate, retains archetype coefficients when available, and writes APS-specific warning bits recording the reason. These warning bits show why the fallback was used and which solution was replaced.

When a replacement is made, the selected rank’s fit columns are exchanged with rank 0 and APS-specific history bits are re-applied while the native Redrock warning bits are preserved. The warning history distinguishes class mismatch, ratio, redshift-shift, swap-applied, no-valid-rank, PCA-unreliable and PCA-confirmed states, together with targeting corroboration, accepted archetype redshift improvement and second-tier BAD_MINFIT use. The fallback runs before top-rank retention; target-class representation is then checked in the retained set, and the metadata-derived survey class is added as an informational field. These bits make the decision observable in L2/quality control (QC).

MOS branch

For a MOS or stack product, APSOB creates one target object per selected fibre and the classifier table supplies the routing key. STAR and WD targets enter the RVS adapter, which builds a CCF initial velocity, constructs a wavelength-dependent resolution matrix from the target LSF, performs the full stellar template fit and writes RVS parameters and warning bits. FERRE then uses the RVS velocity when available, prepares linear spectra and error arrays, runs the configured external Fortran grids, merges grid outputs by fit quality and writes stellar atmospheric parameters. If an RVS velocity is unavailable, the wrapper first uses the retained Redrock velocity. It uses zero only when neither RVS nor Redrock provides a velocity, for example when a target reaches the Galactic branch through a TARGCLASS fallback after a classification mismatch. The selected source and any zero-velocity fallback remain visible in the provenance/QC record.

GALAXY and QSO targets enter the extragalactic MOS adapters. The common spectra are translated into the wavelength, inverse-variance and resolution contracts required by pPXF-based stellar kinematics, emission-line fitting and line-strength measurement. Redrock remains the classification/redshift input to this branch; pPXF remains the external scientific method, while EMIPPXF is PyAPS’s implementation of pPXF for WEAVE emission-line analysis. The final MOS merger combines whichever class-specific products were produced and leaves non-applicable fields empty according to the L2 schema.

IFU branch

Building the patch table

Before an IFU cube reaches pPXF or FERRE, the preparation stage collapses it to a white-light image, detects sources, fits elliptical apertures, optionally cross-matches Gaia and identifies contaminating stars or mask regions. It then co-adds each source aperture and runs Redrock on the aperture spectrum. The resulting patch table contains the source identifier, sky position, semi-axes and angle, row type (target, central object or mask), ranked
$Z$

,
$ZERR$

,
$ZWARN$

, CLASS and SUBCLASS values.

The raw targets.fits table is an intermediate decision product. The operator may review it and, when necessary, create targets_mod.fits: redshift, class, row type and mask regions can be corrected without changing the original detection output. Stage 2 workers read the modified table. The patch table therefore carries the source-detection and classification decisions into the spatial analysis.

Parallel class split

Once the patch is accepted, the automated workflow can launch the two IFU workers in parallel. The ExGal worker processes GALAXY and QSO rows; the Gal worker processes STAR and WD rows. Both depend on patch preparation but act on disjoint rows. A per-target exception is caught and logged so a failed source does not necessarily abort the rest of the patch. This is the principal point where a single spatially complex cube becomes multiple scientifically different processing products.

IFU ExGal path

For each valid GALAXY/QSO patch row, the ExGal preparation stage selects spaxels inside the elliptical aperture and applies mask regions from the same patch table. It assembles the APSOB cube, derives an adaptive minimum S/N cut, optionally applies a surface-brightness filter, and either spatially pre-bins the spaxels or sends them directly to adaptive Voronoi/PowerBin tessellation. The resulting bin spectra retain membership and coordinates. They are log-rebinned to constant velocity scale for pPXF, and the pPXF wavelength window is adapted to the target redshift and the actual clipped wavelength coverage. If the redshift-corrected window is too narrow, PyAPS records the reason and skips the affected fitting stage.

The ExGal branch then executes pPXF stellar kinematics, PyAPS’s EMIPPXF implementation of pPXF for WEAVE emission-line analysis, and line-strength measurement according to its switches. Its LSF is transformed to the rest frame, and spaxel-weighted curves are aggregated to bins; bounded LSF buckets limit repeated external template preparation. The patch table, bin table, binned spectra and analysis outputs are merged into an IFU L2 product with links back to the generating spaxels.

IFU Galactic path

For each STAR/WD patch row, the Gal worker uses the same spatial aperture and APSOB cube construction but keeps the wavelength grid in the observed frame. If a patch row lacks a redshift and class_patch=True, Redrock is rerun on that row’s aperture before fitting. Galactic preparation uses a stellar-specific adaptive S/N policy and deliberately disables the extended- source surface-brightness filter: valid low-S/N PSF-wing spaxels are not treated like low-surface-brightness galaxy outskirts. Larger spatial pre-binning may be used to produce fewer, higher-S/N bins. The saved spectra remain linearly sampled because the current PyAPS preparation and configuration for RVS and FERRE use linear wavelength spacing.

The Gal branch then runs RVS and FERRE on the accepted spatial bins, using per-bin or fallback LSF arrays and preserving the spatial bin membership in the resulting tables. The final IFU Galactic merger records stellar parameters and kinematics alongside the patch/bin identity. If an aperture is missing or empty, an S/N cut removes every spaxel, or a fit raises an exception, PyAPS records a failure for that target.

This product-to-module mapping describes the route followed by each input. Exact configuration values, external software versions, scheduler dependencies and release identity are stored in the run provenance.

Ambiguous and multi-class targets

One target, several ranked classes

Redrock¹ (Bolton et al., 2012; Guy et al., 2023; Anand et al., 2024) can return, for one APS_ID, a rank-0 STAR solution, a rank-1 GALAXY solution and a rank-2 QSO solution. These are competing hypotheses for the same spectrum. PyAPS retains the alternatives in the classification table. The Galactic and extragalactic selectors each inspect the first three CLASS and catalogue-informed SRVY_CLASS entries independently. A MOS target can therefore enter both branches when its retained hypotheses span STAR/WD and GALAXY/QSO, or when the catalogue class and measured ranking favour different families.

The catalogue-priority rules, same-class candidate search, PCA-archetype arbitration and warning filters are detailed in W5. They preserve competing interpretations and record fallback decisions before the two science branches select targets.

IFU ambiguity is resolved at the patch-row level

For an IFU cube, the source aperture is the unit of classification. A field may therefore contain STAR, WD, GALAXY and QSO rows simultaneously. The ExGal and Gal workers read the same edited patch table and process branch-specific rows. If one aperture has retained hypotheses in both class families, update_patch_table splits it into separate Gal and ExGal rows with their corresponding ranked redshift, error and warning fields. A contaminating source can be changed to a mask row (type M) so that its aperture is excluded from neighbouring targets; a central object (type C) can be skipped when extracted target rows already represent it. Manual edits are made in the modified patch table, preserving the raw detection table and the complete decision history.

Automation and expert review

Automatic behavior includes header-based product recognition, APSOB normalisation, rank retention, class-priority inference, configured fallback logic, class-based worker splitting and per-target exception capture. Expert review remains necessary when a redshift/classification is ambiguous, a patch aperture is wrong, a mask source is missed, or a fallback rate exceeds its accepted threshold. Stored ranks, fallback bits and edited patch tables preserve the complete decision path for that review.

---

1. https://github.com/desihub/redrock↩︎