*****************************************************
     MOdeling of DAta - MODA.LIB V1.0
               for the HP48
*****************************************************

     1. Overview
     2. Installation
     3. Description
     4. Examples
     5. Miscellaneous

*****************************************************
1. Overview
*****************************************************

  The library MODA.LIB provides routines for non-
  linear chi-square fitting,  which are based  on
  the Levenberg-Marquardt algorithm.

  The two basic ingredients of any fitting proce-
  dure are the data and a function. The data  are
  typically  the  result of some measurements  in
  which pairs of values (x_i, y_i)  (independent,
  dependent)  i=1,...,N are recorded. The results
  of the measurements,  i.e. the dependent  vari-
  ables y_i will have a certain measurement error.
  The function f is supposed to encode the mecha-
  nism that produced the data. f depends on x and
  on parameters a_i, i=1,...,M.

  The aim  of  the  fitting procedure  is to find
  those  values  of  the parameters  a_i which do
  best describe the experimental values.

                     * * *

  Comments & suggestions,
  as well as bug reports are welcome!
  Steven Ahlig

  ahlig@pion06.tphys.physik.uni-tuebingen.de

*****************************************************
2. Installation
*****************************************************

  MODA.LIB is an auto-attaching library with
  library number 1055. To install it on your
  HP48G(X,+) download the file  MODA.LIB  in
  binary mode to your calculator.    Put now
  the  content  of  the  created variable on
  the  stack  and  store  it  in the port of
  your choice. Switch the calculator off and
  on.
  MODA.LIB should now be installed.

*****************************************************
3. Description
*****************************************************

  The menu of MODA.LIB looks as follows:

  [NEW] [LEMA] [SPAR] [INFO] [X->F] [PLOT]



  [NEW]

     is the basic input command.   [NEW] opens
     an  INFORM screen  and  you  are asked to
     enter the data and the function f.
     The field  DATA  takes  a  matrix with at
     least 3 columns and any number of rows.

       1.column:  x-values  (indep.)
       2.column:  y-values  (depen.)
       3.column:  errors of y-values

     Enter the function  f  in the field named
     MODEL.  f  should depend on  x  and on at
     least one  parameter  which may have  any
     name.

     [OK] will open a 2nd  INFORM screen where
     you are asked  to enter the  start values
     of the parameters a_i, i=1,...,M.

     * See the examples and section 5 for more
       details and  for an  explanation of the
       error "invalid input".

  [LEMA]    (LEvenberg-MArquardt)

     performs a specified number of Levenberg-
     Marquardt iterations.  LEMA takes one po-
     sitive  integer  from  the  stack   which
     counts the number of iterations.
     The result of these iterations is  a  new
     set of parameters  a_i, i=1,...,M.   LEMA
     puts the value of chi^2  that corresponds
     to these new parameters on the stack.

     * See section  5  for  the  definition of
       chi^2.

     * See the examples to get an  idea of the
       number of iterations that are necessary
       to obtain a good fit.

  [SPAR]     ( Show PARameters )

     lists the current values  of  the parame-
     ters a_i, i=1,...,M.

  [INFO]

     gives the current value of chi^2 together
     with a probability.  Both quantities mea-
     sure the 'goodness of the fit'.
     chi^2 is a number between 0 and infinity.
     It measures  the difference  between  the
     data and the model function f(x,a_i) in a
     specific way.    The smaller the value of
     chi^2 the better is the fit.
     It takes some more lines   to explain the
     meaning of the probability:  SUPPOSE your
     model function f   IS   the correct model
     function in the sense that the deviations
     of the data from the values of f are ONLY
     due to random measurement-errors.
     One could ask:    What is the probability
     that random measurement-errors do produce
     a value of chi^2 as poor (i.e. as large )
     as the current value of chi^2?
     The answer is given  by  [INFO]  together
     with the corresponding value of chi^2.
     The closer the value  of this probability
     is to 1 the better is the fit.

     * The definitions of chi^2 and the proba-
       bility are given in section 5.

  [X->F]

     takes one real number  from the stack and
     calculates the  value  of the model func-
     tion f for this argument and for the cur-
     rent values of the parameters a_i,
     i=1,...,M.

  [PLOT]

     plots the data-points  together  with the
     model function  f  for the current values
     of the parameters a_i, i=1,...,M.

*****************************************************
4. Examples
*****************************************************


DATA:
[[1.05   0.11    0.02]
 [2.03   0.233   0.03]
 [3.02   0.694   0.02]
 [4.0    2.130   0.02]
 [5.05   0.638   0.02]
 [6.03   0.219   0.02]
 [7.02   0.105   0.03]
 [8.0    0.061   0.02]]

 the data show a peak,
 therefore it seems reasonable to try

