soxs_spatial_solution

The soxs_spatial_solution recipe enhances the wavelength solution achieved with soxs_disp_solution by expanding the solution into the spatial dimension (along the slit). The resulting 2-dimensional solution accounts for any tilt in the spectral lines relative to the cross-dispersion axis. The recipe is similar in logic to soxs_disp_solution, but now samples arc lines along the slit in the cross-dispersion direction using a multi-pinhole slit mask.

Usage

The soxs_spatial_solution recipe can be run with the following convention:

soxspipe [-Vx] spat_solution <inputFrames> [-o <outputDirectory> -s <pathToSettingsFile> --poly=<oowwss>]

To rerun a previously executed soxs_spatial_solution recipe, you can find the execution command at the end of the recipe log file (found in the workspace products/soxs_spatial_solution directory). Use the -x flag to overwrite the product files if they already exist. For example, from the root of your workspace, you would run a command like:

soxspipe spat_solution sof/20260111T095625_NIR_3_SSOL_MULTPIN_15_0S_SOXS.sof -s ./sessions/base/soxspipe.yaml  -x

While the default polynomial fitting orders have been carefully tuned to robustly reduce most data, it is possible to execute this recipe while providing the dispersion-solution polynomial fitting orders through the command line, with command line settings overriding those in the YAML settings file. For instance, to attempt a dispersion solution fit using 3rd (x) and 4th-order (y) spectral-order (oo) component, a 5th-order (for both x and y) wavelength (ww) component, and a 2nd (x) and 4th-order (y) slit-position component (ss):

soxspipe spat_solution sof/20260111T095625_NIR_3_SSOL_MULTPIN_15_0S_SOXS.sof -s ./sessions/base/soxspipe.yaml --poly=345524

To adjust the default settings for the soxs_spatial_solution recipe, open the soxspipe.yaml file referenced in the command above in a text editor, navigate to the soxs_spatial_solution dictionary, save the file and rerun the recipe command. The settings’ descriptions can be found in Table 22.

Product files are written in the products/soxs_spatial_solution, and QC plots are in the qc/soxs_spatial_solution workspace directory. A report of the product files, QC plots and metrics is also printed to the terminal. The QC metrics calculated for soxs_spatial_solution are found in soxs_spatial_solution_qc and a typical QC plot in soxs_spatial_solution_qc_fig.

Reduction Tips

If this recipe fails because a fit for the dispersion solution is not found, the first parameter to adjust is poly-fitting-residual-clipping-sigma. Try setting a value lower than the default value by 0.5 and running the recipe again. If the recipe still fails, repeat the reduction in steps of 0.5 down to 3 sigma.

You can also try adjusting the polynomial fitting orders in order-deg and wavelength-deg. However, please be advised the pipeline itself will dynamically adjust these values if they fail to fit the default set. It will slowly reduce the orders and refit until it finds a fit or decides a fit can not be found (after five iterations of decreasing the orders).

Parameters

Table 22 The soxs_spatial_solution recipe parameters.

Parameter

Description

Type

Entry Point

Related Util

use_flat

divide image by master flat frame

bool

settings

-

subtract_background

fit and subtract the intra-order background light

bool

settings

subtract_background

pixel_window_size

the size of the square window used to search for an arc-lamp emission line, centred on the predicted pixel position of the line

int

settings

create_dispersion_map

pinhole_detection_thres_sigma

minimum significance required for arc-line to be considered ‘detected’

float

settings

create_dispersion_map

order_deg

degree of echelle order number component of global polynomial fit to the dispersion solution [x, y]

int/list

settings file or command-line

create_dispersion_map

wavelength_deg

degree of wavelength component of global polynomial fit to the dispersion solution [x, y]

int/list

settings file or command-line

create_dispersion_map

slit_deg

degree of slit position component of global polynomial fit to the dispersion solution [x, y]

int/list

settings file or command-line

create_dispersion_map

poly_clipping_iteration_limit

number of sigma-clipping iterations to perform before settings on a polynomial fit for the dispersion solution

int

settings

create_dispersion_map

poly_fitting_residual_clipping_sigma

sigma clipping limit when fitting global polynomial to the dispersion solution

float

settings

