twodfdr core classes¶

Parameter Handling¶

class twodfdr.args.TdfArgs(*args, **kwargs)¶

Python bindings to the args structure that carries parameters used by twodfdr recipes.

Notes

The params supplied may be either a cpl.ui.ParameterList or a dict generated from a cpl.ui.ParameterList.

Parameters:

params (cpl.ui.ParameterList or dict, optional) – A parameter list with the parameters to import.
idx (str, optional) – The idx file to import args from.

See also

TdfArgs.as_dict: Converts a parameter list to a dict.

static as_dict(params)¶

Converts a parameter list to a dict.

Parameters:: params (cpl.ui.ParameterList) – A parameter list to convert.
Returns:: A dictionary of parameter names and their values.
Return type:: dict

getc(name, default=None)¶

Get a string valued parameter.

Parameters:

name (str) – The name of the parameter.
default (str, optional) – The default value of the parameter.

Returns:

The value of the parameter.

Return type:

str

getd(name, default=None)¶

Get a double valued parameter.

Parameters:

name (str) – The name of the parameter.
default (double, optional) – The default value of the parameter.

Returns:

The value of the parameter.

Return type:

double

geti(name, default=None)¶

Get an integer valued parameter.

Parameters:

name (str) – The name of the parameter.
default (int, optional) – The default value of the parameter.

Returns:

The value of the parameter.

Return type:

int

getl(name, default=None)¶

Get a boolean valued parameter.

Parameters:

name (str) – The name of the parameter.
default (bool, optional) – The default value of the parameter.

Returns:

The value of the parameter.

Return type:

bool

getr(name, default=None)¶

Get a float valued parameter.

Parameters:

name (str) – The name of the parameter.
default (float, optional) – The default value of the parameter.

Returns:

The value of the parameter.

Return type:

float

parse_params(params)¶

Parse all the items from a parameter list.

Parameters:: params (cpl.ui.ParameterList or dict)

put(name, val)¶

Set a parameter based on its detected type.

Parameters:

name (str) – The name of the parameter.
val (str) – The value of the parameter.

putc(name, val)¶

Set a string valued parameter.

Parameters:

name (str) – The name of the parameter.
val (str) – The value of the parameter.

putd(name, val)¶

Set a double valued parameter.

Parameters:

name (str) – The name of the parameter.
val (double) – The value of the parameter.

puti(name, val)¶

Set an integer valued parameter.

Parameters:

name (str) – The name of the parameter.
val (int) – The value of the parameter.

putl(name, val)¶

Set a boolean valued parameter.

Parameters:

name (str) – The name of the parameter.
val (bool) – The value of the parameter.

putr(name, val)¶

Set a float valued parameter.

Parameters:

name (str) – The name of the parameter.
val (float) – The value of the parameter.

class twodfdr.config.AAOmega(*args, **kwargs)¶

Defines an AAOmega configuration.

Parameters:: grating (str, optional) – The desired grating (e.g. 580V).

static gratings()¶

Returns a list of gratings with their own configurations.

Returns:: A list of gratings.
Return type:: list of str

class twodfdr.config.AAOmegaConfig(*args, **kwargs)¶

setup_combine()¶

AAOmega Specific Combination Parameters.

Notes

Sourced from TAB_CombineAAOmega.idx.

class twodfdr.config.SAMI(*args, **kwargs)¶

Defines a SAMI configuration.

Parameters:: grating (str, optional) – The desired grating (e.g. 1000R).

class twodfdr.config.TdfConfig(*args, **kwargs)¶

A replacement for 2dfdr idx files.

Notes

This parent class contains the base parameters common to all instrument profiles. Instrument profiles inherit from this class and can adjust the internal parameterlist as required.

static oenum(params, n, o, dval, a, d)¶

Adds a ParameterEnum parameter to a ParameterList while accounting for an override value.

Parameters:

params (cpl.ui.ParameterList) – The parameter list.
n (str) – The name of the parameter.
o (str) – The override value of the parameter. If None and n is missing from params, the value is set to the dval value.
dval (str) – The default value to use if o is None and n is missing from params.
a (tuple of str) – All values of the parameter.
d (str) – The description of the parameter.

static orange(params, n, o, dval, lo, hi, d)¶

Adds a ParameterRange parameter to a ParameterList while accounting for an override value.

Parameters:

params (cpl.ui.ParameterList) – The parameter list.
n (str) – The name of the parameter.
o (int or double) – The override value of the parameter. If None and n is missing from params, the value is set to the dval value.
dval (int or double) – The default value to use if o is None and n is missing from params.
lo (int or double) – The minimum value of the parameter.
hi (int or double) – The maximum value of the parameter.
d (str) – The description of the parameter.

static oval(params, n, o, dval, d)¶

Adds a ParameterValue parameter to a ParameterList while accounting for an override value.

Parameters:

params (cpl.ui.ParameterList) – The parameter list.
n (str) – The name of the parameter.
o (str, bool, int or double) – The override value of the parameter. If None and n is missing from params, the value is set to the dval value.
dval (str, bool, int or double) – The default value to use if o is None and n is missing from params.
d (str) – The description of the parameter.

enum(n, v, a, d)¶

Adds a ParameterEnum parameter to a ParameterList.

Parameters:

n (str) – The name of the parameter.
v (str) – The value of the parameter.
a (tuple of str) – All values of the parameter.
d (str) – The description of the parameter.

range(n, v, lo, hi, d)¶

Adds a ParameterRange parameter to a ParameterList.

Parameters:

n (str) – The name of the parameter.
v (int or double.) – The value of the parameter.
lo (int or double.) – The minimum value of the parameter.
hi (int or double.) – The maximum value of the parameter.
d (str) – The description of the parameter.

setup_calib()¶

Wavelength and Flux Calibration.

Notes

Sourced from TAB_Calib.idx.

abstractmethod setup_combine()¶

Parameters Controlling Combination of Reduced Files.

Notes

To be implemented by subclasses.

setup_constants()¶: Constants had no widget in drcontrol GUI to change.

setup_experimental()¶

Setup Experimental Parameters.

Notes

Sourced from RnDTab.idx.

setup_extraction()¶

Extraction Parameters.

Notes

Sourced from TAB_Extraction.idx.

setup_general()¶

General Data Reduction Options.

Notes

Sourced from TAB_General.idx.

setup_plots()¶

Turn off plotting in all cases.

Notes

Sourced from TAB_Plots.idx. Adding these parameters just in case they are retrieved, even though we are not interested in generating the plots.

setup_sky()¶

Sky Subtraction Parameters.

Notes

Sourced from TAB_Sky.idx.

setup_velcor()¶

Velocity Corrections To Spectral Data.

Notes

Sourced from TAB_VelCor.idx.

val(n, v, d)¶

Adds a ParameterValue parameter to a ParameterList.

Parameters:

n (str) – The name of the parameter.
v (str, bool, int or double) – The value of the parameter.
d (str) – The description of the parameter.

property grating¶

Returns the selected grating.

Returns:: The grating name (e.g. 580V).
Return type:: str

property params¶

Accesses the ParameterList.

Returns:: The parameter list.
Return type:: cpl.ui.ParameterList

File Input/Output¶

class twodfdr.io.Tdfio(fid, status, fmode, ftype, fname, *args, **kwargs)¶

Python bindings to the 2dfdr TDFIO module.

Parameters:

fid (int) – The internal FITS identifier for the file.
status (int) – The global status
fmode (TdfioMode) – The mode of the opened FITS file.
ftype (TdfioType) – The type of FITS file to open.

Notes

The constructor for Tdfio is not typically needed by the user. Use Tdfio.open() or Tdfio.create_by_copy() to create Tdfio objects instead.

See also

twodfdr.io.Tdfio.open: Opens a 2dfdr FITS file.
twodfdr.io.Tdfio.create_by_copy: Creates a new STD type (destination) object by copying a source object.
twodfdr.io.Tdfio.TdfioMode: Mode to be used for opening FITS files.
twodfdr.io.Tdfio.TdfioType: File type to be used for opening FITS files.

classmethod create_by_copy(ifname, ofname)¶

Creates a new TdfioType.STD type (destination) object by copying a source object.

Parameters:

ifname (str) – Name of source input file. File is opened and CLOSED by this routine.
ofname – Name of output file. This file is created and filled by this routine. It is left open and made accessible via the returned instance of Tdfio.

Notes

All HDUs present in the source object are copied to the new destination object.

The source object must be either type TdfioType.RAW or TdfioType.STD. It must have at least a primary image HDU and a fibre table HDU named either ‘FIBRES’ or ‘FIBRES_IFU’.

The new object will be type TdfioType.STD, and will have at least these three HDUs in the following order:

[0] IMAGE (primary) Copied from source object. The destination image data will be rotated if the source file is a 6df raw file.
[1] VARIANCE. Ifa variance array is present in the source object (never in RAW files) variance data is copied from source object.
[2] FIBRE TABLE in FITS binary table. Copied from source object. See docs/2dfdr_file_format.html (2dfdr File Format).

