Getting started

Installation

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

Install a pre-release/development version from source

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

Editable install (development)

python -m pip install -e .

If you already have the repository cloned, run the install command from the repo root.

Quick examples

Plot a LAMOST spectrum

from specbox import SpecLAMOST

spec = SpecLAMOST("input_file.fits")
spec.plot()

View a multi-row parquet table (SPARCL)

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

viewer = PGSpecPlotThreadEnhanced(
    spectra="sparcl_spectra.parquet",
    SpecClass=SpecSparcl,
    output_file="sparcl_vi_results.csv",
    z_max=6.0,
    load_history=True,
)
viewer.run()

CLI quick start

Viewer

specbox-viewer --spectra COMBINED_SPECS.fits --spec-class euclid

Notes:

If --output-file is omitted, viewer writes to vi_{input_file_name}_results.csv.
History is auto-loaded when that CSV already exists.
Images and cutout downloads are off by default; add --images to enable them.
Add --redshift-table PATH --redshift-key object_id --redshift-column Z to overlay a reference redshift table at startup without rewriting the source spectra.

For AIMS-z review bundles:

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

Notes:

aimsz-review reads parquet rows directly using wavelength, flux, ivar, and mask.
Session CSVs use canonical string IDs like aimsz:{object_id} to make history loading stable.
sparcl and aimsz-review plot raw spectra by default; use the Downsample toolbar toggle for native pyqtgraph downsampling.
Dual-arm Euclid parquet viewer mode pairs BGS/RGS rows by shared extname (or objid fallback), not by row index.
With an external redshift table, startup redshift precedence is z_vi > z_ref > z_temp > redshift.

Euclid coadd (BGS+RGS)

specbox-coadd \
  --rgs-file sz_ragn_dr1_rgs_chunk_001.fits \
  --bgs-file sz_ragn_dr1_bgs_chunk_001.fits \
  --output-prefix coadd/sz_ragn_dr1_coadd_chunk_001 \
  --pair-by extname_intersection

Raw Euclid FITS to parquet

specbox-euclid-parquet \
  --fits sz_ragn_dr1_rgs_chunk_001.fits \
  --output-prefix parquet/sz_ragn_dr1_rgs_chunk_001

View Euclid parquet

# Raw single-arm Euclid parquet
specbox-viewer --spectra parquet/sz_ragn_dr1_rgs_chunk_001_part001.parquet --spec-class euclid

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

Merge an external redshift table into parquet

specbox-merge-redshift-table \
  --spectra parquet/sz_ragn_dr1_rgs_chunk_001_part001.parquet \
  --redshift-table catalog.fits \
  --redshift-key object_id \
  --redshift-column Z \
  --output parquet/sz_ragn_dr1_rgs_chunk_001_part001_with_zref.parquet \
  --fill-z-vi

PCF redshift

# Default: Type 1 template only
specbox-pcf --fits coadd/sz_ragn_dr1_coadd_chunk_001.fits

# Type 1 + Type 2 (ragn_na; internally constrained to 0 < z < 3)
specbox-pcf --fits coadd/sz_ragn_dr1_coadd_chunk_001.fits --enable-type2

# ragn_dr1 only (as type1)
specbox-pcf --fits coadd/sz_ragn_dr1_coadd_chunk_001.fits --ragn-dr1-only