Tramline API#

Tramline map (TLM) generation: detecting fibre traces on the detector, linking them via multi-target tracking, and matching traces to physical fibre IDs. See the TLM stage theory for background.

Tramline map generation using astropy-based I/O.

This module provides functions for generating tramline maps from FITS images, replacing the Fortran TDFIO functions with astropy-based equivalents.

TODO: check the usage of the arguments in the function calls.

kspecdr.tlm.make_tlm.convert_fibre_types_to_trace_status(instrument_code: int, fibre_types: ndarray, nf: int) → ndarray[source]#

Convert fibre types to trace status.

Parameters:

  • instrument_code (int) – Instrument code

  • fibre_types (np.ndarray) – Array of fibre types

  • nf (int) – Number of fibres

Returns:

Array of trace status (‘YES’, ‘NO’, ‘MAYBE’)

Return type:

np.ndarray

kspecdr.tlm.make_tlm.convert_traces_to_tramline_map(traces: ndarray, match_vector: ndarray, nf: int) → ndarray[source]#

Convert identified traces to fibre tramline map array.

Parameters:

  • traces (np.ndarray) – Detected traces

  • match_vector (np.ndarray) – Vector matching fibre numbers to trace numbers

  • nf (int) – Number of fibres

Returns:

Tramline map array

Return type:

np.ndarray

kspecdr.tlm.make_tlm.detect_traces(img_data: ndarray, nspec: int, nspat: int, max_ntraces: int, nf: int, order: int = 4, sparse_fibs: bool = False, experimental: bool = False, pk_search_mthd: int = 0, dodist: bool = True) → Tuple[int, ndarray, ndarray, ndarray][source]#

Detect fiber traces across an image.

This function examines IMG_DATA(NSPAT, NSPEC) for identifiable fibre traces and creates a traces pathlist array. It returns a representation of a spatial profile slice and peak list that can be used for other analysis.

This function replaces the Fortran LOCATE_TRACES call.

Parameters:

  • img_data (np.ndarray) – Image data of shape (nspat, nspec) - Horizontal Dispersion

  • nspec (int) – Dimensions of the image (spectral, spatial)

  • nspat (int) – Dimensions of the image (spectral, spatial)

  • max_ntraces (int) – Maximum number of traces to return

  • nf (int) – Number of fibers in instrument

  • order (int, optional) – Order of polynomial fitting (default: 4)

  • sparse_fibs (bool, optional) – If there is only a sparse number of fibers (default: False)

  • experimental (bool, optional) – If to use experimental restrictions for blurred data (default: False)

  • pk_search_mthd (int, optional) – Peak search method: 0=standard, 1=local peaks, 2=wavelet (default: 0)

  • dodist (bool, optional) – Whether to do distortion modeling (default: True)

Returns:

  • ntraces (int) – Number of traces found.

  • tracea (np.ndarray) – Trace array of shape (nspec, max_ntraces).

  • rep_slice (np.ndarray) – Representation profile slice of shape (nspat,).

  • rep_pkpos (np.ndarray) – Representation slice peak list of shape (nspat,).

kspecdr.tlm.make_tlm.get_fibre_separation(instrument_code: int) → float[source]#

Get nominal fibre separation for instrument.

Parameters:

instrument_code (int) – Instrument code

Returns:

Nominal fibre separation in pixels

Return type:

float

kspecdr.tlm.make_tlm.interpolate_tramlines(tramline_map: ndarray, match_vector: ndarray, sep: float) → None[source]#

Interpolate missing fibre traces.

Parameters:

  • tramline_map (np.ndarray) – Tramline map array

  • match_vector (np.ndarray) – Vector matching fibre numbers to trace numbers

  • sep (float) – Nominal separation between fibres

kspecdr.tlm.make_tlm.interpolate_tramlines_taipan(tramline_map: ndarray, match_vector: ndarray, nominal_positions: ndarray) → None[source]#

Interpolate missing fibre traces for TAIPAN instrument.

Parameters:

  • tramline_map (np.ndarray) – Tramline map array

  • match_vector (np.ndarray) – Vector matching fibre numbers to trace numbers

  • nominal_positions (np.ndarray) – Nominal fibre positions

kspecdr.tlm.make_tlm.make_tlm(args: Dict[str, Any]) → None[source]#

Generate a tramline map from an image file.

This function replaces the Fortran MAKE_TLM subroutine.

Parameters:

args (dict) – Dictionary containing method arguments including: - ‘IMAGE_FILENAME’: Input image file path - ‘TLMAP_FILENAME’: Output tramline map file path (optional)

kspecdr.tlm.make_tlm.make_tlm_from_im(im_file: ImageFile, tlm_fname: str, args: Dict[str, Any]) → None[source]#

Generate tramline map from an opened image file.

This function replaces the Fortran MAKE_TLM_FROM_IM subroutine.

Parameters:

  • im_file (ImageFile) – Opened image file handler

  • tlm_fname (str) – Output tramline map filename

  • args (dict) – Method arguments

kspecdr.tlm.make_tlm.make_tlm_other(im_file: ImageFile, tlm_fname: str, instrument_code: int, args: Dict[str, Any]) → None[source]#

Generate tramline map for non-2DF instruments.

This function replaces the Fortran MAKE_TLM_OTHER subroutine.

Parameters:

  • im_file (ImageFile) – Opened image file handler

  • tlm_fname (str) – Output tramline map filename

  • instrument_code (int) – Instrument code

  • args (dict) – Method arguments

