specbox.basemodule

Package

class specbox.basemodule.ConvenientSpecMixin(wave=None, flux=None, err=None, wave_unit=None, flux_unit=None, *args, **kwargs)

Bases: object

A mixin class for convenient spectrum operations.

property flux_unit

property flux

property wave_unit

property wave

property err

property spec

trim(wave_range, plot=True, inplace=False)

Trim the spectrum to a given wavelength range.

Parameters:

• wave_range (tuple) – The wavelength range to trim the spectrum.

• plot (bool) – Plot the trimmed spectrum.

• inplace (bool) – If True, the spectrum is trimmed in place. If False, a new ConvenientSpecMixin object is created.

Returns:

The trimmed spectrum (self if inplace=True, otherwise a copy).

Return type:

ConvenientSpecMixin

flux_conserve_resample(wave, inplace=False)

smooth(window_length, polyorder, plot=True, inplace=False, sigclip=False, **kwargs)

Smooth the spectrum with scipy.signal.savgol_filter.

Parameters:

• window_length (int) – The length of the filter window (i.e., the number of coefficients). window_length must be a positive odd integer. If mode is 'interp', window_length must be less than or equal to the size of x.

• polyorder (int) – The order of the polynomial used to fit the samples. polyorder must be less than window_length.

• plot (bool) – Plot the smoothed spectrum.

• inplace (bool) – Replace the original spectrum with the smoothed one.

• sigclip (bool) – Sigma clip the smoothed spectrum.

• kwargs (dict) – Keyword arguments forwarded to scipy.signal.savgol_filter.

Returns:

The smoothed spectrum.

Return type:

ConvenientSpecMixin

plot(ax=None, **kwargs)

Plot the spectrum.

Parameters:

ax (matplotlib.axes.Axes) – The axes to plot on. If None, a new set of axes is created.

Returns:

The axes that were plotted on.

Return type:

matplotlib.axes.Axes

copy()

to_restframe(z=None, inplace=False)

Convert the spectrum to the rest-frame.

Parameters:

• z (float) – Redshift of the spectrum.

• inplace (bool) – If True, the spectrum is converted to the rest-frame in place. If False, only a new Spectrum object is created.

class specbox.basemodule.SpecIOMixin(*args, **kwargs)

Bases: object

Mixin class for reading and writing spectra.

read(filename, ext=0, **kwargs)

write(filename, **kwargs)

class specbox.basemodule.SpecPandasRow(filename: str | Path | None = None, *args, df: DataFrame | None = None, ext: int = 1, row: int | None = None, file_format: str | None = None, pandas_read_kwargs: Mapping[str, Any] | None = None, wave_col: str = 'wavelength', flux_col: str = 'flux', err_col: str | None = None, ivar_col: str | None = 'ivar', wave_unit: Unit | None = Unit('Angstrom'), flux_unit: Unit | None = Unit(dimensionless), meta_cols: Sequence[str] = (), array_cols: Mapping[str, str] = (), **kwargs)

Bases: ConvenientSpecMixin

Spectrum backed by a single row of a pandas DataFrame.

This class is meant for “table-of-spectra” files where each row stores arrays (e.g. wavelength/flux/ivar) plus scalar metadata (e.g. ra/dec/z).

Notes

• ext is treated as a 1-based row selector for compatibility with the FITS multi-extension viewer (which uses ext=index+1).

• Parquet reading requires either pyarrow or fastparquet installed.

classmethod count_in_file(filename: str | Path, *, file_format: str | None = None, pandas_read_kwargs: Mapping[str, Any] | None = None) → int

read(filename: str | Path | None = None, *, df: DataFrame | None = None, ext: int = 1, row: int | None = None, file_format: str | None = None, pandas_read_kwargs: Mapping[str, Any] | None = None, wave_col: str | None = None, flux_col: str | None = None, err_col: str | None = None, ivar_col: str | None = None, meta_cols: Sequence[str] | None = None, array_cols: Mapping[str, str] | None = None, **kwargs)

class specbox.basemodule.SpecSparcl(filename: str | Path | None = None, *args, df: DataFrame | None = None, ext: int = 1, row: int | None = None, file_format: str | None = None, pandas_read_kwargs: Mapping[str, ~typing.Any] | None=None, wave_unit: Unit | None = Unit("Angstrom"), flux_unit: Unit | None = <Quantity 1.e-17 erg / (Angstrom s cm2)>, **kwargs)

Bases: SpecPandasRow

Reader for SPARCL spectra stored as a dataframe (e.g. parquet).

