00001 //# -------------------------------------------------------------------- 00002 //# LineFinder.h: this defines utility functions of line finding 00003 //# -------------------------------------------------------------------- 00004 //# Copyright (C) 2015 00005 //# National Astronomical Observatory of Japan 00006 //# 00007 //# This library is free software; you can redistribute it and/or modify it 00008 //# under the terms of the GNU Library General Public License as published by 00009 //# the Free Software Foundation; either version 2 of the License, or (at your 00010 //# option) any later version. 00011 //# 00012 //# This library is distributed in the hope that it will be useful, but WITHOUT 00013 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 00014 //# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public 00015 //# License for more details. 00016 //# 00017 //# You should have received a copy of the GNU Library General Public License 00018 //# along with this library; if not, write to the Free Software Foundation, 00019 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA. 00020 //# 00021 //# Correspondence concerning AIPS++ should be addressed as follows: 00022 //# Internet email: aips2-request@nrao.edu. 00023 //# Postal address: AIPS++ Project Office 00024 //# National Radio Astronomy Observatory 00025 //# 520 Edgemont Road 00026 //# Charlottesville, VA 22903-2475 USA 00027 //# 00028 //# $Id$ 00029 #ifndef _CASA_LINEFINDER_H_ 00030 #define _CASA_LINEFINDER_H_ 00031 00032 #include <list> 00033 00034 #include <casa/aipstype.h> 00035 #include <casa/Arrays/Vector.h> 00036 00037 namespace casa { //# NAMESPACE CASA - BEGIN 00038 00039 namespace linefinder { 00040 /* 00041 * Find spectral lines of a spectrum using a threshold based on median 00042 * absolute deviation (MAD). 00043 * The median of lower 80% of MAD values are used to define the 00044 * threshold of line channels. 00045 * 00046 * @param[in] num_data : the number of elements in data and mask vector. 00047 * @param[in] data : a float vector of data to detect lines. should be aligned. 00048 * @param[in] mask : a boolean vector which indecates if the corresponding elements 00049 * in data should be used in line detection. 00050 * Note mask is modified in the function. Edge channels are masked. 00051 * @param[in] threshold: a multiplication factor to define threshold. 00052 * @param[in] max_iteration : the maximum number of iteration to detect line, 00053 * and eliminate the line channels to redefine MAD array. 00054 * @param[in] minwidth : minimum line width (in channel) to detect as lines 00055 * @param[in] maxwidth : maximum line width (in channel) to detect as lines 00056 * @param[in] avg_limit : maximum width of channel binning to run line detection. 00057 * @param[in] edge : the number of elements at the begining and end of data array 00058 * that should be ignored in line detection. 00059 * @return a list of line channel ranges 00060 * 00061 * [overview of line detection algorithm] 00062 * 1. Median absolute deviation of each data element is calculated and 00063 * defined as MAD array. 00064 * 2. Calculate median of MAD array. Only lower 80% of valid elements 00065 * (mask=true and not in lines) are used to calculate the value. 00066 * 3. Compare each element of MAD array and the product of 00067 * threshold and median of MAD. Elements that exceeds 00068 * the threshold value are detected as channels. 00069 * 4. Line range modifications,e.g., extend line ranges for wing component, 00070 * merge overlapping lines, and check if line meets maxwidth and 00071 * minwidth criteria. 00072 * 5. Go to step 1 and repeat line detection by removing line channels 00073 * from MAD calculations. stop iteration either if loop reaches 00074 * max_iteration, no lines found in the bin level, no new line channel 00075 * is detected, or MAD threshold increased compared to the previous 00076 * iteration. 00077 * 6. bin data with 4 times coarser width and repeat line detection again 00078 * untill bin width reaches to avg_limit. 00079 * Merge line ranges detected in the current bin level to previous result. 00080 */ 00081 std::list<std::pair<size_t, size_t>> MADLineFinder(size_t const num_data, 00082 float const data[/*num_data*/], bool mask[/*num_data*/], 00083 float const threshold, uint8_t max_iteration, size_t const minwidth, 00084 size_t const maxwidth, size_t const avg_limit, 00085 std::pair<size_t, size_t> edge); 00086 00087 /* 00088 Create a boolean mask vector from ranges. 00089 mask : a boolean vector that stores output mask. see below for 00090 the values set to each elements of mask. 00091 ranges : a list of start and end idices pairs to set value in mask. 00092 invert : a flag to define values of elements inbetween ranges. 00093 the elements of mask vector whose values are inbetween 00094 one of start end idices in ranges list are set to 00095 true if invert=false (default), otherwise, false. 00096 initialize : whether or not initialize all elements in mask vector. 00097 when initialize=true, mask array is initialized by 00098 false if invert=false (default) or true if invert=true. 00099 when initilize=false, only elements inbetween ranges 00100 list will be modified. 00101 */ 00102 void getMask(size_t const num_mask, bool mask[/*num_mask*/], 00103 std::list<std::pair<size_t, size_t>>& ranges, bool invert = false, 00104 bool initialize = true); 00105 } 00106 } //# NAMESPACE CASA - END 00107 00108 #endif /* _CASA_LINEFINDER_H_ */