The source object may or may not have keyword header scale factors BSCALE and BZERO, and read data is affected accordingly. Raw files normally have BZERO set to 32768 and this offset is applied when the image data is read. Data is written to the destination before it has a keyword header and data is therefore not scaled.

Returns:: A new Tdfio object with the output file opened with mode TdfioMode.R and type TdfioType.STD.
Return type:: Tdfio

classmethod open(fname, fmode, ftype)¶

Opens a 2dfdr FITS file.

Parameters:

fname (str) – The path to the FITS file to open.
fmode (TdfioMode) – The mode to be used to open the FITS file.
ftype (TdfioType) – The type of FITS file to open.

Notes

The file is opened in 1 of 3 modes (TdfioMode.R (READ), TdfioMode.RW (UPDATE) or TdfioMode.W (WRITE)) determined from the fmode argument.

The file is opened as 1 of 4 types (TdfioType.RAW, TdfioType.STD, TdfioType.TLM, or TdfioType.DIAG) determined from the ftype argument. The ftype is used only in this subroutine.

Returns:: A new Tdfio object with the opened FITS file.
Return type:: Tdfio

static astropy2tdf(data)¶

Converts an astropy.fits data array to match the orientation expected by Tdfio.

Parameters:: data (numpy.ndarray) – The data array read from the FITS file using astropy.fits (the data attribute of the HDU).
Returns:: The data array rotated 90 degrees and flipped along axis=0 to match the orientation expected by Tdfio.
Return type:: numpy.ndarray

static delete(fname)¶

Delete a file.

Parameters:: fname (str) – Name of the file to be deleted.
Returns:: The status flag after deletion.
Return type:: int

Notes

This is a static method.

static fib_copy(tin, tout)¶

Copies the entire fibres table from the source FITS file object to the destination object.

Parameters:

tin (Tdfio) – Tdfio object for the input FITS file.
tout (Tdfio) – Tdfio object for the output FITS file.

Notes

Destination fibre table is named either ‘FIBRES’ or ‘FIBRES_IFU’ to remove any extraneous prefix like ‘STRUCT.MORE.FIBRES’.

Returns:: The status flag after the copy operation.
Return type:: int

static fib_copy_row(tin, rin, tout, rout)¶

Copies a fibre table row from one frame to another.

Parameters:

tin (Tdfio) – Tdfio object for the input FITS file.
rin (int) – Index of fibre table entry in input file.
tout (Tdfio) – Tdfio object for the output FITS file.
rout (int) – Index of fibre table entry in output file.

Notes

This subroutine is used when 2dfdr combines reduced spectra files. During this process it may be necessary to add new fibre spectra to the data and corresponding new rows to the fibre table in the combined output file.

Returns:: The status flag after the copy operation.
Return type:: int

static header_copy(tin, tout)¶

Copies the primary header keywords from the input Tdfio object to the output object.

Parameters:

tin (Tdfio) – Tdfio object for the input FITS file.
tout (Tdfio) – Tdfio object for the output FITS file.

Returns:

The status flag after deletion.

Return type:

int

static replace_bad_pixels(data, fill=False, fill_value=0)¶

Replace bad pixel values, originally flagged as -9.1191291391491E-36, for nan.

Parameters:

data (numpy.ndarray) – The data array read from the FITS file (the data attribute of the HDU).
fill (bool) – If True, it will replace bad pixel values with fill_value.
fill_value (array_like, optional)

Returns:

A copy of data but with bad pixel values replaced with the fill_value.

Return type:

numpy.ndarray

static suffix(fname, suf)¶

Adds a suffix to a FITS filename.

Parameters:

fname (str) – The FITS filename to be altered (e.g. 21apr10008.fits).
suf (str) – The suffix to be added (e.g. ‘red’).

Notes

The input filename extension may be .FTS, .FITS, .fts or .fits. The output filename extension will always be .fits.

Returns:: The filename with the suffix suf added (e.g. 21apr10008red.fits).
Return type:: str

static tdf2astropy(data)¶

Converts a Tdfio data array to match the orientation expected by astropy.fits.

Parameters:: data (numpy.ndarray) – The data array read from the FITS file using Tdfio (e.g. using Tdfio.read).
Returns:: The data array rotated -90 degrees and flipped along axis=0 to match the orientation expected by astropy.fits.
Return type:: numpy.ndarray

axis_exists()¶

Determines whether axis information exists for the given object.

Notes

Axis information exists if the CRVALn, CDELTn and CRPIXn keywords exist for extensions n = 1 and 2. See axis_read for details.

Return type:: bool

axis_read(axis)¶

Reads axis data from the given object into a numpy.ndarray with double precision.

Parameters:: axis (int) – Number of axis whose vector is to be read, either 1 (abscissa) or 2 (ordinate).
Returns:: A numpy.ndarray of double precision values containing the axis data. If axis is 1, this corresponds to the wavelength at the centre of each pixel in angstroms. If axis is 2, this correpsonds to the fibre number (ordinate).
Return type:: numpy.ndarray

Notes

2dfdr previously used the Starlink Extensible N-Dimension File format (NDF). NDF used two vectors to represent the pixel abscissa and ordinate of the image. This same capability is assumed by callers of these routines.

FITS inherently provides only a limited axis facility, and initially (at least) this facility is used to provide a NDF-like capability. Under FITS axis information is defined to be linear. This is sufficient because although 2dfdr uses vectors to hold the information they always have uniform spacing.

The FITS facility uses the FITS keywords CRVALn, CRPIXn, CDELTn and NAXISn where n is the axis, either 1 (abscissa), or 2 (ordinate). These same keywords are used by external FITS viewers such as fv and ds9 to describe the axes. FITS keywords CTYPEn and CUNITn complete the axes description by supplying the label and units, respectively.

The same algorithms employed by the Starlink NDF and FITS converters ndf2fits and fits2ndf are used here, and the code was taken in (large) part from the Starlink application/convert/libcof/cof_camax.f source file.

Need to know a few things:

1 The axis values correspond to the centre of each pixel
2 In FITS representation the first pixel has its centre at (1,1) i.e. it extends from 0.5 to 1.5.

axis_wcs_write(axis, data)¶

Given a (uniform) axis vector, derives the WCS keyword values, and writes them to the given object.

Parameters:

axis (int) – Number of axis whose vector is to be read, either 1 (abscissa) or 2 (ordinate).
data (numpy.ndarray) – Vector containing axis data to write.

axis_write(axis, crval, cdelt, crpix)¶

Writes given values for CRVALn, CDELTn and CRPIXn to the given object.

Parameters:

axis (int) – Number of axis to write, either 1 (abscissa) or 2 (ordinate).
crval (double) – Co-ordinate value of axis.
cdelt (double) – Co-ordinate increment along axis.
crpix (double) – Reference pixel along axis.

close()¶: Closes a FITS file and releases its internal FITS identifier.

fib_exists_delcor()¶

Returns whether the DELCOR column exists in the fibre table.

Notes

The DELCOR column is added to data products if the following parameters are specified: COR2MPP (True) and VELCOR (True).

Returns:: True if the DELCOR column exists in the fibre table. False otherwise.
Return type:: bool

fib_exists_velcor()¶

Returns whether the VELCOR column exists in the fibre table.

Notes

The VELCOR column is added to data products if the following parameters are specified: COR2MPP (False) and VELCOR (True).

Returns:: True if the VELCOR column exists in the fibre table. False otherwise.
Return type:: bool

fib_read_delcor()¶

Returns the DELCOR velocity corrections from the fibre table.

Returns:: A numpy.ndarray with the velocity corrections. The size of the array reflects the number of velocity corrections found.
Return type:: numpy.ndarray

fib_read_mags()¶

Returns the magnitudes from the fibre table.

Notes

Reads the fibre table and returns the object magnitudes for all fibres in a numpy.ndarray. An error message is sent and status is set if the table is not found.

Returns:: A numpy.ndarray with the fibre magnitudes. The size of the array reflects the number of magnitudes found.
Return type:: numpy.ndarray

fib_read_names()¶

Returns the object names from the fibre table.

Notes

Reads the fibre table and returns the object names for all fibres in a numpy.ndarray. An error message is sent and status is set if the table is not found.

Returns:: A numpy.ndarray with the fibre names. The size of the array reflects the number of names found.
Return type:: numpy.ndarray

fib_read_pivot()¶

Returns the pivot indices from the fibre table.

Notes

Reads the fibre table and returns the pivot number values for all fibres in a numpy.ndarray. An error message is sent and status is set if the table is not found.

Returns:: A numpy.ndarray with the pivot indices. The size of the array reflects the number of pivot indices found.
Return type:: numpy.ndarray

fib_read_radec()¶

Returns the Right Ascensions and Declinations from the fibre table.

Notes

