Spectrum¶

This module contains a few different routines for the manipulation of spectra.

Log lambda spacing¶

Throughout Starfish, we try to utilize log-lambda spaced spectra whenever possible. This is because this sampling preserves the Doppler content of the spectrum at the lowest possible sampling. A spectrum spaced linear in log lambda has equal-velocity pixels, meaning that

\[\frac{v}{c} = \frac{\Delta \lambda}{\lambda}\]

A log lambda spectrum is defined by the WCS keywords CDELT1, CRVAL1, and NAXIS1. They are related to the physical wavelengths by the following relationship

\[\lambda = 10^{{\rm CRVAL1} + {\rm CDELT1} \cdot i}\]

where \(i\) is the pixel index, with \(i = 0\) referring to the first pixel and \(i = ({\rm NAXIS1} - 1)\) referring to the last pixel.

The wavelength array and header keywords are often stored in a wl_dict dictionary, which looks like {"wl":wl, "CRVAL1":CRVAL1, "CDELT1":CDELT1, "NAXIS1":NAXIS1}.

These keywords are related to various wavelengths by

\[\frac{v}{c} = \frac{\Delta \lambda}{\lambda} = 10^{\rm CDELT1} - 1\]

\[{\rm CDELT1} = \log_{10} \left ( \frac{v}{c} + 1 \right )\]

\[{\rm CRVAL1} = \log_{10} ( \lambda_{\rm start})\]

Many spectral routines utilize a keyword dv, which stands for \(\Delta v\), or the velocity difference (measured in km/s) that corresponds to the width of one pixel.

\[\textrm{dv} = c \frac{\Delta \lambda}{\lambda}\]

When resampling wavelength grids that are not log-lambda spaced (e.g., the raw synthetic spectrum from the library) onto a log-lambda grid, the dv must be calculated. Generally, calculate_dv() works by measuring the velocity difference of every pixel and choosing the smallest, that way no spectral information will be lost.

Starfish.utils.calculate_dv(wave: Sequence)[source]¶

Given a wavelength array, calculate the minimum dv of the array.

Parameters: wave (array-like) – The wavelength array
Returns: delta-v in units of km/s
Return type: float

Starfish.utils.create_log_lam_grid(dv, start, end)[source]¶

Create a log lambda spaced grid with N_points equal to a power of 2 for ease of FFT.

Parameters

dv (float) – Upper bound on the velocity spacing in km/s
start (float) – starting wavelength (inclusive) in Angstrom
end (float) – ending wavelength (inclusive) in Angstrom

Returns

a wavelength dictionary containing the specified properties. Note that the returned dv will be less than or equal to the specified dv.

Return type

dict

Raises

ValueError – If starting wavelength is not less than ending wavelength
ValueError – If any of the wavelengths are less than 0

Starfish.utils.calculate_dv_dict(wave_dict)[source]¶

Given a wave_dict, calculate the velocity spacing.

Parameters: wave_dict (dict) – wavelength dictionary
Returns: delta-v in units of km/s
Return type: float

Order¶

We organize our data into orders which are the building blocks of Echelle spectra. Each order has its own wavelength, flux, optional flux error, and optional mask.

Note

Typically, you will not be creating orders directly, but rather will be using them as part of a Spectrum object.

The way you interact with orders is generally using the properties wave, flux, and sigma, which will automatically apply the order’s mask. If you want to reach the underlying arrays, say to create a new mask, use the appropriate _-prepended properties.

>>> order = Order(...)
>>> len(order)
3450
>>> new_mask = order.mask & (order._wave > 0.9e4) & (order._wave < 4.4e4)
>>> order.mask = new_mask
>>> len(order)
2752

API/Reference¶

class Starfish.spectrum.Order(_wave: nptyping.types._ndarray.NDArray, _flux: nptyping.types._ndarray.NDArray, _sigma: Optional[nptyping.types._ndarray.NDArray] = None, mask: Optional[nptyping.types._ndarray.NDArray] = None)[source]¶

A data class to hold astronomical spectra orders.

Parameters

_wave (numpy.ndarray) – The full wavelength array
_flux (numpy.ndarray) – The full flux array
_sigma (numpy.ndarray, optional) – The full sigma array. If None, will default to all 0s. Default is None
mask (numpy.ndarray, optional) – The full mask. If None, will default to all Trues. Default is None

name¶

Type: str

__len__()[source]¶

property flux¶

The masked flux array

Type: numpy.ndarray

mask: Optional[nptyping.types._ndarray.NDArray] = None¶

property sigma¶

The masked flux uncertainty array

Type: numpy.ndarray

property wave¶

The masked wavelength array

Type: numpy.ndarray

Spectrum¶

A Spectrum holds the many orders that make up your data. These orders, described by Order, are treated as rows in a two-dimensional array. We like to store these spectra in HDF5 files so we recommend creating a pre-processing method that may require any additional dependencies (e.g., IRAF) for getting your data into 2-d wavelength arrays calibrated to the same flux units as your spectral library models.

>>> waves, fluxes, sigmas = process_data("data.fits")
>>> data = Spectrum(waves, fluxes, sigmas, name="Data")
>>> data.save("data.hdf5")

Our HDF5 format is simple, with each dataset having shape (norders, npixels):

/
  waves
  fluxes
  sigmas
  masks

Whether you save your data to hdf5 or have an external process that saves into the same format above, you can then load the spectrum using

>>> data = Spectrum.load("data.hdf5")

When using HDF5 files, we highly recommended using a GUI program like HDF View to make it easer to see what’s going on.

To access the data, you can either access the full 2-d data arrays (which will have the appropriate mask applied) or iterate order-by-order

>>> data = Spectrum(...)
>>> len(data)
4
>>> data.waves.shape
(4, 2752)
>>> num_points = 0
>>> for order in data:
...   num_points += len(order)
>>> num_points == np.prod(data.shape)
True

API/Reference¶

class Starfish.spectrum.Spectrum(waves, fluxes, sigmas=None, masks=None, name='Spectrum')[source]¶

Object to store astronomical spectra.

Parameters

waves (1D or 2D array-like) – wavelength in Angtsrom
fluxes (1D or 2D array-like) – flux (in f_lam)
sigmas (1D or 2D array-like, optional) – Poisson noise (in f_lam). If not specified, will be zeros. Default is None
masks (1D or 2D array-like, optional) – Mask to blot out bad pixels or emission regions. Must be castable to boolean. If None, will create a mask of all True. Default is None
name (str, optional) – The name of this spectrum. Default is “Spectrum”

Note

If the waves, fluxes, and sigmas are provided as 1D arrays (say for a single order), they will be converted to 2D arrays with length 1 in the 0-axis.

Warning

For now, the Spectrum waves, fluxes, sigmas, and masks must be a rectangular grid. No ragged Echelle orders allowed.

name¶

The name of the spectrum

Type: str

__getitem__(index: int)[source]¶

__len__()[source]¶

__setitem__(index: int, order: Starfish.spectrum.Order)[source]¶

property fluxes¶

The 2 dimensional masked flux arrays

Type: numpy.ndarray

classmethod load(filename)[source]¶

Load a spectrum from an hdf5 file

Parameters: filename (str or path-like) – The path to the HDF5 file.