stisblazefix Documentation¶

Warning

Please note that AURA/STScI is not responsible for any damages resulting from the use of this software.

The stisblazefix python module is designed to empirically correct STIS echelle data for misalignment in the blaze function. It does this by shifting the overall sensitivity curve applied to each order to find the shifts that make the measured flux in the wavelength overlap of adjacent echelle orders most consistent, under the assumption that the shift to be applied to each echelle order is a linear function of the order number.

Once installed, the fluxfix function of the module can be run by supplying a list of STIS echelle x1d FITS file names, as well as an output name to be used for the PDF diagnostic plots produced. For example:

stisblazefix.fluxfix(['ocb6i2020_x1d.fits', 'ocb6f2010_x1d.fits'], 'example.pdf')

This will produce as output the files ocb6i2020_x1f.fits and ocb6f2010_x1f.fits with corrected values for the extracted flux and error vectors, as well as a PDF file with a diagnostic plot for each exposure showing changes made to the data.

Example blaze correction to HST/STIS E230H dataset OCB6I2020.¶

Installation¶

Dependencies¶

The stisblazefix package is designed to run in the AstroConda environment. After installation, launch it via:

source activate astroconda

LMFIT is required, but is not currently in the standard AstroConda distribution. It can be added to an Anaconda environment by first activating the desired environment and then running:

conda install -c conda-forge lmfit

Warning

Requires at least numpy 1.13, bugs occur with numpy 1.12.

Note

If it is necessary or desirable to install this module in a conda environment that does not include the AstroConda software channel, it may be possible as long as compatible versions of Astropy and Matplotlib are available.

Conda Installation¶

Once LMFIT is installed, install the stisblazefix module via:

conda install -c sean-lockwood stisblazefix

Manual Installation¶

Alternatively, you may download and manually install stisblazefix via:

python setup.py install

Python API¶

Most users will be interested in the fluxfix function.

This module contains the following functions:

findshift : calculates the shift to the blaze function that best aligns the spectrum.
fluxcorrect : takes a shift to the blaze function and recalculates the flux and error.
fluxfix : takes a list of x1d fits files and generates corrected x1f files and diagnostic plots.
generateplot: takes an old and corrected spectrum and generates a diagnostic plot.
plotblaze : plots the sensitivity curves for an extracted spectrum.
residfunc : wrapper for lmfit minimizer.
residcalc : calculates the flux residuals for the overlapping regions of an echelle spectrum.

stisblazefix.findshift(filedata, guess, iterate=True)¶

Find pixshift that best aligns spectral orders.

Use lmfit to calculate the pixshift (to apply to the blaze function) as a linear function of relative spectral order that minimizes the flux overlap residuals as calculated in residcalc.

filedata: the data attribute of an x1d FITS file.
guess : a tuple containing the starting parameters for the fit.
iterate : Boolean that determines whether the function iterates to find the best fit.

Returns pixshift, the error in the pixshift, and the final parameters.

stisblazefix.fluxcorrect(filedata, pixshift)¶

Recalculate and return corrected flux and error vectors, based on shifted blaze function.

filedata is the data attribute of an x1d fits file.
pixshift is a 1D vector with length equal to the number of orders in the echelle spectrum. It contains the shift of the blaze function in pixels as a function of relative spectral order.

stisblazefix.fluxfix(files, pdfname, guess=None, iterate=True, nxplot=1, **kwargs)¶

Corrects STIS echelle spectra by aligning the sensitvity function to compensate for shifts in the blaze function.

This routine will iterate over a list of STIS echelle x1d files and for each exposure in each file it will find the shifts of the sensitivy curves for the spectral orders that maximize the flux consistency in the overlap between orders. Corrected flux and error vectors are then calculated and saved to new output files where _x1d.fits is replaced with _x1f.fits.

It assumes that amount by which the sensitivity curve for each spectral order needs to be shifted is a linear function of the order number. The optimal shifts for each exposure to minimize the flux inconsistency in the overlapping regions of the spectral orders are found. Each exposure is treated independently.

