1.26. detectLines

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

Description

Automatic line detection for HCSS

This tool uses SmoothBaseline which determines the regions of lines before to fit a baseline. The resulting regions of lines are then separated using a moving average and slope detection method. 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: Detect the lines of a Spectrum1d using the default values
lines = DetectLinesTask()(data)
Example 2: Detect the lines of a Spectrum1d without splitting it
lines = DetectLinesTask()(data, nbOfSplits=1)
Example 3: Detect the lines with specific values for the detection (box, midcycle)
box      = 100  # No unit
midcycle = 2E7  # per inverse wavenumber in micron
#
lines = DetectLinesTask()(data, box=box, midcycle=midcycle)
Example 4: Detect 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 = DetectLinesTask()(data,
                            fwhmEmission=fwhmEmission, fwhmAbsorption=fwhmAbsorption,
                            calibration=calibration, minSNR=minSNR, width=width)
Example 5: Extract the detected lines and the spectrum without its baseline
detected = lines["detected"]    # All the lines that were detected
Example 6: Extract the baseline-subtracted spectrum
baselineSubtracted = lines["baseline"]
Example 7: Export the detected lines to a Spectrum1d
frequency = baselineSubtracted.getWave()
intensity = baselineSubtracted.getFlux()
detectedS1d = detected.exportTo("Spectrum1d", frequency, intensity)
Example 8: Save the detected lines to a CASSIS linelist
# spectrum is your original Spectrum1d
fwhm        = {"emission": 0.005, "absorption": 0.002}
calibration = 0.1
width       = 0.05
#
detectedCassis = detected.saveSpectrumTo("path/to/detected.txt",
                                     spectrum=spectrum,
                                     width=width, fwhm=fwhm, calibration=calibration)

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.

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 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 detected lines * the initial spectrum without its baseline (this resulting spectrum is determined by smoothBaseline after masking the regions of lines)

History

  • DR-25/03/2015: Initial version
  • MB-20/10/2015: Update parameters and documentation