bossdata.spec module

Access spectroscopic data for a single BOSS target.

class bossdata.spec.Exposures(header)[source]

Bases: object

Table of exposure info extracted from FITS header keywords.

Parse the NEXP and EXPIDnn keywords that are present in the header of HDU0 in spPlate and spec FITS files.

The constructor initializes the table attribute with column names offset, camera, science, flat and arc, and creates one row for each keyword EXPIDnn, where offset equals the keyword sequence number nn, camera is one of b1, b2, r1, r2, and the remaining columns record the science and calibration exposure numbers.

Use get_info() to retrieve the n-th exposure for a particular camera (b1, b2, r1, r2). Note that when this class is initialized from a spec file header, it will only describe the two cameras of a single spectrograph (b1+r1 or b2+r2). The num_by_camera attribute is a dictionary of ints indexed by camera that records the number of science exposures available for that camera.

Parameters:header (dict) – dictionary of FITS header keyword, value pairs.

Returns:

get_info(exposure_index, camera)[source]

Get information about a single camera exposure.

Parameters:
  • exposure_index (int) – The sequence number for the requested camera exposure, in the range 0 - (num_exposures[camera]-1).
  • camera (str) – One of b1,b2,r1,r2.
Returns:

A structured array with information about the requested exposure, corresponding to one row of our table attribute.

Raises:
  • ValueError – Invalid exposure_index or camera.
  • RuntimeError – Exposure not present.
class bossdata.spec.SpecFile(path)[source]

Bases: object

A BOSS spec file containing summary data for a single target.

A spec file contains co-added spectra for a single target of an observation. This class supports the full version described in the data model as well as a lite version that does not contain the per-exposure HDUs with indices >= 4. Use the lite attribute to detect which version an object represents.

To read all co-added spectra of an observation use bossdata.plate.PlateFile. Individual exposures of a half-plate can be read using bossdata.plate.FrameFile.

The plate, mjd and fiber attributes specify the target observation. The info attribute contains this target’s row from spAll as a structured numpy array, so its metadata can be accessed as info['OBJTYPE'], etc.

Use get_valid_data() to access this target’s spectra, or the exposures attribute for a list of exposures used in the coadd (see bossdata.plate.Plan for alternative information about the exposures used in a coadd.) The num_exposures attribute gives the number of science exposures used for this target’s co-added spectrum (counting a blue+red pair as one exposure). Use get_exposure_name() to locate files associated the individual exposures used for this co-added spectrum.

This class is only intended for reading the BOSS spec file format, so generic operations on spectroscopic data (redshifting, resampling, etc) are intentionally not included here, but are instead provided in the speclite package.

Parameters:path (str) – Local path of the spec FITS file to use. This should normally be obtained via bossdata.path.Finder.get_spec_path() and can be automatically mirrored via bossdata.remote.Manager.get() or using the bossfetch script. The file is opened in read-only mode so you do not need write privileges.
get_exposure_hdu(exposure_index, camera)[source]

Lookup the HDU for one exposure.

This method will not work on “lite” files, which do not include individual exposures.

Parameters:
  • exposure_index (int) – Individual exposure to use, specified as a sequence number starting from zero, for the first exposure, and increasing up to self.num_exposures-1.
  • camera (str) – Which camera to use. Must be one of b1,b2,r1,r2.
Returns:

The HDU containing data for the requested exposure.

Return type:

hdu

Raises:

RuntimeError – individual exposures not available in lite file.

get_exposure_name(sequence_number, band, ftype='spCFrame')[source]

Get the file name of a single science exposure data product.

Use the exposure name to locate FITS data files associated with individual exposures. The supported file types are: spCFrame, spFrame, spFluxcalib and spFluxcorr. This method is analogous to bossdata.plate.Plan.get_exposure_name(), but operates for a single target and only knows about exposures actually used in the final co-add.

Parameters:
  • sequence_number (int) – Science exposure sequence number, counting from zero. Must be less than our num_exposures attribute.
  • band (str) – Must be ‘blue’ or ‘red’.
  • ftype (str) – Type of exposure file whose name to return. Must be one of spCFrame, spFrame, spFluxcalib, spFluxcorr. An spCFrame is assumed to be uncompressed, and all other files are assumed to be compressed.
Returns:

Exposure name of the form [ftype]-[cc]-[eeeeeeee].[ext] where [cc] identifies the spectrograph (one of b1,r1,b2,r2) and [eeeeeeee] is the zero-padded exposure number. The extension [ext] is “fits” for spCFrame files and “fits.gz” for all other file types.

Return type:

str

Raises:

ValueError – one of the inputs is invalid.

get_pixel_mask(exposure_index=None, camera=None)[source]

Get the pixel mask for a specified exposure or the combined coadd.

Returns the and_mask for coadded spectra. The entire mask is returned, including any pixels with zero inverse variance.

Parameters:
  • exposure_index (int) – Individual exposure to use, specified as a sequence number starting from zero, for the first exposure, and increasing up to self.num_exposures-1. Uses the co-added spectrum when the value is None.
  • camera (str) – Which camera to use. Must be either ‘b1’, ‘b2’ (blue) or ‘r1’, ‘r2’ (red) unless exposure_index is None, in which case this argument is ignored.