Args:

files (list of str): A list of file names corresponding to STIS echelle x1d files. All file names should end in _x1d.fits and should contain extracted and flux calibrated STIS echelle spectra output from CalSTIS.

pdfname (str): Name for the output PDF file.

guess (tuple of two floats): Contains a starting guess for the linear relation used to shift the blaze function. Should be in the form (a, b), where the blaze shift for each spectral order x will be a + b*x. Defaults to None, which then substitutes a suitable guess supplied in the code.

iterate (bool): When set to True the code will iterate to find the values for a & b that minimimize the inconsistency in the flux ovelap regions. When set to False, the code will use the values supplied in Guess without iterating. Defaults to True.

nxplot (integer): default 1. When set to a value > 1 will add extra plot pages, each comparing the original and corrected spectrum over approximately 1/nxplot of the wavelength range, but allowing a slight wavelength overlap between the plots.

Returns:

A list of dictionaries, one for each exposure found in the x1d files. Each list element contains:

pixshift : array of pixel shift values applied to sens curve
acof : offset applied to sens curve of lowest order
bcof : change in offset per order
acoferr : formal error in the value for acof
bcoferr : formal error in the value for bcof
oldresids : vector of residual flux differences in order overlaps of original data
oldresiderr : error vector for oldresids
newresids : vector of residual flux differences in order overlaps of corrected data
newresiderr : error vector for newresids
filename : input file name
extno : extension number of input file for this exposure

Produces:

A new copy of each x1d file with the fluxes and errors corrected for the new shift of the sensitivity vector. The new files replace x1d in the file names with x1f.
A multipage PDF file with diagnostic plots for each exposure.

stisblazefix.generateplot(origdata, newflux, newerr, pixshift, params, paramerr, oldresids=None, oldresiderr=None, ntrim=5)¶

Generate a diagnostic plot for a corrected spectrum.

Plot spectrum and residuals before and after correction to blaze function, and pixshift vs relative spectral order. Return a figure object.

origdata: the data attribute of an x1d FITS file. This should contain the original flux.
newflux : the corrected flux.
newerr : the corrected error.
pixshift: a 1D vector with length equal to the number of orders in the echelle spectrum.

kwargs:

oldresids : the residuals for the uncorrected data.
oldresiderr : the error in the residuals for the uncorrected data.
ntrim : the cut made to the edges of the orders to avoid various edge problems. Defaults to 5.

If neither oldresids or oldresiderr is passed, they will be calculated from origdata.

stisblazefix.plotblaze(filename, pdfname, ntrim=7)¶: Plot the blaze function for each order of a STIS echelle spectrum.

stisblazefix.residcalc(filedata, flux=None, err=None, dq=None, ntrim=5)¶

Calculate and return the flux overlap residuals and weighted error.

Flux residuals are calculated by summing the flux in the overlapping region in adjacent orders, taking the ratio, and subtracting from one.

filedata is the data attribute of an x1d FITS file.

kwargs:

flux : flux vector the same size as the flux in filedata.
err : error vector the same size as the error in filedata.
dq : data quality vector the same size as the dq in filedata.
ntrim: cut made to the edges of the orders to avoid various edge problems. Defaults to 5.

If either flux or error is passed, they will be used to calculate the residuals. Otherwise, the flux and error arrays from filedata will be used.

stisblazefix.residfunc(pars, x, filedata)¶

Wrapper for lmfit minimizer. Return weighted residuals for a given pixshift.

pars : a tuple containing lmfit parameters.
x : the input variable, in this case relative spectral order.
filedata: the data attribute of an x1d FITS file.

Release History¶

v1.0a1: Initial pre-release of stisblazefix package. Additional updates are pending.
v1.0a2: Improved handling of divide-by-zero warnings. Reduced conda package size.
v1.1: Fixed bug in lmfit dependency call when iterate=False.

Support¶

For support, please contact the STScI help desk at http://hsthelp.stsci.edu