TwoDSpec API

class aspired.spectral_reduction.TwoDSpec(data: numpy.ndarray | astropy.io.fits.hdu.hdulist.HDUList | astropy.io.fits.hdu.hdulist.PrimaryHDU | astropy.io.fits.hdu.hdulist.ImageHDU | ImageReducer | ImageReduction = None, header: astropy.io.fits.Header = None, verbose: bool = True, logger_name: str = 'TwoDSpec', log_level: str = 'INFO', log_file_folder: str = 'default', log_file_name: str = None, **kwargs)[source]

This is a class for processing a 2D spectral image.

The constructor takes the data and the header, and the the header infromation will be read automatically. See set_properties() for the detail information of the keyword arguments. The extraction always consider the x-direction as the dispersion direction, while the y-direction as the spatial direction.

Parameters:
  • data (2D numpy array (M x N) OR astropy.io.fits object) – 2D spectral image in either format

  • header (FITS header (deafult: None)) – THIS WILL OVERRIDE the header from the astropy.io.fits object

  • verbose (bool (Default: True)) – Set to False to suppress all verbose warnings, except for critical failure.

  • logger_name (str (Default: TwoDSpec)) – This will set the name of the logger, if the name is used already, it will reference to the existing logger. This will be the first part of the default log file name unless log_file_name is provided.

  • log_level (str (Default: 'INFO')) – Four levels of logging are available, in decreasing order of information and increasing order of severity: (1) DEBUG, (2) INFO, (3) WARNING, (4) ERROR and (5) CRITICAL. WARNING means that there is is_optimal operations in some parts of that step. ERROR means that the requested operation cannot be performed, but the software can handle it by either using the default setting or skipping the operation. CRITICAL means that the requested operation cannot be resolved without human interaction, this is most usually coming from missing data.

  • log_file_folder (None or str (Default: "default")) – Folder in which the file is save, set to default to save to the current path.

  • log_file_name (None or str (Default: None)) – File name of the log, set to None to print to screen only.

  • **kwargs (keyword arguments (Default: see set_properties())) – see set_properties().

add_arc(arc: numpy.ndarray | astropy.io.fits.hdu.hdulist.HDUList | astropy.io.fits.hdu.image.PrimaryHDU | astropy.io.fits.hdu.image.ImageHDU | astropy.nddata.CCDData | str, header: astropy.io.fits.Header = None)[source]

To provide an arc image. Make sure left (small index) is blue, right (large index) is red.

Parameters:
  • arc (numpy.ndarray, PrimaryHDU/ImageHDU, ImageReducer, str) – The image of the arc image.

  • header (FITS header (deafult: None)) – An astropy.io.fits.Header object. This is not used if arc is a PrimaryHDU or ImageHDU.

add_bad_mask(bad_mask: numpy.ndarray | astropy.io.fits.hdu.hdulist.HDUList | astropy.io.fits.hdu.image.PrimaryHDU | astropy.io.fits.hdu.image.ImageHDU | str = None)[source]

To provide a mask to ignore the bad pixels in the reduction.

Parameters:

bad_mask (numpy.ndarray, PrimaryHDU/ImageHDU, ImageReducer, str) – The bad pixel mask of the image, make sure it is of the same size as the image and the right orientation.

add_data(data: numpy.ndarray | astropy.io.fits.hdu.hdulist.HDUList | astropy.io.fits.hdu.hdulist.PrimaryHDU | astropy.io.fits.hdu.hdulist.ImageHDU | astropy.nddata.CCDData | ImageReducer | ImageReduction, header: astropy.io.fits.Header = None)[source]

Adding the 2D image data to be processed. The data can be a 2D numpy array, an AstroPy ImageHDU/Primary HDU object or an ImageReducer object.

Parameters:
  • data (2D numpy array (M x N) OR astropy.io.fits object) – 2D spectral image in either format

  • header (FITS header (deafult: None)) – This take priority over the header from the fits.hdu.hdulist.HDUList, fits.hdu.image.PrimaryHDU, or CCDData.

add_trace(trace: list | numpy.ndarray, trace_sigma: list | numpy.ndarray, spec_id: int | list | numpy.ndarray = None)[source]

Add user-supplied trace. The trace has to have the size as the 2D spectral image in the dispersion direction.

Parameters:
  • trace (list or numpy.ndarray (N)) – The spatial pixel value (can be sub-pixel) of the trace at each spectral position.

  • trace_sigma (list or numpy.ndarray (N)) – Standard deviation of the Gaussian profile of a trace

  • spec_id (int (Default: None)) – The ID corresponding to the spectrum_oned object

