scopesim.effects.spectral_trace_list_utils module

Utility classes and functions for SpectralTraceList.

This module contains

• the definition of the SpectralTrace class. The visible effect should always be a SpectralTraceList, even if that contains only one SpectralTrace.

• the definition of the XiLamImage class

• utility functions for use with spectral traces

class scopesim.effects.spectral_trace_list_utils.SpectralTrace(trace_tbl, cmds=None, **kwargs)

Bases: object

Definition of one spectral trace.

A SpectralTrace describes the mapping of spectral slit coordinates to the focal plane. The class reads an order layout and fits several functions to describe the geometry of the trace.

Slit coordinates are: - xi : spatial position along the slit [arcsec] - lam : Wavelength [um] Focal plane coordinates are: - x, y : [mm]

compute_interpolation_functions()

Compute various interpolation functions between slit and focal plane.

Focal plane coordinates are x and y, in mm. Slit coordinates are xi (spatial coordinate along the slit, in arcsec) and lam (wavelength, in um).

footprint(wave_min=None, wave_max=None, xi_min=None, xi_max=None)

Return corners of rectangle enclosing spectral trace.

Parameters:

wave_min, wave_maxfloat [um], Quantity

Minimum and maximum wavelength to compute the footprint on. If None, use the full range that spectral trace is defined on. Float values are interpreted as microns.

xi_min, xi_maxfloat [arcsec], Quantity

Minimum and maximum slit position on the sky. If None, use the full range that spectral trace is defined on. Float values are interpreted as arcsec.

fov_grid()

Provide information on the source space volume required by the effect.

Returns:

A dictionary with entries wave_min and wave_max.

Spatial limits are determined by the ApertureMask effect

and are not returned here.

map_spectra_to_focal_plane(fov)

Apply the spectral trace mapping to a spectral cube.

The cube is contained in a FieldOfView object, which also has world coordinate systems for the Source (sky coordinates and wavelengths) and for the focal plane. The method returns a section of the fov image along with info on where this image lies in the focal plane.

plot(wave_min=None, wave_max=None, xi_min=None, xi_max=None, *, c='r', axes=None, plot_footprint=True, plot_wave=True, plot_ctrlpnts=True, plot_outline=False, plot_trace_id=False)

Plot control points (and/or footprint) of the SpectralTrace.

Parameters:

wave_minfloat, optional

Minimum wavelength, if any.

wave_maxfloat, optional

Maximum wavelength, if any.

xi_minfloat, optional

Minimum slit, if any.

xi_maxfloat, optional

Maximum slit, if any.

cstr, optional

Colour, any valid matplotlib colour string. The default is “r”.

axesmatplotlib axes, optional

The axes object to use for the plot. If None (default), a new figure with one axes will be created.

Returns:

axesmatplotlib axes

The axes object containing the plot.

Other Parameters:

plot_footprintbool, optional

Plot a rectangle encompassing all control points, which may be larger than the area actually covered by the trace, if the trace is not exactly perpendicular to the detector. The default is True.

plot_wavebool, optional

Annotate the wavelength points. The default is True.

plot_ctrlpntsbool, optional

Plot the individual control points as makers. The default is True.

plot_outlinebool, optional

Plot the smallest tetragon encompassing all control points. The default is False.

plot_trace_idbool, optional

Write the trace ID in the middle of the trace. The default is False.

rectify(hdulist, interps=None, wcs=None, **kwargs)

Create 2D spectrum for a trace.

Parameters:

hdulistHDUList

The result of scopesim readout

interpslist of interpolation functions

If provided, there must be one for each image extension in hdulist. The functions go from pixels to the images and can be created with, e.g., RectBivariateSpline.

wcsThe WCS describing the rectified XiLamImage. This can be created

in a simple way from the fov included in the OpticalTrain used in the simulation run producing hdulist.

The WCS can also be set up via the following keywords:

bin_widthfloat [um]