Returns:

Array of integers, one per pixel, encoding the mask bits defined in bossdata.bits.SPPIXMASK (see also http://www.sdss3.org/dr10/algorithms/bitmask_sppixmask.php).

Return type:

numpy.ndarray

get_valid_data(exposure_index=None, camera=None, pixel_quality_mask=None, include_wdisp=False, include_sky=False, use_ivar=False, use_loglam=False, fiducial_grid=False)[source]

Get the valid data for a specified exposure or the combined coadd.

You will probably find yourself using this idiom often:

data = spec.get_valid_data(...)
wlen,flux,dflux = data['wavelength'][:],data['flux'][:],data['dflux'][:]
Parameters:
  • exposure_index (int) – Individual exposure to use, specified as a sequence number starting from zero, for the first exposure, and increasing up to self.num_exposures-1. Uses the co-added spectrum when the value is None.
  • camera (str) – Which camera to use. Must be either ‘b1’, ‘b2’ (blue) or ‘r1’, ‘r2’ (red) unless exposure_index is None, in which case this argument is ignored.
  • pixel_quality_mask (int) – An integer value interpreted as a bit pattern using the bits defined in bossdata.bits.SPPIXMASK (see also http://www.sdss3.org/dr10/algorithms/bitmask_sppixmask.php). Any bits set in this mask are considered harmless and the corresponding spectrum pixels are assumed to contain valid data. When accessing the coadded spectrum, this mask is applied to the AND of the masks for each individual exposure. No mask is applied if this value is None.
  • include_wdisp – Include a wavelength dispersion column in the returned data.
  • include_sky – Include a sky flux column in the returned data.
  • use_ivar – Replace dflux with ivar (inverse variance) in the returned data.
  • use_loglam – Replace wavelength with loglam (log10(wavelength)) in the returned data.
  • fiducial_grid – Return co-added data using the fiducial wavelength grid. If False, the returned array uses the native grid of the SpecFile, which generally trims pixels on both ends that have zero inverse variance. Set this value True to ensure that all co-added spectra use aligned wavelength grids when this matters.
Returns:

Masked array of per-pixel records. Pixels with no valid data are included but masked. The record for each pixel has at least the following named fields: wavelength in Angstroms (or loglam), flux and dflux in 1e-17 ergs/s/cm2/Angstrom (or flux and ivar). Wavelength values are strictly increasing and dflux is calculated as ivar**-0.5 for pixels with valid data. Optional fields are wdisp in constant-log10-lambda pixels and sky in 1e-17 ergs/s/cm2/Angstrom. The wavelength (or loglam) field is never masked and all other fields are masked when ivar is zero or a pipeline flag is set (and not allowed by pixel_quality_mask).

Return type:

numpy.ma.MaskedArray

Raises:
  • ValueError – fiducial grid is not supported for individual exposures.
  • RuntimeError – co-added wavelength grid is not aligned with the fiducial grid.
bossdata.spec.fiducial_loglam[source]

Array of fiducial log10(wavelength in Angstroms) covering all spectra.

Lookup the log10(wavelength) or wavelength corresponding to a particular integral pixel index using:

>>> fiducial_loglam[100]
3.554100305027835
>>> 10**fiducial_loglam[100]
3581.7915291606305

The bounding wavelengths of this range are:

>>> 10**fiducial_loglam[[0,-1]]
array([  3500.26      ,  10568.18251472])

The SpecFile.get_valid_data() and PlateFile.get_valid_data() methods provide a fiducial_grid option that returns data using this grid.

bossdata.spec.fiducial_pixel_index_range = (0, 4800)

Range of fiducial pixel indices that covers all spectra.

Use get_fiducial_pixel_index() to calculate fiducial pixel indices.

bossdata.spec.get_fiducial_pixel_index(wavelength)[source]

Convert a wavelength to a fiducial pixel index.

The fiducial wavelength grid used by all SDSS co-added spectra is logarithmically spaced:

wavelength = wavelength0 * 10**(coef * index)

The value coef = 1e-4 is encoded in the FITS HDU headers of SDSS coadded data files with the keyword CD1_1 (and sometimes also COEFF1). The value of wavelength0 defines index = 0 and is similarly encoded as CRVAL1 (and sometimes also COEFF0). However, its value is not constant between different SDSS co-added spectra because varying amounts of invalid data are trimmed. This function adopts the constant value 3500.26 Angstrom corresponding to index = 0:

>>> get_fiducial_pixel_index(3500.26)
0.0

Note that the return value is a float so that wavelengths not on the fiducial grid can be converted and detected:

>>> get_fiducial_pixel_index(3500.5)
0.29776960129179741

The calculation is automatically broadcast over an input wavelength array:

>>> wlen = np.arange(4000,4400,100)
>>> get_fiducial_pixel_index(wlen)
array([ 579.596863  ,  686.83551692,  791.4898537 ,  893.68150552])

Use fiducial_pixel_index_range for an index range that covers all SDSS spectra and fiducial_loglam to covert integer indices to wavelengths.

Parameters:wavelength (float) – Input wavelength in Angstroms.
Returns:Array of floating-point indices relative to the fiducial wavelength grid.
Return type:numpy.ndarray