Reads the fibre table and returns the RA and DEC for all fibres in separate numpy.ndarrays. The values are in decimal degrees and are double precision. An error message is sent and status is set if the table is not found.

Returns:: The first component being a numpy.ndarray of RA in degrees and double precision. The second component being a numpy.ndarray of DEC in degrees and double precision. The size of the arrays reflect the number of RA and DEC values found.
Return type:: tuple

fib_read_types()¶

Returns the fibre types from the fibre table.

Notes

Reads the fibre table and returns the types of all fibres in a numpy.ndarray. Each type is a single character and gives the fibre usage for the corresponding fibre. An error message is sent and status is set if the table is not found.

The fibre types are as follows:

‘F’ - Fiducial star, aka guide fibre.
‘N’ - Not in use, i.e. broken, dead or no fibre. These fibres will not be on the focus plate but may not be dead, and hence may see some vignetted light from a random sky
position.
‘P’ - Program (science) object.
‘S’ - Sky
‘U’ - Unallocated, unused. These fibres were not part of the fibre configuration. In previous observations they may or may not be on the focus plate. Currently they are always parked at the plate edge. If they are on the plate they see a random spot in the sky. If they are NOT on the plate they are likely to see some vignetted light from a random sky position.
‘X’ - P type that is also a calibration target.
‘Y’ - P type that is also a calibration target.

Returns:: A numpy.ndarray with the fibre names. The size of the array reflects the number of fibre types found.
Return type:: numpy.ndarray

fib_read_velcor()¶

Returns the VELCOR velocity corrections from the fibre table.

Returns:: A numpy.ndarray with the velocity corrections. The size of the array reflects the number of velocity corrections found.
Return type:: numpy.ndarray

fib_read_xy()¶

Returns the field plate coordinates from the fibre table.

Notes

Reads the fibre table and returns the X and Y field plate positions for all fibres in separate numpy.ndarrays. An error message is sent and status is set if the table is not found.

Returns:: The first component being a numpy.ndarray of X positions in microns. The second component being a numpy.ndarray of Y positions in microns. The size of the arrays reflect the number of X and Y values found.
Return type:: tuple

fib_read_xygpos()¶

Returns the IFU X and Y positions from the fibre table.

Notes

Reads the X and Y positions in the Integrated Field Unit (IFU) grid for all fibres. The positions are returned in separate numpy.ndarrays. An error message is sent and status is set if the table is not found.

This can only be used with the FIBRES_IFU fibre table.

Returns:: The first component being a numpy.ndarray of X positions in microns. The second component being a numpy.ndarray of Y positions in microns. The size of the arrays reflect the number of X and Y values found.
Return type:: tuple

fib_set_size(nrows)¶

Set number of rows (one for each fibre) in fibre table.

Parameters:: nrows (int) – Number of rows to be in the fibre table.

Notes

Rows are added at table end if table grows in size, or removed from table end if table shrinks in size. Does nothing if table size is unchanged.

This subroutine is used when 2dfdr combines spectra files. Since different objects may be included in the different observations being combined, the number of spectra in the output combined file may increase.

fib_type()¶

Identifies if there is a fibre table and if one, its type.

Notes

Leaves current HDU at table if it was found.

Return type:: TdfioFibType

fib_write_delcor(data)¶

Writes fibres table DELCOR column with the given vector.

Notes

If the DELCOR column already exists, the values are replaced. Otherwise, a new column is added.

Parameters:: data (numpy.ndarray) – Vector containing velocity corrections to write.

fib_write_exptime(data)¶

Writes fibre table exposure time column with given vector.

Notes

First add an exposure time column to the fibre table if not already present. Then fill the column with the given values.

This subroutine is used when 2dfdr combines spectra files. Since different input observations in the combine operation may have different exposure times and some objects may be repeated in those observations and some not, fibre spectra in the output file may have different exposure times.

Parameters:: data (numpy.ndarray) – Vector containing exptime data to write.

fib_write_types(data)¶

Writes fibres table fibre types with the given vector.

Parameters:: data (numpy.ndarray) – Vector containing exptime data to write.

fib_write_velcor(data)¶

Writes fibres table VELCOR column with the given vector.

Notes

If the VELCOR column already exists, the values are replaced. Otherwise, a new column is added.

Parameters:: data (numpy.ndarray) – Vector containing velocity corrections to write.

get_size()¶

Returns file image and variance size.

Returns:: The components being the first (i.e. width) and second (i.e. height) dimensions.
Return type:: tuple

hist_write(text)¶

Inserts a history record into the given NDF object.

Parameters:: text (str) – History text to be written.

key_delete(key)¶

Removes a header keyword.

Parameters:: key (str) – The FITS header keyword to be removed.

Notes

Write is always done to the primary HDU.

key_exists(key)¶

Determines whether a FITS header keyword is present.

Returns:: True if key is in the FITS header. Otherwise False.
Return type:: bool

key_read(key, ktype)¶

Reads a FITS header keyword if present.

Parameters:

key (str) – The name of the FITS header keyword to read.
ktype (TdfioKeyType) – The type of the FITS header keyword to read.

Returns:

Tuple with first component being int, double, str or bool, and the second component being the FITS header keyword comment.

Return type:

tuple

key_write(key, ktype, kval, kcomment=None)¶

Writes a FITS header keyword.

Parameters:

key (str) – The name of the FITS header keyword to write.
ktype (TdfioKeyType) – The type of the FITS header keyword to read.
kval (int, double, str or bool) – The FITS header keyword value to write.
kcomment (str, optional) – The FITS header keyword comment to write.

Notes

Write is always done to the primary HDU.

nod_shuffle()¶

Determines data object’s nod and shuffle status.

Notes

The are two N&S modes used with AAOmega.

Nod and Shuffle (aka Classic Nod and Shuffle) Every other fibre is blanked out and the remaining fibres are alternately shifted to the blanked fibre position, SHIFT= ~10 pixels.
Mini-Shuffle. All fibres are used and alternately shifted into a position between adjacent fibres (spectra), SHIFT= ~4 pixels. This mode is also called micro-shuffle, especially by Rob.

Early in AAOmega observing it was discovered the red and blue detectors used different amounts of time during initialisation. Since the system shutter is opened by the detector when initialisation is complete meant the shutter opened too quickly for the slower detector. A workaround was created by always running in nod-and-shuffle mode and using the software control to open the system shutter at the proper time. This has the side effect of always setting the METHOD keyword to N&S mode (“CCD Charge shuffling technique”).

Return type:: TdfioNSType

overscan_exists()¶

Determines whether overscan region information exists for the given object.

Notes

Overscan information exists within the following keywords: DETECTXS DETECTXE DETECTYS DETECTYE WINDOXS1 WINDOXE1 WINDOYS1 WINDOYE1 WINDOXS2 WINDOXE2 WINDOYS2 WINDOYE2

Returns:: Returns True if overscan region information exists, otherwise False.
Return type:: bool

Notes

Currently the only instrument without these keywords is TAIPAN as this is still in the design process. For now there is no overscan region in the Taipan.

pixcal_delete()¶

Deletes the PIXEL CALIBRATION array HDUs.

See also

twodfdr.io.Tdfio.pixcal_exists: Returns whether axis information WAVE_LHS or WAVE_RHS exists for the given object.
twodfdr.io.Tdfio.pixcal_read: Read axis information WAVE_LHS and WAVE_RHS exists for the given object.
twodfdr.io.Tdfio.pixcal_read_bincentres: Read wavelength data and calculated the centres of each bin.
twodfdr.io.Tdfio.pixcal_read_binwidths: Read wavelength data and calculated the binwidth of each bin.
twodfdr.io.Tdfio.pixcal_write_bins: Writes wavelength data using the bins data.
twodfdr.io.Tdfio.pixcal_write: Writes the wavelength calibrations for the edges of each pixel for each fibre in a FITS file

pixcal_exists()¶

Returns whether axis information WAVE_LHS or WAVE_RHS exists in the FITS file.

Returns:: Returns True if the object has WAVE_LHS or WAVE_RHS information, otherwise False. Axis information exists if the CRVALn, CDELTn and CRPIXn keywords exist for n = 1 and 2.
Return type:: bool

See also

twodfdr.io.Tdfio.pixcal_delete: Deletes the PIXEL CALIBRATION array HDUs.
twodfdr.io.Tdfio.pixcal_read: Read axis information WAVE_LHS and WAVE_RHS exists for the given object.
twodfdr.io.Tdfio.pixcal_read_bincentres: Read wavelength data and calculated the centres of each bin.
twodfdr.io.Tdfio.pixcal_read_binwidths: Read wavelength data and calculated the binwidth of each bin.
twodfdr.io.Tdfio.pixcal_write_bins: Writes wavelength data using the bins data.
twodfdr.io.Tdfio.pixcal_write: Writes the wavelength calibrations for the edges of each pixel for each fibre in a FITS file.