create_dispersion_map

poly_clipping_pinhole_sets

clipping performed on multi-pinhole sets (true) or individual pinholes (false)

bool

settings

create_dispersion_map

map_to_image_displacement_threshold

maximum distance allowed from the pixel centre when calculating wavelength, order and slit-position for 2d disp-sol image

float

settings

create_dispersion_map

mph_line_set_min

full multi-pinholes sets (same arc line) with fewer than mph_line_set_min lines detected get clipped

int

settings

create_dispersion_map

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

Input

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

Data Type

Content

Related OB

FITS Image

Arc Lamp through multi-pinhole mask

SOXS_slt_cal_VISArcsMultiplePinhole, SOXS_slt_cal_NIRArcsMultiplePinhole

FITS Image

Master Dark Frame (VIS only, optional)

-

FITS Image

Master Bias Frame (VIS only)

-

FITS Image

Master Flat Frame (optional)

-

FITS Image

Dark frame (Lamp-Off) of equal exposure length as multi-pinhole frame (Lamp-On) (NIR only)

SOXS_slt_cal_NIRArcsMultiplePinhole

FITS Table

First-guess Dispersion map table

Output

Table 24 Output files for the soxs_spatial_solution recipe and their respective ESO PRO keywords.

Label

Content

Data Type

PRO CATG

PRO TYPE

PRO TECH

SPAT SOL

Full dispersion-spatial solution

FITS

DISP_TAB_<ARM>

REDUCED

ECHELLE,MULTI-PINHOLE

2D MAP

2D detector map of wavelength, slit position and order

FITS

DISP_IMAGE_<ARM>

REDUCED

ECHELLE,MULTI-PINHOLE

BKGROUND

Fitted intra-order image background

PDF

-

-

-

DISP MAP LINES

Dispersion solution fitted lines

FITS

-

-

-

DISP MAP LINES MISSING

Undetected arc lines

FITS

-

-

-

DISP MAP RES

Dispersion solution QC plots

PDF

-

-

-

QC Metrics

Table 25 Quality Control metrics calculated in the soxs_spatial_solution recipe.

Label

Description

Unit

Acceptable Range

DETLINES CLIP NUM

Total number of detected lines clipped during solution fitting

lines

-

DETLINES NUM

Number of lines detected in single pinhole frame

lines

-

DETLINES FRAC

Proportion of input line-list lines detected on single pinhole frame

VIS: [0.95,1.0]

DETLINES TOT

Total number of line in single line-list

lines

-

GOODLINES FRAC

Proportion of good, unclipped lines in single pinhole frame

lines

VIS: [0.55,1.0] NIR: [0.4,1.0]

PINHOLE COUNT MIN

The minimum number of pinholes found across all orders (should be 9)

pinholes

VIS: 9, NIR: 9

X RES MAX

Maximum residual in fitting of pinholes along x-axis (global)

pixels

-

X RES MIN

Minimum residual in fitting of pinholes along x-axis (global)

pixels

-

X RES MEDIAN

Median of absolute residuals in fitting of pinholes along x-axis (global)

pixels

-

X RES SD

Std-dev of residuals in fitting of pinholes along x-axis (global)

pixels

VIS: [0,0.25], NIR: [0,0.42]

Y RES MAX

Maximum residual in fitting of pinholes along y-axis (global)

pixels

-

Y RES MIN

Minimum residual in fitting of pinholes along y-axis (global)

pixels

-

Y RES MEDIAN

Median of absolute residuals in fitting of pinholes along y-axis (global)

pixels

-

Y RES SD

Std-dev of residuals in fitting of pinholes along y-axis (global)

pixels

VIS: [0,0.48], NIR: [0,0.12]

XY RES MAX

Maximum residual in fitting of pinholes (global)

pixels

-

XY RES MIN

Minimum residual in fitting of pinholes (global)

pixels

-

XY RES MEDIAN

Median residual in fitting of pinholes (global)

pixels

VIS: [0,0.7], NIR: [0,0.3]

XY RES SD

Std-dev of residuals in fitting of pinholes (global)

pixels

VIS: [0,0.5], NIR: [0,0.4]

X DIFF MEDIAN

