casa  5.7.0-16
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Fit2D.h
Go to the documentation of this file.
1 //# Fit2D.h: Class to fit 2-D objects to Lattices or Arrays
2 //# Copyright (C) 1997,1998,1999,2000,2001,2002
3 //# Associated Universities, Inc. Washington DC, USA.
4 //#
5 //# This library is free software; you can redistribute it and/or modify it
6 //# under the terms of the GNU Library General Public License as published by
7 //# the Free Software Foundation; either version 2 of the License, or (at your
8 //# option) any later version.
9 //#
10 //# This library is distributed in the hope that it will be useful, but WITHOUT
11 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12 //# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
13 //# License for more details.
14 //#
15 //# You should have received a copy of the GNU Library General Public License
16 //# along with this library; if not, write to the Free Software Foundation,
17 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
18 //#
19 //# Correspondence concerning AIPS++ should be addressed as follows:
20 //# Internet email: aips2-request@nrao.edu.
21 //# Postal address: AIPS++ Project Office
22 //# National Radio Astronomy Observatory
23 //# 520 Edgemont Road
24 //# Charlottesville, VA 22903-2475 USA
25 //#
26 //# $Id$
27 
28 #ifndef LATTICES_FIT2D_H
29 #define LATTICES_FIT2D_H
30 
31 //# Includes
32 #include <casacore/casa/aips.h>
37 
38 namespace casacore { //# NAMESPACE CASACORE - BEGIN
39 
40 template<class T> class Array;
41 template<class T> class Matrix;
42 template<class T> class Vector;
43 template<class T> class Lattice;
44 template<class T> class MaskedLattice;
45 
46 
47 // <summary>
48 // Fit 2-D objects to 2-D Lattices or Arrays
49 // </summary>
50 
51 // <use visibility=export>
52 
53 // <reviewed reviewer="" date="" tests="">
54 // </reviewed>
55 
56 // <prerequisite>
57 // <li> <linkto class=Lattice>Lattice</linkto>
58 // </prerequisite>
59 
60 // <synopsis>
61 // This class allows you to fit different types of 2-D models
62 // to either Lattices or Arrays. These must be 2 dimensional;
63 // for Lattices, the appropriate 2-D Lattice can be made with
64 // the SubLattice class.
65 //
66 // You may fit more than one model simultaneously to the data.
67 // Models are added with the addModel method. With this method,
68 // you also specify the initial guesses of the parameters of
69 // the model. Any parameters involving coordinates are
70 // expected in zero-relative absolute pixel coordinates (e.g. the centre of
71 // a model). Additionally with the addModel method,
72 // you may specify which parameters are to be held fixed
73 // during the fitting process. This is done with the
74 // parameterMask Vector which is in the same order as the
75 // parameter Vector. A value of True indicates the parameter
76 // will be fitted for. Presently, when you say fix the minor axis,
77 // you really end up fixing the axial ratio (internals). I don't
78 // have a solution for this presently.
79 //
80 // For Gaussians, the parameter Vector (input or output) consists, in order, of
81 // the peak, x location, y location, FWHM of major axis, FWHM of minor axis,
82 // and position angle of the major axis (in radians). The
83 // position angle is positive +x to +y
84 // in the pixel coordinate system ([0,0] in center of image) and
85 // in the range -2pi to 2pi. When the solution is recovered, the
86 // position angle will be in the range 0 to pi.
87 //
88 // </synopsis>
89 // <example>
90 // <srcblock>
91 // </srcblock>
92 // </example>
93 
94 // <todo asof="1998/12/11">
95 // <li> template it
96 // <li> Speed up some Array calculations indexed with IPositions
97 // <li> Don't handle Lattices simply by getting pixels into Arrays
98 // <li> make an addModel interface taking functionals
99 // </todo>
100 
101 class Fit2D
102 {
103 public:
104 
105  // Enum describing the different models you can fit
106  enum Types {
107  GAUSSIAN = 0,
108  DISK = 1,
109  LEVEL=2,
110  PLANE=3,
112  };
113 
114  // Enum describing output error conditions
115  enum ErrorTypes {
116 // ok
117  OK = 0,
118 // Did not converge
120 // Solution failed
121  FAILED = 2,
122 // There were no unmasked points
123  NOGOOD = 3,
124 // No models set
125  NOMODELS = 4,
126 // Number of conditions
128  };
129 
130  // Constructor
131  explicit Fit2D(LogIO& logger);
132 
133  // Destructor
134  ~Fit2D();
135 
136  // Copy constructor. Uses copy semantics except for the logger
137  // for which a reference copy is made
138  Fit2D(const Fit2D& other);
139 
140  // Assignment operator. Uses copy semantics except for the logger
141  // for which a reference copy is made
142  Fit2D& operator=(const Fit2D& other);
143 
144  // Add a model to the list to be simultaneously fit and
145  // return its index. Specify the initial guesses for
146  // the model and a mask indicating whether the parameter
147  // is fixed (False) during the fit or not. Returns the
148  // the model number added (0, 1, 2 etc)
149  //<group>
151  const Vector<Double>& parameters,
152  const Vector<Bool>& parameterMask);
154  const Vector<Double>& parameters);
155  //</group>
156 
157  // Convert mask from a string to a vector. The string gives the parameters
158  // to keep fixed in the fit (f (flux), x (x position), y (y position),
159  // a (FWHM major axis), b (FWHM minor axis), p (position angle)
160  static Vector<Bool> convertMask (const String fixedmask,
162 
163 
164  // Set a pixel selection range. When the fit is done, only
165  // pixels in the specified range are included/excluded.
166  // Only the last call of either of these will be active.
167  //<group>
168  void setIncludeRange (Double minVal, Double maxVal);
169  void setExcludeRange (Double minVal, Double maxVal);
170  void resetRange();
171  //</group>
172 
173  // Return number of parameters for this type of model
175 
176  // Recover number of models
177  uInt nModels() const;
178 
179  // Determine an initial estimate for the solution of the specified
180  // model type to the given data - no compound models are allowable
181  // in this function. If you have specified an include
182  // or exclude pixel range to the fitter, that will be honoured.
183  // This function does not interact with the addModel function.
184  // Returns a zero length vector if it fails to make an estimate.
185  //<group>
186  template<class T> Vector<Double> estimate(Fit2D::Types type,
187  const MaskedLattice<T>& data);
188  template<class T> Vector<Double> estimate(
190  );
191  template<class T> Vector<Double> estimate(
193  );
194  template<class T> Vector<Double> estimate(
196  );
197  //</group>
198 
199  // Do the fit. Returns an enum value to tell you what happened if the fit failed
200  // for some reasons. A message can also be found with function errorMessage if
201  // the fit was not successful. For Array(i,j) i is x and j is y
202  //<group>
203  template <class T> Fit2D::ErrorTypes fit(const MaskedLattice<T>& data,
204  const Lattice<T>& sigma);
205  template <class T> Fit2D::ErrorTypes fit(const Lattice<T>& data,
206  const Lattice<T>& sigma);
207  template <class T> Fit2D::ErrorTypes fit(const Array<T>& data,
208  const Array<T>& sigma);
209  template <class T> Fit2D::ErrorTypes fit(const Array<T>& data,
210  const Array<Bool>& mask,
211  const Array<T>& sigma);
212  //</group>
213 
214  // Find the residuals to the fit. xOffset and yOffset allow one to provide a data
215  // array that is offset in space from the grid that was fit. In this way, one
216  // can fill out a larger image than the subimage that was fit, for example. A negative
217  // value of xOffset means the supplied data array represents a grid that has a y axis left
218  // of the grid of pixels that was fit. A negative yOffset value means the supplied data
219  // array represents a grid that has an x axis that is below the x axis of the grid of pixels
220  // that was fit.
221  // NOTE these may need to be templated at some point in the future. My
222  // current need does not require they be templated. - dmehring 29jun2018
223  //<group>
224  template <class T> Fit2D::ErrorTypes residual(
225  Array<T>& resid, Array<T>& model,
226  const Array<T>& data, Int xOffset=0, int yOffset=0
227  ) const;
228 
230  const MaskedLattice<Float>& data);
232  const Lattice<Float>& data);
233  //</group>
234  // If function fit failed, you will find a message here
235  // saying why it failed
236  String errorMessage () const;
237 
238  // Recover solution for either all model components or
239  // a specific one. These functions will return an empty vector
240  // if there is no valid solution. All available parameters (fixed and
241  // adjustable) are included in the solution vectors.
242  //<group>
244  Vector<Double> availableSolution (uInt which) const;
245  //</group>
246 
247  // The errors. All available parameters (fixed and adjustable) are
248  // included in the error vectors. Unsolved for parameters will
249  // have error 0.
250  //<group>
252  Vector<Double> availableErrors(uInt which) const;
253  //</group>
254 
255  // The number of iterations that the fitter finished with
256  uInt numberIterations() const;
257 
258  // The chi squared of the fit. Returns 0 if fit has been done.
259  Double chiSquared () const;
260 
261  // The number of points used for the last fit
262  uInt numberPoints () const;
263 
264  // Return type as a string
265  static String type(Fit2D::Types type);
266 
267  // Return string type as enum (min match)
268  static Fit2D::Types type(const String& type);
269 
270  // Find type of specific model
271  Fit2D::Types type(uInt which);
272 
273  // Convert p.a. (radians) from positive +x -> +y
274  // (Fit2D) to positive +y -> -x (Gaussian2D)
275  static Double paToGauss2D (Double pa) {return pa - C::pi_2;};
276 
277  // Convert p.a. (radians) from positive +y -> -x
278  // (Gaussian2D) to positive +x -> +y (Fit2D)
279  static Double paFromGauss2D (Double pa) {return pa + C::pi_2;};
280 
281 private:
282 
283  mutable LogIO itsLogger;
294 
296 
298  const Matrix<Double>& pos,
299  const Vector<Double>& sigma);
300 
301 // Returns available (adjustable + fixed) solution for model of
302 // interest and tells you where it began in the full solution vector
303 // Does no axial ratio nor position angle conversions from direct
304 // fit solution vector
305 // <group>
306  Vector<Double> availableSolution (uInt& iStart, uInt which) const;
307  Vector<Double> availableErrors (uInt& iStart, uInt which) const;
308 // </group>
309 
310  Vector<Double> getParams(uInt which) const;
311  void setParams(const Vector<Double>& params, uInt which);
312 
313  Bool includeIt (Double value, const Vector<Double>& range,
314  Int includeIt) const;
315 
316  template <class T> Bool selectData (
317  Matrix<Double>& pos, Vector<Double>& values,
318  Vector<Double>& weights, const Array<T>& pixels,
319  const Array<Bool>& mask, const Array<T>& sigma
320  );
321 
322  void piRange (Double& pa) const;
323 
324 };
325 
327  Int includeIt) const
328 {
329  if (includeIt==0) return True;
330 //
331  if (includeIt==1) {
332  if (value >= range(0) && value <= range(1)) return True;
333  } else if (value < range(0) || value > range(1)) {
334  return True;
335  }
336 //
337  return False;
338 }
339 
340 } //# NAMESPACE CASACORE - END
341 
342 #ifndef CASACORE_NO_AUTO_TEMPLATES
343 #include <casacore/lattices/LatticeMath/Fit2D2.tcc>
344 #endif //# CASACORE_NO_AUTO_TEMPLATES
345 
346 #endif
347 
348 
void piRange(Double &pa) const
int Int
Definition: aipstype.h:50
std::vector< double > Vector
Definition: ds9context.h:24
Fit2D & operator=(const Fit2D &other)
Assignment operator.
There were no unmasked points.
Definition: Fit2D.h:123
Bool itsValidSolution
Definition: Fit2D.h:284
LogIO itsLogger
Definition: Fit2D.h:279
LatticeExprNode mask(const LatticeExprNode &expr)
This function returns the mask of the given expression.
uInt itsNumberPoints
Definition: Fit2D.h:293
Vector< Double > availableErrors() const
The errors.
Solution failed.
Definition: Fit2D.h:121
Vector< Double > itsSolution
Definition: Fit2D.h:289
Bool includeIt(Double value, const Vector< Double > &range, Int includeIt) const
Definition: Fit2D.h:326
Fit2D::ErrorTypes fit(const MaskedLattice< T > &data, const Lattice< T > &sigma)
Do the fit.
String errorMessage() const
If function fit failed, you will find a message here saying why it failed.
const Double pi_2
pi/2
A templated, abstract base class for array-like objects with masks.
Vector< Double > getParams(uInt which) const
ErrorTypes
Enum describing output error conditions.
Definition: Fit2D.h:115
ostream-like interface to creating log messages.
Definition: LogIO.h:167
Fit2D(LogIO &logger)
Constructor.
static Double paFromGauss2D(Double pa)
Convert p.a.
Definition: Fit2D.h:279
Vector< Double > availableSolution() const
Recover solution for either all model components or a specific one.
ABSTRACT CLASSES Deliberately vague to be general enough to allow for many different types of data
Definition: PlotData.h:48
uInt numberPoints() const
The number of points used for the last fit.
static String type(Fit2D::Types type)
Return type as a string.
Did not converge.
Definition: Fit2D.h:119
Double chiSquared() const
The chi squared of the fit.
A templated, abstract base class for array-like objects.
LatticeExprNode pa(const LatticeExprNode &left, const LatticeExprNode &right)
This function finds 180/pi*atan2(left,right)/2.
Fit2D::ErrorTypes fitData(const Vector< Double > &values, const Matrix< Double > &pos, const Vector< Double > &sigma)
static Vector< Bool > convertMask(const String fixedmask, Fit2D::Types type)
Convert mask from a string to a vector.
void setParams(const Vector< Double > &params, uInt which)
NonLinearFitLM< Double > itsFitter
Definition: Fit2D.h:288
double Double
Definition: aipstype.h:55
void setExcludeRange(Double minVal, Double maxVal)
Bool itsInclude
Definition: Fit2D.h:285
Fit2D::ErrorTypes residual(Array< T > &resid, Array< T > &model, const Array< T > &data, Int xOffset=0, int yOffset=0) const
Find the residuals to the fit.
Types
Enum describing the different models you can fit.
Definition: Fit2D.h:106
String itsErrorMessage
Definition: Fit2D.h:292
Bool itsValid
Definition: Fit2D.h:284
Vector< Double > itsErrors
Definition: Fit2D.h:290
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
Vector< Double > itsPixelRange
Definition: Fit2D.h:286
const Bool False
Definition: aipstype.h:44
Bool selectData(Matrix< Double > &pos, Vector< Double > &values, Vector< Double > &weights, const Array< T > &pixels, const Array< Bool > &mask, const Array< T > &sigma)
template &lt;class T, class U&gt; class vector;
Definition: MSFlagger.h:37
~Fit2D()
Destructor.
Fit 2-D objects to 2-D Lattices or Arrays.
Definition: Fit2D.h:101
uInt numberIterations() const
The number of iterations that the fitter finished with.
Number of conditions.
Definition: Fit2D.h:127
Bool itsHasSigma
Definition: Fit2D.h:284
static Double paToGauss2D(Double pa)
Convert p.a.
Definition: Fit2D.h:275
Vector< uInt > itsTypeList
Definition: Fit2D.h:295
Double itsChiSquared
Definition: Fit2D.h:291
String: the storage and methods of handling collections of characters.
Definition: String.h:223
void setIncludeRange(Double minVal, Double maxVal)
Set a pixel selection range.
CompoundFunction< AutoDiff< Double > > itsFunction
Definition: Fit2D.h:287
Vector< Double > estimate(Fit2D::Types type, const MaskedLattice< T > &data)
Determine an initial estimate for the solution of the specified model type to the given data - no com...
No models set.
Definition: Fit2D.h:125
const Bool True
Definition: aipstype.h:43
Sum of a collection of Functions which behaves as one Function object.
LatticeExprNode value(const LatticeExprNode &expr)
This function returns the value of the expression without a mask.
uInt addModel(Fit2D::Types type, const Vector< Double > &parameters, const Vector< Bool > &parameterMask)
Add a model to the list to be simultaneously fit and return its index.
unsigned int uInt
Definition: aipstype.h:51
static uInt nParameters(Fit2D::Types type)
Return number of parameters for this type of model.
uInt nModels() const
Recover number of models.
#define casacore
&lt;X11/Intrinsic.h&gt; #defines true, false, casacore::Bool, and String.
Definition: X11Intrinsic.h:42