The reference schema used by outlier_sparcl_spectra.parquet is: - arrays: wavelength, flux, ivar (+ optional mask, model) - scalars: ra, dec, redshift, specid, spectype, …

class specbox.basemodule.SpecAIMSZReview(filename: str | Path | None = None, *args, df: DataFrame | None = None, ext: int = 1, row: int | None = None, file_format: str | None = None, pandas_read_kwargs: Mapping[str, ~typing.Any] | None=None, wave_unit: Unit | None = Unit("Angstrom"), flux_unit: Unit | None = <Quantity 1.e-17 erg / (Angstrom s cm2)>, **kwargs)

Bases: SpecPandasRow

Reader for AIMS-z review parquet spectra.

Expected row schema: - arrays: wavelength, flux, ivar, mask - scalars: object_id, targetid, ra, dec, redshift,

spectype, data_release

• optional review context columns used by the viewer UI

REVIEW_CONTEXT_COLUMNS = ('review_priority_tier', 'review_score', 'review_rank_within_tier', 'review_slice_label', 'z_ref', 'z_ml_expect', 'z_pcf_best', 'pcf_template_best', 'pcf_score_best')

class specbox.basemodule.SpecEuclidCoaddRow(filename: str | Path | None = None, *args, df: DataFrame | None = None, ext: int = 1, row: int | None = None, file_format: str | None = None, pandas_read_kwargs: Mapping[str, Any] | None = None, wave_unit: Unit | None = Unit('Angstrom'), flux_unit: Unit | None = Unit('erg / (Angstrom s cm2)'), **kwargs)

Bases: SpecPandasRow

Reader for Euclid BGS+RGS coadd spectra stored in dataframe files.

Expected row schema: - arrays: wavelength, flux, err (optional: mask, arm) - scalars: objid, ra, dec, and merge diagnostics.

class specbox.basemodule.SpecSDSS(filename=None, redshift=None, *args, **kwargs)

Bases: SpecIOMixin, ConvenientSpecMixin

Class for SDSS spectra. :param filename: Name of the SDSS spectrum file. :type filename: str

read(filename, redshift=None, **kwargs)

Read the SDSS spectrum file. :param filename: Name of the SDSS spectrum file. :type filename: str

write(filename, **kwargs)

class specbox.basemodule.SpecIRAF(filename=None, redshift=None, *args, **kwargs)

Bases: ConvenientSpecMixin, SpecIOMixin

Class for reading IRAF spectra.

read(filename, **kwargs)

Read the spectrum. :param filename: Name of the file to read. :type filename: str :param ra: Right ascension of the object in degrees. :type ra: float :param dec: Declination of the object in degrees. :type dec: float :param telescope: Name of the telescope. Default is None. :type telescope: str :param side: Side (arm) of the spectrograph (e.g. blue, red). Default is None. :type side: str

trim(wave_range, plot=True, inplace=False)

Trim the spectrum to a given wavelength range.

Parameters:

• wave_range (tuple) – The wavelength range to trim the spectrum.

• plot (bool) – Plot the trimmed spectrum.

• inplace (bool) – If True, the spectrum is trimmed in place. If False, a new SpecIRAF object is created.

Returns:

The trimmed spectrum (self if inplace=True, otherwise a copy).

Return type:

SpecIRAF

class specbox.basemodule.SpecLAMOST(filename=None, flux_calibrated=False, redshift=None, *args, **kwargs)

Bases: ConvenientSpecMixin, SpecIOMixin

A class for LAMOST Low Resolution Spectral (LRS) data.

read(filename, **kwargs)

Read the data from a LAMOST LRS file. :param filename: Name of the file to read. :type filename: str

class specbox.basemodule.SpecEuclid1d(filename=None, ext=None, extname=None, clip=True, good_pixels_only=False, redshift=None, lrange=None, *args, **kwargs)

Bases: ConvenientSpecMixin, SpecIOMixin

Class for reading 1D spectra from Euclid. The datamodel of Q1 1D spectra is described in https://euclid.esac.esa.int/dr/q1/dpdd/sirdpd/dpcards/sir_combinedspectra.html.

classmethod count_in_file(filename)

read(filename, ext=None, extname=None, clip=True, good_pixels_only=False, lrange=None, **kwargs)

Read the Euclid 1D spectrum. :param filename: Name of the Euclid spectrum file. :type filename: str :param ext: Extension number of the spectrum. :type ext: int :param extname: Extension name of the spectrum. :type extname: str :param clip: If True, clip the spectrum to the useful range. :type clip: bool :param good_pixels_only: If True, keep only recommended pixels according to Euclid MASK flags.

