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, mask_updated = 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, mask_updated = 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.LSQBivariateSpline) – Fitted spline object

  • mask (ndarray, in the same format as self.norm_flux_coo[:,4]) – Mask that includes pixels that are marked as outlier by sigma clipping perfored while fitting the spline

flux_coo()[source]

To produce pixel list / pixel table 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.

Generates the normalised pixel table with 0th, 1st, 2nd, 3rd and 4th columns containing data of pixel coordinate (distance from the trace), flux, variance, column number and (bad-pixel) mask.

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

Returns:

  • psf_frame (ndarray) – Data cube containing pixel-sampled PSF for each column

  • psf_spline (A list containing scipy.interpolate.LSQUnivariateSpline objects) – Fitted spline objects, one object per column

  • mask (ndarray, in the same format as self.norm_flux_coo[:,4]) – Mask that includes pixels that are marked as outlier by sigma clipping perfored while fitting the spline

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

  • mask (ndarray, in the same format as self.norm_flux_coo[:,4]) – Mask that includes pixels that are marked as outlier by sigma clipping perfored while fitting the spline

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.

The three methods to estimate PSF used by the SingleOrderPSF class, in turn, uses the following functions to fit splines to the data:

stark.fit_spline_univariate(pixel_sorted, oversample=1, clip=5, niters=3, verbose=True, **kwargs)[source]

Fit a Univariate spline to pixel arrays

Given a normalized sorted pixel array (in the same form as output from norm_flux_coo) this function fit univariate spline as a function of pixel coordinates.

