bossdata.plate module

Access BOSS plate data products.

class bossdata.plate.FrameFile(path, index=None, calibrated=None)

Bases: object

A BOSS frame file containing a single exposure of one spectrograph (half plate).

This class supports both types of frame data files: the uncalibrated spFrame and the calibrated spCFrame. Use get_valid_data() to access this plate’s data and the plug_map attribute to access this plate’s plug map.

BOSS spectrographs read out 500 fibers each. SDSS-I/II spectrographs (plate < 3510) read out 320 fibers each. The plate, camera and exposure_id attributes provide the basic metadata for this exposure. The complete HDU0 header is available as the header attribute.

This class is only intended for reading the BOSS frame 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 frame FITS file to use. This should normally be obtained via Plan.get_exposure_name() 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.
• index (int) – Identifies if this is the first (1) or second (2) spectrograph, which determines whether it has spectra for fibers 1-500 (1-320) or 501-1000 (321-640). You should normally obtain this value using Plan.get_spectrograph_index(). As of v0.2.7, this argument is optional and will be inferred from the file header when not provided, or checked against the file header when provided.
• calibrated (bool) – Identifies whether this is a calibrated (spCFrame) or un-calibrated (spFrame) frame file. As of v0.2.7, this argument is optional and will be inferred from the file header when not provided, or checked against the file header when provided.

get_fiber_offsets(fiber)

Convert fiber numbers to array offsets.

Parameters:fibers (numpy.ndarray) – Numpy array of fiber numbers 1-1000 (or 1-640 for plate < 3510). All fibers must be in the appropriate range 1-500 (1-320) or 501-1000 (321-640) for this frame’s spectograph. Fibers do not need to be sorted and repetitions are ok. Returns:Numpy array of offsets 0-499 (or 0-319 for plate < 3510). Return type:numpy.ndarray Raises:ValueError – Fiber number is out of the valid range for this spectrograph.

get_pixel_masks(fibers)

Get the pixel masks for specified fibers.

The entire mask is returned for each fiber, including any pixels with zero inverse variance.

Parameters:fibers (numpy.ndarray) – Numpy array of fiber numbers 1-1000 (or 1-640 for plate < 3510). All fibers must be in the appropriate range 1-500 (1-320) or 501-1000 (321-640) for this frame’s spectograph. Fibers do not need to be sorted and repetitions are ok. Returns:Integer numpy array of shape (nfibers,npixels) where (i,j) encodes the mask bits defined in bossdata.bits.SPPIXMASK (see also http://www.sdss3.org/dr10/algorithms/bitmask_sppixmask.php) for pixel-j of the fiber with index fibers[i]. Return type:numpy.ndarray

get_valid_data(fibers, pixel_quality_mask=None, include_wdisp=False, include_sky=False, use_ivar=False, use_loglam=False)

Get the valid for the specified fibers.

Parameters:

• fibers (numpy.ndarray) – Numpy array of fiber numbers 1-1000 (or 1-640 for plate < 3510). All fibers must be in the appropriate range 1-500 (1-320) or 501-1000 (321-640) for this frame’s spectograph. Fibers do not need to be sorted and repetitions are ok.
• 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.
• 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.

Returns:

Masked array of shape (nfibers,npixels). Pixels with no valid data are included but masked. The record for each pixel has at least the following named fields: wavelength in Angstroms, flux and dflux in 1e-17 ergs/s/cm2/Angstrom. 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

class bossdata.plate.Plan(path)

Bases: object

The plan file for configuring the BOSS pipeline to combine exposures of a single plate.

Combined plan files are small text files that list the per-spectrograph (b1,b2,r1,r2) exposures used as input to a single coadd. Use the exposure_table attribute to access this information. Note that bossdata.spec.SpecFile has a similar exposures attribute which only includes exposures actually used in the final co-add, so is generally a subset of the planned exposures.

Parameters:path (str) – The local path to a plan file.

get_exposure_name(sequence_number, band, fiber, ftype='spCFrame')

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. Note that this method returns None when the requested exposure is not present in the plan, so the return value should always be checked.

Parameters:

• sequence_number (int) – Science exposure sequence number, counting from zero. Must be less than our num_science_exposures attribute.
• fiber (int) – Fiber number to identify which spectrograph to use, which must be in the range 1-1000 (or 1-640 for plate < 3510).
• 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. Returns None if the name is unknown for this band and fiber combination.

Return type:

str

Raises:

ValueError – one of the inputs is invalid.

get_spectrograph_index(fiber)

Get the spectrograph index 1,2 for the specified fiber.

Parameters:fiber (int) – Fiber number to identify which spectrograph to use, which must be in the range 1-1000 (or 1-640 for plate < 3510). Returns:Value of 1 if fiber is read out by the first spectrograph 1-500 (1-320), or else 2 for the second spectrograph. Return type:int Raises:ValueError – fiber is outside the allowed range 1-1000 (1-640) for this plate.

class bossdata.plate.PlateFile(path)

Bases: object

A BOSS plate file containing combined exposures for a whole plate.

This class provides an interface to the spPlate data product, containing all co-added spectra for a single observation. To instead read individual co-added spectra, use bossdata.spec.SpecFile. To access individual exposures of a half-plate use FrameFile.

Use get_valid_data() to access this plate’s data, or the exposures attribute for a list of exposures used in the 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). The plug_map attribute records this plate’s plug map.