Pixels are considered bad when MASK is odd or MASK >= 64.

Parameters:

lrange (str, optional) – Arm label used for clipping policy (e.g. 'BGS' or 'RGS'). If None, LRANGE is read from the HDU header.

read_parquet(filename, ext=None, extname=None, clip=True, good_pixels_only=False, lrange=None, **kwargs)

property z_vi

class specbox.basemodule.SpecEuclid1dDual(rgs: SpecEuclid1d | None = None, bgs: SpecEuclid1d | None = None, rgs_file: str | None = None, bgs_file: str | None = None, ext: int | None = None, extname: str | None = None, rgs_filename: str | None = None, bgs_filename: str | None = None, rgs_ext: int | None = None, bgs_ext: int | None = None, rgs_extname: str | None = None, bgs_extname: str | None = None, clip: bool = True, good_pixels_only: bool = False, redshift: float | None = None)

Bases: object

Container for paired Euclid 1D spectra (RGS + BGS).

This keeps SpecEuclid1d unchanged while enabling joint visualization and combined-arm analysis workflows.

plot_together(ax=None, stacked: bool = False, labels: bool = True)

Plot RGS and BGS together.

Parameters:

• ax (matplotlib.axes.Axes, optional) – Existing axes. If None, a new figure is created.

• stacked (bool, default False) – If True, plot in two stacked panels; otherwise overlay both arms.

• labels (bool, default True) – Add legend labels when True.

merge()

Build merged spectrum on RGS wavelength bins.

Returns:

Keys: wavelength, flux, err, mask, arm.

Return type:

dict

for_redshift()

Return arm arrays plus merged view for redshift measurements.

Module: basemodule

class specbox.basemodule.basemodule.ConvenientSpecMixin(wave=None, flux=None, err=None, wave_unit=None, flux_unit=None, *args, **kwargs)

Bases: object

A mixin class for convenient spectrum operations.

property flux_unit

property flux

property wave_unit

property wave

property err

property spec

trim(wave_range, plot=True, inplace=False)

Trim the spectrum to a given wavelength range.

Parameters:

• wave_range (tuple) – The wavelength range to trim the spectrum.

• plot (bool) – Plot the trimmed spectrum.

• inplace (bool) – If True, the spectrum is trimmed in place. If False, a new ConvenientSpecMixin object is created.

Returns:

The trimmed spectrum (self if inplace=True, otherwise a copy).

Return type:

ConvenientSpecMixin

flux_conserve_resample(wave, inplace=False)

smooth(window_length, polyorder, plot=True, inplace=False, sigclip=False, **kwargs)

Smooth the spectrum with scipy.signal.savgol_filter.

Parameters:

• window_length (int) – The length of the filter window (i.e., the number of coefficients). window_length must be a positive odd integer. If mode is 'interp', window_length must be less than or equal to the size of x.

• polyorder (int) – The order of the polynomial used to fit the samples. polyorder must be less than window_length.

• plot (bool) – Plot the smoothed spectrum.

• inplace (bool) – Replace the original spectrum with the smoothed one.

• sigclip (bool) – Sigma clip the smoothed spectrum.

• kwargs (dict) – Keyword arguments forwarded to scipy.signal.savgol_filter.

Returns:

The smoothed spectrum.

Return type:

ConvenientSpecMixin

plot(ax=None, **kwargs)

Plot the spectrum.

Parameters:

ax (matplotlib.axes.Axes) – The axes to plot on. If None, a new set of axes is created.

Returns:

The axes that were plotted on.

Return type:

matplotlib.axes.Axes

copy()

to_restframe(z=None, inplace=False)

Convert the spectrum to the rest-frame.

Parameters:

• z (float) – Redshift of the spectrum.

• inplace (bool) – If True, the spectrum is converted to the rest-frame in place. If False, only a new Spectrum object is created.

class specbox.basemodule.basemodule.SpecIOMixin(*args, **kwargs)

Bases: object

Mixin class for reading and writing spectra.

read(filename, ext=0, **kwargs)

write(filename, **kwargs)

class specbox.basemodule.basemodule.SpecPandasRow(filename: str | Path | None = None, *args, df: DataFrame | None = None, ext: int = 1, row: int | None = None, file_format: str | None = None, pandas_read_kwargs: Mapping[str, Any] | None = None, wave_col: str = 'wavelength', flux_col: str = 'flux', err_col: str | None = None, ivar_col: str | None = 'ivar', wave_unit: Unit | None = Unit('Angstrom'), flux_unit: Unit | None = Unit(dimensionless), meta_cols: Sequence[str] = (), array_cols: Mapping[str, str] = (), **kwargs)