ap_extract(apwidth: int | list | numpy.ndarray = 9, skysep: int | list | numpy.ndarray = 3, skywidth: int | list | numpy.ndarray = 5, skydeg: int = 1, sky_sigma: float = 3.0, optimal: bool = True, algorithm: str = 'horne86', model: str = 'gauss', bounds: dict = None, lowess_frac: float = 0.1, lowess_it: int = 3, lowess_delta: float = 0.0, tolerance: float = 1e-06, cosmicray_sigma: float = 4.5, max_iter: int = 99, forced: bool = False, variances: list | numpy.ndarray = None, npoly: int = 21, polyspacing: int = 1, pord: int = 5, qmode: str = 'fast-linear', nreject: int = 100, display: bool = False, renderer: str = 'default', width: int = 1280, height: int = 720, return_jsonstring: bool = False, save_fig: bool = False, fig_type: str = 'iframe+png', filename: str = None, open_iframe: bool = False, spec_id: int | list | numpy.ndarray = None)[source]

Extract the spectra using the traces, support tophat or optimal extraction. The sky background is fitted in one dimention only. The uncertainty at each pixel is also computed, but the values are only meaningful if correct gain and read noise are provided.

Tophat extraction: Float is accepted but will be rounded to an int,

which gives the constant aperture size on either side of the trace to extract.

Optimal extraction: Float or 1-d array of the same size as the trace.

If a float is supplied, a fixed standard deviation will be used to construct the gaussian weight function along the entire spectrum. (Choose from horne86 and marsh89 algorithm)

Nothing is returned unless return_jsonstring of the plotly graph is set to be returned. The count, count_sky and count_err are stored as properties of the TwoDSpec object.

count: 1-d array

The summed count at each column about the trace.

count_err: 1-d array

the uncertainties of the count values.

count_sky: 1-d array

The integrated sky values along each column.

Parameters:
  • apwidth (int or list of int (Default: 7)) – Half the size of the aperature (fixed value for tophat extraction). If a list of two ints are provided, the first element is the lower half of the aperture and the second one is the upper half.

  • skysep (int or list of int (Default: 3)) – The separation in pixels from the aperture to the sky window.

  • skywidth (int or list of int (Default: 5)) – The width in pixels of the sky windows on either side of the aperture. Zero (0) means ignore sky subtraction.

  • skydeg (int (Default: 1)) – The polynomial order to fit between the sky windows.

  • spec_id (int (Default: None)) – The ID corresponding to the spectrum_oned object

  • optimal (bool (Default: True)) – Set optimal extraction. (Default is True)

  • algorithm (str (Default: 'horne86')) – Available algorithms are horne86 and marsh89

  • model (str (Default: 'lowess')) – Choice of model: ‘lowess’ and ‘gauss’.

  • bounds (dict) – Limits of the gaussian function: ‘amplitude’, ‘mean’ and ‘stddev’. e.g. {‘amplitude’: [0.0, 100.0]} This is only used if the trace was provided manually.

  • lowess_frac (float (Default: 0.1)) – Fraction of “good data” retained for LOWESS fit.

  • lowess_it (int (Default: 3)) – Number of iteration in LOWESS fit – the number of residual-based reweightings to perform.

  • lowess_delta (float (Default: 0.0)) – The delta parameter in LOWESS fit – distance within which to use linear-interpolation instead of weighted regression.

  • tolerance (float (Default: 1e-6)) – The tolerance limit for the convergence of the optimal extraction

  • cosmicray_sigma (float (Deafult: 4.5)) – Cosmic ray sigma clipping limit. This is for rejecting pixels when using horne87 and marsh89 optimal cleaning. Use sigclip in kwargs for configuring cosmicray cleaning with astroscrappy.

  • max_iter (float (Default: 99)) – The maximum number of iterations before optimal extraction fails and return to standard tophot extraction

  • forced (bool (Default: False)) – To perform forced optimal extraction by using the given aperture profile as it is without interation, the resulting uncertainty will almost certainly be wrong. This is an experimental feature.

  • variances (list or numpy.ndarray (Default: None, only used if algorithm) – is horne86) The weight function for forced extraction. It is only used if force is set to True.

  • npoly (int (Default: 21, only used if algorithm is marsh89)) – Number of profile to be use for polynomial fitting to evaluate (Marsh’s “K”). For symmetry, this should be odd.

  • polyspacing (float (Default: 1, only used if algorithm is marsh89)) – Spacing between profile polynomials, in pixels. (Marsh’s “S”). A few cursory tests suggests that the extraction precision (in the high S/N case) scales as S^-2 – but the code slows down as S^2.

  • pord (int (Default: 5, only used if algorithm is marsh89)) – Order of profile polynomials; 1 = linear, etc.

  • qmode (str (Default: 'fast-linear', only used if algorithm is marsh89)) – How to compute Marsh’s Q-matrix. Valid inputs are ‘fast-linear’, ‘slow-linear’, ‘fast-nearest’, and ‘slow-nearest’. These select between various methods of integrating the nearest-neighbor or linear interpolation schemes as described by Marsh; the ‘linear’ methods are preferred for accuracy. Use ‘slow’ if you are running out of memory when using the ‘fast’ array-based methods.

  • nreject (int (Default: 100, only used if algorithm is marsh89)) – Number of outlier-pixels to reject at each iteration.

  • display (bool (Default: False)) – Set to True to display disgnostic plot.

  • renderer (str (Default: 'default')) – plotly renderer options.

  • width (int/float (Default: 1280)) – Number of pixels in the horizontal direction of the outputs

  • height (int/float (Default: 720)) – Number of pixels in the vertical direction of the outputs

  • return_jsonstring (bool (Default: False)) – set to True to return json str that can be rendered by Plotly in any support language.

  • save_fig (bool (default: False)) – Save an image if set to True. Plotly uses the pio.write_html() or pio.write_image(). The support format types should be provided in fig_type.

  • fig_type (string (default: 'iframe+png')) – Image type to be saved, choose from: jpg, png, svg, pdf and iframe. Delimiter is ‘+’.

  • filename (str (Default: None)) – Filename for the output, all of them will share the same name but will have different extension.

  • open_iframe (bool (Default: False)) – Open the iframe in the default browser if set to True.