Parameters:

  • pixel_sorted (ndarray) – Normalized pixel array with pixel coordinates, normalized flux, normalized variance, and column indices; sorted according to pixel coordinates

  • oversample (int, optional) – Determines the number of knots in pixel coordindates direction. Default number of knots is equal to total pixel numbers in aperture (corresponds to oversample`=1). If `oversample is greater than 1, it will put oversamples*total pixel number knots in pixel coordinate direction.

  • clip (int, optinal) – Number of sigmas to perform sigma clipping while fitting a spline. Default is 5.

  • niter (int, optional) – Number of iteration to perform Default is 3.

  • verbose (bool, optional) – Boolean on whether to print details or not. Default is True.

  • **kwargs – Additional keywords provided to LSQUnivariateSpline

Returns:

  • psf_spline (scipy.interpolate.LSQUnivariateSpline object) – Fitted spline object.

  • mask (ndarray) – Array containing location of masked points.

stark.fit_spline_bivariate(pixel_array, oversample=1, knot_col=10, clip=5, niters=3, verbose=True, **kwargs)[source]

Fit a Bivariate spline to pixel arrays

Given a normalized pixel array (in the same form as output from norm_flux_coo) this function fit bi-variate spline as a function of pixel coordinates and column indices.

Parameters:

  • pixel_array (ndarray) – Normalized pixel array with pixel coordinates, normalized flux, normalized variance, and column indices.

  • oversample (int, optional) – Determines the number of knots in pixel coordindates direction. Default number of knots is equal to total pixel numbers in aperture (corresponds to oversample`=1). If `oversample is greater than 1, it will put oversamples*total pixel number knots in pixel coordinate direction.

  • knot_col (int, optional) – Number of knots in column indices direction. Default is 10.

  • clip (int, optinal) – Number of sigmas to perform sigma clipping while fitting a spline. Default is 5.

  • niter (int, optional) – Number of iteration to perform Default is 3.

  • verbose (bool, optional) – Boolean on whether to print details or not. Default is True.

  • **kwargs – Additional keywords provided to LSQBivariateSpline

Returns:

  • psf_spline (scipy.interpolate.LSQBivariateSpline object) – Fitted spline object.

  • mask (ndarray) – Array containing location of masked points.

Apart from spectral extraction, stark also provides tools for background subtraction and tracing the spectrum:

stark.reduce.col_by_col_bkg_sub(frame, mask)[source]

To perform column by column background subtraction

Given a frame and a mask on source, this function perform background subtraction at column level. The subtracted background is median of unmasked data.

The original version of this function was written for jwebbinars: https://github.com/spacetelescope/jwebbinar_prep/blob/main/tso_session/ExploringTSOProducts.ipynb

Parameters:

  • frame (ndarray) – 2D data frame of the data with shape [nrows, ncols]

  • mask (ndarray) – Mask array with the same size as frame. Only points with 1 will be considered to estimate background.

Returns:

  • corrected_image (ndarray) – Background corrected image.

  • sub_bkg (ndarray) – Array containing subtracted background from each column

stark.reduce.polynomial_bkg_cols(frame, mask, deg, sigma=5)[source]

To fit a polynomial background subtraction along columns

Given a frame, mask and degree of polynomial, this function fits a polynomial with specified degree to the unmasked background along columns.

Parameters:

  • frame (ndarray) – 2D data frame of the data with shape [nrows, ncols]

  • mask (ndarray) – Mask array with the same size as frame. Only points with 1 will be considered to estimate background.

  • deg (int) – Degree of the polynomial

  • sigma (int) – sigma clipping threshold for polynomial fitting Default is 5, use None in case of no sigma clipping

Returns:

  • corrected_image (ndarray) – Background corrected image

  • subtracted_bkg (ndarray) – Subtracted background, same shape as corrected_image

stark.reduce.polynomial_bkg_rows(frame, mask, deg, sigma=5)[source]

To fit a polynomial background subtraction along rows

Given a frame, mask and degree of polynomial, this function fits a polynomial with specified degree to the unmasked background along rows.

Parameters:

  • frame (ndarray) – 2D data frame of the data with shape [nrows, ncols]

  • mask (ndarray) – Mask array with the same size as frame. Only points with 1 will be considered to estimate background.

  • deg (int) – Degree of the polynomial

  • sigma (int) – sigma clipping threshold for polynomial fitting Default is 5, use None in case of no sigma clipping

Returns:

  • corrected_image (ndarray) – Background corrected image

  • subtracted_bkg (ndarray) – Subtracted background, same shape as corrected_image

stark.reduce.background2d(frame, mask, clip=5, bkg_estimator='median', box_size=(10, 2))[source]

To perform 2D background subtraction

Given the frame and mask this function will use photutils to estimate a 2D background of the given image. Subsequently, it will subtract this background from the data.

Parameters:

  • frame (ndarray) – 2D data frame of the data with shape [nrows, ncols]

  • mask (ndarray) – Mask array with the same size as frame. Only points with 1 will be considered to estimate background.

  • clip (int) – sigma clipping value

  • bkg_estimator (str, either 'median' or 'mmm') – See, bkg_estimator keyword in photutils.background.Background2D class for details Default is median

  • box_size ((ny,nx)) – See, box_size keyword in photutils.background.Background2D class for details Default is (10,2)

Returns:

  • corrected_image (ndarray) – Background corrected image

  • bkg (ndarray) – Subtracted background

stark.reduce.trace_spectrum(frame, xstart, xend, ystart, yend, kernel=None, radius=10, num_iter=100, **kwargs)[source]

To find the trace of the spectrum in single frame

This function finds the trace of the spectrum in single frame using deconvolution and centering.

Parameters:

  • frame (ndarray) – Single 2D frame image

  • xstart (int) – Start column number of the trace

  • xend (int) – End column number of the trace

  • ystart (int) – Start row number for trace search

  • yend (int) – End row number for trace search

  • kernel (Callable function) – Callable function to define kernel Default is Gaussian function

  • radius (int) – Radius of the aperture while defining the kernel Default is 5.

  • num_iter (int) – Number of iteration for Richardson Lucy deconvolution

  • **kwargs – Additional keywords provided to the kernel function

Returns:

  • xpos (ndarray) – x-positions of the traced spectrum

  • ypos (ndarray) – Traced position of the spectrum

  • kern2D (ndarray) – 2D kernel used in deconvolution

  • deconv (ndarray) – Deconvolved image

stark.reduce.trace_spectra(frames, xstart, xend, ystart, yend, niter=3, clip=3, nknots=8, **kwargs)[source]

Tracing spectra for multiple frames

This function compute trace for all frames in input data using trace_spectrum function, and then fits a univariate spline to smooth the positions. “Master” median spline is then computed to define the shape robustly. Then for each frames the shape is assumed to be the same as the master median spline and fit for jitter.

Parameters:

  • frames (ndarray) – 3D data cube with dimension, [nints, nrows, ncols]

  • xstart (int) – Start column number of the trace

  • xend (int) – End column number of the trace

  • ystart (int) – Start row number for trace search

  • yend (int) – End row number for trace search

  • niter (int) – Number of iterations for various fitting procedure. Default is 3.

  • clip (int) – Number of sigma clipping to mask points Default is 3.

  • nknots (int) – Number of knots to be used in spline fitting

  • **kwargs – Additional keywords provided to the trace_spectrum function

Returns:

  • xpos (ndarray) – x-position of the traced spectra, same for each frame

  • y_fitted_trace (ndarray) – Traced position of the spectra in each frame

(Last two functions are computationally expensive.)