LineFinder.h

Go to the documentation of this file.
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_ */
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

Generated on 31 Aug 2016 for casa by  doxygen 1.6.1