ap_trace(nspec: int = 1, smooth: bool = False, nwindow: int = 20, spec_sep: int = 5, trace_width: int = 15, bounds: dict = None, resample_factor: int = 4, rescale: bool = False, scaling_min: float = 0.9995, scaling_max: float = 1.0005, scaling_step: float = 0.001, percentile: float = 5.0, shift_tol: int = 15, fit_deg: int = 3, ap_faint: float = 20.0, display: bool = False, renderer: str = 'default', width: int = 1280, height: int = 720, return_jsonstring: bool = False, save_fig: bool = False, fig_type: str = 'iframe+png', filename: str = None, open_iframe: bool = False)[source]

Aperture tracing by first using cross-correlation then the peaks are fitting with a polynomial with an order of floor(nwindow, 10) with a minimum order of 1. Nothing is returned unless return_jsonstring of the plotly graph is set to be returned.

Each spectral slice is convolved with the adjacent one in the spectral direction. Basic tests show that the geometrical distortion from one end to the other in the dispersion direction is small. With LT/SPRAT, the linear distortion is less than 0.5%, thus, even provided as an option, the rescale option is set to False by default. Given how unlikely a geometrical distortion correction is needed, higher order correction options are not provided.

A rough estimation on the background level is done by taking the n-th percentile of the slice, a rough guess can improve the cross-correlation process significantly due to low dynamic range in a typical spectral image. The removing of the “background” can massively improve the contrast between the peaks and the relative background, hence the correlation method is more likely to yield a true positive.

The trace(s), i.e. the spatial positions of the spectra (Y-axis), found will be stored as the properties of the TwoDSpec object as a 1D numpy array, of length N, which is the size of the spectrum after applying the spec_mask. The line spread function is stored in trace_sigma, by fitting a gaussian on the shift-corrected stack of the spectral slices. Given the scaling was found to be small, reporting a single value of the averaged gaussian sigma is sufficient as the first guess to be used by the aperture extraction function.

Parameters:
  • nspec (int) – Number of spectra to be extracted.

  • smooth (bool (Default: False)) – Set to true to apply a 3x3 median filter before tracing. Not recommended for use with faint spectrum.

  • nwindow (int) – Number of spectral slices (subspectra) to be produced for cross-correlation.

  • spec_sep (int) – Minimum separation between spectra (only if there are multiple sources on the longslit).

  • trace_width (int) – Distance from trace centre to be taken for profile fitting.

  • bounds (dict) – Limits of the gaussian function: ‘amplitude’, ‘mean’ and ‘stddev’. e.g. {‘amplitude’: [0.0, 100.0]}

  • resample_factor (int) – Number of times the collapsed 1D slices in the spatial directions are to be upsampled.

  • rescale (bool) – Fit for the linear scaling factor between adjacent slices.

  • scaling_min (float) – Minimum scaling factor to be fitted.

  • scaling_max (float) – Maximum scaling factor to be fitted.

  • scaling_step (float) – Steps of the scaling factor.

  • percentile (float) – The percentile of the flux to be used as the estimate of the background sky level to the first order. [Count]

  • shift_tol (float) – Maximum allowed shift between neighbouring slices, this value is referring to native pixel size without the application of the resampling or rescaling. [pix]

  • fit_deg (int) – Degree of the polynomial fit of the trace.

  • ap_faint (float) – The percentile tolerance of Count aperture to be used for fitting the trace. Note that this percentile is of the Count, not of the number of subspectra.

  • display (bool (Default: False)) – Set to True to display disgnostic plot.

  • renderer (str (Default: 'default')) – plotly renderer options.

  • width (int/float (Default: 1280)) – Number of pixels in the horizontal direction of the outputs

  • height (int/float (Default: 720)) – Number of pixels in the vertical direction of the outputs

  • return_jsonstring (bool (Default: False)) – set to True to return json str that can be rendered by Plotly in any support language.

  • save_fig (bool (default: False)) – Save an image if set to True. Plotly uses the pio.write_html() or pio.write_image(). The support format types should be provided in fig_type.

  • fig_type (string (default: 'iframe+png')) – Image type to be saved, choose from: jpg, png, svg, pdf and iframe. Delimiter is ‘+’.

  • filename (str (Default: None)) – Filename for the output, all of them will share the same name but will have different extension.

  • open_iframe (bool (Default: False)) – Open the iframe in the default browser if set to True.