kspecdr.tlm.make_tlm.match_traces_to_fibres(instrument_code: int, traces: ndarray, fibre_types: ndarray, pk_posn: ndarray, args: Dict[str, Any]) → Tuple[ndarray, ndarray][source]#

Match detected traces to fibre indices.

Parameters:

  • instrument_code (int) – Instrument code

  • traces (np.ndarray) – Detected traces

  • fibre_types (np.ndarray) – Array of fibre types

  • pk_posn (np.ndarray) – Peak positions

  • args (dict) – Method arguments

Returns:

(match_vector, modelled_fibre_positions)

Return type:

tuple

kspecdr.tlm.make_tlm.predict_wavelength(im_file: ImageFile, tramline_map: ndarray, args: Dict[str, Any]) → ndarray[source]#

Predict wavelength for each pixel along each fibre.

Parameters:

  • im_file (ImageFile) – Image file handler

  • tramline_map (np.ndarray) – Tramline map array

  • args (dict) – Method arguments

Returns:

Wavelength array

Return type:

np.ndarray

kspecdr.tlm.make_tlm.predict_wavelength_from_dispersion(im_file: ImageFile, nspec: int, nf: int) → ndarray[source]#

Predict wavelength from dispersion and central wavelength in the header.

Parameters:

  • im_file (ImageFile) – Image file handler

  • nspec (int) – Number of pixels in the dispersion direction

  • nf (int) – Number of fibres

Returns:

Wavelength array

Return type:

np.ndarray

kspecdr.tlm.make_tlm.predict_wavelength_taipan(im_file: ImageFile, nspec: int, nf: int) → ndarray[source]#

Predict wavelength for TAIPAN instrument (Fortran WLA_TAIPAN equivalent). Reads LAMBDAC and DISPERS from FITS header and computes wavelength for each pixel/fibre.

kspecdr.tlm.make_tlm.read_instrument_data(im_file: ImageFile, instrument_code: int, args: Dict[str, Any]) → Tuple[ndarray, ndarray, ndarray][source]#

Read instrument data from image file.

Parameters:

  • im_file (ImageFile) – Opened image file handler

  • instrument_code (int) – Instrument code

Returns:

(img_data, var_data, fibre_types)

Return type:

tuple

kspecdr.tlm.make_tlm.set_instrument_specific_params(instrument_code: int, args: Dict[str, Any]) → Tuple[int, int, bool, bool, bool, bool][source]#

Set instrument-specific parameters.

Parameters:

  • instrument_code (int) – Instrument code

  • args (dict) – Method arguments

Returns:

(order, pk_search_method, do_distortion, sparse_fibs, experimental, qad_pksearch)

Return type:

tuple

kspecdr.tlm.make_tlm.write_tramline_data(tlm_fname: str, tramline_map: ndarray, instrument_code: int, im_file: ImageFile) → None[source]#

Write tramline data to output file.

Parameters:

  • tlm_fname (str) – Output filename

  • tramline_map (np.ndarray) – Tramline map array

  • instrument_code (int) – Instrument code

  • im_file (ImageFile) – Image file handler

kspecdr.tlm.make_tlm.write_wavelength_data(tlm_fname: str, wavelength_data: ndarray) → None[source]#

Write wavelength data to tramline map file.

Parameters:

  • tlm_fname (str) – Tramline map filename

  • wavelength_data (np.ndarray) – Wavelength array

Fiber matching routines for KSPEC.

This module provides functions to match detected traces to physical fibers for various instruments (TAIPAN, ISOPLANE).

kspecdr.tlm.match_fibers.match_fibers_isoplane(nf: int, pk_posn: ndarray) → Tuple[ndarray, ndarray][source]#

Simple 1-to-1 fiber matching for ISOPLANE.

Traces are assumed ordered by increasing y (trace 1 = lowest y). Fiber table row 1 corresponds to highest y, so mapping is reversed: fiber 0 is assigned the last (highest-y) trace, fiber 1 the second-to-last, etc.

Parameters:

  • nf (int) – Number of fibers

  • pk_posn (np.ndarray) – Detected peak positions (ordered by increasing y)

Returns:

(match_vector, modelled_positions)

Return type:

tuple

kspecdr.tlm.match_fibers.match_fibers_taipan(nf: int, fibre_types: ndarray, pk_posn: ndarray, ar_posn: ndarray, max_del: float = 4.1) → Tuple[ndarray, ndarray][source]#

Match traces to fibers for TAIPAN using LAP (Linear Assignment Problem).

Parameters:

  • nf (int) – Number of fibers

  • fibre_types (np.ndarray) – Array of fibre types (‘P’, ‘S’, ‘N’, etc.)

  • pk_posn (np.ndarray) – Detected peak positions

  • ar_posn (np.ndarray) – Archived/Nominal fiber positions

  • max_del (float) – Maximum acceptable deviation (pixels)

Returns:

(match_vector, modelled_positions) match_vector: Array of size NF, where match_vector[fib_idx] = trace_idx (1-based) modelled_positions: Array of size NF with fitted positions

Return type:

tuple

kspecdr.tlm.match_fibers.taipan_nominal_fibpos(spectid: str, n: int) → ndarray[source]#

Get nominal fiber positions for TAIPAN.

Parameters:

  • spectid (str) – Spectrograph ID (‘B…’ for Blue, otherwise Red)

  • n (int) – Number of fibers (typically 150 or 300)

Returns:

Array of nominal positions

Return type:

np.ndarray