Bases: ConvenientSpecMixin

Spectrum backed by a single row of a pandas DataFrame.

This class is meant for “table-of-spectra” files where each row stores arrays (e.g. wavelength/flux/ivar) plus scalar metadata (e.g. ra/dec/z).

Notes

• ext is treated as a 1-based row selector for compatibility with the FITS multi-extension viewer (which uses ext=index+1).

• Parquet reading requires either pyarrow or fastparquet installed.

classmethod count_in_file(filename: str | Path, *, file_format: str | None = None, pandas_read_kwargs: Mapping[str, Any] | None = None) → int

read(filename: str | Path | None = None, *, df: DataFrame | None = None, ext: int = 1, row: int | None = None, file_format: str | None = None, pandas_read_kwargs: Mapping[str, Any] | None = None, wave_col: str | None = None, flux_col: str | None = None, err_col: str | None = None, ivar_col: str | None = None, meta_cols: Sequence[str] | None = None, array_cols: Mapping[str, str] | None = None, **kwargs)

class specbox.basemodule.basemodule.SpecSparcl(filename: str | Path | None = None, *args, df: DataFrame | None = None, ext: int = 1, row: int | None = None, file_format: str | None = None, pandas_read_kwargs: Mapping[str, ~typing.Any] | None=None, wave_unit: Unit | None = Unit("Angstrom"), flux_unit: Unit | None = <Quantity 1.e-17 erg / (Angstrom s cm2)>, **kwargs)

Bases: SpecPandasRow

Reader for SPARCL spectra stored as a dataframe (e.g. parquet).

The reference schema used by outlier_sparcl_spectra.parquet is: - arrays: wavelength, flux, ivar (+ optional mask, model) - scalars: ra, dec, redshift, specid, spectype, …

class specbox.basemodule.basemodule.SpecAIMSZReview(filename: str | Path | None = None, *args, df: DataFrame | None = None, ext: int = 1, row: int | None = None, file_format: str | None = None, pandas_read_kwargs: Mapping[str, ~typing.Any] | None=None, wave_unit: Unit | None = Unit("Angstrom"), flux_unit: Unit | None = <Quantity 1.e-17 erg / (Angstrom s cm2)>, **kwargs)

Bases: SpecPandasRow

Reader for AIMS-z review parquet spectra.

Expected row schema: - arrays: wavelength, flux, ivar, mask - scalars: object_id, targetid, ra, dec, redshift,

spectype, data_release

• optional review context columns used by the viewer UI

REVIEW_CONTEXT_COLUMNS = ('review_priority_tier', 'review_score', 'review_rank_within_tier', 'review_slice_label', 'z_ref', 'z_ml_expect', 'z_pcf_best', 'pcf_template_best', 'pcf_score_best')

class specbox.basemodule.basemodule.SpecEuclidCoaddRow(filename: str | Path | None = None, *args, df: DataFrame | None = None, ext: int = 1, row: int | None = None, file_format: str | None = None, pandas_read_kwargs: Mapping[str, Any] | None = None, wave_unit: Unit | None = Unit('Angstrom'), flux_unit: Unit | None = Unit('erg / (Angstrom s cm2)'), **kwargs)

Bases: SpecPandasRow

Reader for Euclid BGS+RGS coadd spectra stored in dataframe files.

Expected row schema: - arrays: wavelength, flux, err (optional: mask, arm) - scalars: objid, ra, dec, and merge diagnostics.

class specbox.basemodule.basemodule.SpecSDSS(filename=None, redshift=None, *args, **kwargs)

Bases: SpecIOMixin, ConvenientSpecMixin

Class for SDSS spectra. :param filename: Name of the SDSS spectrum file. :type filename: str

read(filename, redshift=None, **kwargs)

Read the SDSS spectrum file. :param filename: Name of the SDSS spectrum file. :type filename: str

write(filename, **kwargs)

class specbox.basemodule.basemodule.SpecIRAF(filename=None, redshift=None, *args, **kwargs)

Bases: ConvenientSpecMixin, SpecIOMixin

Class for reading IRAF spectra.

read(filename, **kwargs)