pixcal_read()¶

Read axis information WAVE_LHS and WAVE_RHS exists for the given object.

Returns:: The namedtuple (WaveLR) consists of two components: a numpy.ndarray with the WAVE_LHS data (left) and a numpy.ndarray with the WAVE_RHS data (right). This output can be written in a FITS file.
Return type:: namedtuple

See also

twodfdr.io.Tdfio.pixcal_delete: Deletes the PIXEL CALIBRATION array HDUs.
twodfdr.io.Tdfio.pixcal_exists: Returns whether axis information WAVE_LHS or WAVE_RHS exists for the given object.
twodfdr.io.Tdfio.pixcal_read_bincentres: Read wavelength data and calculated the centres of each bin.
twodfdr.io.Tdfio.pixcal_read_binwidths: Read wavelength data and calculated the binwidth of each bin.
twodfdr.io.Tdfio.pixcal_write_bins: Writes wavelength data using the bins data.
twodfdr.io.Tdfio.pixcal_write: Writes the wavelength calibrations for the edges of each pixel for each fibre in a FITS file.

pixcal_read_bincentres()¶

Read axis information WAVE_LHS and WAVE_RHS (if exists), then calculates the centres of each bin.

Notes

The calculation for the bincentre is done by taking the average of the left and right sides for each bin:

bin_centre = 0.5*(bin_lhs + bin_rhs).

Returns:: Array contains the bin_centre of each bin.
Return type:: numpy.ndarray

See also

twodfdr.io.Tdfio.pixcal_delete: Deletes the PIXEL CALIBRATION array HDUs.
twodfdr.io.Tdfio.pixcal_exists: Returns whether axis information WAVE_LHS or WAVE_RHS exists for the given object.
twodfdr.io.Tdfio.pixcal_read: Read axis information WAVE_LHS and WAVE_RHS exists for the given object.
twodfdr.io.Tdfio.pixcal_read_binwidths: Read wavelength data and calculated the binwidth of each bin.
twodfdr.io.Tdfio.pixcal_write_bins: Writes wavelength data using the bins data.
twodfdr.io.Tdfio.pixcal_write: Writes the wavelength calibrations for the edges of each pixel for each fibre in a FITS file.

pixcal_read_binwidths()¶

Read axis information WAVE_LHS and WAVE_RHS (if exists), then calculates the binwidth of each bin.

Notes

The calculation for the bincentre is done by taking the difference of the left and right sides for each bin:

bin_width = bin_lhs - bin_rhs.

Returns:: Array containing the bin_width of each bin.
Return type:: numpy.ndarray

See also

twodfdr.io.Tdfio.pixcal_delete: Deletes the PIXEL CALIBRATION array HDUs.
twodfdr.io.Tdfio.pixcal_exists: Returns whether axis information WAVE_LHS or WAVE_RHS exists for the given object.
twodfdr.io.Tdfio.pixcal_read_bincentres: Read wavelength data and calculated the centres of each bin.
twodfdr.io.Tdfio.pixcal_read: Read axis information WAVE_LHS and WAVE_RHS exists for the given object.
twodfdr.io.Tdfio.pixcal_write_bins: Writes wavelength data using the bins data.
twodfdr.io.Tdfio.pixcal_write: Writes the wavelength calibrations for the edges of each pixel for each fibre in a FITS file.

pixcal_write(data)¶

Writes the wavelength calibrations for the edges of each pixel for each fibre in a FITS file.

Parameters:: data (tuple) – Output of pixcal_read. Since tuples are immutables, any modification in the data has to be store in a new tuple with the same shape as the original data.

See also

twodfdr.io.Tdfio.pixcal_delete: Deletes the PIXEL CALIBRATION array HDUs.
twodfdr.io.Tdfio.pixcal_exists: Returns whether axis information WAVE_LHS or WAVE_RHS exists for the given object.
twodfdr.io.Tdfio.pixcal_read_bincentres: Read wavelength data and calculated the centres of each bin.
twodfdr.io.Tdfio.pixcal_read: Read axis information WAVE_LHS and WAVE_RHS exists for the given object.
twodfdr.io.Tdfio.pixcal_read_binwidths: Read wavelength data and calculated the binwidth of each bin.
twodfdr.io.Tdfio.pixcal_write_bins: Writes wavelength data using the bins data.

pixcal_write_bins(data)¶

Writes axis information WAVE_LHS and WAVE_RHS exists for the given object using the bins data. The given data is written to the FITS file.

Parameters:: data (list) – The data array contains the output of pixcal_read_bincentres and pixcal_read_binwidths functions: data = [bincentres, binwidth]

See also

twodfdr.io.Tdfio.pixcal_delete: Deletes the PIXEL CALIBRATION array HDUs.
twodfdr.io.Tdfio.pixcal_exists: Returns whether axis information WAVE_LHS or WAVE_RHS exists for the given object.
twodfdr.io.Tdfio.pixcal_read_bincentres: Read wavelength data and calculated the centres of each bin.
twodfdr.io.Tdfio.pixcal_read: Read axis information WAVE_LHS and WAVE_RHS exists for the given object.
twodfdr.io.Tdfio.pixcal_read_binwidths: Read wavelength data and calculated the binwidth of each bin.
twodfdr.io.Tdfio.pixcal_write: Writes the wavelength calibrations for the edges of each pixel for each fibre in a FITS file.

read()¶

Reads the image data into a numpy ndarray.

Returns:: A numpy ndarray with the image contents.
Return type:: numpy.ndarray

Notes

Applies only to TdfioType.RAW and TdfioType.STD data. When used to read a 6df raw file, the image is rotated to follow axis convention of the other instruments, i.e. first axis is spectral, second is spatial.

rwss_exists()¶

Returns whether RWSS (Reduced spectra Without Sky Subtraction) data exists in the FITS file.

Returns:: Returns True if the object has a RWSS HDU (extension), otherwise False.
Return type:: bool

See also

twodfdr.io.Tdfio.rwss_read: Reads the RWSS (Reduced spectra Without Sky Subtraction) HDU contents from a FITS file.
twodfdr.io.Tdfio.rwss_write: Writes the RWSS (Reduced spectra Without Sky Subtraction) HDU contents in a FITS file.

rwss_read()¶

Reads the RWSS (Reduced spectra Without Sky Subtraction) HDU contents from a FITS file.

Notes

The data is read from the the FITS file and returned in the given array. The RWSS data are used for improved splicing or deeper analysis.

Returns:: A numpy.ndarray with the RWSS data
Return type:: numpy.ndarray

See also

twodfdr.io.Tdfio.rwss_exists: Returns whether RWSS (Reduced spectra Without Sky Subtraction) data exists in the FITS file.
twodfdr.io.Tdfio.rwss_write: Writes the RWSS (Reduced spectra Without Sky Subtraction) HDU contents in a FITS file.

rwss_write(data)¶

Writes the RWSS (Reduced Without Sky Subtraction) HDU contents. The given data is written to the FITS file.

Parameters:: data (numpy.ndarray) – The data array contains the output of rwss_read (the data attribute of the HDU).

Notes

The RWSS data are used for improved splicing or deeper analysis.

See also

twodfdr.io.Tdfio.rwss_exists: Returns whether RWSS (Reduced spectra Without Sky Subtraction) data exists in the FITS file.
twodfdr.io.Tdfio.rwss_read: Reads the RWSS (Reduced spectra Without Sky Subtraction) HDU contents from a FITS file.

sds_exists()¶

Returns whether the REDUCTION_ARGS extension exists.

Returns:: Returns True if the object has a REDUCTION_ARGS HDU (extension), False otherwise.
Return type:: bool

See also

twodfdr.io.Tdfio.sds_read: Reads the contents of the REDUCTION_ARGS extension.
twodfdr.io.Tdfio.sds_write: Writes reduction parameters to the REDUCTION_ARGS extension.

sds_read()¶

Reads the contents of the REDUCTION_ARGS extension.

Returns:: The reduction parameters returned in a PyCPL parameter list.
Return type:: cpl.ui.ParameterList

See also

twodfdr.io.Tdfio.sds_exists: Returns whether the REDUCTION_ARGS extension exists.
twodfdr.io.Tdfio.sds_write: Writes reduction parameters to the REDUCTION_ARGS extension.

sds_write(targs)¶

Writes reduction parameters to the REDUCTION_ARGS extension.

Parameters:: targs (TdfArgs) – The method arguments.

See also

twodfdr.io.Tdfio.sds_exists: Returns whether the REDUCTION_ARGS extension exists.
twodfdr.io.Tdfio.sds_read: Reads the contents of the REDUCTION_ARGS extension.

setclass(cls)¶

Writes the NDF_CLASS binary table HDU value to the FITS file.

Parameters:: cls (str) – Class of the FITS file to be written

setred()¶: Marks the given object as reduced. Add a HDU with the name REDUCED at the end HDU list of the FITS file.