Returns:

  • JSON-string if return_jsonstring is True, otherwise only an image is

  • displayed

apply_flip_to_arc()[source]

Apply flip to arc.

apply_mask_to_arc()[source]

Apply both the spec_mask and spatial_mask that are already stroed in the object.

apply_rectification()[source]

Accept the dispersion rectification computed.

apply_spatial_mask_to_arc(spatial_mask: numpy.ndarray)[source]

Apply to use only the valid y-range of the chip (i.e. spatial direction)

Parameters:

spatial_mask (1D numpy array (N)) – Mask in the spatial direction, can be the indices of the pixels to be included (size <N) or a 1D numpy array of True/False (size N) (Default is (1,) i.e. keep everything)

apply_spec_mask_to_arc(spec_mask: numpy.ndarray)[source]

Apply to use only the valid x-range of the chip (i.e. dispersion direction)

Parameters:

spec_mask (1D numpy array (M)) – Mask in the dispersion direction, can be the indices of the pixels to be included (size <M) or a 1D numpy array of True/False (size M) (Default is (1,) i.e. keep everything)

apply_transpose_to_arc()[source]

Apply transpose to arc.

create_fits(output: str = '*', recreate: bool = False, empty_primary_hdu: bool = True)[source]
Parameters:
  • output (String (Default: "*")) –

    Type of data to be saved, the order is fixed (in the order of the following description), but the options are flexible. The input strs are delimited by “+”,

    trace: 2 HDUs

    Trace, and trace width (pixel)

    count: 3 HDUs

    Count, uncertainty, and sky (pixel)

    weight_map: 1 HDU

    Weight (pixel)

    arc_spec: 1 HDU

    1D arc spectrum

  • recreate (bool (Default: False)) – Set to True to overwrite the FITS data and header.

  • empty_primary_hdu (bool (Default: True)) – Set to True to leave the Primary HDU blank

extract_arc_spec(spec_width: float | int = None, display: bool = False, renderer: str = 'default', width: int = 1280, height: int = 720, return_jsonstring: bool = False, save_fig: bool = False, fig_type: str = 'iframe+png', filename: str = None, open_iframe: bool = False, spec_id: int | list | numpy.ndarray = None)[source]

This function applies the trace(s) to the arc image then take median average of the stripe before identifying the arc lines (peaks) with scipy.signal.find_peaks(), where only the distance and the prominence keywords are used. Distance is the minimum separation between peaks, the default value is roughly twice the nyquist sampling rate (i.e. pixel size is 2.3 times smaller than the object that is being resolved, hence, the sepration between two clearly resolved peaks are ~5 pixels apart). A crude estimate of the background can exclude random noise which look like small peaks.

Parameters:
  • spec_width (int (Default: None)) – The number of pixels in the spatial direction used to sum for the arc spectrum

  • display (bool) – Set to True to display disgnostic plot.

  • renderer (str) – plotly renderer options.

  • width (int/float) – Number of pixels in the horizontal direction of the outputs

  • height (int/float) – Number of pixels in the vertical direction of the outputs

  • return_jsonstring (bool) – set to True to return json str that can be rendered by Plotly in any support language.

  • save_fig (bool (default: False)) – Save an image if set to True. Plotly uses the pio.write_html() or pio.write_image(). The support format types should be provided in fig_type.

  • fig_type (string (default: 'iframe+png')) – Image type to be saved, choose from: jpg, png, svg, pdf and iframe. Delimiter is ‘+’.

  • filename (str) – Filename for the output, all of them will share the same name but will have different extension.

  • open_iframe (bool) – Open the iframe in the default browser if set to True.

  • spec_id (int (Default: None)) – The ID corresponding to the spectrum_oned object

get_rectification(upsample_factor: int = 1, bin_size: int = 6, n_bin: int = 15, spline_order: int = 3, order: int = 2, coeff: list = None, use_arc: bool = True, apply: bool = False, display: bool = False, renderer: str = 'default', width: int = 1280, height: int = 720, return_jsonstring: bool = False, save_fig: bool = False, fig_type: str = 'iframe+png', filename: str = None, open_iframe: str = False)[source]

ONLY possible if there is ONE trace. If more than one trace is provided, only the first one (i.e. spec_id = 0) will get processed.

The retification in the spatial direction depends on ONLY the trace, while that in the dispersion direction depends on the parameters provided here.

