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

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.
• 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.

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()

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/.