MODEL:
 '1/(A+(X-B)^2)'

 [OK]

 the peak seems to be located  between
 x=3 and x=5 ...    this motivates the
 following choice for the start values:

 A   1.0
 B   3.5

 [OK]

 1 [LEMA]                     ( 1 iteration )
             CHI2: 4783.0197  ( quite large ...)
 1 [LEMA]
             CHI2: 193.7065   ( it's getting better )
 1 [LEMA]
             CHI2: .1167      ( ok, that's good )
 [INFO]
             CHI2: .1167
             PROB: .9999      ( probability of nearly 1 )
 [SPAR]
             A: .46915        ( estimates for the parameters A and B )
             B: 3.9997

 Here are some suggestions for further 'explorations':

   * Try [PLOT] and see how the fitted curve matches
     the data.
   * Try  2.3  [X->F]  to find out the value of f at
     x=2.3 .
   * Use [NEW] to reset the values of A and B to 1.0
     and 3.5 respectively.   Now try 3 [LEMA] to see
     that you can obtain the result in 'one step'.
   * Try it again  with longer names for the parame-
     ters, e.g.  '1/(WIDTH+(X-CENTER)^2)' and notice
     that the 2nd INFORM screen of  [NEW] labels the
     fields with the 1st 3 characters and that the
     names of the parameters are printed in full
     length in the 'help area'.

 In this example  it took only  three iterations  to
 obtain a very good fit.  This was due to the choice
 of reasonable start values and an appropriate model
 function.  The influence of the start values is de-
 monstrated by the following example:
 (Same data and model function f as above.)

 [NEW] [OK]

 A 5.0       ( or WIDTH and )
 B 0.1       ( CENTER if you changed ... )

 [OK]

 1 [LEMA]
             CHI2: 12827.1304    ( oups, we have taken bad start values ... )
 1 [LEMA]
             CHI2: 12453.5042
 4 [LEMA]                        ( lets take 4 iterations at once! )
             CHI2: 10653.5412
 3 [LEMA]                        ( 3 iterations at once )
             CHI2: 5968.9701     ( algorithm begins to find its way )
 2 [LEMA]
             CHI2: 4777.3626
 2 [LEMA]
             CHI2: 3851.0126
 2 [LEMA]
             CHI2: 9.1893        ( already quite good )
 1 [LEMA]
             CHI2: 0.04534       ( ok )

 [INFO]
             CHI2: .04534
             PROB: .99999
 [SPAR]
             A: .46906           ( or WIDTH and )
             B: 4.0039           ( CENTER if you changed ... )

 Of course, the algorithm yields the same values for
 the parameters A and B. But it  took  16 iterations
 to obtain a set of values a_i satisfying chi^2 < 1.

 The algorithm adjusts an internal parameter  to the
 start values of the a_i.  This will take one or two
 iterations  if  you have  chosen  good start values
 and it will  take more  iterations  if  you started
 with bad values.   This explains  the slow progress
 during the first 6 iterations.

 How does one find good start values? -- There is no
 general prescripton or method that allows  to  find
 good start values.    One has to rely on intuition,
 but it helps if  you  have  an  idea  about how the
 graph of  f  changes  when you change the values of
 the parameters.


*****************************************************
4. Miscellaneous
*****************************************************

  [NEW]

      The first INFORM (asking for DATA, MODEL)
      will give the error "invalid input" if at
      least one of the following items is true;

      * the field DATA is empty
      * the field MODEL is empty
      * the matrix in DATA has less than 3 columns
      * the function in MODEL does not contain
        a parameter, i.e. a variable different from
        x
      * the function in the field  MODEL does contain
        more than 8 parameters
        ( This is actually not a 'hard' constraint
          since the routine [LEMA] can handle  any
          number of parameters.   However, I never
          found it necessary to use  more than six
          parameters and therefore I feel  comfor-
          table with an input-routine that is
          limited to 8 parameters. )
        ( Anyway, if you find it necessary to use
          more than 5 parameters  than you should
          quite probably rethink the x-dependence
          of your model function f,  but I do not
          insist on this point. :)  )

      The names of the parameters should follow the
      usual rules for names of variables.  MODA.LIB
      adds  'MDPRO' and  'MDD' to the list of 'for-
      bidden names'  which  contains  PICT, PPAR,
      etc.

      Having completed the 2nd INFORM of [NEW] with
      [OK] you will notice that  your calculator is
      busy for a few moments.   MODA.LIB takes this
      time to calculate some auxiliary functions.

  MEMORY ...

      The data and the model function f as well as the
      results for the  parameters  are stored together
      in the current directory  under the name  MDPRO.
      MDPRO is a list and it is structured as follows:

        { [[][][]]  'A*X+B' { A B } { 2.3 4.5 } #1 #2 #3 %4 }

          \______/  \_____/ \_____/ \_________/ \__________/
         matrix      model    list     list of   three binary
     containing    function    of      param.-   integers and
     the data          f     param.-   values    one real number
     as entered in           names               that are used
     the field                                   by MODA.LIB
     DATA

     The data, the function  f and the  results are stored
     in ONE object and sometimes I will refer to this list
     as 'MODA-project'.
     It is easy to archive MODA-projects:
     copy an old MODA-project to the current directory and
     rename it to 'MDPRO'. MODA.LIB will now work with the
     new MODA-project.
     Use [NEW] to edit the contents of MDPRO.

  DEFINITIONS    ( in LaTeX-syntax )

     Definition of chi^2: (tagged as CHI2)

           chi^2 = \sum_1^N
                   ( \frac{y_i-f(x_i)}{\sigma_i} )^2

        x_i      = i. element of 1. column of DATA-matrix
        y_i      = i. element of 2. column of DATA-matrix
        \sigma_i = i. element of 3. column of DATA-matrix

     Definition of the probability: (tagged as PROB)

            prob = \frac{1}{ 2^{\frac{\nu}{2}}
                             \Gamma( \frac{\nu}{2} )
                           }
                   \int_{\chi^2}^{\infty} dt
                   \exp(-t/2) t^{\frac{\nu}{2}-1}

                   where \nu = N-M


  ERROR: 'no current MODA-project -> NEW'

     MODA.LIB couldn't find MDPRO in the current direc-
     tory, i.e. either you have just installed MODA.LIB
     or you deleted/moved MDPRO. Use [NEW] to enter new
     data.

  PROBABILITY

     The probability is not defined if the number of
     parameters is greater than the number of data-points
     points. In this case [INFO] will give only the value
     of chi^2.

     A probability that is smaller than 0.001 indicates a
     significant difference between the data and the  mo-
     del f. The model f should be rejected.

     A probability that is greater than 0.05 is usualy re-
     garded sufficient to accept the model f.
