soxs_stare

The soxs_stare recipe reduces object frames taken in stare mode. It models and removes the on-frame sky contribution to the flux. The object trace is then fitted and extracted using an optimal extraction routine.

Input

Table 76 Input files for the soxs_stare recipe. The files are typically passed to the soxs_stare recipe via a set-of-file (sof) file listing one file per line.

Data Type	Content	Related OB
FITS Images	Raw science frames of targets observed in stare mode	SOXS_slt_obs_StareSynchro, SOXS_slt_cal_SpecphotStdStare, SOXS_slt_cal_TelluricStdStare
FITS Image	Master bias (UVVIS only)	-
FITS Image	Master dark frame (NIR only)	-
FITS Image	Master flat frame (optional)	-
FITS Table	Order location table containing coefficients to the polynomial fits describing the order locations.	-
FITS Table	Dispersion map table giving coefficients of polynomials describing 2D dispersion/spatial solution	-
FITS Image	Dispersion Map image with 3-extensions (wavelength, slit-position and echelle order number)	-

Table 77 Ancillary (static) files required by the soxs_stare recipe. These files are packaged with and shipped with the code.

Data Type	Content
FITS images	Default bad-pixel map
FITS Binary Table	A spectral format table for the detector, giving the minimum and maximum wavelengths covered by each spectral order.

Parameters

Table 78 The soxs_stare recipe parameters.

Parameter	Description	Type	Entry Point	Related Util
use_flat	divide image by master flat frame	bool	settings file	-
subtract_background	fit and subtract the intra-order background light	bool	settings file	-
use_lacosmic	use la cosmic to remove CRHs before extraction	bool	settings file	-
stacked_clipping_sigma	the sigma clipping limit used when stacking frames into a composite frame	float	settings file	clip_and_stack
stacked_clipping_iterations	the maximum sigma-clipping iterations used when stacking frames into a composite frame	int	settings file	clip_and_stack
horne_extraction_slit_length	the length of the ‘slit’ used to collect object flux (in pixels). Doubles are boxcar extraction aperture size.	int	settings file	horne_extraction
horne_extraction_profile_poly_order	degree of the polynomial used to fit the dispersion-direction profiles of the object.	int	settings file	horne_extraction
horne_extraction_profile_global_clipping_sigma	sigma clipping limit when fitting the object profile (global over the order)	float	settings file	horne_extraction
horne_extraction_profile_clipping_sigma	sigma clipping limit when fitting the dispersion-direction profiles of the object	float	settings file	horne_extraction
horne_extraction_profile_clipping_iteration_count	maximum number of clipping iterations when fitting dispersion-direction profiles	int	settings file	horne_extraction
order_sample_count	number of cross-order slices per order	int	settings file	detect_continuum
slice_length	length of each slice (pixels)	int	settings file	detect_continuum
slice_width	width of each slice (pixels)	int	settings file	detect_continuum
peak_sigma_limit	height gaussian peak must be above median flux to be “detected” by code (std via median absolute deviation)	float	settings file	detect_continuum
order_deg	degree of order-component of global polynomial fit to object trace	int	settings file	detect_continuum
disp_axis_deg	degree of y-component of global polynomial fit to object trace	int	settings file	detect_continuum
poly_fitting_residual_clipping_sigma	clipping limit (median and mad) when fitting global polynomial to object trace	float	settings file	detect_continuum
poly_clipping_iteration_limit	maximum number of clipping iterations when fitting global polynomial to object trace	int	settings file	detect_continuum
background_subtraction: bspline_deg	degree of bsplines used to fit the inter-order background (if subtract_background == True)	int	settings file	subtract_background
background_subtraction: gaussian_blur_sigma	Standard deviation of Gaussian kernel used to smooth background image (if subtract_background == True)	int	settings file	subtract_background
response: max_iteration	maximum number of iterations used to fit the polynomial to the response function	int	settings file	response_function
response: poly_order	degree of the polynomial used to fit the response function	int	settings file	response_function

Method

The algorithm used in the soxs_stare recipe is shown in Fig. 49.

Fig. 49 The soxs_stare recipe algorithm. At the top of the diagram, NIR input data is found on the right and VIS on the left.

If more than one stare mode frame is passed to the soxs_stare recipe, there is a call to clip_and_stack to combine the data into a single frame. The single stare-mode frame is detrended using the detrend, optionally dividing by a master flat field and fitting and removing the background scattered light. The sky-flux is modelled and removed using the subtract_sky util, and finally, the object is optimally extracted using the horne_extraction utility.

Note a boxcar extraction is also preformed alongside the Horne extraction. Use the horne-extraction-slit-length to control the size of the aperture used to preform the boxcar extraction on the object trace.

Output

Table 79 Output files for the soxs_stare recipe and their respective ESO PRO keywords. Some output file may not be generated depending on the user’s pipeline settings.

