specbox

A simple tool to manipulate and visualize UV/optical/NIR spectra for astronomical research.

Documentation

Online documentation is hosted on Read the Docs: https://specbox.readthedocs.io/en/latest/index.html

Citation

@software{fu_2026_18642758,
  author       = {Fu, Yuming},
  title        = {specbox: a simple tool to manipulate and visualize UV/optical/NIR spectra for astronomical research},
  month        = feb,
  year         = 2026,
  publisher    = {Zenodo},
  version      = {v1.0.0},
  doi          = {10.5281/zenodo.18642758},
  url          = {https://doi.org/10.5281/zenodo.18642758}
}

License

GPLv3. See LICENSE.

Installation

Dependencies

• numpy
• scipy
• astropy
• pyqtgraph
• PySide6
• specutils
• matplotlib
• pandas
• pyarrow or fastparquet (optional, for reading parquet spectra tables)
• requests
• pillow (PIL)
• astroquery

It is recommended to set up an isolated environment before installing (choose either option A or B):

# Option A: Python venv
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip

# Option B: conda
conda create -n specbox python=3.13 -y
conda activate specbox
python -m pip install --upgrade pip

Install the stable release from PyPI (recommended):

python -m pip install specbox

To install a pre-release/development version from source:

git clone https://github.com/rudolffu/specbox.git  
cd specbox
python -m pip install .

Usage

Command-line tools

specbox installs three CLIs:

• specbox-viewer: launch the enhanced viewer
• specbox-coadd: coadd Euclid BGS+RGS chunks
• specbox-euclid-parquet: convert raw single-arm Euclid combined FITS to parquet
• specbox-pcf: run template PCF redshift and write Z_TEMP

# Viewer (history auto-loads when output CSV already exists)
specbox-viewer --spectra your_spectra.fits --spec-class euclid

# Viewer without image panel or cutout downloads
specbox-viewer --spectra your_spectra.fits --spec-class euclid --no-images

# Coadd paired Euclid arms (default: EXTNAME intersection)
specbox-coadd --rgs-file rgs_chunk.fits --bgs-file bgs_chunk.fits --output-prefix coadd/out_chunk_001

# Convert raw single-arm Euclid FITS to parquet
specbox-euclid-parquet --fits rgs_chunk.fits --output-prefix parquet/rgs_chunk_001

# PCF default: Type 1 only
specbox-pcf --fits coadd/out_chunk_001.fits

# PCF with Type 1 + Type 2 (ragn_na, internally limited to 0 < z < 3)
specbox-pcf --fits coadd/out_chunk_001.fits --enable-type2

# PCF with ragn_dr1 only (mapped to type1)
specbox-pcf --fits coadd/out_chunk_001.fits --ragn-dr1-only

Main classes and functions

The main classes and functions of specbox are:

basemodule.py:

• SpecLAMOST and SpecSDSS: classes to read and manipulate spectra from the LAMOST and SDSS surveys, respectively.
• SpecIRAF: class to read and manipulate spectra from the IRAF format.
• SpecEuclid1d: reader for Euclid combined 1D spectra, with MASK/good_mask support and optional good_pixels_only=True.
• SpecEuclid1dDual: paired Euclid reader for BGS+RGS with overlap scaling and merged/coadd-ready outputs.
• SpecEuclidCoaddRow: reader for dataframe/parquet rows containing coadded spectra arrays.
• SpecPandasRow: generic reader for "table-of-spectra" files readable by pandas (parquet/csv/feather/...), where each row stores arrays (e.g. wavelength/flux/ivar).
• SpecSparcl: SPARCL parquet/table reader (e.g., for file sparcl_spectra.parquet). Common metadata columns include data_release, targetid, and (optional) euclid_object_id for Euclid overlay.
• SpecAimszReview: AIMS-z review-bundle reader for review_bundle_specbox.parquet, including review metadata such as object_id, review_priority_tier, z_ref, z_ml_expect, and z_pcf_best.

qtmodule.py:

• PGSpecPlot: class to plot spectra in a pyqtgraph plot.
• PGSpecPlotApp: class to create a pyqtgraph plot with a QApplication instance.
• PGSpecPlotThread: class to create a pyqtgraph plot in a thread.

Examples

Plotting a spectrum from the LAMOST survey

from specbox import SpecLAMOST

spec = SpecLAMOST('input_file.fits')
spec.plot()
# Smooth the spectrum
spec.smooth(5, 3, inplace=False)

Reading a SPARCL parquet spectra table (one row per spectrum)

from specbox.basemodule import SpecSparcl

# ext is a 1-based row index (ext=1 -> first row)
sp1 = SpecSparcl("sparcl_spectra.parquet", ext=1)
sp1.plot()

Reading raw Euclid spectra from parquet rows

from specbox.basemodule import SpecEuclid1d

sp = SpecEuclid1d("sz_ragn_dr1_rgs_chunk_001_part001.parquet", ext=1)
sp.plot()

Run the viewer on Euclid coadd parquet

specbox-viewer \
  --spectra coadd/sz_ragn_dr1_coadd_chunk_001_part001.parquet \
  --spec-class euclid-coadd

Add --no-images when cutouts are unavailable or should be skipped entirely.

Run a PGSpecPlotThread for visual inspection of a list of spectra

from specbox import SpecLAMOST
from specbox.qtmodule import PGSpecPlotThread
from glob import glob

basepath = 'lamost_spec/fits_files/'
flist = glob(basepath+'*fits.gz')
flist.sort()
flist = flist[0:60]

a = PGSpecPlotThread(speclist=flist, SpecClass=SpecLAMOST, output_file='vi_output_test60.csv')
a.run()

Run a viewer over a multi-row parquet file (SPARCL/table-of-spectra)

from specbox.basemodule import SpecSparcl
from specbox.qtmodule import PGSpecPlotThreadEnhanced

viewer = PGSpecPlotThreadEnhanced(
    spectra="sparcl_spectra.parquet",
    SpecClass=SpecSparcl,
    # Optional: overlay Euclid spectrum when the parquet has `euclid_object_id`
    # and the Euclid combined FITS uses that ID as `EXTNAME`.
    euclid_fits="COMBINED_EUCLID_SPECS.fits",
    output_file="sparcl_vi_results.csv",
    z_max=6.0,
    load_history=True,
)
viewer.run()

Notes:

• Results CSV includes targetid and data_release (when available from the input table).
• The enhanced viewer has a Save PNG button that writes screenshots to ./saved_pngs/.

Review an AIMS-z bundle parquet

specbox-viewer \
  --spectra review_bundle_specbox.parquet \
  --spec-class aimsz-review

aimsz-review uses the same row-wise parquet transport style as SpecSparcl, but adds review context in the info panel and writes a reviewer-facing CSV with:

• object_id
• objid
• objname
• targetid
• ra
• dec
• data_release
• class_vi
• z_vi
• qa_flag
• notes

Canonical stored class_vi values in review mode are:

• QSO_DEFAULT
• QSO
• QSO_NARROW
• QSO_BAL
• LIKELY_Q
• GALAXY
• STAR
• UNKNOWN
• BAD

Legacy labels such as QSO(Default), QSO(narrow), QSO(Narrow), QSO(BAL), and LIKELY are accepted on load and normalized automatically.