Median difference between observed and predicted pinhole detector locations along the x-axis (global)

pixels

-

X DIFF SD

Standard deviation in difference between observed and predicted pinhole detector locations along the x-axis (global)

pixels

-

Y DIFF MEDIAN

SMedian difference between observed and predicted pinhole detector locations along the y-axis (global)

pixels

-

Y DIFF SD

Standard deviation in difference between observed and predicted pinhole detector locations along the y-axis (global)

pixels

-

XY DIFF MEDIAN

Median difference between observed and predicted pinhole detector locations (global)

pixels

-

XY DIFF SD

Standard deviation of difference between observed and predicted pinhole detector locations (global)

pixels

-

FWHM PIN MEDIAN

Median FWHM of detected lines in pinhole frames (global)

pixels

VIS: [1.60,1.72], NIR: [1.55,1.85]

FWHM PIN SD

Standard deviation in FWHM of detected lines in pinhole frames (global)

pixels

VIS: [0.0,0.16], NIR: [0.0,0.145]

R PIN MEDIAN

Median spectral resolution measured from detected lines in pinhole frames (global)

-

X RES MAX O<N>

Maximum residual in fitting of pinholes along x-axis (order N)

pixels

-

X RES MIN O<N>

Minimum residual in fitting of pinholes along x-axis (order N)

pixels

-

X RES MEDIAN O<N>

Median of absolute residuals in fitting of pinholes along x-axis (order N)

pixels

-

X RES SD O<N>

Std-dev of residuals in fitting of pinholes along x-axis (order N)

pixels

-

Y RES MAX O<N>

Maximum residual in fitting of pinholes along y-axis (order N)

pixels

-

Y RES MIN O<N>

Minimum residual in fitting of pinholes along y-axis (order N)

pixels

-

Y RES MEDIAN O<N>

Median of absolute residuals in fitting of pinholes along y-axis (order N)

pixels

-

Y RES SD O<N>

Std-dev of residuals in fitting of pinholes along y-axis (order N)

pixels

-

XY RES MAX O<N>

Maximum residual in fitting of pinholes (order N)

pixels

-

XY RES MIN O<N>

Minimum residual in fitting of pinholes (order N)

pixels

-

XY RES SD O<N>

Std-dev of residuals in fitting of pinholes along (order N)

pixels

-

X DIFF MEDIAN O<N>

Median difference between observed and predicted pinhole detector locations along the x-axis (order N)

pixels

-

X DIFF SD O<N>

Standard deviation in difference between observed and predicted pinhole detector locations along the x-axis (order N)

pixels

-

Y DIFF MEDIAN O<N>

SMedian difference between observed and predicted pinhole detector locations along the y-axis (order N)

pixels

-

Y DIFF SD O<N>

Standard deviation in difference between observed and predicted pinhole detector locations along the y-axis (order N)

pixels

-

XY DIFF MEDIAN O<N>

Median difference between observed and predicted pinhole detector locations (order N)

pixels

-

FWHM PIN MEDIAN O<N>

Median FWHM of detected lines in pinhole frames (order N)

pixels

-

FWHM PIN SD O<N>

Standard-deviation in FWHM of detected lines in pinhole frames (order N)

pixels

-

R PIN MEDIAN O<N>

Median spectral resolution measured from detected lines in pinhole frames (order N)

-
image-20260414113416591

Fig. 16 A QC plot resulting from the soxs_spatial_solution recipe. The top-left panel shows an SOXS VIS arc-lamp frame, taken with a multi-pinhole mask. The green circles represent arc lines detected in the image, and the blue circles and red crosses are lines that were detected but dropped because other pinholes of the same arc line were not detected, or because the lines were clipped during polynomial fitting. The grey circles represent arc lines reported in the static calibration table that were not detected in the image. The bottom-left panel shows the same arc-lamp frame with the dispersion solution overlaid as a blue grid. Lines travelling along the dispersion axis (left to right) are lines of equal slit position, and lines travelling in the cross-dispersion direction (top to bottom) are lines of equal wavelength. The top-right panel shows the residuals of the dispersion solution fit, and the bottom-right panel shows the resolution measured for each line (projected through the pinhole mask), with different colours for each echelle order and the mean order resolution in black.