shifts_read()¶

Reads the polynomial coefficients used in wavelength calibration values into the given array.

Returns:: A numpy.ndarray with the RWSS data
Return type:: numpy.ndarray

See also

twodfdr.io.Tdfio.shifts_write: Writes the polynomial coefficients used in wavelength calibration values HDU contents in a FITS file.

shifts_write(data)¶

Writes the polynomial coefficients used in wavelength calibration (aka SHIFTS) values from the given array.

Parameters:: data (numpy.ndarray) – The data array contains the output of rwss_read (the data attribute of the HDU).

See also

twodfdr.io.Tdfio.shifts_read: Reads the polynomial coefficients used in wavelength calibration values HDU contents from a FITS file.

sky_exists()¶

Reads sky data from file SKY HDU into the given vector. If SKY HDU does NOT exist, the vector is filled with zeroes.

Returns:: Returns True if the object has a variance HDU (extension), False otherwise.
Return type:: bool

sky_read()¶

Reads sky data from file SKY HDU into the given vector.

Return type:: numpy.ndarray

Notes

If SKY HDU does NOT exist, the vector is filled with zeroes.

See also

twodfdr.io.Tdfio.sky_write: Writes sky data from file SKY HDU into the given vector.

sky_write(data)¶

Writes sky data from file SKY HDU into the given vector.

Parameters:: data (numpy.ndarray) – The data array contains the output of sky_read (the data attribute of the HDU).

See also

twodfdr.io.Tdfio.sky_read: Reads sky data from file SKY HDU into the given vector.

stamp_version(version=None)¶

Stamps a file with the 2dfdr release version number.

Parameters:: version (str, optional) – The default is to use the current twodfdr release version. Otherwise a version string may be specified here.

telcor_write(data)¶

Writes a telluric absorption spectrum vector in the FITS file.

Parameter¶

datastr: Telluric absorption correction to be written

thput_exists()¶

Returns whether throughput data exists in the FITS file.

Returns:: Returns True if the object has a throughput data HDU (extension), False otherwise.
Return type:: bool

See also

twodfdr.io.Tdfio.thput_read: Reads the fibre throughput values into given vector.
twodfdr.io.Tdfio.thput_write: Writes a fibre throughput calibration vector.

thput_read()¶

Reads the fibre throughput values into given vector.

Notes

Reads fibre throughput calibration data into given vector.

Returns:: A numpy.ndarray with the throughput values
Return type:: numpy.ndarray

See also

twodfdr.io.Tdfio.thput_exists: Returns whether throughput data exists in the FITS file.
twodfdr.io.Tdfio.thput_write: Writes a fibre throughput calibration vector.

thput_write(data)¶

Writes a fibre throughput calibration vector in a FITS file.

Parameters:: data (numpy.ndarray) – The data array contains the output of thput_read (the data attribute of the HDU).

See also

twodfdr.io.Tdfio.thput_exists: Returns whether throughput data exists in the FITS file.
twodfdr.io.Tdfio.thput_read: Reads the fibre throughput values into given vector.

tlmap_read()¶

Reads the tramline map data into the given array.

Returns:: A numpy.ndarray with the tramline map values.
Return type:: numpy.ndarray

See also

twodfdr.io.Tdfio.tlmap_write: Writes a tramline map array.

tlmap_write(data)¶

Writes a tramline map array.

Parameters:: data (numpy.ndarray) – The data array contains the output of tramline map values.

See also

twodfdr.io.Tdfio.tlmap_read: Reads the tramline map data into the given array.

tsig_exists()¶

Determines whether the sigma profile extension exists in the FITS file

Returns:: Returns True if the object has a ‘SIGMAPRF’ HDU, False otherwise.
Return type:: bool

See also

twodfdr.io.Tdfio.tsig_read: Reads the sigma profile data values into given vector.
twodfdr.io.Tdfio.tsig_write: Writes the sigma profile data values.

tsig_read()¶

Reads the sigma profile data from a FITS file.

Returns:

numpy.ndarray
A numpy.ndarray with sigma profile extension of the FITS file

See also

twodfdr.io.Tdfio.tsig_exists: Returns whether sigma profile data exists in the FITS file.
twodfdr.io.Tdfio.tsig_write: Writes the sigma profile data values.

tsig_write(data)¶

Writes a fibre throughput calibration vector in a FITS file.

Parameters:: data (numpy.ndarray) – The data array contains the output of tsig_read (the data attribute of the HDU).

See also

twodfdr.io.Tdfio.tsig_exists: Returns whether sigma profile data exists in the FITS file.
twodfdr.io.Tdfio.tsig_read: Reads the sigma profile data values into given vector.

var_exists()¶

Returns whether variance data exists in the FITS file.

Returns:: Returns True if the object has a variance HDU (extension), False otherwise.
Return type:: bool

See also

twodfdr.io.Tdfio.var_read: Reads the variance data into the given array (files opened with type TdfioType.STD).
twodfdr.io.Tdfio.var_read_row: Reads a row of image and variance data into the given vectors.
twodfdr.io.Tdfio.var_write: Writes a row of image and variance data into the given vectors.

var_read()¶

Reads the variance data into the given array (files opened with type TdfioType.STD).

Notes

The data is read from the FITS file and returned in the given array. The VARIANCE data are used for improved splicing or deeper analysis.

Returns:: A numpy.ndarray with the VARIANCE data
Return type:: numpy.ndarray

See also

twodfdr.io.Tdfio.var_exists: Returns whether variance data exists in the FITS file.
twodfdr.io.Tdfio.var_read_row: Reads a row of image and variance data into the given vectors.
twodfdr.io.Tdfio.var_write: Writes a row of image and variance data into the given vectors.

var_read_row(row)¶

Reads a row of image and variance data into the given vectors.

Returns:: The namedtuple (PriVar) consists of two components: a numpy.ndarray with the image data (primary) and a numpy.ndarray with the variance data (variance).
Return type:: namedtuple

See also

twodfdr.io.Tdfio.var_exists: Returns whether variance data exists in the FITS file.
twodfdr.io.Tdfio.var_read: Reads the variance data into the given array (files opened with type TdfioType.STD).
twodfdr.io.Tdfio.var_write: Writes a row of image and variance data into the given vectors.

var_write(data)¶

Writes a row of image and variance data into the given vectors.

Parameters:: data (numpy.ndarray) – The data array contains the output of var_read (the data attribute of the HDU).

See also

twodfdr.io.Tdfio.var_exists: Returns whether variance data exists in the FITS file.
twodfdr.io.Tdfio.var_read: Reads the variance data into the given array (files opened with type TdfioType.STD).
twodfdr.io.Tdfio.var_read_row: Reads a row of image and variance data into the given vectors.

velocity_exists()¶

Returns whether direction velocity data exists in the FITS file.

Returns:: Returns True if the object has a variance HDU (extension), False otherwise.
Return type:: bool

See also

twodfdr.io.Tdfio.velocity_read: Reads direction velocity data into the given vectors from a FITS file.
twodfdr.io.Tdfio.velocity_write: Writes a velocity data into the given vectors.

velocity_read()¶

Reads direction velocity data into the given vectors from a FITS file.

Returns:: The namedtuple (DirVel) consists of six components: a numpy.ndarray with the baryocentric velocity (bary), a numpy.ndarray with the heliocentric velocity (helio), a numpy.ndarray with the geocentric velocity (geo), a numpy.ndarray with the velocity corrections (corvel), a numpy.ndarray with the mean plate positions (mean_plate_pos) and a numpy.ndarray with the option vector list (params).
Return type:: namedtuple

See also

twodfdr.io.Tdfio.velocity_exists: Returns whether direction velocity data exists in the FITS file.
twodfdr.io.Tdfio.velocity_write: Writes a velocity data into the given vectors.

velocity_write(bvec, hvec, gvec, vcorv, zcorv, scorv, ovec)¶

Writes the velocity data into a FITS file.

Parameters:: data (tuple) – The data tuple contains the output of velocity_read (the data attribute of the HDU).

See also

twodfdr.io.Tdfio.velocity_exists: Returns whether direction velocity data exists in the FITS file.
twodfdr.io.Tdfio.velocity_read: Reads direction velocity data into the given vectors from a FITS file.

wave_delete()¶

Deletes the wavelength array HDUs.

See also

twodfdr.io.Tdfio.wave_read: Reads the wavelength array data.
twodfdr.io.Tdfio.wave_write: Writes the wavelength array data in a FITS file.

wave_exists()¶

Checks whether the wavelength array data are present.

Returns:: True if the WAVELA extension is present.
Return type:: bool

wave_read()¶

Reads the wavelength array data.

Returns:: The wavelength data is in the form (first dimension of WLRAY, first dimension of WLRAY).
Return type:: numpy.ndarray

See also

twodfdr.io.Tdfio.wave_write: Writes the wavelength array data in a FITS file.

wave_write(data)¶