The spectral bin width. This is best computed automatically from the spectral dispersion of the trace.

wave_min, wave_maxfloat [um]

Limits of the wavelength range to extract. The default is the the full range on which the SpectralTrace is defined. This may extend significantly beyond the filter window.

xi_min, xi_maxfloat [arcsec]

Spatial limits of the slit on the sky. This should be taken from the header of the hdulist, but this is not yet provided by scopesim

property trace_id

Return the name of the trace.

class scopesim.effects.spectral_trace_list_utils.Transform2D(matrix, pretransform_x=None, pretransform_y=None, posttransform=None)

Bases: object

2-dimensional polynomial transform.

The class is instantiated from a m x n matrix A that contains the coefficients of the polynomial. Along rows, the power of x increases; along columns, the power of y increases, such that A[j, i] is the coefficient of x^i y^j.

The functions pretransform_x and pretransform_y can be used to transform the input variables before the matrix is applied. The function posttransform can be applied to the output after application of the matrix.

In Scopesim, a usecase for the pre- and post-transform functions is the METIS LMS, where the matrices are applied to phases while Scopesim operates on wavelengths. The functions to pass are lam2phase and phase2lam.

Parameters:

matrixnp.array

matrix of polynomial coefficients

pretransform_xfunction, tuple

pretransform_yfunction, tuple

If not None, the function is applied to the input variable x or y before the actual 2D transform is computed

posttransformfunction, tuple

If not None, the function is applied to the output variable after the 2D transform is computed

When passed as a tuple, the first element is the function itself,

the second element is a dictionary of arguments to the function.

Example:

```

def rescale(x, scale=1.):

return x * scale

pretransform_x = (rescale, {“scale”: 0.5})

```

classmethod fit(xin, yin, xout, degree=4)

Determine polynomial fits.

gradient()

Compute the gradient of a 2d polynomial transformation.

class scopesim.effects.spectral_trace_list_utils.XiLamImage(fov, dlam_per_pix)

Bases: object

Class to compute a rectified 2D spectrum.

The class produces and holds an image of xi (relative position along the spatial slit direction) and wavelength lambda.

Parameters:

fovFieldOfView

dlam_per_pixa 1-D interpolation function from wavelength (in um) to

dispersion (in um/pixel); alternatively a number giving an average dispersion

scopesim.effects.spectral_trace_list_utils.fill_zeros(x)

Fill in zeros in a sequence with the previous non-zero number.

scopesim.effects.spectral_trace_list_utils.fit2matrix(fit)

Return coefficients from a polynomial fit as a matrix.

The Polynomial2D fits of degree n have coefficients for all i, j with i + j <= n. How would one rearrange those?

scopesim.effects.spectral_trace_list_utils.get_affine_parameters(coords)

Return rotation and shear for each MTC point along a SpectralTrace.

Parameters:

coordsdict of 2D arrays

Each dict entry [“x”, “y”, “s”] contains a [N, M] 2D array of coordinates, where:

• N is the number of points along the slit (e.g. ~5), and

• M is the number of positions along the trace (e.g. >100)

Returns:

rotationsarray

[deg] Rotation angles for M positions along the Trace

shearsarray

[deg] Shear angles for M positions along the Trace

scopesim.effects.spectral_trace_list_utils.make_image_interpolations(hdulist, **kwargs)

Create 2D interpolation functions for images.

scopesim.effects.spectral_trace_list_utils.rolling_median(x, n)

Calculate the rolling median of a sequence for +/- n entries.

scopesim.effects.spectral_trace_list_utils.xilam2xy_fit(layout, params)

Determine polynomial fits of FPA position.

Fits are of degree 4 as a function of slit position and wavelength.

scopesim.effects.spectral_trace_list_utils.xy2xilam_fit(layout, params)

Determine polynomial fits of wavelength/slit position.

Fits are of degree 4 as a function of focal plane position