.-
help for ^makfun^                                   (STB-45: gr30)
.-

Produce 3-D summary of data
---------------------------

 ^makfun^ x y [^,^ ^x(^# or matname^)^ ^y(^# or matname^)^ ^z(^zexpression^)^
        ^gr^ound^(^#^)^ ^sm^ooth ]

       x,y any two existing vars 



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

      ^makfun^ generates a function z=f(x,y) on an [x,y]-grid based on 
      specified cutpoints or on quantiles of existing data in memory. 
      The data are preserved but 3 matrices are created and left behind 
      on exit: 
            x-cutpoints are in mat hlXcut
            y-cutpoints are in mat hlYcut
            z-values    are in mat hlZfun

      The aim was to provide an interface to the 3D-programs @hidlin@ or 
      @altitude@ which can only plot functions, not data, but it turns out 
      that ^makfun^ has general utility because hlZfun stores a nice (smooth 
      if desired) 3D-summary of real data.

      The graphical representation of this summary is obtained either from 
      ^hidlin^ or ^altitude^ via the included ^hlmakfun^ function-declaration 
      program, which uses the saved matrices to reconstruct the surface.



Options
-------
      x(# or matname): indicates how the x-variable is to be cut?
            either:      number of quantiles (default=sqrt(N)/3, uses @xtile@)
            or:          a matrix which contains the desired x-cutpoints
            - intervals are half-open (low,high] like for xtile
            - with m intervals or quantiles there are m-1 cutpoints

      y(# or matname): similar, either nquant or matname 

      z(zexpression) : indicates which summary is to be produced?
            either ^freq^ or ^statistic varname^ (default freq)
            ( choices for  statistic  are the same as with @collapse@ )

      ground:  z-value to be used when an [x,y] cell is empty and the 
            zexpression cannot be evaluated (default 0)

      smooth:  requests that computed z-values be smoothed using surrounding 
            cells, each with a weight of 1, and the target cell with a 
            weight of 2 as shown below

                  1            1            1

                  1            2            1

                  1            1            1

            For cells located outside the grid or if their contents are 
            unknown (ground) a weight of 0 is used. Thus, for a corner 
            cell at most 3 neighbours are available and for a cell 
            elsewhere on an edge there are at most 5 neighbours. 

            The original hlZfun matrix is copied into matrix hlZfu1 and
            the smoothed summary is stored in hlZfun.


The bare call: ^makfun x y^  uses qx=qy= min(root(_N)/3,matsize) quantiles 
               and produces the counts on the grid



Example
-------

use auto and study average mpg in the quartiles of price by foreign

(output not shown, full detail shown in STB-45)

   . ^use auto^

   . ^mat A=(0)^
* (needed to cut the 2 levels of foreign: <=0 vs >0;  2 quantiles wouldn't do)
 
   . ^makfun foreign price, x(A) y(4) z(mean mpg)^
* (prepares for graphing, may want to inspect generated matrices)

   . ^hidlin makfun, x(-1 1  .2)  y(3200 16000 200) e(1 -1000 -3)^
* (graph appears, may need to modify this, as below for instance)

   . ^hidlin makfun, x(-1 1  .1)  y(3200  8000 200) e(1 -2000 -3) b c^


Author 
------

      Guy D. van Melle
      University of Lausanne, Switzerland
      guy.van-melle@@inst.hospvd.ch


Also see
--------
    STB:  gr30 (STB-45)
 manual:  [R] pctile, collapse
on-line:  ^help^ for @pctile@, @collapse@