.-
help for ^ipf^                                                    (STB-55: sbe34)
.-

Log-linear modelling using Iterative Proportional Fitting
---------------------------------------------------------

        ^ipf^ ^varlist^ ^[^weight^]^, ^fit(^string^)^
              [ ^constr(^string^)^ ^confile(^filename^)^
              ^convars(^varlist^)^ ^save(^filename^)^ ^expect^ ^nolog^ ]

^fweight^s are  allowed; see help weights.


Description 
----------- 

The iterative proportional fitting (IPF) algorithm is a simple method
to calculate the expected counts of a hierarchical loglinear
model. The algorithm's rate of convergence is first order. The more
commonly used Newton-Rhapson algorithm is second order, however, each
iteration of the IPF algorithm is quicker because Newton-Rhapson
inverts matrices. This makes the IPF algorithm much quicker for
contingency tables with numerous cells.

The IPF algorithm has the following steps:

  1) Initial estimates of the expected frequencies are given. The
     initial estimates should have associations and interactions that are
     less complex than the model being fitted. By default the initial
     frequencies are 1.

  2) Successively adjust the estimates of the expected frequencies by
     scaling factors so they match each marginal table.

  3) The scaling continues until the loglikelihood converges.

The algorithm always converges to the correct expected frequencies
even when the likelihood is poorly behaved, for example, when there
are zero fitted counts.

The varlist defines the dimension of the continguency table that the
poisson likelihood is calculated over. If the varlist is not specified
the variables in the fit() option define the dimensions of the
continguency table.


Options
-------

^nolog^ specifies whether the loglikelihood is displayed at each iteration.

^fit(^string^)^ specifies the loglinear model. It requires special syntax of
   the form ^var1*var2+var3+var4^. ^var1*var2^ allows all the interactions
   between the two variables and also the main effects of ^var1^ and ^var2^.
   The main effects for ^var3^ and ^var4^ are also contained in the model but
   no interactions. This syntax is used in most books on Loglinear modelling.

^confile(^filename^)^ specifies a *.dta file that contains initial values
   for the expected counts, the variable containing the frequencies must
   be called Efreqold.
   This option requires ^convars^ also to specified.

^convars(^varlist^)^ specifies the variables in the file ^confile(^filename^)^
   excluding Efreqold.

^save(^filename^)^ specifies the expected frequencies and probabilities for
   every cell to be saved in a *.dta file.

^expect^ specifies that the expected frequencies are displayed.

^constr(^string^)^ specifies initial values for the expected frequencies. The
   syntax requires a condition in square brackets followed by a value for the
   expected frequency. Hence [sex=="male"]2 replaces all initial values for
   males to be 2.


Examples
--------

For a 3-way continguency table containing the factors sex, age and treatment
the saturated model is given by

   ^. ipf, fit(sex*age*treatment)^

If the data was not individual records the command would require a variable
containing the frequency counts, ^freq^ say.

   ^. ipf [fw=freq], fit(sex*age*treatment)^

Using a file for initial frequencies.

   ^. ipf [fw=freq], fit( sex+age) convars(sex age) confile(constrain) exp^


Authors
-------

    Dr. Adrian Mander
    MRC-Biostatistics Unit,
    Institute of Public Health,
    Forvie Site,
    Cambridge, UK
    Phone: (0)1223 330393
    Fax:   (0)1223 330388
    Email: adrian.mander@@mrc-bsu.cam.ac.uk


Also see
--------

   STB: STB-55 sbe34