This class is only intended for reading the BOSS plate 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 plate FITS file to use. This should normally be obtained via bossdata.path.Finder.get_plate_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_fiber_offsets(fiber)

Convert fiber numbers to array offsets.

Parameters:fibers (numpy.ndarray) – Numpy array of fiber numbers 1-1000 (or 1-640 for plate < 3510). Fibers do not need to be sorted and repetitions are ok. Returns:Numpy array of offsets 0-999. Return type:numpy.ndarray Raises:ValueError – Fiber number is out of the valid range for this plate.

get_pixel_masks(fibers)

Get the pixel masks for specified fibers.

The entire mask is returned for each fiber, including any pixels with zero inverse variance. Returns the ‘and_mask’ and ignores the ‘or_mask’.

Parameters:fibers (numpy.ndarray) – Numpy array of fiber numbers 1-1000 (or 1-640 for plate < 3510). Fibers do not need to be sorted and repetitions are ok. Returns:Integer numpy array of shape (nfibers,npixels) where (i,j) encodes the mask bits defined in bossdata.bits.SPPIXMASK (see also http://www.sdss3.org/dr10/algorithms/bitmask_sppixmask.php) for pixel-j of the fiber with index fibers[i]. Return type:numpy.ndarray

get_valid_data(fibers, pixel_quality_mask=None, include_wdisp=False, include_sky=False, use_ivar=False, use_loglam=False, fiducial_grid=False)

Get the valid for the specified fibers.

Parameters:

• fibers (numpy.ndarray) – Numpy array of fiber numbers 1-1000 (or 1-640 for plate < 3510). Fibers do not need to be sorted and repetitions are ok.
• 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. 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 shape (nfibers,npixels). 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

class bossdata.plate.TraceSet(hdu)

Bases: object

A set of interpolating functions along each trace of a half plate.

TraceSets use the terminology that x is the pixel coordinate along the nominal wavelength direction and y is some quantity to be interpolated as a function of x. This implementation is based on the original SDSS IDL code: https://trac.sdss3.org/browser/repo/idlutils/trunk/pro/trace/traceset2xy.pro

Note that red and blue CCDs are handled differently, as described here:

The plan is to switch from 1-phase to 2-phase readout on
the red CCDs in summer 2010. This will effectively make
the pixels more uniform, and the flat-fields much better.

A problem introduced will be that the central two rows will
each be taller by 1/6 pix. That will flat-field, but there
will be a discontinuity of 1/3 pix across this point.
Technically, the PSF will also be different for those pixels,
and the resulting resolution function.

Parameters:hdu – fitsio HDU containing the trace set data as a binary table. Raises:ValueError – Unable to initialize a trace set with this HDU.

get_y(xpos=None, ignore_jump=False)

Evaluate the interpolating function for each trace.

Parameters:

• xpos (numpy.ndarray) – Numpy array of shape (ntrace,nx) with x-pixel coordinates along each trace where y(x) should be evaluated. For BOSS, ntrace = 500 and for SDSS-I/II (plate < 3510), ntrace = 320. The value of ntrace is available as self.ntrace. If this argument is not set, self.default_xpos will be used, which consists of num_fibers identical traces with x-pixel coordinates at each integer pixel value covering the full allowed range.
• ignore_jump (bool) – Include a jump when this is set and this is a 2-phase readout. There is probably no good reason to set this False, but it is included for compatibility with the original IDL code.

Returns:

Numpy array y with shape (ntrace,nx) that matches the input xpos or else the default self.default_xpos. ypos[[i,x]] gives the value of the interpolated y(x) with x equal to xpos[[i,x]].

Return type:

numpy.ndarray

bossdata.plate.get_num_fibers(plate)

Return the number of fiber holes for a given plate number.

Plate numbers 3510 or larger are (e)BOSS plates with 1000 fibers. Smaller plate numbers are assumed to be SDSS-I/II with 640 fibers.

Parameters:plate (int) – Plate number. Returns:The value 640 or 1000. Return type:int