Writes the wavelength array data in a FITS file.

Parameters:: data (numpy.ndarray) – The wavelength data to be written.

See also

twodfdr.io.Tdfio.wave_read: Reads the wavelength array data.

write(data)¶

Writes the Primary HDU with the given array.

Raises:: RuntimeError – If the FITS file was opened as RAW type (read-only).
Parameters:: data (numpy.ndarray) – The image data to be written.

property fid¶

The internal file identifier.

Returns:: The file identifier.
Return type:: int

property height¶

The image height.

Returns:: The image height.
Return type:: int

property instrument¶

Returns the code for the instrument that produced the current file.

Notes

A central database for instrument names. Used to tranlate the value given in the file’s “INSTRUME” FITS keyword to the corresponding code (see TDFRED_PAR). The code is then normally used is a SELECT statement.

Returns:: The instrument type of the current file.
Return type:: TdfioInstType

property ndf_class¶

Returns the CLASS associated with a FITS file.

Notes

Returns the NDF_CLASS binary table HDU value from the given FITS file. If the NDF_CLASS HDU does not exist, find the RUNCMD keyword and translate its value to a class.

Returns:: The class associated with a FITS file.
Return type:: str

property status¶

The current value of the internal status flag.

Returns:: The current value of the internal status flag.
Return type:: int

property width¶

The image width.

Returns:: The image width.
Return type:: int

class twodfdr.io.TdfioFibType(*values)¶

Fibre table type (if present).

FIBRES = 1¶: FIBRES table was found.

FIBRES_IFU = 2¶: FIBRES_IFU table was found.

NONE = 0¶: No fibre table found.

class twodfdr.io.TdfioInstType(*values)¶

Instrument type.

AAOMEGA_2DF = 3¶: 2dF-AAOmega

AAOMEGA_HECTOR = 12¶: Hector-AAOmega

AAOMEGA_IFU = 4¶: IFU-AAOMega

AAOMEGA_KOALA = 8¶: Koala-AAOmega

AAOMEGA_SAMI = 7¶: SAMI-AAOmega

FMOS = 5¶: FMOS

GENERIC = 9¶: Generic

GENERIC_IR = 10¶: Generic IR

HERMES = 6¶: HERMES

SIXDF = 2¶: 6dF

SPECTOR_HECTOR = 13¶: Spector-AAOmega

TAIPAN = 11¶: TAIPAN

TWODF = 1¶: 2dF

class twodfdr.io.TdfioKeyType(*values)¶

Keyword type to be used for reading/writing a keyword from/to the FITS header.

BOOL = 'LOGICAL'¶: Boolean

DOUBLE = 'REAL'¶: Double

INT = 'INT'¶: Integer

STR = 'CHAR'¶: String

class twodfdr.io.TdfioMode(*values)¶

Mode to be used for opening FITS files.

Notes

Files of type TdfioType.RAW are always read-only.

R = 'READ'¶: Open an existing file with read-only permission (no write).

RW = 'UPDATE'¶: Open an existing file with read and write permissions.

W = 'WRITE'¶: Delete the file if it exists, then open a new file with read and write permissions.

class twodfdr.io.TdfioNSType(*values)¶

The nod and shuffle status

MINI = 2¶: Mini-shuffle nod and shuffle data

NONE = 0¶: Not nod and shuffle data

NORMAL = 1¶: Normal nod and shuffle data

class twodfdr.io.TdfioType(*values)¶

File type to be used for opening FITS files.

DIAG = 4¶: Diagnostic frames are FITS files written by 2dfdr to hold data sets to be reviewed later. They have no defined format, and normally have READ/WRITE access.

RAW = 1¶: Raw frames are produced by the instrument. They have an integer (32-bit) image data array and no variance array. They are only ever READ-ONLY access.

STD = 2¶: STanDard frames have real (32-bit) image and variance data arrays. They are created and filled by 2dfdr, and are either “im” image, “ex” extracted, “red” reduced or combined reduced files. They can have either READ-ONLY or READ/WRITE access.

TLM = 3¶: TramLine Map frames have real (32-bit) tramline map and wavelength data arrays, and are produced by 2dfdr. They can have either READ-ONLY or READ/WRITE access.

Core Reduction Methods¶

twodfdr.methods.combine_image(params, flist, cmeth=None, minpix=None, ofname=None, odir=None, legacy=False)¶

Combine image objects into a single object.

Parameters:

params (cpl.ui.ParameterList) – The method arguments.
flist (list of str) – The filenames of the files to be combined.
cmeth (StackMethod) – Method to use in combining the lines. Default: StackMethod.MEDIAN.
minpix (int) – Minimum number of pixels required to contribute to an output pixel. Default: 1.
ofname (str, optional) – The filename of the reduced sky frame. Default: stack.fits.
odir (str, optional) – The directory to write the output files.
legacy (bool, optional, default False) – Use the legacy version of the method.

Notes

The objects to be combined must all have the same image dimensions, and all must have variances of these same dimensions. All combinations are weighted by the (scaled) input variances. There is a limit on the number of objects which can be combined which is set to 200.

This code originally appeared in clalib/class_group.f that stated it was based on software taken from the Starlink CCDPACK package.

Returns:: A list of the combined output files. There may be more than one file if flist contains files with different exposure times.
Return type:: list of str

twodfdr.methods.make_tlm(params, image, ofname=None, odir=None, legacy=False)¶

Generate a tramline map from an image file from specifications entirely given in the args. This routine implements the make_tlm and make_tlm_from_im functionality entirely from Python.

Parameters:

params (cpl.ui.ParameterList) – The method arguments.
image (str) – The filename of the image frame for which to generate tramline map.
ofname (str, optional) – The output tramline map file name. This file is created, filled with tramline map, wavelength and optional sigma profile, and then closed by this routine. The default value of ofname is to add the suffix ‘tlm.fits’.
odir (str, optional) – The directory to write the output files.
legacy (bool, optional, default False) – Use the legacy version of the method.

Notes

This can be considered a template for extending or modifying make_tlm from Python.

Returns:: To be determined
Return type:: str

twodfdr.methods.reduce_arc(params, arc, tlm, ofname=None, legacy=False)¶

Reduces a raw arc file to produce im(age), ex(tracted) and red(uced) arc files. This routine implements the reduce_arc functionality entirely from Python.

Parameters:

params (cpl.ui.ParameterList) – The method arguments.
arc (str) – The filename of the arc image to be reduced.
tlm (str) – The filename of the tramline map.
ofname (str, optional) – The filename of the reduced arc.
legacy (bool, optional, default False) – Use the legacy version of the method.

Notes

Arc (aka wavelength calibration) frames are taken using the lamps of the 2dF calibration unit. The lamps illuminate a deployable screen below the wide field corrector.

Wavelength calibration using a sky exposure (aka sky scrunch) is never done on arcs frames.

The following steps are performed:

Create calibrated im(age) file from raw instrument file using same MAKE_IM procedure as science frames. See make_im for details.

Create ex(tracted) spectra file from im(age) file using same MAKE_EX procedure as science frames. See make_ex for details.

Scrunch using input arc calibration file (WAVEL_FILENAME) if any. If no calibration file is given (generally the case), scrunch using SHIFTS set to unit scaling, i.e. 0,1,0,0,0,0…

Determine polynomial coefficients indicating wavelength correction (aka SHIFTS) by comparing image peaks with known lamp lines.

Copy image & variance from ex(tracted) to red(uced) and apply SHIFTS.

The output file ofname will have all the input ex(tracted) extensions (some modified) plus:

SHIFTS: fibre count X MAX_SHIFTS array with rebinning polynomial coefficients.

REDUCED: indicates file is reduced.

Returns:: To be determined
Return type:: str

twodfdr.methods.reduce_fflat(params, flat, wave, tlm, ofname=None, legacy=False)¶

Reduces a raw multi-fibre flat file to produce im(age), ex(tracted) and red(uced) fflat files. A tlm (tramline map) file may also be produced.

Parameters:

params (cpl.ui.ParameterList) – The method arguments.
flat (str) – The filename of the flat to be reduced.
wave (str) – The filename of the reduced arc.
tlm (str) – The filename of the tramline map.
ofname (str, optional) – The filename of the red(uced) flat.
legacy (bool, optional, default False) – Use the legacy version of the method.

Notes

When a group of science frames (including calibration files) is reduced it is necessary to call this routine twice to fully process a fibre flat.

On the first reduction the scrunch is done without a wavelength calibration frame, i.e. unit scaling.

The second reduction is done after the first pass results are used in the reduction of the arc frame. The reduced arc frame is then used to wavelength calibrate during the second reduction of the fibre flat.

The following steps are performed:

