1.96. identifyLines

Full Name: herschel.hifi.dp.tools.IdentifyLinesTask
Alias: identifyLines
Type: Jython Task - Jython Task
Import: from herschel.hifi.dp.tools import IdentifyLinesTask

Description

Automatic line identification for HIFI data

Identify the lines in the data by comparing them with the given CASSIS linelist. The identification of the lines in the data consists in 3 steps:

  • the detection of possible lines in the data

  • the filtering of the detected lines using the signal-to-noise ratio

  • the comparison of the remaining lines of the data with the known linelist from the linelist

The resulting lines are objects (Line class) with specific attributes and methods for handling them individually. They are stored in a convenient data structure (Linelist class) that allow global manipulations of all the lines. (cf examples)

Examples

Example 1: Identify the lines of a Spectrum1d using the default values
lines = IdentifyLinesTask()(data, vlsr)
Example 2: Identify the lines of a Spectrum1d without splitting it
lines = IdentifyLinesTask()(data, vlsr, nbOfSplits=1)
Example 3: Identify the lines with specific values for the detection (box, midcycle)
box      = 100  # No unit
midcycle = 2E7  # per inverse wavenumber in micron
#
lines = IdentifyLinesTask()(data, vlsr, box=box, midcycle=midcycle)
Example 4: Identify the lines with specific values for the filtering (fwhmEmission, fwhmAbsorption, calibration, minSNR, width)
fwhmEmission   = 0.010  # the emission lines have a FWHM = 10 MHz
fwhmAbsorption = 0.004  # the absorption lines have a FWHM = 4 MHz
calibration    = 0.1    # the calibration of HIFI
minSNR         = 5      # the lines with a signal-to-noise ration >= 5 will be taken as real lines
width          = 0.1    # the RMS is computed on a width of 100 MHz around the line
#
lines = IdentifyLinesTask()(data, vlsr,
                            fwhmEmission=fwhmEmission, fwhmAbsorption=fwhmAbsorption,
                            calibration=calibration, minSNR=minSNR, width=width)
Example 5: Extract the detected, identified, unidentified
Warning: These elements are present only if there is a least a line in it.
detected     = lines["detected"]    # All the lines that were detected
identified   = lines["identified"]  # Lines detected whose frequencies are known
unidentified = lines["identified"]  # Lines detected whose frequencies are not known
Example 6: Extract the baseline-subtracted spectrum
baselineSubtracted = lines["baseline"]
Example 7: Export the identified lines to a Spectrum1d
frequency = baselineSubtracted.getWave()
intensity = baselineSubtracted.getFlux()
identifiedS1d = identified.exportTo("Spectrum1d", frequency, intensity)
Example 8: Export the identified lines to a SpectralLineList
Use the exportLines task.

API details

Properties

Spectrum1d data [INPUT, MANDATORY, default=None]

The data that contain the line to identify

String linelist [INPUT, OPTIONAL, default=None]

The path to the CASSIS linelist file. If no linelist is provided, a default linelist is chosen.

Double vlsr [INPUT, MANDATORY, default=None]

The vlsr of the source in km/s

Integer box [INPUT, OPTIONAL, default=200]

The input smooth box. Used by SmoothBaseline in the detection step.

Double midcycle [INPUT, OPTIONAL, default=1.7E6]

The mid of fringe search range (per inverse wavenumber in micron) Used by SmoothBaseline in the detection step.

Integer nbOfSplits [INPUT, OPTIONAL, default=4]

The number of shorter spectra of the same size to create from the initial wide spectrum. Splitting the initial spectrum has 2 benefits: - the fit of the baseline is better, which slightly improves the detection - the number of channels to be processed by SmoothBaseline is reduced, which greatly improves its speed If you don't want the data to be split, set nbOfSplits = 1.

Double fwhmEmission [INPUT, OPTIONAL, default=3.0]

The FWHM value (in km/s) for the emission lines. This value is used for the computation of the noise flux in the criterion for filtering real lines. Used in the filtering step.

Double fwhmAbsorption [INPUT, OPTIONAL, default=1.0]

The FWHM value (in km/s) for the absorption lines. This value is used for the computation of the noise flux in the criterion for filtering real lines. Used in the filtering step.

Double toleranceFactorEmi [INPUT, OPTIONAL, default=1.5]

The tolerance factor for the emission lines. Used in the comparison step.

Double toleranceFactorAbs [INPUT, OPTIONAL, default=1.5]

The tolerance factor for the absorption lines. Used in the comparison step.

Double calibration [INPUT, OPTIONAL, default=0.1]

The calibration of the instrument used in the computation of the noise flux Used in the filtering step.

Double minSNR [INPUT, OPTIONAL, default=5.0]

The minimum signal-to-noise ratio for which the filtered line is accepted Used in the filtering step.

Double width [INPUT, OPTIONAL, default=0.05]

The width of the region (in GHz) on which the RMS is computed around the line Used in the filtering step.

Double overlap [INPUT, OPTIONAL, default=0.25]

The overlap (in GHz) between the split spectra. Overlapping the spectra prevent the loss of lines between 2 consecutive spectra.

Integer smoothBox [INPUT, OPTIONAL, default=7]

The number of points on which the smoothing is done. (necessary for the moving average) This value must be odd otherwise smoothBox = smoothBox + 1. The number of channels on each side of the center of the smoothBox is: (smoothBox - 1) / 2

String snrType [INPUT, OPTIONAL, default=Intensity.]

The signal on noise ratio calculation algorithm (Intensity or Flux).

PyDictionary lines [OUTPUT, MANDATORY, default=None]

* the linelists objects for the lines - detected - identified - unidentified * the baseline spectrum

History

  • DR-06/11/2013: Initial version
  • DR-13/11/2014: The CASSIS linelist is optional
  • MB-20/10/2015: Update parameters and documentation