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",
    load_history=True,
)
viewer.run()

For default SPARCL parquet tables, the scalar redshift column initializes both SpecSparcl.redshift and the viewer startup z_vi. If redshift is missing or non-finite, positive finite z_desi, z_sdss, z_ref, then z are used as fallbacks.

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 viewer mode pairs BGS/RGS rows by source ID union, not by row index; rows with only one arm still load with the missing arm marked unavailable.
Processed Euclid parquet startup uses z_vi > z_sdss > z_desi > z_hybrid > z_fusion > z_temp > z_pcf_best > z_gaia > z_phot; external z_ref values from --redshift-table remain an overlay.

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

Euclid parquet flux-like columns default to the raw archive scale of 1e-16 erg/s/cm^2/Angstrom. Add a scalar flux_scale column to override this for already-scaled processed files.

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

Development and releases

Package versions are derived from Git tags with setuptools-scm. Do not edit specbox.__version__ or hard-code a package version in pyproject.toml; the runtime __version__ comes from installed package metadata.

Release flow:

git tag v1.0.2
git push origin v1.0.2

Then publish a GitHub Release for that tag. PyPI upload is intentionally tied to the GitHub Release publication event, not to tag pushes.