Create calibrated im(age) file from raw instrument file using same make_im procedure as science frames. See make_im.F95 for details.
Create ex(tracted) spectra file from im(age) file using same make_ex procedure as science frames. See make_ex.F95 for details.
Make copy of ex(tracted) file.
Scrunch the copy using a reduced arc file as the wavelength calibrator. This places the copy in wavelength space so the normalisation and averaging will occur there. During the first reduction there is (normally) NO arc file available. In this case use unit scaling which is effectively a no operation.
Normalise in the spectral direction each individual spectra by their median value. Then average pixels in the spatial direction to obtain an average response function. Averaging can be done in one of two ways: either using all fibres or by sweeping a local window of LAF_PAR size across the fibres. Plot the response function if requested.
Un-Scrunch the copy to return it to pixel space. This is appropriate because the reduced fibre flat is used to calibrate science data before it is wavelength calibrated.
Extrapolate out ends of the copy to correct for missing pixels due to scrunching.
Use scrunched, averaged, un-scrunched and extrapolated copy produced in steps 1-7 to normalise the ex(tracted) frame producing the red(uced) frame.

The output file ofname will have all the input ex(tracted) extensions: (modified) plus

Returns:: To be determined
Return type:: str

twodfdr.methods.reduce_sky(params, sky, tlm, wave, flat, extr=None, ofname=None, odir=None, legacy=False)¶

Reduce sky frame.

Parameters:

params (cpl.ui.ParameterList) – The method arguments.
sky (str) – The filename of the sky frame to reduce.
tlm (str) – The filename of the tramline map.
wave (str) – The filename of the reduced arc.
flat (str) – The filename of the reduced flat.
extr (str, optional, default None) – Extraction operation to override value of EXTR_OPERATION in params. One of TRAM, NEWTRAM, GAUSS, OPTEX or SMCOPTEX. If None and EXTR_OPERATION is missing from params, the default is GAUSS.
ofname (str, optional) – The filename of the reduced sky frame.
odir (str, optional) – The directory to write the output files.
legacy (bool, optional, default False) – Use the legacy version of the method.

Notes

N.B. This recipe is meant to also support a list of reduced sky frames, however the aaorun implementation seems to operate only on individual raw sky frames. This should be revisited in the future.

Accurate sky subtraction requires calibration of the relative throughput of the science fibres. These are stable to 0.5% during observations but vary at the 10% level between different fibre configurations. This requires calibration data for each field plate setup. This is normally achieved by generating dark sky flats for each fibre configuration from a short sequence of offset sky frames.

This routine processes the raw sky frames to produce the calibration frame.

To perform the throughput calibration (see CMFSPEC_FTPCAL) each object spectrum is divided by the summed spectrum for the same fibre in the offset skies. This is typically for data where there are no suitable sky lines within the spectral range, so the normal throughput calibration from the strength of a strong sky line line cannot be used.

Returns:: To be determined
Return type:: str

Common Reduction Algorithms¶

class twodfdr.modules.Arc(*args, **kwargs)¶

Python bindings to the various reduce_arc related subroutines.

static blue_hermes_arc_sanity_check(reduced_arc)¶

HERMES Blue data Sanity Check

Parameters:: reduced_arc (Tdfio) – The input reduced arc frame.

Notes

Writes results to some text files: SANITY_CHK.dat and EXG.dat (?).

Returns:: The sanity check flag.
Return type:: bool

static calibrate_spectral_axes(spectra, variance, pred_axis, goodfib, lamb_tab, flux_tab, maxshift)¶

Calibrating the pixels of extracted spectra derived from arc lamp sources of specified spectral atlas.

Parameters:

spectra (numpy.ndarray) – Spectra in which to find arc lines.
variance (numpy.ndarray) – Variances of Spectra.
pred_axis (numpy.ndarray) – Predicted Wavelength values of pixel edges in angstroms.
goodfib (numpy.ndarray) – Array of boolean values specifying whether corresponding spectrum/fibre is to be included.
lamb_tab (numpy.ndarray) – Table list of known arc lines of lamp in angstroms.
flux_tab (numpy.ndarray) – Table list for corresponding flux/count value (no units).
maxshift (int) – The value of maxshift.

Returns:

The calibrated pixels array (pixcal_dp).

Return type:

numpy.ndarray

Notes

Currently implemented for TAIPAN and KOALA instruments only, with some experiments for AAOmega data.

Calibrates the pixels of extracted arclamp spectra SPECTRA(1:NPIX,1:NFIB) based on supplied predicted axis PRED_AXIS(1:NPIX+1) and spectral atlas LAM_TAB(1:SIZE_TAB), FLUX_TAB(1:SIZE_TAB). Returns pixel calibrations in double precision.

There are 3 Major Steps:

1. For a chosen reference fibre (picked to be as close to the centre of the image as possible where the optical distortions are assumed minimal) determine quadratics that would map the pixel axis of each of the remaining fibres onto the reference fibre, i.e. a mapping that corrects for relative distortion.

2. For the spectrum on the reference axis, determine a correction polynomial (cubic) that will map the predicted axis of this spectrum to a wavelength axis that alligns specific identified arc lines to values supplied from a table/atlas.

3. For each fibre, calibrate the axes from via the established association to the reference fibre.

static do_arc_profiles(targs)¶

Experimental work that determines the PSF profiles for each fibre at each spectral column from the arc images and associated tramline maps.

Parameters:: targs (TdfArgs) – The method arguments.

static read_arc_file(xvec, lamp)¶

Reads an ASCII text arc file containing the wavelengths and intensities of lines produced by a reference arc lamp.

Parameters:

xvec (numpy.ndarray) – Wavelength axis vector. Only used to find minimum and maximum acceptable wavelengths.
lamp (str) – The lamp name. Only used to derive the arc filename.

Notes

Input files are named for their arc lamp type and always have the filename extension “.arc”. The files for well known lamps are kept in the drcontrol module in the arc_files directory.

Input files may contain comment lines beginning with either “*” or “#”. Normally useful lines contain two numbers on each file line giving a wavelength and intensity. SPECIAL lines (beginning with “#MAP”) contain wavelength, intensity and a SECOND WAVELENGTH

Ascii lines that contain the word “unreferenced” implies that the data on this file line refers to an arc line known to exist on this lamp but is not known on any reference table. Hence this line can be used for arc line list matching but not satisfactorily in functional fitting as we cannot guarantee the accuracy of the this arc line position in Anstroms. We highlight the arc line reference status by negating the intensity values of unreferenced lines in the return values

Returns:: The namedtuple (ArcList) consists of four components: a numpy.ndarray of wavelengths (wlist), a numpy.ndarray of intensities (ilist), a numpy.ndarray of labels (labels) and a numpy.ndarray of second wavelengths (wlist2).
Return type:: namedtuple

static spectral_resolution(reduced_arc, targs)¶

Analyse the reduction frame image for spectral resolution and store results as an extension within this frame.

Parameters:

reduced_arc (Tdfio) – The input reduced arc frame.
targs (TdfArgs) – The method arguments.

Notes

Calculate and Analyse the average spectrum for arcline details then perform sliding window sigma fit for each relevant fibre

class twodfdr.modules.Combine(*args, **kwargs)¶

Python bindings to the various combine_image, combine_spectra and related subroutines.

Notes

static combine_image(targs)¶

Combine image objects into a single object.

Parameters:: targs (TdfArgs) – The method arguments.

Notes

The objects to be combined must all have the same image dimensions, and all must have variances of these same dimensions. All combinations are weighted by the (scaled) input variances. There is a limit on the number of objects which can be combined which is set to MAX_FILES.

This code originally appeared in clalib/class_group.f that stated it was based on software taken from the Starlink CCDPACK package.

The main code was moved into routine COMBINE_IMAGE_FILES and this routine is foucused on listing and grouping those files as was required when there are dark images with differnt exposure times. (mnb 25/nov/21)

static combine_spectra(targs)¶

Combine multi-fibre spectra reduced frames.

Parameters:: targs (TdfArgs) – The method arguments.

Notes

An outline of the code structure (somewhat dated)

1) Extract all the object types, names and magnitudes, and fibre numbers for every frame. See COMBINE_GETLIST().

2) Determine total number of fibres in combined output. This is important for fields with different objects allocated to the fibres, or where fibres were broken. The total number of fibres in the output file will be the number in the first input file (for example 400 for a normal MOS AAOmega frame) PLUS the number of other different (either in name or location) PROGRAM and SKY objects in other than the first frame. See COMBINE_GETLIST().

3) For each object put all of the good spectra with that object name into the array to be combined.

Pass to the combining routine COMB3().
Add extra fibre info into the output frame fibre table.

static getfilesfromargs(maxfiles, targs)¶

Obtain the list of files that are to be to be combined as listed in the

Parameters:

maxfiles (int) – Maximum size of returned file list.
targs (TdfArgs) – The method arguments.

Returns:

The list of opened file names.

Return type:

list of str

static image_files(flist, ofname, targs)¶

Parameters:

flist (list of str) – Filenames to combine.
ofname (str) – The filename of the combined image.
targs (TdfArgs) – The method arguments.