Label	Content	Data Type	PRO CATG	PRO TYPE	PRO TECH
EXTRACTED ORDERS TABLE	Table of the extracted source in each order	FITS	SCI_SLIT_FLUX_<ARM>	REDUCED	ECHELLE,SLIT
EXTRACTED MERGED TABLE	Table of the extracted, order-merged	FITS	SCI_SLIT_FLUX_<ARM>	REDUCED	ECHELLE,SLIT
EXTRACTED FLUXCAL SPECTRUM	Table of the flux calibrated extracted spectrum	FITS	SCI_SLIT_FLUX_<ARM>	REDUCED	ECHELLE,SLIT
SKY SUBTRACTED OBJECT	The sky-subtracted object	FITS	-	-	-
SKY MODEL	The sky background model	FITS	-	-	-
SKY SUB RESIDUALS	The sky subtraction residuals	FITS	-	-	-
RESPONSE_FUNC	Response function coefficients	FITS	RESP_TAB_<ARM>	REDUCED	ECHELLE,SLIT
EFFICIENCY	Efficiency estimate	FITS	EFFICIENCY_TAB_<ARM>	REDUCED	ECHELLE,SLIT
EXTRACTED MERGED ASCII	Ascii version of extracted source spectrum	TXT	-	-	-
BKGROUND	Fitted intra-order image background	PDF	-	-	-
SKY MODEL QC PLOTS	QC plots for the sky-background modelling	PDF	-	-	-
SKY SUBTRACTION QUICKLOOK	Sky-subtraction quicklook	PDF	-	-	-
OBJECT TRACE RES	Residuals of the object trace polynomial fit	PDF	-	-	-
EXTRACTED ORDERS QC PLOT	QC plot of extracted source	PDF	-	-	-
EXTRACTED MERGED QC PLOT	QC plot of extracted order-merged source	PDF	-	-	-
EXTRACTED MERGED FLUXCALIBRATED QC PLOT	QC plot of extracted order-merged, flux-calibrated source	PDF	-	-	-
RESPONSE QC PLOT	Response curve QC plot.	PDF	-	-	-

QC Metrics

Table 80 Quality Control metrics calculated in the soxs_stare recipe. Note that the acceptable ranges are enforced only for standard stars, not for science frames.

Label	Description	Unit	Acceptable Range
BADPIX FRAC	Fraction of bad pixels		VIS: [0.0,0.01], NIR: [0.00,0.01]
INNER ORDER PIX MEAN	Mean inner-order pixel value	electrons	VIS: [-40,60], NIR: [-40,60]
INNER ORDER PIX SUM	Sum of all inner-order pixel values	electrons	-
BADPIX NUM	Number of bad pixels		-
N ORDERS	Number of orders containing an object trace		VIS: 4, NIR: 15
SAMPLES DET NUM	Number of samples where a continuum is detected		-
SAMPLES DET FRAC	Fraction of samples where a continuum is detected		VIS: [0.93,1.0], NIR: [0.7,1.0]
SAMPLES TOT NUM	Total number of samples along orders		-
SAMPLES CLIP NUM	Number of continuum sample clipped during solution fitting		-
SAMPLES CLIP FRAC	Fraction of detected continuum samples clipped during solution fitting		VIS: [0.0,0.2], NIR: [0.0,0.3]
X RES MAX	Maximum residual in continuum fit along x-axis	px	-
X RES MIN	Minimum residual in continuum fit along x-axis	px	-
X RES SD	Std-dev of residual continuum fit along x-axis	px	VIS: [0.0,0.2]
Y RES MAX	Maximum residual in continuum fit along y-axis	px	-
Y RES MIN	Minimum residual in continuum fit along y-axis	px	-
Y RES SD	Std-dev of residual continuum fit along y-axis	px	NIR: [0.0,0.5]
EFF MEDIAN	The median efficiency (global)		VIS: [0.04,0.30], NIR: [0.02,0.2]
SNR MEDIAN	The median signal-to-noise ratio across all orders (global)		VIS: [50,1000], NIR: [7,200]
EFF MEDIAN O<N>	The median efficiency (order N)		-
SNR MEDIAN O<N>	The median signal-to-noise ratio across all orders (order N)		-

Fig. 50 A QC plot resulting from the soxs_stare recipe. This is a SOXS NIR wavelength and flux calibrated spectrum of the standard star CD-325613. The top- and middle-panels show the flux and wavelength calibrated spectrum, the top in linear-flux and the middle in log-flux scale. The bottom panel shows the signal-to-noise ratio across the entire wavelength range covered by the spectrum.

Recipe API

class soxs_stare(log, settings=False, inputFrames=[], verbose=False, overwrite=False, command=False, debug=False, turnOffMP=False)

Bases: soxspipe.recipes.base_recipe.base_recipe

Reduce SOXS/Xshooter data taken in stare mode

Key Arguments

• log – logger

• settings – the settings dictionary

• inputFrames – input fits frames. Can be a directory, a set-of-files (SOF) file or a list of fits frame paths.

• verbose – verbose. True or False. Default False

• overwrite – overwrite the product file if it already exists. Default False

• command – the command called to run the recipe

• debug – show debug plots. Default False

• turnOffMP – turn off multiprocessing. True or False. Default False. If True, multiprocessing will be turned off and the recipe will run in serial. This is useful for debugging.

See produce_product method for usage.

Initialization

clean_up(forceFail=False)

clip_and_stack(frames, recipe, ignore_input_masks=False, post_stack_clipping=True)

detrend(inputFrame, master_bias=False, dark=False, master_flat=False, order_table=False)

flag_poor_data()

get_recipe_settings()

prepare_frames(save=False)

produce_product()

The code to generate the product of the soxs_stare recipe

Return:

• productPath – the path to the final product

Usage

from soxspipe.recipes import soxs_stare
recipe = soxs_stare(
    log=log,
    settings=settings,
    inputFrames=fileList
)
stareFrame = recipe.produce_product()

qc_median_flux_level(frame, frameType='MBIAS', frameName='master bias', medianFlux=False)

qc_ron(frameType=False, frameName=False, masterFrame=False, rawRon=False, masterRon=False)

report_output(rformat='stdout')

subtract_mean_flux_level(rawFrame)

update_fits_keywords(frame, rawFrames=False)

verify_input_frames()

verify the input frame match those required by the soxs_stare recipe

Return:

• None

If the fits files conform to the required input for the recipe, everything will pass silently; otherwise, an exception will be raised.

xsh2soxs(frame)