WikiStart: fitdocs.txt

File fitdocs.txt, 32.1 KB (added by pcr, 12 years ago)

documentation for model fitting procedures

Line 
1
2----- Documentation for Fit\average_parameters.pro -----
3 NAME:
4      AVERAGE_PARAMETERS
5
6 AUTHOR:
7      pierre.cruzalebes@oca.eu
8
9 PURPOSE:
10      average parameter vector estimates using weighted mean,
11      calculate errors from direct bootstrap (if enough parameter
12      vectors to average)
13
14 CATEGORY:
15      fitting
16
17 INPUTS:
18      need text input file (in OBS_PATH/INP/ directory) with:
19        - number of model parameter file(s) to average
20        - input model parameter file name(s)
21       - observation parameter file name(s) associated
22
23 REQUIREMENTS:
24      data read in input model parameter file(s) (in OBS_PATH/ subdirectory,
25      .out extension) must be in ASCII format and contain (in this order) :
26        - model flag, flux flag, synthetic exitance+radiance file names,
27        data format flag, starting parameters, free parameter flags,
28        goodness-of-fit parameter, input parameters, inferior errors,
29        superior errors, confidence level
30
31      data read in input observation parameter file(s) (in OBS_PATH/ subdirectory,
32      .obs extension, one row per observation) are of complex type :
33        - (DIT[s] , NDIT), (RA[deg] , DEC[deg]), (START_UTC[h] , END_UTC[h]),
34        (START_FWHM["] , END_FWHM), (START_TAU0[s] , START_TAU0[s]), (MJD@Oh , 0)
35
36 OUPUTS:
37      data written in output file (in OBS_PATH/OUT/ directory) must be in
38      ASCII format and contain (in this order) :
39        - model flag, flux flag, synthetic exitance+radiance file name,
40        data format flag, starting parameters, free parameter flags,
41        goodness-of-fit parameter, output parameters, inferior errors,
42        superior errors, nber of degrees of freedom
43
44 LOCAL PROCEDURE CALLED:
45        RESET_PLOT
46
47 LOCAL FUNCTION USED:
48        EXTRACT_PROHEADER
49       GET_OUTLIER_FENCES
50       TRI_STDEV
51        WAVG
52        WSTDEV
53        WSTERR
54
55 LOCAL SYSTEM VARIABLE USED:
56       EPSILON
57        FORMAT_OUT
58       MAX_REL_ERR
59        NB_BOOT_LOOPS
60        NB_DATA_BOOT
61        NB_MAX_PARAM
62       NB_OB_MAX
63       NB_TARG_MAX
64        OBS_PATH
65        PLOT_DEV
66        SPIDAST_PATH
67
68 REVISION HISTORY:
69      Written by pcr 2010/10/22
70      last modification by pcr 2010/12/12
71
72----- Documentation for Fit\boot_fit.pro -----
73 NAME:
74        BOOT_FIT
75
76 AUTHOR:
77       pierre.cruzalebes@oca.eu
78
79 PURPOSE:
80        Proceed nonparametric residual bootstrap iterations (random shoot
81       of centered  residuals with replacement) of gradient-expansion fits
82       calculate free-parameter confidence intervals.
83
84 CATEGORY:
85        fitting.
86
87 CALLING SEQUENCE:
88        DPAR = BOOT_FIT(XX,BSL,BWARR,MEAS,WGHT,PAR,PAR0,IDXF,NMODEL,VISI,
89                       TEFF,REF,CLEVEL,NBOOT,PAROUT,DCHISQR,IDXC,PAR_ARR)
90
91 INPUTS:
92        XX = Row vector of synthetic wavelengths,
93                or structure with synthetic wavelength vector XX.WVL
94                and relative impact parameter vect. XX.RIP
95        BSL = Row vector of baselengths.
96        BWARR = 2-D ARRAY WITH # OF BASELENGTHS AND # OF WAVELENGTHS FOR EACH PART
97                (DEFINED BY P2VM SETTING).
98                BWARR(I,0) = # OF BASELENGTHS FOR PART I
99                BWARR(I,1) = # OF WAVELENGTHS FOR PART I
100        MEAS = Row vector of measurements, length(MEAS)=length(XX or XX.WVL)
101                                                      *length(BSL).
102        WGHT = Row vector of experimental weight, same length as MEAS.
103        PAR = Row vector of parameter values.
104        PAR0 = Row vector of starting parameter values.
105       IDXF = Row vector of free parameter indexes, length lower or equal to PAR.
106       NMODEL = Nber of model used for fit.
107       VISI = Visibility flag ( 1:vis / 0:no vis ),
108              for bispectrum calculation VISI=table.
109        TEFF = Effective temperature used with MARCS flux or intensity tabulated data.
110        REF = Row vector of reference synthetic fluxes, same length as XX,
111                or 2-dim array of ref. synth. intensities, dim=(length(XX.WVL),
112                                                               length(XX.RIP)).
113        CLEVEL = Desired confidence level.
114        NBOOT = number of bootstrap loops.
115
116 OUTPUTS:
117        CLEVEL = Final confidence level.
118        PAROUT = 2-dim array of final parameters, dim=(length(PAR),!NB_BOOT_LOOPS).
119        DCHISQR = Row vector of final chi-square differences sorted
120                 by ascending order, length=!NB_BOOT_LOOPS.
121        IDXC = Row vector of success indexes (parameters in confidence region),
122              length lower or equal to !NB_BOOT_LOOPS.
123       PAR_ARR = 2-dim array of confid lev/nb of chi2 val in
124                 68.3%/95.4%/99.7%/99.99%-CI,
125                 and param(s) at lower/upper fences of each CI, dim=(length(PAR)+1,3)
126
127 FUNCTION RESULT:
128        DPAR = Row array of parameter inferior/superior error estimate(s),
129              dim=(length(PAR),2).
130
131 COMMON BLOCKS:
132        NONE.
133
134 SIDE EFFECTS:
135        NONE.
136
137 REQUIREMENTS:
138      The function to be fit must be defined and called in MODEL_DATA_FUNCT_PROJ.
139        For an example see FUNCT in the PV-WAVE User's Library.
140        Call to MODEL_DATA_FUNCT_PROJ is:
141        MODEL_DATA_FUNCT_PROJ,XX,BSL,BWARR,PAR,IDXF,NMODEL,VISI,TEFF,REF,
142            DEPTH_INTENS_DATA,DATA_FIT
143        where:
144                XX = row vector or structure of independant variables
145                        (wavelength or wavelength + relative inpact parameter), input.
146        BSL = row vector of baselength, input.
147                BWARR = 2-D array, input
148                PAR = row vector of parameters, input.
149        IDXF = row vector unforzen-parameter indexes, input.
150        NMODEL = number of model used for calculation of function, input.
151        VISI = visibility flag or bispectrum index table, input.
152                TEFF = temperature, input.
153        REF = row vector of synthetic fluxes or 2-dim array of synthetic
154                     intensities, input.
155               DEPTH_INTENS_DATA = 2-dim complex array with optical depth
156                                   and intensity
157                       or flag (=1/0) for opt. depth based models, output.
158                DATA_FIT = row vector of projected function values at each projected
159                          frequency (or proj. wavelength if base=0), output.
160 RESTRICTIONS:
161        NONE.
162
163 PROCEDURE:
164        SEE CODE.
165
166 LOCAL PROCEDURE CALLED:
167        LOCA_SCALE_CHI2
168        LOCA_SCALE_NORM
169        MODEL_DATA_FUNCT_PROJ
170
171 LOCAL FUNCTION USED:
172       GET_OUTLIER_FENCES
173        LM_FIT
174
175 LOCAL SYSTEM VARIABLE USED:
176        EPSILON
177       MAX_REL_ERR
178        NB_BASE_STEP
179        NB_BOOT_MIN
180       NB_DATA_BOOT
181       NB_DATA_MAX
182        NB_MAX_BOOTS
183        NB_DATA_MAX
184        NB_RES_STEP
185
186 REVISION HISTORY:
187       Written by pcr 2007/12/17
188        last modification by pcr 2011/01/04
189
190----- Documentation for Fit\create_fitting_batch.pro -----
191 NAME:
192      CREATE_FITTING_BATCH
193
194 AUTHOR:
195      pierre.cruzalebes@oca.eu
196
197 PURPOSE:
198      create program batch for model fitting processing and make input files
199      used by programs :
200      - limb-darkened spectral radiance conversion
201      - model fitting
202      - model parameter averaging
203
204 CATEGORY:
205      fitting
206
207 INPUTS:
208     needs text input file (in OBS_PATH/INP/ directory) with :
209        - target name
210        - data format ('vis', 'spec', 'coh', 'bisp', 'trip' or 'clos')
211        - model number used for fitting
212        - starting parameters (for LM)
213        - parameter flags (0:frozen / 1:unfrozen)
214        - name of synthetic spectrum ('none' if not needed)
215        - min and max wavelengths of global spectral range covered
216        with all bandwidths in all parts [mum] (in same row)
217       - fit format ('ob', 'part', 'dir', 'run', or 'all' for fit of model
218       with individual OBs, with target files contained in each data
219       part, directory (=day) or run, or with all target files)
220       - allocation programme information file (used only if fit format = 'run')
221
222 REQUIREMENTS:
223      individual OB files and dir/run/global concatenated obs parameter
224      files (in SCIENCE/ sub-directory) must have been previously created by
225      concatenate_observations call(s)
226
227      data read in allocation programme file (in OBS_PATH/ directory) must be in ASCII format
228      and contain 2*nrun+1 rows with :
229      - total number of run(s) allocated for the observing programme and obs run name(s) (same row)
230      then for each run :
231      - nber of allocated night(s) in run and name(s) of obs data directory(ies) (1 dir per obs night)
232
233 OUTPUTS:
234      model fitting processing batch text file (in SPIDAST_PATH/ directory)
235      and needed text input files (in OBS_PATH/INP/ directory)
236
237LOCAL PROCEDURE CALLED:
238        EXTRACT_PROHEADER
239
240 LOCAL FUNCTION USED:
241        NONE
242
243 LOCAL SYSTEM VARIABLE USED:
244        MAX_HEADER
245        NB_BAND_MAX
246       NB_PAIR_MAX
247        NB_OB_MAX
248        NB_PART_MAX
249        NB_TARG_MAX
250       NB_TRIPLE_MAX
251        OBS_PATH
252       SPEC_RES
253        SPIDAST_PATH
254
255 REVISION HISTORY:
256       Written by pcr 2010/11/03
257       last modification by pcr 2011/01/11
258
259----- Documentation for Fit\fit_model.pro -----
260 NAME:
261      FIT_MODEL
262
263 AUTHOR:
264      pierre.cruzalebes@oca.eu
265
266 PURPOSE:
267      fit model parameter(s)on calibrated spectro-interferometric data
268      use bootstrap loops of non-linear least squares fit (gradient-expansion
269      algorithm) combining gradient search with analytical solution
270      developed from linearizing fitting function.
271
272 CATEGORY:
273      fitting
274
275 INPUTS:
276      need text input file (in OBS_PATH/INP/ directory) with:
277        - data format ('vis', 'spec', 'coh', 'bisp', 'trip' or 'clos')
278        - number of part(s) (one file per P2VM setting)
279      spec data :
280        - input calibrated spec file name(s) (1 name per row)
281      other data :
282        - baselength file name(s)
283        - input calibrated data file name(s) (1 name per row, same order
284        than in baselength files : NTEL*(NTEL-1)/2 baselines per OB)
285      then, for all data formats :
286        - model number used for fitting
287        - starting parameters (for LM)
288        - parameter flags (0:frozen / 1:unfrozen)
289        - synthetic exitance and radiance file names ('none' if not needed,
290        in same row)
291        - number of values per parameter, used for chi-square plots
292        - desired confidence level (between 0 and 1)
293        - number of bootstrap iterations (-1 for no fit)
294        - optionaly : final spectral resolution at mean wavelength
295
296 REQUIREMENTS:
297      type of data used for fitting must be:
298        'vis' for visibility data
299        'spec' for spectrum data
300        'coh' for coherent spectrum data
301        'bisp' for bispectrum data
302        'trip' for triple product data
303        'clos' for closure phase data
304
305       spec data:
306       data read/written in input/output calibrated/fitted spec file (in
307       subdirectory of OBS_DATA/) must be in ASCII format and contain
308       (1 row per spectral channel):
309        - wavelength and bandwidth [m], flux and error [W/m^2/mum]
310        for each data file
311
312       data read in input baseline file(s) (in subdirectory of OBS_PATH/)
313       must be in ASCII format and contain (2*NBASE=NTEL*(NTEL-1) columns, one
314       row per obs file):
315        - (length[m] , angle[deg]) of each projected baseline
316        at obs file start/end
317
318       vis data:
319       data read/written in input/output calibrated/fitted vis. file (in
320       subdirectory of OBS_PATH/) must be in ASCII format and contain (1 row per
321       spectral channel):
322        - wavelength and bandwidth [m], visibility and error for each data file
323
324       coh spec data:
325       data read/written in input/output calibrated/fitted coh. spec. file (in
326       subdirectory of OBS_PATH/) must be in ASCII format and contain (1 row per
327       spectral channel):
328        - wavelength and bandwidth [m], coherent flux and error [W/m^2/mum]
329        for each data file
330
331       bisp data:
332       data read/written in input/output calibrated/fitted bisp. file (in
333       subdirectory of OBS_PATH/) must be in ASCII format and contain (1 row per
334       spectral channel):
335        - wavelength and bandwidth [m], real part of bispectrum and error,
336        imaginary part of bispectrum and error [(W/m^2/mum)^3]
337        for each data file
338
339       trip data:
340       data read/written in input/output calibrated/fitted triple prod. file (in
341       subdirectory of OBS_PATH/) must be in ASCII format and contain (1 row per
342       spectral channel):
343        - wavelength and bandwidth [m], real part of triple product and error,
344        imaginary part of triple product and error for each data file
345 
346       clos data:
347       data read/written in input/output calibrated/fitted clos. phase file (in
348       subdirectory of OBS_PATH) must be in ASCII format and contain (1 row per
349       spectral channel):
350        - wavelength and bandwidth [m], closure phase and error [deg]
351        for each data file
352
353       flag for model are defined in model_spectrum.pro as well as order of starting
354       parameters
355
356       data read in input synthetic exitance file (of name exitance_file_stem.spec,
357       in SYNTHE_PATH/ directory) must be in ASCII format and contain:
358        - wavelength [AA = 10^-4 mum] and exitance [erg/cm^2/s/AA =
359        10*W/m^2/mum)
360
361       if input synthetic radiance available (in SYNTHE_PATH/ directory)
362       use also radiance data composed of !NB_LUMIN+1 columns with:
363        - zero and relative impact parameters
364        (!NB_LUMIN values between 0. and 1., in first row)
365        - wavelength [mum] and !NB_LUMIN values of absolute radiance
366        [W/m^2/mum/sr] (one row per spectral channel)
367
368 OUTPUTS:
369      data written in output fit file (of name input_file_stem.out, in
370       OBS_PATH/OUT/ directory) must be in ASCII format and contain
371       (in this order):
372        - model flag, flux flag, synthetic exitance+radiance file names,
373        data format flag, starting parameters, free flags, final
374        goodness-of-fit parameter, fitted parameters, inferior errors,
375        superior errors, number of degrees of freedom
376
377       data written in covariance file (of name input_file_stem.cova, in
378       OBS_PATH/OUT/ directory) must be in ASCII format and contain
379       the covariance matrix (of size NB_MAX_PARAM*NB_MAX_PARAM)
380
381       data written in output first parameter file (of name input_file_stem.par,
382       in OBS_PATH/OUT/ directory) must be in ASCII format and contain (in this
383       order) :
384        - delta(chi-square) and free parameter vector(s) (1 row per vector)
385
386       data written in output second parameter file (of name input_file_stem.param,
387       in OBS_PATH/OUT/ directory) must be in ASCII format and contain
388       (in this order, one row per confid level) :
389        - confid lev/nb of chi2 val in confidence interval, and free param(s)
390        at lower/upper fences of each CI
391
392 LOCAL PROGRAM CALLED:
393        ENGELKE
394        GET_SYN_REF
395        LOCA_SCALE_NORM
396        MODEL_DATA_FUNCT
397        MODEL_DATA_FUNCT_PROJ
398        MODEL_SPECTRUM
399        PLANCK
400        PLOT_DISTRI
401        RESET_PLOT
402       UNIFORM_DISK
403
404 LOCAL FUNCTION USED:
405        BOOT_FIT
406        EXTRACT_PROHEADER
407        FUNCTPROJ
408        GET_OUTLIER_FENCES
409        LM_FIT
410        MAKE_TAB3
411        SYM
412        TRAP
413
414 LOCAL SYSTEM VARIABLE USED:
415        EPSILON
416        FORMAT_OUT
417        MAS2RADIAN
418        MAX_LONG
419        MAX_REL_ERR
420        NB_BASE_STEP
421        NB_BOOT_MIN
422        NB_DATA_MAX
423        NB_LAMBDA_MAX
424        NB_MAX_FITS
425        NB_MAX_PARAM
426        NB_OB_MAX
427        NB_PAIR_MAX
428        NB_RES_STEP
429        OBS_PATH
430       PARAM_REL_DIST
431        PLOT_DEV
432        SPEC_RES
433        SPIDAST_PATH
434        SYNTHE_PATH
435
436 REVISION HISTORY:
437       Written by pcr 2006/09/15
438       last modification by pcr 2011/01/22
439
440----- Documentation for Fit\fit_sed.pro -----
441 NAME:
442      FIT_SED
443
444 AUTHOR:
445      pierre.cruzalebes@oca.eu
446
447 PURPOSE:
448      fit model parameter(s) on SED data
449      use bootstrap loops of non-linear least squares method (gradient-expansion
450      algorithm) combining gradient search with analytical solution
451      developed from linearizing fitting function
452
453 INPUTS:
454     need text input file with :
455        - input SED and broadband effective parameter file name ('none' if
456        not needed, in same row)
457        - flag for model to be used for fitting
458        - starting parameters (for LM)
459        - parameter flags (0:frozen / 1:unfrozen)
460        - synthetic exitance file name
461        - number of values per parameter, used for chi-squared plots
462        - desired confidence level (between 0. and 1.)
463        - number of bootstrap iterations (-1 for no fit)
464
465 REQUIREMENTS:
466      data read in SED file (in subdirectory of OBS_PATH/)
467      must be in ASCII format and contain (in this order) :
468        - wavelength and bandwidth [mum], measured flux and error [W/m^2/mum]
469
470      data read in broadband effective parameter file (in ALL_DATA_PATH/
471      directory) must be in ASCII format and contain (in this order) :
472        - effective wavelength and bandwidth [mum] in each band for the used
473        model
474
475      flag for model are defined in model_spectrum.pro
476      as well as start-parameter order
477
478      data read in input synthetic exitance file (of name exitance_file_stem.spec
479      in SYNTHE_PATH/ directory) must be in ASCII format and contain :
480        - wavelength [AA = 10^-4 mum] and exitance [erg/cm^2/s/AA =
481        10*W/m^2/mum]
482
483 OUTPUTS:
484      data written in output file (of name input_file_stem.out in OBS_PATH/OUT/
485      directory) must be in ASCII format and contain (in this order) :
486        - model flag , flux flag, synthetic exitance+radiance file names, data
487        format flag, starting parameters, free flags, final goodness-of-fit
488        parameter, fitted parameters, inferior errors, superior errors, number
489        of degrees of freedom
490
491      data written in covariance file (of name input_file_stem.cova in
492      OBS_PATH/OUT/ directory) must be in ASCII format and contain the covariance
493      matrix (of size NB_MAX_PARAM*NB_MAX_PARAM)
494
495      data written in first parameter file (of name input_file_stem.par in
496      OBS_PATH/OUT/ directory) must be in ASCII format and contain
497      (in this order) :
498        - delta(chi2) and free parameter vector(s) (1 row per vector)
499
500      data written in second parameter file (of name input_file_stem.param in
501      OBS_PATH/OUT/ directory) must be in ASCII format and contain (in this order,
502      one row per confid level) :
503        - confid lev/nb of chi2 val in confidence interval, and free param(s)
504        at lower/upper fences of each CI
505
506 LOCAL PROCEDURE_CALLED:
507        ENGELKE
508        GET_SYN_REF
509        LOCA_SCALE_NORM
510        MODEL_DATA_FUNCT_PROJ
511        MODEL_SPECTRUM
512        PLANCK
513        PLOT_DISTRI
514        RESET_PLOT
515
516 LOCAL FUNCTION USED:
517        BOOT_FIT
518        EXTRACT_PROHEADER
519        FUNCTPROJ
520        GET_OUTLIER_FENCES
521        LM_FIT
522        TRAP
523
524 LOCAL SYSTEM VARIABLE USED:
525        ALL_DATA_PATH
526        EPSILON
527        FORMAT_OUT
528        MARCS_RES
529        MAX_LONG
530       MAX_REL_ERR
531        NB_BOOT_MIN
532        NB_DATA_MAX
533        NB_MAX_FITS
534        NB_MAX_PARAM
535        NB_RES_STEP
536        OBS_PATH
537       PARAM_REL_DIST
538        PLOT_DEV
539        SPIDAST_PATH
540        SYNTHE_PATH
541
542 REVISION HISTORY:
543       Written by pcr 2007/02/01
544       last modification by pcr 2011/01/22
545
546----- Documentation for Fit\ld_poly_fit.pro -----
547 NAME:    LD_POLY_FIT
548
549 PURPOSE: Non-linear least squares fit to a function of an arbitrary number
550          of parameters. The function may be any non-linear function where
551          the partial derivatives are known or can be approximated.
552
553 CATEGORY:
554          fitting.
555
556 USAGE:   yfit = LD_POLY_FIT(x, y, w, params [,sigmas])
557
558 INPUT:
559          x      - A vector of independent variables
560          y      - A vector of dependent variable, same length as x
561          w      - A vector of weights, same length as x. For no weighting set
562                   w(i) = 1., for instrumental weighting w(i) = 1./y(i), etc
563          params - On input, a vector containing the initial estimates of the
564                   parameters. The length of params must equal the number of
565                   parameters in the function that is trying to be fit to the
566                   x,y data
567
568 OUTPUT:
569          params - A vector of the calculated parameters of the fitted
570                   function
571          sigmas - (Optional) a vector of standard deviations of the
572                   parameters
573
574 RETURNED
575          yfit   - A vector of fitted dependent variable values
576
577 SIDE EFFECTS:
578          The function to be fit must be defined and called LD_POLY_FUNCT. The call
579          to LD_POLY_FUNCT is LD_POLY_FUNCT, x,p,f, pder where:
580             x - Input, a vector of independent variables
581             p - Input, a vector of function parameters
582             f - Output, a vector of values of the function, f(i)=ld_poly_funct(x(i))
583             pder - Optional output, an array of size length_of_x by
584                    number_of_parameters containing the partial derivatives
585                    of funct. pder(i,j) is the derivative of the function at
586                    the ith point with respect to the jth parameter.
587
588 PROCEDURE:
589          Copied from "CURFIT", least squares fit to a non-linear function,
590          pages 237-239, Bevington, Data Reduction and Error Analysis for the
591          Physical Sciences.
592
593          "This method is the Gradient-expansion algorithm which combines the
594          best features of the gradient search with the method of linearizing
595          the fitting function."
596
597          Iterations are perform until the chi square changes by only 0.1% or
598          until 20 iterations have been performed. The initial guess of the
599          parameter values should be as close to the actual values as
600          possible or the solution may not converge.
601
602 LOCAL PROCEDURE CALLED:
603        NONE
604
605 LOCAL FUNCTION USED:
606        LD_POLY_FUNCT
607
608 LOCAL SYSTEM VARIABLE USED:
609        EPSILON
610
611 REVISION HISTORY:
612       Written by pcr 2008/04/23
613        last modification by pcr 2010/06/28
614
615----- Documentation for Fit\ld_poly_funct.pro -----
616 NAME:
617        LD_POLY_FUNCT
618
619 AUTHOR:
620       pierre.cruzalebes@oca.eu
621
622 PURPOSE:
623        EVALUATE THE POLYNOMIAL LIMB-DARKENED LAW DERIVED FROM MANDUCA ET AL. (1997)
624        AND OPTIONALLY RETURN THE VALUE OF IT'S PARTIAL DERIVATIVES.
625        NORMALLY, THIS FUNCTION IS USED BY LD_POLY_FIT TO FIT THE
626        POLYNOMIAL LAW TO ACTUAL LIMB-DARKENED DATA.
627
628 CATEGORY:
629        FITTING.
630
631 CALLING SEQUENCE:
632        LD_POLY_FUNCT,X,A,F,PDER
633
634 INPUTS:
635        X = VALUES OF INDEPENDENT VARIABLE (= 1-MU).
636        A = PARAMETERS OF EQUATION DESCRIBED BELOW.
637
638 OUTPUTS:
639        F = VALUE OF FUNCTION AT EACH X(I).
640
641 OPTIONAL OUTPUT PARAMETERS:
642        PDER = (N_ELEMENTS(X),NDEGREE) ARRAY CONTAINING THE
643                PARTIAL DERIVATIVES.  P(I,J) = DERIVATIVE
644                AT ITH POINT W/RESPECT TO JTH PARAMETER.
645
646 COMMON BLOCKS:
647        NONE.
648
649 SIDE EFFECTS:
650        NONE.
651
652 RESTRICTIONS:
653        NONE.
654
655 PROCEDURE:
656        F = 1-A(0)*X-A(1)*X^2-A(2)*X^3-A(3)*X^4+...
657
658 LOCAL PROCEDURE CALLED:
659        NONE
660
661 LOCAL FUNCTION USED:
662        NONE
663
664 LOCAL SYSTEM VARIABLE USED:
665        NONE
666
667 REVISION HISTORY:
668       Written by pcr 2008/04/23
669        last modification by pcr 2010/07/01
670
671----- Documentation for Fit\lm_fit.pro -----
672 NAME:
673        LM_FIT
674
675 PURPOSE:
676        Non-linear least squares fit to a synthetic function of an
677        arbitrary number of parameters.
678        Function may be any non-linear function where
679        the partial derivatives are known or can be approximated.
680
681 CATEGORY:
682        Fitting
683
684 CALLING SEQUENCE:
685        YFIT = LM_FIT(SX,BL,BWA,VY,WG,PA,IDX,MNB,VIS,TEMP,SRF,COVAA)
686
687 INPUTS:
688        SX = Independent variables  = Row vector of synthetic wavelengths,
689                or structure with wavelengths and impact parameters.
690       BL = Row vector of baselengths.
691        BWA= 2-D array with # of baselengths and # of wavelengths for each part
692                (defined by P2VM setting).
693                BWA(I,0) = # of baselengths for part I
694                BWA(I,1) = # of wavelengths for part I
695        VY = Row vector of dependent variables (can be complex).
696        WG = Row vector of weights (can be complex), same length as VY.
697        PA = Row vector containing the initial parameter estimates. 
698       IDX = Row vector of unfrozen-parameter indexes.
699       MNB = Model nber.
700       VIS = Visibility flag (if null no vis, else vis),
701                for bispectrum calculation VIS = bispectrum index table .
702        TEMP = Effective temperature used with MARCS flux/intensity data.
703        SRF = Row vector (or matrix) of synthetic fluxes (or intensities).
704        PRINT_INFO = Flag for LM-info printing  ( 0: no print / 1: print ).
705
706 OUTPUTS:
707        PA = Row vector of parameters containing fit.
708       IDX = Row vector of output unfrozen-parameter indexes.
709        PRINT_INFO = Flag for LM-info printing  ( -1: fit failed ).
710        COVAA = Formal covariance matrix of the fit.
711
712
713 FUNCTION RESULT:
714        YFIT = Row vector of calculated values (same length as Y).
715       
716 COMMON BLOCKS:
717        NONE.
718
719 SIDE EFFECTS:
720        The function to be fit must be defined and called in MODEL_DATA_FUNCT_PROJ.
721        For an example see FUNCT in the PV-WAVE User's Library.
722        Call to MODEL_DATA_FUNCT_PROJ is:
723        MODEL_DATA_FUNCT_PROJ,XX,BASE,BWA,PA,IDX,MNB,VIS,TEMP,R0,
724          DEPTH_INTENS_DATA,F_PROJ,PDER_PROJ
725        where:
726            XX = row vector or structure of independant variables
727                        (wavelength or wavelength + relative inpact parameter), input.
728           BASE = row vector of baselength, input.
729            BWA = 2-D array, input
730            PA = row vector of parameters, input.
731           IDX = row vector unfrozen-parameter indexes, input.
732           MNB = model flag for calculation of function (and partial derivatives), input.
733           VIS = visibility flag or bispectrum index table, input.
734            TEMP = temperature, input.
735           R0 = row vector of synthetic fluxes or 2-D array of synthetic intensities, input.
736           DEPTH_INTENS_DATA = 2-dim complex array with optical depth and intensity
737                        or flag (=1/0) for opt. depth based models, output.
738            F_PROJ = row vector of projected function values at each projected frequency
739                       (or proj. wavelength if base=0), output.
740            PDER_PROJ = 2-dim array containing the projected partial derivatives, optional output.
741                        PDER_PROJ(I,J) = projected derivative at Ith projected frequency (or wavelength)
742                        w/respect to JTH parameter.
743 RESTRICTIONS:
744        NONE.
745
746 PROCEDURE:
747        Copied from "CURFIT", least squares fit to a non-linear
748        function, pages 237-239, Bevington, Data Reduction and Error
749        Analysis for the Physical Sciences.
750        Modified, to output covariance matrix and make final function
751        call, Amara Graps, August 1987
752
753        "This method is the Gradient-expansion algorithm which
754        combines the best features of the gradient search with
755        the method of linearizing the fitting function."
756
757        Iterations are performed until the chi square changes by
758        only TOL_CHI2 (in absolute or fractional) or until NITER iterations have been performed.
759
760        The initial guess of the parameter values should be
761        as close to the actual values as possible or the solution
762        may not converge.
763
764 LOCAL PROCEDURE CALLED:
765        MODEL_DATA_FUNCT_PROJ
766
767 LOCAL FUNCTION USED:
768        COMPLEX2REAL
769
770 LOCAL SYSTEM VARIABLE USED:
771        EPSILON
772        CHI2_LM_TOLE
773       DEL_FLAMBDA_LM
774        FLAMBDA_LM
775       MAX_REL_ERR
776        NB_LM_ITER
777
778 REVISION HISTORY:
779       Written by pcr 2006/10/24
780        last modification by pcr 2011/01/22
781
782----- Documentation for Fit\polybootw.pro -----
783 NAME:
784        POLYBOOTW
785
786 AUTHOR:
787       pierre.cruzalebes@oca.eu
788
789 PURPOSE:
790        Proceed nonparametric residual bootstrap iterations (ramdom shoot of
791       residuals with replacement) of polynomial weighted fits
792        giving estimates of upper and lower coefficient errors.
793
794 CATEGORY:
795        fitting.
796
797 CALLING SEQUENCE:
798        DCOEFF = POLYBOOTW(X,Y,WEIGHT,DEG,CLEVEL,COEFF)
799
800 INPUTS:
801        X = Row vector of independent coordinates.
802        Y = Row vector of data, same length as X.
803        WEIGHT = Row vector of experimental weights, same length as Y
804               (e.g. proportional to (meas errors)^-2).
805        DEG = Degree of polynomial to be fitted to data.
806        CLEVEL = Desired confidence level (between 0 and 1).
807        COEFF = Row vector of polynomial coefficients, length=DEG+1.
808
809 OUTPUTS:
810       None.
811
812 FUNCTION RESULT:
813        DCOEFF = Row array of parameter inferior/superior error estimate(s),
814                dim=(DEG+1,2).
815
816 COMMON BLOCKS:
817        NONE.
818
819 SIDE EFFECTS:
820        NONE.
821
822 RESTRICTIONS:
823        NONE.
824
825 PROCEDURE:
826        SEE CODE.
827
828 LOCAL PROCEDURE CALLED:
829        LOCA_SCALE_CHI2
830
831 LOCAL FUNCTION USED:
832        GET_OUTLIER_FENCES
833
834 LOCAL SYSTEM VARIABLE USED:
835        NB_BOOT_LOOPS
836       NB_DATA_BOOT
837        NB_MAX_BOOTS
838
839 REVISION HISTORY:
840       written by pcr 2008/06/05
841        last modification by pcr 2010/12/12
842
843----- Documentation for Fit\poly_boot.pro -----
844 NAME:
845        POLY_BOOT
846
847 AUTHOR:
848       pierre.cruzalebes@oca.eu
849
850 PURPOSE:
851        Proceed nonparametric residual bootstrap iterations (ramdom shoot of
852       residuals with replacement) of polynomial fits
853        giving estimates of upper and lower coefficient errors.
854
855 CATEGORY:
856        fitting.
857
858 CALLING SEQUENCE:
859        DCOEFF = POLY_BOOT(X,Y,DEG,CLEVEL,COEFF)
860
861 INPUTS:
862        X = Row vector of independent coordinates.
863        Y = Row vector of data, same length as X.
864        DEG = Degree of polynomial to be fitted to data.
865        CLEVEL = Desired confidence level (between 0 and 1).
866        COEFF = Row vector of polynomial coefficients, length=DEG+1.
867
868 OUTPUTS:
869       None.
870
871 FUNCTION RESULT:
872        DCOEFF = Row array of parameter inferior/superior error estimate(s),
873                dim=(DEG+1,2).
874
875 COMMON BLOCKS:
876        NONE.
877
878 SIDE EFFECTS:
879        NONE.
880
881 RESTRICTIONS:
882        NONE.
883
884 PROCEDURE:
885        SEE CODE.
886
887 LOCAL PROCEDURE CALLED:
888        LOCA_SCALE_CHI2
889
890 LOCAL FUNCTION USED:
891       GET_OUTLIER_FENCES
892
893 LOCAL SYSTEM VARIABLE USED:
894        NB_BOOT_LOOPS
895       NB_DATA_BOOT
896        NB_MAX_BOOTS
897
898 REVISION HISTORY:
899       Written by pcr 2008/06/04
900        last modification by pcr 2010/12/12
901
902----- Documentation for Fit\test_model.pro -----
903 NAME:
904      TEST_MODEL
905
906 AUTHOR:
907      pierre.cruzalebes@oca.eu
908
909 PURPOSE:
910      test model and partial derivatives vs parameters
911      and also test Levenberg-Marquardt (LM) algorithm
912
913 CATEGORY:
914      fitting
915
916 INPUTS:
917      need text input file (in OBS_PATH/INP/ directory) with:
918        - number of baselength file(s) (one file per P2VM setting,
919        null if not needed, e.g. for flux or sed fit)
920        - baselength file name(s) (if needed)
921        - nber of wavelength bands
922      for each baselength file:
923        - name(s) of wavelength list(s) (1 row per spectral band)
924     then:
925        - data format
926        - model number used for fitting
927        - number of values per parameter, band number, pair number
928        (used for derivative test)
929        - parameter value(s) (= starting parameters used for fit)
930        - parameter flags (0:frozen / 1:unfrozen) (used for fit)
931        - synthetic exitance and radiance file names ('none' if not needed,
932        in same row)
933        - parameter relative error used for fit (null if no fit)
934
935 REQUIREMENTS:
936      data read in input baseline file(s) (in subdirectory of OBS_PATH/)
937      must be in ASCII format and contain (2*NBASE=NTEL*(NTEL-1) columns, one
938      row per obs file) :
939        - (length[m] , angle[deg]) of each projected baseline at obs file start/end
940
941      data read in wavelength list(s) (in subdirectory of OBS_PATH/)
942      must be in ASCII format and contain (one row per spectral channel,
943      decreasing order of wavelength):
944        - wavelength and bandwith [m]
945
946      data format must be:
947        'vis' for visibility data
948        'spec' for spectrum data
949        'coh' for coherent spectrum data
950        'bisp' for bispectrum data
951        'sed' for sed data
952
953      model number is defined in model_spectrum.pro
954      as well as order of starting parameters
955
956      data read in input synthetic exitance file (.spec, 4 first
957      characters=temperature, in SYNTHE_PATH/ directory)
958      must be in ASCII format and contain 2 columns of data:
959        - wavelength (in AA = 10^-4 mu) and spectral exitance (in
960        erg.cm^-2.s^-1.AA^-1 = 10*W.m^-2.mu^-1)
961
962      if input synthetic radiance available (in SYNTHE_PATH/ directory)
963      use also radiance data composed of !NB_LUMIN+1 columns with:
964        - zero and relative impact parameters (!NB_LUMIN values between 0.
965        and 1., in first row)
966        - wavelength [mum] and !NB_LUMIN values of absolute radiance
967        [W/m^2/mum/sr] (one row per spectral channel)
968
969      also use relative impact parameter list of name RIP_LIST_NAME composed of:
970        - 1 column of NB_LUMIN values (between 0. and 1.)
971
972 OUTPUTS:
973      data written in test data file(s) (in the same subdirectory of OBS_PATH/,
974      one file per baseline/triplet) must be in ASCII format and contain
975      (in this order, one row per wavelength):
976      for visibility data (.vis):
977        - wavelength and bandwidth (in m), visibility and error
978      for flux data (.spec):
979        - wavelength and bandwidth (in m), flux and error (in W.m^-2.mu^-1)
980      for coherent flux data (.coh):
981        - wavelength and bandwidth (in m), coherent flux and error
982        (in W.m^-2.mu^-1),
983      for bispectral data (.bisp):
984        - wavelength and bandwidth (in m), bispectrum real part and error,
985        bispectrum imaginary part and error (all in W^3.m^6.mu^-3)
986      for sed data (.sed):
987        - wavelength and bandwidth (in m), flux and error (in W.m^-2.mu^-1)
988
989 LOCAL PROCEDURE CALLED:
990        ENGELKE
991        GET_SYN_REF
992        MODEL_DATA_FUNCT_PROJ
993        MODEL_SPECTRUM
994        PLANCK
995        RESET_PLOT
996
997 LOCAL FUNCTION USED:
998        COSD
999        EXTRACT_PROHEADER
1000        FUNCTPROJ
1001        LM_FIT
1002        MAKE_TAB3
1003        SIND
1004        TRAP
1005
1006 LOCAL SYSTEM VARIABLE USED:
1007        EPSILON
1008        MARCS_RES
1009        MAS2RADIAN
1010        NB_BASE_STEP
1011        NB_DATA_MAX
1012        NB_LAMBDA_MAX
1013        NB_MAX_PARAM
1014        NB_OB_MAX
1015        NB_PAIR_MAX
1016        NB_RES_STEP
1017        OBS_PATH
1018        PLOT_DEV
1019        SPIDAST_PATH
1020        SYNTHE_PATH
1021
1022 REVISION HISTORY:
1023       Written by pcr 2006/09/22
1024       last modification by pcr 2011/01/13
1025