static lflat_extra(tin, resdat, resvar)¶

If the files being combined are long-slit flat frames, then create master long-slit flat calibration frame by normalising the result by it’s median and setting it’s special class.

Parameters:

tin (Tdfio) – The output file.
resdat (numpy.ndarray) – The image data.
resvar (numpy.ndarray) – The image variance data.

Returns:

The first and second elements being the modified resdat and resvar numpy ndarrays, respectively.

Return type:

tuple

Notes

Master long-slit flat frames are used to later calibrate other science and calibration frames.

This function has been modified to return the modified 2d arrays and access them from Python.

static open_files(flist, targs, hist=False)¶

Open files to be combined.

Parameters:

flist (list of str) – Filenames to open.
targs (TdfArgs) – The method arguments.
hist (bool, optional.) – Write history records.

Returns:

The first being a list of opened Tdfio objects for the files opened with fmode = TdfioMode.R and ftype = TdfioType.STD. The second being the identifiers of the files to be combined (numpy.ndarray of ints). The third being the nod-and-shuffle mode (TdfioNSType).

Return type:

tuple

static stack(stack, variances, cmeth, minpix, niter, nsigma, alpha, rmin, rmax)¶

To combine a stack of spectral lines into single line, using one of several methods.

Parameters:

stack (numpy.ndarray) – Array of lines which are to be combined into a single line. Dimensions are npix, nlines.
variances (numpy.ndarray.) – Array of variances for the stack.
cmeth (StackMethod) – Method to use in combining the lines.
minpix (int) – Minimum number of pixels required to contribute to an output pixel.
niter (int) – Maximum number of iterations (StackMethod.MODE and StackMethod.SCLIP_MEAN only). Should be set to one for StackMethod.SCLIP_MEAN.
nsigma (double) – Number of sigmas to clip data at (StackMethod.MODE and StackMethod.SCLIP_MEAN only).
alpha (double) – Fraction of data values to remove from data (StackMethod.TRIM_MEAN only).
rmin (double) – Minimum allowed data value (StackMethod.TEXCL_MEAN only).
rmax (double) – Maximum allowed data value (StackMethod.TEXCL_MEAN only).

Returns:

A tuple of numpy.ndarrays of dimension npix. The first component being the stacked data array, while the second is the corresponding variance array.

Return type:

tuple

class twodfdr.modules.DeriveShifts(*args, **kwargs)¶

Python bindings to the derive_shifts modules and subroutines.

static derive_shifts(spectra, variance, axis, goodfib, wlist, ilist, n_shifts, fitorder, type_flag, pkmtch_mthd, sigma_clip, quad_filter, use_wsm, yposv)¶

Derive wavelength polynomial coefficients (aka SHIFTS).

Parameters:

spectra (numpy.ndarray) – Spectra in which to find line peaks.
variance (numpy.ndarray) – Variances on spectra.
axis (numpy.ndarray) – Wavelength pixel centre coordinates in Angstroms.
goodfib (numpy.ndarray) – Array of boolean values specifying whether corresponding spectrum/fibre is to be included.
wlist (numpy.ndarray) – List of known arc lamp lines wavelength in Angstroms.
ilist (numpy.ndarray) – Intensity for each corresponding wlist entry in ??? units.
n_shifts (int) – Running median sample size.
fitorder (int) – Order to use for polynomial fit, 1 to MAX_SHIFTS inclusive.
type_flag (bool) – Fit type being done: either True (arc frame) or False (object frame, i.e. sky lines). N.B. Need for and use of this flag is suspicious. Why are there differences between fitting arc lamp lines and sky lines?
pkmtch_mthd (int) – Which Peakmatch algorithm to use: 0 (default Will Saunders’ quasi Newton-Raphson method) or 1 (brute for sampling method).
sigma_clip (bool) – Whether to do sigma clipping or not.
quad_filter (bool) – Whether to apply quad filter or not.
use_wsm (bool) – Whether to use Whale Shark Matching algorithm or not.
yposv (numpy.ndarray) – Y position vector.

Notes

Used to fit image arc lines to reference lines by finding peaks in the frame and then comparing them with known lines. This function is used in two places:

the reduction of arc frames to fit image lines to known arc lamp lines
the reduction of science frames to fit sky lines

The resultant “shifts” table defines the coefficients of polynomials which are used later for scrunching.

Small perturbations in the “shift” coefficients cause a bigger change in the final results. Output is very sensitive to scrunching and polynomials expressed in the standard form such as ax^3+bx^2+cx+d are very sensitive to their coefficients.

The shift values (polynomial coefficients) are herein derived (using a Will Saunders approach) by working on each fiber from the middle to the outer in a two step process.

1. Find a single shift value that will make the best match, this takes as input a good initial estimate, which is taken from that evaluated for the last fiber.

2. Make a best polynomial fitted match after having determined a best single shift.

This process only works if the initial estimate is sufficiently close. When there are gaps between the fibers, the last shift value found becomes a poorer match due to the optical distortion.

In the case of SAMI which has gaps between blocks of 63 fibers, the last shift value is in high risk of being inadequate. Further, when the code tries to spectrally match data from a missing fiber that is not listed as bad, it will produce rubbish for that fiber instead of ignoring it and pass on the rubbish initial shift value for processing the next fiber. Will’s code DOES implement a running median filter of stack size 11 to ignore the odd bad value, but again, when deriving 63 trash values, this will NOT suffice.

The name SHIFTS is a MISNOMER since the values represent a polynomial, not a simple shift. It is thought the original algorithm was a shift and this was expanded without changing the name.

N.B. This code was mostly written by Will and is completely heuristic. It needs a good science-based cleanup.

The subroutine calling structure is as follows:: DERIVE_SHIFTS – ONLY ENTRY POINT | |–>UMFSARC_SHIFT - get shift in two line lists | | | |–>PEAKMATCH3I - find best match between lines | | | |–>GETBESTSHIFT2 - find best match between lines | | | |–>SHIFTMERIT_FN - Wills Gaussian weighted “Merit” function | |–>UMFSARC_FIT - fit arc ??? | | | |–>UMFSARC_FIND - find best match for line wavelength in list | | | |–>UMFSARC_PFIT - perform least-squares polynomial fit | | | |–>CLIP_SIGMA - do sigma clipping | |–>WS_RefPkMatch - Whale Shark ??? | | | |–>WS_GenRefPkMatch - General Whale Shark ??? | |–>WSARC_FIT - ??? | | | |–>WS_chebfit0 - Whale Shark ??? | | | |–>L1 - TOMS routine to return minimax fit (See l1.F95) | |–>UPDATE_FIFO - insert new value into FIFO

Returns:: Output shifts. An array with dimensions nfib,max_shifts.
Return type:: numpy.ndarray

static derive_shifts_samhec(targs, spectra, variance, axis, wavela, goodfib, wlist, ilist, n_shifts, fitorder, type_flag, pkmtch_mthd, sigma_clip, quad_filter, use_wsm, yposv, instcode, skyfit)¶

Derive wavelength polynomial coefficients for SAMI/Hector instruments (aka SHIFTS).

Parameters:

targs (TdfArgs) – The method arguments.
spectra (numpy.ndarray) – Spectra in which to find line peaks.
variance (numpy.ndarray) – Variances on spectra.
axis (numpy.ndarray) – Wavelength pixel centre coordinates in Angstroms.
wavela (numpy.ndarray) – Predicted 2D wavelength array
goodfib (numpy.ndarray) – Array of boolean values specifying whether corresponding spectrum/fibre is to be included.
wlist (numpy.ndarray) – List of known arc lamp lines wavelength in Angstroms.
ilist (numpy.ndarray) – Intensity for each corresponding wlist entry in ??? units.
n_shifts (int) – Running median sample size.
fitorder (int) – Order to use for polynomial fit, 1 to MAX_SHIFTS inclusive.
type_flag (bool) – Fit type being done: either True (arc frame) or False (object frame, i.e. sky lines). N.B. Need for and use of this flag is suspicious. Why are there differences between fitting arc lamp lines and sky lines?
pkmtch_mthd (int) – Which Peakmatch algorithm to use: 0 (default Will Saunders’ quasi Newton-Raphson method) or 1 (brute for sampling method).
sigma_clip (bool) – Whether to do sigma clipping or not.
quad_filter (bool) – Whether to apply quad filter or not.
use_wsm (bool) – Whether to use Whale Shark Matching algorithm or not.
yposv (numpy.ndarray) – Y position vector.
instcode (TdfioInstType) – The instrument type in the format of the TdfioInstType enum. Retrievable from the instrument property of Tdfio objects.
skyfit (bool) – Whether this is fitting skylines, or a regular arc

Notes

Used to fit image arc lines to reference lines by finding peaks in the frame and then comparing them with known lines. This function is used in two places:

the reduction of arc frames to fit image lines to known arc lamp lines
the reduction of science frames to fit sky lines