pinktoe               package:pinktoe               R Documentation

_P_i_n_k_t_o_e: _c_o_n_v_e_r_t _S _t_r_e_e_s _t_o _w_e_b _f_i_l_e_s _f_o_r _i_n_t_e_r_a_c_t_i_v_e _t_r_a_v_e_r_s_a_l.

_D_e_s_c_r_i_p_t_i_o_n:

     Pinktoe converts a S tree object to a set of HTML and perl files
     that can be, once uploaded to a perl-aware web server,
     interactively traversed by a user with a web browser. This is
     useful for large trees or trees where the variables require
     description by verbose text.

_U_s_a_g_e:


     pinktoe(treeobj, textfn, tittext, treeid="",
      cgibindir = paste("/~magpn/cgi-bin/", treeid, "/", sep = ""),
      htmldir = paste("/home/magpn/public_html/Research/Politics/TREE/", treeid, "/", sep = ""),
      localdir = "Tree/",
      stateprintfn = partyprint, requirelib = "../party.lib", commonhtml)

_A_r_g_u_m_e_n_t_s:

 treeobj: A tree object (such as that produced by the  
 `tree'
          function).
 

  textfn: A user supplied function that prints out text to a file in
          response to
 a variable name.
 

 tittext: A user supplied function that prints out title text to a file
          in
 response to a variable name.
 

  treeid: This is a character string which is appended to both
          `cgibindir' and `htmldir'.
 This can be useful when you are
          building
 web pages for a collection of trees and store
          different trees in
 separate directories.

cgibindir: A character string containing the directory where the perl
          files
 generated by pinktoe (with the extension `.pl') will
          be stored.
 (This should be the directory part of the URL of
          the cgi-bin
 directory).
 

 htmldir: A character string containing the directory where the HTML
          files
 generated by pinktoe (with the extension `.htm') will
          be stored.
 (This should be a pathname understood and able to
          be found
 by perl).
 

localdir: A local location to store both the HTML and perl files
          immediately
 after they are generated.
 

stateprintfn: A user-supplied function that decides what to do when
          supplied with
 the `yval' reached at the leaf of a tree. Some
          
 text can be output, or maybe a perl function call.
 

requirelib: A library of perl functions that can be called by, e.g.
          `stateprintfn'. The library that this refers to
 should
          reside in the `cgibin' directory. If no function calls
 are
          planned then it doesn't matter what argument is supplied.
 

commonhtml: A user-supplied function that prints out some HTML code.
          This is
 appended to every HTML web page.
 

_D_e_t_a_i_l_s:

     See the example below for usage. See
 <URL:
     http://www.stats.bris.ac.uk/~magpn/Research/Pinktoe/Welcome.html>
     for a full description

_V_a_l_u_e:

     No value.

_n_o_t_e:

     Release 1.0
 Copyright Guy Nason 2001 under the GPL

_A_u_t_h_o_r(_s):

     Guy Nason, <URL: http://www.stats.bris.ac.uk/~magpn>

_R_e_f_e_r_e_n_c_e_s:

     Nason, G.P. (2001) Pinktoe: putting S trees on the web
 Technical
     Report 01:17, Department of Mathematics
 University of Bristol,
     Bristol UK.

_S_e_e _A_l_s_o:

     `tree'

_E_x_a_m_p_l_e_s:


     #
     # An example already exists above concerning early
     # day motions. The early day motions example concerns binary variables and
     # a categorical response variable.
     #
     #
     # The next example shows how to use pinktoe on a tree built from the
     # kyphosis dataset found in multiple chapters in Chambers, J.M.
     # and Hastie, T.J. (1993) Statistical models in S, Chapman and
     # Hall/CRC: London. I'm a bit confused because at the time of writing
     # (May 2001) Amazon says the book is out of print and the publisher says
     # "In stock".
     #
     #
     #
     # Generate a tree
     #

     z.kyphosis <- tree(kyphosis)


     data("zkyphosis")

     #
     # Now really should do usual tree modelling things like check the model,
     # test the assumptions, prune, cross-validation etc. However, for the
     # purposes of this example we just want to turn the S tree into a set of
     # web pages that we can traverse.
     #
     # So, we have to first write some user-supplied functions.
     # The first one is the textfn. Let's call this
     # kyphosis.text:
     #

     kyphosis.text <- function(n, file = "", append = F)
     {
             cat("<BR>\n", file = file, append = append)
             cat("Variable: ", n, ": ", file = file, append = append)
             if(n == "Start")
                     cat("The beginning of the range of vertabrae involved<BR>\n", 
                             file = file, append = append)
             else if(n == "Age")
                     cat("The age of the child in months<BR>\n", file = file, 
                             append = append)
             else if(n == "Number")
                     cat("The number of vertebrae involved in the operation<BR>\n", 
                             file = file, append = append)
             else cat("print \"Unknown variable<BR>\"\n", file = file, append = 
                             append)
     }

     #
     # So when any of the variables are input to kyphosis.text an
     # appropriate line of explanatory text is printed out.
     #
     #
     # Now let's write the function that returns <TITLE> text:
     # the tittextfn
     #

     kyphosistittext <- function(label)
     return(paste("Variable:", label))

     #
     # This was very simple. It just appends the word "Variable: " in front of the
     # variable name. Notice that this function does not print anything out, just
     # returns a character string.
     #
     #
     # Now the stateprintfn. When this function receives
     # a yval at a leaf it has to print out the final state. In
     # this case there are only two final states for kyphosis: present or absent.
     # Here is the code:
     #

     kyphosisprint <- function(yval, file = "", append = F)
     {
             if(yval == "present")
                     cat(" &present;\n", file = file, append = append)
             else if(yval == "absent")
                     cat(" &absent;\n", file = file, append = append)
             else cat("print \"Unknown kyphosis state<BR>\"\n", file = file, append
                              = append)
     }

     #
     # Note that the above code calls the perl functions present and absent
     # (the call is with & in front). So, we have to supply the definitions of
     # these separately. We do this in a perl library called kyphosis.lib. This
     # file contains the following text:
     # (n.b. don't copy the following into R it won't make sense. Copy it to
     # a file)
     #


     sub present {
             print "Kyphosis is <BLINK>Present</BLINK><BR>\n";
             &rethome;
             }

     sub absent {
             print "Kyphosis is <BLINK>Absent</BLINK><BR>\n";
             &rethome;
             }

     sub rethome {
             print "<P>\n";
             print "<a href=\"http://www.stats.bris.ac.uk/~magpn\">Return to <EM>Guy Nason's</EM> page</a>";
             }


     #
     # which as you can see merely prints out whether kyphosis is absent or
     # present. Actually, this text is very simple and could have placed in
     # the stateprintfn directly. However, more
     # complex functionality in the .lib file might make it
     # clearer to have this separation.
     #
     # For the commonhtml function I use my
     # genericcommonhtml function which provides a link back to
     # my home page. But you can modify this...
     #
     #

     genericcommonhtml <- function(file, append)
     {
             cat("<a href=\"http://www.stats.bris.ac.uk/~magpn\">Return to <EM>Guy Nason's</EM> home page</a>\n",
                     file = file, append = append)
     }
     #
     # For this example we need to create a local directory called Tree to store
     # the files in. You might have already done this so the following command
     # is not necessary if the directory exists.
     #
     system("mkdir Tree")

     #
     # Now let's issue the call to pinktoe to build the HTML and perl trees.
     #

     pinktoe(z.kyphosis, textfn=kyphosis.text, tittext=kyphosistittext, "",
       cgibindir="/~magpn/cgi-bin/TEST/",
       htmldir="/home/magpn/public_html/TEST/",
       localdir="Tree/",
       stateprintfn=kyphosisprint,
       requirelib="../kyphosis.lib",
       commonhtml=genericcommonhtml)

     #
     # Pinktoe should produce a collection of HTML and perl files in the Tree
     # subdirectory.
     #
     # Note that the end / of both the cgibindir and htmldir should be provided.
     #
     #
     # Then FTP the HTML files to the htmldir you specified.
     # Then FTP the perl files to the cgibindir you specified and change their
     # permissions to be executable by anybody (presuming this is what you want).
     #
     #
     # Then point your browser to the HTML file that has _1 at the end of its
     # filename. In this example it is Start_1.htm You should then be able to
     # traverse the tree.
     #
     # As an example. Here is the Start_1.htm
     # I prepared using the above example. Try it out and check it against the
     # tree.
     #
     # Of course, the kyphosis tree is pretty simple and with only 3 numeric
     # variables it is quite easy just to use the tree diagram. However, things
     # are more complicated with larger trees and where the variables have a lot
     # of associated information, such as with the early day motion data.
     #
     #

