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 namesoffset
,camera
,science
,flat
andarc
, and creates one row for each keyword EXPIDnn, whereoffset
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 usingbossdata.plate.FrameFile
.The
plate
,mjd
andfiber
attributes specify the target observation. Theinfo
attribute contains this target’s row from spAll as a structured numpy array, so its metadata can be accessed asinfo['OBJTYPE']
, etc.Use
get_valid_data()
to access this target’s spectra, or theexposures
attribute for a list of exposures used in the coadd (seebossdata.plate.Plan
for alternative information about the exposures used in a coadd.) Thenum_exposures
attribute gives the number of science exposures used for this target’s co-added spectrum (counting a blue+red pair as one exposure). Useget_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 viabossdata.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
withivar
(inverse variance) in the returned data. - use_loglam – Replace
wavelength
withloglam
(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()
andPlateFile.get_valid_data()
methods provide afiducial_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 keywordCD1_1
(and sometimes alsoCOEFF1
). The value ofwavelength0
definesindex = 0
and is similarly encoded asCRVAL1
(and sometimes alsoCOEFF0
). 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 toindex = 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 andfiducial_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