API

The simplest way to extract spectrum is performing aperture extraction. While not robust, it can provide an initial guess of the spectrum. With stark, it is possible to do aperture extraction of spectrum using the following function.

stark.aperture_extract(frame, variance, ord_pos, ap_rad, uniform=False)[source]

Simple aperture extraction of the spectrum

Given the 2D frame of the data, and its variance, this function extracts spectrum by simply adding up values of pixels along slit.

Parameters:

frame (ndarray) – 2D data frame from which the spectrum is to be extracted
variance (ndarray) – The noise image of the same format as frame, specifying the variance of each pixel.
ord_pos (ndarray) – Array defining position of the trace
ap_rad (float) – Radius of the aperture around the order position
uniform (bool, optional) – Boolean on whether the slit is uniformally lit or not. If not then it will simply sum up counts in the aperture, else average the counts and multiply by slit-length. Default is False.

Returns:

spec (ndarray) – Array containing extracted spectrum for each order and each column.
var (ndarray) – Variance array for spec, the same shape as spec.

The main class of stark is SingleOrderPSF which has functionalities to read single order PSF data whether it is timeseries data or not. Users can first load the data using this class, and then use its different methods to fit a univariate or bivariate spline to it to estimate the stellar PSF. Details of this class and its methods are as below:

class stark.SingleOrderPSF(frame, variance, ord_pos, ap_rad, spec=None, mask=None)[source]

Given a data frame, its variance, order positions and aperture radius, this class generates a PSF frame for the data. The input data should be a 3D data cube with dimensions [nints, nrows, ncols], with variace array of the same shape. Optionally, a normalisation spectra and bad pixel map can be provided. This class works only for single order spectrum.

Example usage:

>>> data = stark.SingleOrderPSF(frame=data_frame, variance=data_variance, ord_pos=ord_pos, ap_rad=aperture_radius)
>>> psf_frame, psf_spline = data.univariate_psf_frame()

when fitting a univariate spline, as function of pixel coordinate, to the whole dataset, or,

>>> data = stark.SingleOrderPSF(frame=data_frame, variance=data_variance, ord_pos=ord_pos, ap_rad=aperture_radius)
>>> psf_frame, psf_spline = data.bivariate_psf_frame()

when fitting bivariate spline, as function of pixel coordinate and column number, to the whole dataset.

Here, psf_frame is resultant PSF frame and psf_spline is scipy.interpolate.LSQUnivariateSpline (or, scipy.interpolate.LSQBivariateSpline) object.

Parameters:

frame (ndarray) – 3D array containing data, [nints, nrows, ncols]
variance (ndarray) – 3D array as same size as frame containing variance of the data.
ord_pos (ndarray) – 2D array, with shape [nints, ncols] contaning pixel positions of order
ap_rad (float) – Aperture radius
spec (ndarray, optional) – 2D array, of [nints, ncols] size, providing normalisation spectrum.
mask (ndarray, optional) – 3D array containing mask, same shape as frame. Default is None.

bivariate_psf_frame(**kwargs)[source]

To generate PSF frame by fitting a bivariate spline to the whole dataset

Given a stark.SingleOrderPSF object, this function derives a single 2D PSF for whole data cube and use it to generate pixel-sampled PSFs for each column.

Parameters:

**kwargs – Additional keywords provided to fit_spline_bivariate function and to LSQBivariateSpline

Returns:

psf_frame (ndarray) – Data cube containing pixel-sampled PSF for each column
psf_spline (scipy.interpolate.LSQUnivariateSpline) – Fitted spline object

flux_coo()[source]

To produce pixel list with source coordinates

Given a 3D data cube, this function produces an array, stored as self.pix_array, with pixel coordinates (distace from order position), their flux, variances, column number and mask. Also generates a 3D array (self.col_array_pos) of size [nints, ncols, 3] to store positions of pixels in self.pix_array. E.g., if the data in self.pix_array from columns 100 to 300 are desired, those corresponds to indices self.col_array_pos[i,100,0] to `self.col_array_pos[i,300,0] for i-th integration in the self.pix_array. This information is to be used when producing PSFs. This function works for single order spectrum.

norm_flux_coo()[source]

Normalises the fluxes by summing up pixel values.

Given the self.pixel array and self.col_array_pos from self.flux_coo function, this function provides the normalized fluxes. If no normalisation spectrum is provided, the pixel sum is used.

table2frame(table)[source]: This helper function is to generate back 2D frames from pixel table in self.norm_array

univariate_multi_psf_frame(colrad=100, **kwargs)[source]

To generate PSF frame using fitting 1D-spline to a window of multiple columns around given column

To derive one PSF spline for each column, and uses it to generate the pixel-sampled PSF for each column.

Parameters:

colrad (int) – Radius of column window Default is 100
**kwargs – Additional keywords provided to fit_spline_univariate function and to LSQUniivariateSpline

univariate_psf_frame(**kwargs)[source]

To generate PSF frame by fitting univariate spline for the whole dataset

Given a stark.SingleOrderPSF object, this function derives a single PSF for whole data cube and use it to generate pixel-sampled PSFs for each column.

Parameters:

**kwargs – Additional keywords provided to fit_spline_univariate function and to LSQUnivariateSpline

Returns:

psf_frame (ndarray) – Data cube containing pixel-sampled PSF for each column
psf_spline (scipy.interpolate.LSQUnivariateSpline) – Fitted spline object

An optimal extraction of the stellar spectrum can be computed with a robust estimate of stellar PSF found from SingleOrderPSF class.

stark.optimal_extract(psf_frame, data, variance, mask, ord_pos, ap_rad)[source]

Use derived PSF frame (the psf sampled on the image) to extract the spectrum.

This function fits the derived PSF frame to the actual data to extract the spectrum and variance on it.

Parameters:

psf_frame (ndarray) – PSF frame with dimension [nrows, ncols]
data (ndarray) – 2D array containing data, [nrows, ncols]
variance (ndarray) – Variance on the data frame, same shape as the data array
mask (ndarray) – Array containing mask; only those points with value = True will be considered in extraction
ord_pos (ndarray) – 1D array, with length ncols, contaning pixel positions of order
ap_rad (float) – Radius of the aperture to consider

Returns:

spec (ndarray) – Extracted flux as a matrix with format [ncols]
var (ndarray) – Variance of each fluc point in the same format as spec.
synth (ndarray) – Synthetic image constructed using the flux and the PSF frame; useful for producing a residual image.