Parameters:
  • spec_id (int (Default: None)) – The ID corresponding to the spectrum_oned object

  • upsample_factor (float (Default: 1)) – The upsampling rate for the correlation (10 times means precise to 1/10 of a pixel). The upsampling uses cubic spline that is adopted in the scipy.ndimage.zoom() function.

  • bin_size (int (Default: 6)) – Number of rows in a slice.

  • n_bin (int (Default: 10)) – Number of slices parallel to the trace to be correlated to to compute the distortion in the dispersion direction. (i.e. there are 10 // 2 = 5 slices below and above the trace.)

  • spline_order (int (Default: 3)) – The order of spline for resampling.

  • order (int (Default: 2)) – The order of polynomial to fit for the distortion in the dispersion direction

  • coeff (list or numpy.ndarray (Default: None)) – The polynomial coefficients for aligned the dispersion direction as a function of distance from the trace.

  • apply (bool (Default: False)) – Apply the rectification directly without checking.

  • display (bool (Default: False)) – Set to True to display disgnostic plot.

  • renderer (str (Default: 'default')) – plotly renderer options.

  • width (int/float (Default: 1280)) – Number of pixels in the horizontal direction of the outputs

  • height (int/float (Default: 720)) – Number of pixels in the vertical direction of the outputs

  • return_jsonstring (bool (Default: False)) – set to True to return json str that can be rendered by Plotly in any support language.

  • save_fig (bool (default: False)) – Save an image if set to True. Plotly uses the pio.write_html() or pio.write_image(). The support format types should be provided in fig_type.

  • fig_type (string (default: 'iframe+png')) – Image type to be saved, choose from: jpg, png, svg, pdf and iframe. Delimiter is ‘+’.

  • filename (str (Default: None)) – Filename for the output, all of them will share the same name but will have different extension.

  • open_iframe (bool (Default: False)) – Open the iframe in the default browser if set to True.

inspect_arc_spec(display: bool = True, renderer: str = 'default', width: int = 1280, height: int = 720, return_jsonstring: bool = False, save_fig: bool = False, fig_type: str = 'iframe+png', filename: str = None, open_iframe: bool = False, spec_id: int | list | numpy.ndarray = None)[source]

Display the extracted arc spectrum.

Parameters:
  • display (bool) – Set to True to display disgnostic plot.

  • renderer (str) – plotly renderer options.

  • width (int/float) – Number of pixels in the horizontal direction of the outputs

  • height (int/float) – Number of pixels in the vertical direction of the outputs

  • return_jsonstring (bool) – set to True to return json str that can be rendered by Plotly in any support language.

  • save_fig (bool (default: False)) – Save an image if set to True. Plotly uses the pio.write_html() or pio.write_image(). The support format types should be provided in fig_type.

  • fig_type (string (default: 'iframe+png')) – Image type to be saved, choose from: jpg, png, svg, pdf and iframe. Delimiter is ‘+’.

  • filename (str) – Filename for the output, all of them will share the same name but will have different extension.

  • open_iframe (bool) – Open the iframe in the default browser if set to True.

  • spec_id (int (Default: None)) – The ID corresponding to the spectrum_oned object

inspect_extracted_spectrum(spec_id: int | list | numpy.ndarray = None, display: bool = True, renderer: str = 'default', width: int = 1280, height: int = 720, return_jsonstring: bool = False, save_fig: bool = False, fig_type: str = 'iframe+png', filename: str = None, open_iframe: bool = False)[source]

Call this method to inspect the extracted spectrum.

Parameters:
  • spec_id (int (Default: None)) – The ID corresponding to the spectrum_oned object

  • display (bool) – Set to True to display disgnostic plot.

  • renderer (str) – plotly renderer options.

  • width (int/float) – Number of pixels in the horizontal direction of the outputs

  • height (int/float) – Number of pixels in the vertical direction of the outputs

  • return_jsonstring (bool) – set to True to return json str that can be rendered by Plotly in any support language.

  • save_fig (bool (default: False)) – Save an image if set to True. Plotly uses the pio.write_html() or pio.write_image(). The support format types should be provided in fig_type.

  • fig_type (string (default: 'iframe+png')) – Image type to be saved, choose from: jpg, png, svg, pdf and iframe. Delimiter is ‘+’.

  • filename (str) – Filename for the output, all of them will share the same name but will have different extension.

  • open_iframe (bool) – Open the iframe in the default browser if set to True.

inspect_extraction(display: bool = True, renderer: str = 'default', width: int = 1280, height: int = 720, return_jsonstring: bool = False, save_fig: bool = False, fig_type: str = 'iframe+png', filename: str = None, open_iframe: bool = False, spec_id: int | list | numpy.ndarray = None)[source]

Display the extracted spectrum/a.

Parameters:
  • display (bool (Default: False)) – Set to True to display disgnostic plot.

  • renderer (str (Default: 'default')) – plotly renderer options.

  • width (int/float (Default: 1280)) – Number of pixels in the horizontal direction of the outputs

  • height (int/float (Default: 720)) – Number of pixels in the vertical direction of the outputs

  • return_jsonstring (bool (Default: False)) – set to True to return json str that can be rendered by Plotly in any support language.

  • save_fig (bool (default: False)) – Save an image if set to True. Plotly uses the pio.write_html() or pio.write_image(). The support format types should be provided in fig_type.

  • fig_type (string (default: 'iframe+png')) – Image type to be saved, choose from: jpg, png, svg, pdf and iframe. Delimiter is ‘+’.

  • filename (str (Default: None)) – Filename for the output, all of them will share the same name but will have different extension.

  • open_iframe (bool (Default: False)) – Open the iframe in the default browser if set to True.

inspect_line_spread_function(spec_id: int | list | numpy.ndarray = None, display: bool = True, renderer: str = 'default', width: int = 1280, height: int = 720, return_jsonstring: bool = False, save_fig: bool = False, fig_type: str = 'iframe+png', filename: str = None, open_iframe: bool = False)[source]

Call this method to inspect the line spread function used to extract the spectrum.

Parameters:
  • spec_id (int (Default: None)) – The ID corresponding to the spectrum_oned object

  • display (bool) – Set to True to display disgnostic plot.

  • renderer (str) – plotly renderer options.

  • width (int/float) – Number of pixels in the horizontal direction of the outputs

  • height (int/float) – Number of pixels in the vertical direction of the outputs

  • return_jsonstring (bool) – set to True to return json str that can be rendered by Plotly in any support language.

  • save_fig (bool (default: False)) – Save an image if set to True. Plotly uses the pio.write_html() or pio.write_image(). The support format types should be provided in fig_type.

  • fig_type (string (default: 'iframe+png')) – Image type to be saved, choose from: jpg, png, svg, pdf and iframe. Delimiter is ‘+’.

  • filename (str) – Filename for the output, all of them will share the same name but will have different extension.

  • open_iframe (bool) – Open the iframe in the default browser if set to True.

inspect_residual(log: bool = True, display: bool = True, renderer: str = 'default', width: int = 1280, height: int = 720, return_jsonstring: bool = False, save_fig: bool = False, fig_type: str = 'iframe+png', filename: str = None, open_iframe: bool = False)[source]

Display the reduced image with a supported plotly renderer or export as json strings.

Parameters:
  • log (bool) – Log the ADU count per second in the display. Default is True.

  • display (bool) – Set to True to display disgnostic plot.

  • renderer (str) – plotly renderer options.

  • width (int/float) – Number of pixels in the horizontal direction of the outputs

  • height (int/float) – Number of pixels in the vertical direction of the outputs

  • return_jsonstring (bool (Default: False)) – set to True to return json string that can be rendered by Plotly in any support language.

  • save_fig (bool (default: False)) – Save an image if set to True. Plotly uses the pio.write_html() or pio.write_image(). The support format types should be provided in fig_type.

  • fig_type (string (default: 'iframe+png')) – Image type to be saved, choose from: jpg, png, svg, pdf and iframe. Delimiter is ‘+’.

  • filename (str (Default: None)) – Filename for the output, all of them will share the same name but will have different extension.

  • open_iframe (bool (Default: False)) – Open the save_iframe in the default browser if set to True.

Return type:

JSON strings if return_jsonstring is set to True.

inspect_trace(display: bool = True, renderer: str = 'default', width: int = 1280, height: int = 720, return_jsonstring: bool = False, save_fig: bool = False, fig_type: str = 'iframe+png', filename: str = None, open_iframe: bool = False)[source]

Display the trace(s) over the image.

Parameters:
  • display (bool (Default: False)) – Set to True to display disgnostic plot.

  • renderer (str (Default: 'default')) – plotly renderer options.

  • width (int/float (Default: 1280)) – Number of pixels in the horizontal direction of the outputs

  • height (int/float (Default: 720)) – Number of pixels in the vertical direction of the outputs

  • return_jsonstring (bool (Default: False)) – set to True to return json str that can be rendered by Plotly in any support language.

  • save_fig (bool (default: False)) – Save an image if set to True. Plotly uses the pio.write_html() or pio.write_image(). The support format types should be provided in fig_type.

  • fig_type (string (default: 'iframe+png')) – Image type to be saved, choose from: jpg, png, svg, pdf and iframe. Delimiter is ‘+’.

  • filename (str (Default: None)) – Filename for the output, all of them will share the same name but will have different extension.

  • open_iframe (bool (Default: False)) – Open the iframe in the default browser if set to True.

Returns:

  • JSON-string if return_jsonstring is True, otherwise only an image is

  • displayed

remove_trace(spec_id: int = None)[source]
Parameters:

spec_id (int) – The ID corresponding to the spectrum_oned object

save_csv(output: str = '*', filename: str = None, overwrite: bool = False, recreate: bool = False)[source]

Save the reduced image to disk. Each trace is saved into a separate file.

Parameters:
  • output (String (Default: "*")) –

    Type of data to be saved, the order is fixed (in the order of the following description), but the options are flexible. The input strs are delimited by “+”,

    trace: 2 HDUs

    Trace, and trace width (pixel)

    count: 3 HDUs

    Count, uncertainty, and sky (pixel)

    weight_map: 1 HDU

    Weight (pixel)

    arc_spec: 1 HDU

    1D arc spectrum

  • filename (str (Default: TwoDSpecExtracted)) – Filename for the output, all of them will share the same name but will have different extension.

  • overwrite (bool) – Default is False.

  • recreate (bool (Default: False)) – Set to True to overwrite the FITS data and header before exporting as CSV.

save_fits(output: str = '*', filename: str = None, overwrite: bool = False, recreate: bool = False, empty_primary_hdu: bool = True)[source]

Save the reduced image to disk. Each trace is saved into a separate file.

Parameters:
  • output (String (Default: "*")) –

    Type of data to be saved, the order is fixed (in the order of the following description), but the options are flexible. The input strs are delimited by “+”,

    trace: 2 HDUs

    Trace, and trace width (pixel)

    count: 3 HDUs

    Count, uncertainty, and sky (pixel)

    weight_map: 1 HDU

    Weight (pixel)

    arc_spec: 1 HDU

    1D arc spectrum

  • filename (str (Default: TwoDSpecExtracted)) – Filename for the output, all of them will share the same name but will have different extension.

  • overwrite (bool) – Default is False.

  • recreate (bool (Default: False)) – Set to True to overwrite the FITS data and header.

  • empty_primary_hdu (bool (Default: True)) – Set to True to leave the Primary HDU blank

set_airmass(airmass: float | str = None)[source]

Set the airmass of the image.

Parameters:

airmass (str, float, int or None (Default: None)) – If a string is provided, it will be treated as a header keyword for the airmass value. Float or int will be used as the airmass value. If None is provided, the header will be searched with the set of default airmass keywords.

set_airmass_keyword(keyword_list: list, append: bool = False, update: bool = True)[source]

Set the airmass keyword list.

Parameters:
  • keyword_list (list) – List of keyword (string).

  • append (bool (Default: False)) – Set to False to overwrite the current list.

  • update (bool (Default: True)) – Set to True to search for the readnoise after the new list is provided.

set_arc_header(header: astropy.io.fits.Header)[source]

Adding the header for the arc.

Parameters:

header (FITS header (deafult: None)) – An astropy.io.fits.Header object. This is not used if arc is a PrimaryHDU or ImageHDU.

set_exptime(exptime: float | str = None)[source]

Set the exptime of the image.

Parameters:

exptime (str, float, int or None (Default: None)) – If a string is provided, it will be treated as a header keyword for the exptime value. Float or int will be used as the exptime value. If None is provided, the header will be searched with the set of default exptime keywords.

set_exptime_keyword(keyword_list: list, append: bool = False, update: bool = True)[source]

Set the exptime keyword list.

Parameters:
  • keyword_list (list) – List of keyword (string).

  • append (bool (Default: False)) – Set to False to overwrite the current list.

  • update (bool (Default: True)) – Set to True to search for the readnoise after the new list is provided.

set_gain(gain: float | str = None)[source]

Set the gain of the image.

Parameters:

gain (str, float, int or None (Default: None)) – If a string is provided, it will be treated as a header keyword for the gain value. Float or int will be used as the gain value. If None is provided, the header will be searched with the set of default gain keywords.

set_gain_keyword(keyword_list: list, append: bool = False, update: bool = True)[source]

Set the gain keyword list.

Parameters:
  • keyword_list (list) – List of keyword (string).

  • append (bool (Default: False)) – Set to False to overwrite the current list.

  • update (bool (Default: True)) – Set to True to search for the readnoise after the new list is provided.

set_header(header: astropy.io.fits.Header)[source]

Set/replace the header.

Parameters:

header (astropy.io.fits.header.Header) – FITS header from a single HDU.

set_properties(saxis: int = None, variance: int | float = None, spatial_mask: numpy.ndarray = None, spec_mask: numpy.ndarray = None, flip: bool | int = None, cosmicray: bool | int = None, gain: int | float = -1, readnoise: int | float = -1, fsmode: str = None, psfmodel: str = None, seeing: int | float = -1, exptime: int | float = -1, airmass: int | float = -1, verbose: bool = None, **kwargs)[source]

The read noise, detector gain, seeing and exposure time will be automatically extracted from the FITS header if it conforms with the IAUFWG FITS standard.

Currently, there is no automated way to decide if a flip is needed.

The supplied file should contain 2 or 3 columns with the following structure:

column 1: one of bias, dark, flat or light
column 2: file location
column 3: HDU number (default to 0 if not given)

If the 2D spectrum is

blue

red

saxis

flip

left

right

1

False

right

left

1

True

top

bottom

0

False

bottom

top

0

True

Spectra are sorted by their brightness. If there are multiple spectra on the image, and the target is not the brightest source, use at least the number of spectra visible to eye and pick the one required later. The default automated outputs is the brightest one, which is the most common case for images from a long-slit spectrograph.

Parameters:
  • saxis (int (Default: 1)) – dispersion direction, 0 for vertical, 1 for horizontal.

  • variance (2D numpy array (M, N)) – The per-pixel-variance of the frame.

  • spatial_mask (1D numpy array (size: N. Default is (1,))) – Mask in the spatial direction, can be the indices of the pixels to be included (size <N) or a 1D numpy array of True/False (size N)

  • spec_mask (1D numpy array (Size: M. Default: (1,))) – Mask in the dispersion direction, can be the indices of the pixels to be included (size <M) or a 1D numpy array of True/False (size M)

  • flip (bool (Deafult: False)) – If the frame has to be left-right flipped, set to True.

  • cosmicray (bool (Default: True)) – Set to True to remove cosmic rays, this directly alter the reduced image data. We only explicitly include the 4 most important parameters in this function: gain, readnoise, fsmode, and psfmodel, the rest can be configured with kwargs.

  • gain (float (Deafult: -1)) – Gain of the detector in unit of electron per photon, not important if noise estimation is not needed. Negative value means “pass”, i.e. do nothing. None means grabbing from the header, though if it is not found, it is set to 1.0.

  • readnoise (float (Deafult: -1)) – Readnoise of the detector in unit of electron, not important if noise estimation is not needed. Negative value means “pass”, i.e. do nothing. None means grabbing from the header, though if it is not found, it is set to 0.0.

  • fsmode (str (Default: None. Use 'convolve' if not set.)) – Method to build the fine structure image: median: Use the median filter in the standard LA Cosmic algorithm. convolve: Convolve the image with the psf kernel to calculate the fine structure image.

  • psfmodel (str (Default: None. Use 'gaussy' if not set.)) – Model to use to generate the psf kernel if fsmode is convolve and psfk is None. The current choices are Gaussian and Moffat profiles. ‘gauss’ and ‘moffat’ produce circular PSF kernels. The gaussx and gaussy produce Gaussian kernels in the x and y directions respectively. gaussxy and gaussyx apply the Gaussian kernels in the x then the y direction, and first y then x direction, respectively.

  • seeing (float (Deafult: -1)) – Seeing in unit of arcsec, use as the first guess of the line spread function of the spectra. Negative value means “pass”, i.e. do nothing. None means grabbing from the header, though if it is not found, it is set to 1.0.

  • exptime (float (Deafult: -1)) – Esposure time for the observation, not important if absolute flux calibration is not needed. Negative value means “pass”, i.e. do nothing. None means grabbing from the header, though if it is not found, it is set to 1.0.

  • airmass (float (Default: -1)) – The airmass where the observation carries out. Negative value means “pass”, i.e. do nothing. None means grabbing from the header, though if it is not found, it is set to 0.0.

  • verbose (bool) – Set to False to suppress all verbose warnings, except for critical failure.

  • **kwargs

    Extra keyword arguments for the astroscrappy.detect_cosmics: https://astroscrappy.readthedocs.io/en/latest/api/ astroscrappy.detect_cosmics.html The default setting is:

    astroscrappy.detect_cosmics(indat, inmask=None, bkg=None,
        var=None, sigclip=4.5, sigfrac=0.3, objlim=5.0, gain=1.0,
        readnoise=6.5, satlevel=65536.0, niter=4, sepmed=True,
        cleantype='meanmask', fsmode='median', psfmodel='gauss',
        psffwhm=2.5, psfsize=7, psfk=None, psfbeta=4.765,
        verbose=False)
    

set_readnoise(readnoise: float | str = None)[source]

Set the readnoise of the image.

Parameters:

readnoise (str, float, int or None (Default: None)) – If a string is provided, it will be treated as a header keyword for the readnoise value. Float or int will be used as the readnoise value. If None is provided, the header will be searched with the set of default readnoise keywords.

set_readnoise_keyword(keyword_list: list, append: bool = False, update: bool = True)[source]

Set the readnoise keyword list.

Parameters:
  • keyword_list (list) – List of keyword (string).

  • append (bool (Default: False)) – Set to False to overwrite the current list.

  • update (bool (Default: True)) – Set to True to search for the readnoise after the new list is provided.

set_seeing(seeing: float | str = None)[source]

Set the seeing of the image.

Parameters:

seeing (str, float, int or None (Default: None)) – If a string is provided, it will be treated as a header keyword for the seeing value. Float or int will be used as the seeing value. If None is provided, the header will be searched with the set of default seeing keywords.

set_seeing_keyword(keyword_list: list, append: bool = False, update: bool = True)[source]

Set the seeing keyword list.

Parameters:
  • keyword_list (list) – List of keyword (string).

  • append (bool (Default: False)) – Set to False to overwrite the current list.

  • update (bool (Default: True)) – Set to True to search for the readnoise after the new list is provided.