soxs_disp_solution

The soxs_disp_solution recipe generates a first-guess dispersion solution for the instrument (measured along the central trace for each echelle order).

Usage

The soxs_disp_solution recipe can be run with the following convention:

soxspipe [-Vx] disp_solution <inputFrames> [-o <outputDirectory> -s <pathToSettingsFile> --poly=<od>]

To rerun a previously executed soxs_disp_solution recipe, you can find the execution command at the end of the recipe log file (found in the workspace products/soxs_disp_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 disp_solution sof/20260111T095553_NIR_3_DSOL_PINHOLE_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 and a 5th-order (for both x and y) wavelength (ww) component:

soxspipe disp_solution sof/20260111T095553_NIR_3_DSOL_PINHOLE_15_0S_SOXS.sof -s ./sessions/base/soxspipe.yaml --poly=3455

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

Product files are written in the products/soxs_disp_solution, and QC plots are in the qc/soxs_disp_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_disp_solution are found in soxs_disp_solution_qc and a typical QC plot in soxs_disp_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, wavelength-deg and slit-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 9 The soxs_disp_solution recipe parameters.

Parameter

Description

Type

Entry Point

Related Util

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 file

create_dispersion_map

pinhole_detection_thres_sigma

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

float

settings file

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

poly_clipping_iteration_limit

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

int

settings file

create_dispersion_map

poly_fitting_residual_clipping_sigma

sigma clipping limit when fitting global polynomial to the dispersion solution

float

settings file

create_dispersion_map

Input

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

Data Type

Content

Related OB

FITS Image

Arc Lamp through single pinhole mask

SOXS_slt_cal_VISArcsPinhole, SOXS_slt_cal_NIRArcsPinhole

FITS Image

Master Dark Frame (VIS only, optional)

-

FITS Image

Master Bias Frame (VIS only)

-

FITS Image

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

SOXS_slt_cal_NIRArcsPinhole

Output

Table 11 Output files for the soxs_disp_solution recipe and their respective ESO PRO keywords.

Label

Content

Data Type

PRO CATG

PRO TYPE

PRO TECH

DISP MAP

first pass dispersion solution

FITS Table

DISP_TAB_<ARM>

REDUCED

ECHELLE,PINHOLE

DISP MAP LINES

dispersion solution fitted lines

FITS Table

-

-

-

DISP MAP LINES MISSING

undetected arc lines

FITS Table

-

-

-

DISP MAP RES

dispersion solution QC plots

PDF

-

-

-

QC Metrics

Table 12 Quality Control metrics calculated in the soxs_disp_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.9,1.0], NIR: [0.9,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

-

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

VIS: [0.0,0.15], NIR: [0.0,0.35]

X RES SD

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

pixels

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

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

VIS: [0.0,0.9], NIR: [0.0,0.13]

Y RES SD

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

pixels

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

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

NIR: [0,1.0]

XY RES SD

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

pixels

VIS: [0,1.5], NIR: [0,1.0]

X DIFF MEDIAN

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

pixels

-

X DIFF SD

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

pixels

VIS: [0,3.0], NIR: [0,1.3]

Y DIFF MEDIAN

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

pixels

-

Y DIFF SD

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

pixels

VIS: [0,10.0], NIR: [0,1.5]

XY DIFF MEDIAN

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

pixels

NIR: [0,6.0]

XY DIFF SD

Std-dev of difference between observed and predicted pinhole detector locations (global)

pixels

NIR: [0,1.9]

FWHM PIN MEDIAN

Median FWHM of detected lines in pinhole frames (global)

pixels

VIS: [1.60,1.75], NIR: [1.75,1.89]

FWHM PIN SD

Std-dev in FWHM of detected lines in pinhole frames (global)

pixels

VIS: [0.1,0.2], NIR: [0,0.211]

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>

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

pixels

-

Y DIFF MEDIAN O<N>

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

pixels

-

Y DIFF SD O<N>

Std-dev 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>

Std-dev 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)

-

The typical solution for the soxs_disp_solution recipe has sub-pixel residuals.

image-20250124164511814

Fig. 13 A QC plot resulting from the soxs_disp_solution recipe as run on a SOXS NIR single pinhole arc lamp frame. A ‘good’ dispersion solution will have sub-pixel residuals (mean residuals \(<\) 0.5 pixels). The top-left panel shows an SOXS NIR arc-lamp frame, taken with a single pinhole mask. The green circles represent arc lines detected in the image, and the blue circles and red crosses were detected but dropped due to poor DAOStarFinder fitting or clipped during the polynomial fitting, respectively. 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 at the pixel locations modelled for the original lines in the line list. The top-right panels show the residuals of the dispersion solution fit, and the final panels (bottom-right) the resolution measured for each line (as projected through the pinhole mask) with different colours for each echelle order and the mean order resolution in black.