Read the spectrum. :param filename: Name of the file to read. :type filename: str :param ra: Right ascension of the object in degrees. :type ra: float :param dec: Declination of the object in degrees. :type dec: float :param telescope: Name of the telescope. Default is None. :type telescope: str :param side: Side (arm) of the spectrograph (e.g. blue, red). Default is None. :type side: str

trim(wave_range, plot=True, inplace=False)

Trim the spectrum to a given wavelength range.

Parameters:

• wave_range (tuple) – The wavelength range to trim the spectrum.

• plot (bool) – Plot the trimmed spectrum.

• inplace (bool) – If True, the spectrum is trimmed in place. If False, a new SpecIRAF object is created.

Returns:

The trimmed spectrum (self if inplace=True, otherwise a copy).

Return type:

SpecIRAF

class specbox.basemodule.basemodule.SpecLAMOST(filename=None, flux_calibrated=False, redshift=None, *args, **kwargs)

Bases: ConvenientSpecMixin, SpecIOMixin

A class for LAMOST Low Resolution Spectral (LRS) data.

read(filename, **kwargs)

Read the data from a LAMOST LRS file. :param filename: Name of the file to read. :type filename: str

class specbox.basemodule.basemodule.DoubleSpec(spb=None, spr=None, spbfile=None, sprfile=None, varb=None, varr=None, instr=None)

Bases: object

combine(normalize_left=False, output=None, overwrite=True)

close()

class specbox.basemodule.basemodule.NIRSpecS3d(fname, redshift=None)

Bases: object

class specbox.basemodule.basemodule.SpecCoadd1d(filename=None, redshift=None, *args, **kwargs)

Bases: ConvenientSpecMixin, SpecIOMixin

Class for reading 1D coadded spectra generated by PypeIt.

read(filename, **kwargs)

write_to_iraf(w1=None, w2=None, dw=1.0, bad_wave_ranges=None)

specbox.basemodule.basemodule.fake_multispec_data(arrlist)

class specbox.basemodule.basemodule.SpecEuclid1d(filename=None, ext=None, extname=None, clip=True, good_pixels_only=False, redshift=None, lrange=None, *args, **kwargs)

Bases: ConvenientSpecMixin, SpecIOMixin

Class for reading 1D spectra from Euclid. The datamodel of Q1 1D spectra is described in https://euclid.esac.esa.int/dr/q1/dpdd/sirdpd/dpcards/sir_combinedspectra.html.

classmethod count_in_file(filename)

read(filename, ext=None, extname=None, clip=True, good_pixels_only=False, lrange=None, **kwargs)

Read the Euclid 1D spectrum. :param filename: Name of the Euclid spectrum file. :type filename: str :param ext: Extension number of the spectrum. :type ext: int :param extname: Extension name of the spectrum. :type extname: str :param clip: If True, clip the spectrum to the useful range. :type clip: bool :param good_pixels_only: If True, keep only recommended pixels according to Euclid MASK flags.

Pixels are considered bad when MASK is odd or MASK >= 64.

Parameters:

lrange (str, optional) – Arm label used for clipping policy (e.g. 'BGS' or 'RGS'). If None, LRANGE is read from the HDU header.

read_parquet(filename, ext=None, extname=None, clip=True, good_pixels_only=False, lrange=None, **kwargs)

property z_vi

class specbox.basemodule.basemodule.SpecEuclid1dDual(rgs: SpecEuclid1d | None = None, bgs: SpecEuclid1d | None = None, rgs_file: str | None = None, bgs_file: str | None = None, ext: int | None = None, extname: str | None = None, rgs_filename: str | None = None, bgs_filename: str | None = None, rgs_ext: int | None = None, bgs_ext: int | None = None, rgs_extname: str | None = None, bgs_extname: str | None = None, clip: bool = True, good_pixels_only: bool = False, redshift: float | None = None)

Bases: object

Container for paired Euclid 1D spectra (RGS + BGS).

This keeps SpecEuclid1d unchanged while enabling joint visualization and combined-arm analysis workflows.

plot_together(ax=None, stacked: bool = False, labels: bool = True)

Plot RGS and BGS together.

Parameters:

• ax (matplotlib.axes.Axes, optional) – Existing axes. If None, a new figure is created.

• stacked (bool, default False) – If True, plot in two stacked panels; otherwise overlay both arms.

• labels (bool, default True) – Add legend labels when True.

merge()

Build merged spectrum on RGS wavelength bins.

Returns:

Keys: wavelength, flux, err, mask, arm.

Return type:

dict

for_redshift()

Return arm arrays plus merged view for redshift measurements.