L1 product depth and stacking hierarchy
Describes version 2.0Table 1 distinguishes the Level-1 stacking depths.
The stacking level records which observations contribute to the input. The CPS can provide single-exposure products, observing block (OB)-level stacks, duplicate-OB superstacks and target-level supertargets. IFU data have the corresponding cube, cubelet and supercube/supercubelet hierarchy. A deeper product changes the number of contributing exposures, the spatial sampling and the exposure graph, while the APSOB interface keeps the downstream spectral representation stable.
| L1 level | Typical product families | What changes relative to the previous level | APS and L2 treatment |
|---|---|---|---|
| Single exposure | single; one calibrated arm per file |
One exposure, one arm/setup and its own calibration history | APSOB reads the fibre or cube layout, applies masks/calibration and joins available arms; L2 filename retains the single-input identity and primary headers reference each arm |
| OB stack | stack (MOS), stackcube (LIFU), stackcubelet (mIFU) |
Multiple singles from one OB are combined; inverse variance (IVAR), sky/cosmic-ray flags and metadata represent the stack | Same APSOB target/spaxel interface; classification and class-specific engines run once on the stack product; L2 stores the stack references and constituent history |
| Duplicate-OB superstack | superstack, supercube, supercubelet |
Multiple compatible OB-level products are combined, increasing depth while preserving a duplicate-OB lineage | APS processes the deepest compatible arm products selected by the controller; L2 preserves the superstack identity and all available L1 references; it is not a new observing mode |
| Target supertarget | 1-D MOS supertarget; LIFU/mIFU supertarget | Several observations of a target/field or bundle are combined, potentially with small spatial offsets; the product is target- or field-centred rather than a single OB | APSOB uses the same APSTARG/APSSPEC boundary, but patch/bundle/CNAME and provenance fields become essential; L2 naming uses the target identity and reserved supertarget index |
| Mixed-depth or mixed-level arms | e.g. superstack blue with stack red | The two arms can have different exposure depth, constituent counts and calibration dates | APS retains per-arm metadata, wavelength/IVAR differences and L1 references; Redrock’s multi-arm CPU patch prevents unequal valid-pixel/IVAR ranges from silently changing the coefficient solve; the mixed case is a separate validation stratum |
The controller’s preferred selection is the deepest compatible product available for the requested target and configuration (supertarget
superstack/ supercube
OB stack/cube
single), subject to arm coverage, resolution, binning and provenance constraints. This preference does not mean that APS silently co-adds arbitrary files: the selected L1 products are already CPS products, and APS records the exact inputs used. A MOS L2 product therefore contains classification, stellar and galaxy tables for the selected fibre rows; an IFU L2 product contains patch and bin products linked to the selected cube/cubelet and its source exposures. Empty class branches remain schema-defined empty products and are never replaced by a result from a different stacking level.
The implementation-level detector is deliberately simpler than this product hierarchy. aps_utils.stack_level scans the basename in an ordered mapping: single returns level 0, stack (and therefore names such as stackcube and stackcubelet) returns level 1, super returns level 3, and the wve_ prefix returns level 4. If none of these substrings is found, the initialized value is level 4. The order matters because wve_ is checked before super, and because this detector uses filenames. The operations layer stores this value as a processing field, while the L2 filename is formed from the controller’s headname and suffix. Run processing record retains both the input basenames and the header-derived product identity alongside the numeric stacking level used by the controller.