ProfitPress Mega CDROM2 Shareware Freeware (MSDOS)(1992)(Eng)

home *** CD-ROM | disk | FTP | other *** search

/ ProfitPress Mega CDROM2 …eeware (MSDOS)(1992)(Eng) / ProfitPress-MegaCDROM2.B6I / APPS / STATISTI / MVSP2.ZIP / PLOT14.DOC < prev next >

Wrap

Text File | 1990-07-15 | 56.0 KB | 1,146 lines

=============================================================== Note to MVSP users: This document describes the general use of PLOTGRAM and PLOTREE (the latter is not included with MVSP), as written by Chris Meachem. There are some added comments by Joe Felsenstein that deal with his versions of the programs (DOTGRAM) for dot matrix printers. At the end is the specific information about using PLOTGRAM itself. I have modifed the documentation slightly to reflect the changes I have made to PLOTGRAM, mainly by merging DOTGRAM and PLOTGRAM and adding a few more options. For specific details about how to use PLOTGRAM with the treefiles produced by MVSP see the MVSP documentation. - WLK =============================================================== Copyright 1986 by Christopher A. Meacham. Permission is granted to copy, distribute, and modify this document provided that (1) this copyright message is not removed and (2) no fee is charged for this document. (for versions 1.4 of PLOTGRAM, distributed with MVSP 2.0) GENERAL DOCUMENTATION FOR THE GRAPHICS PROGRAMS PLOTREE AND PLOTGRAM Christopher A. Meacham Botany Department, University of Georgia, Athens, GA 30602, U.S.A. Present address: University Herbarium, University of California, Berkeley, CA 94720, U.S.A. Plotree and Plotgram are flexible graphics programs that are designed to draw tree diagrams of widely different formats on a variety of graphics devices and that are capable of being run on computers of nearly all sizes from microcomputers to large mainframes. They are written in a very standard subset of the Pascal programming language. The two programs accept as input a description of a tree diagram and produce as output the device-dependent graphics instuctions that cause the diagram to be drawn. The user can control the action of Plotree and Plotgram by setting various parameters. Plotree draws "ball and stick" trees and Plotgram draws phenograms and cladograms. The two programs are very similar in their operation. This document covers those aspects that are common to the two programs. The specific documentation for each program describes in more detail the style of tree drawn by the program and how the user controls the form of the tree. NOTE TO USERS OF PREVIOUS VERSIONS At the conference among producers of phylogenetic software that was held last week (24 June 1986) at the meetings of the Society for the Study of Evolution at Durham, NH, a standard format for machine- readable trees was accepted. This format will be described in detail in a forthcoming issue of the Journal of Classification. Versions 1.3 of Plotree and Plotgram incorporate some changes toward this standard. Basically, the trees required by versions 1.3 adhere to a subset of the full standard and will thus be readable to programs that implement the full standard. The next release of Plotree and Plotgram will implement the full standard. The side-effect of this change is that trees read by versions 1.0 through 1.2 of the two programs are not readable by versions 1.3. Trees under the new standard are terminated by a ';', not a '*'. The symbol that is replaced by a blank in tree labels is a '_', not a '#'. If you have trees to plot that you produced for older versions of the programs, these two changes can be made by relatively painless editing. The other major change to the format is that the subtree description associated with a node comes before, rather than after, the labels and length associated with the node. This standardization really doesn't matter to any version of the two programs; all versions read both formats. Following a suggestion by David L. Swofford, a '*' as the first non-blank character of a line in the parameter file indicates a comment. OVERVIEW OF PLOTREE AND PLOTGRAM EXECUTION The user supplies input to Plotree or Plotgram in two files that are designated "parmfile" and "treefile" in the source code. Parmfile is read first and contains instructions that cause the program to change various parameter settings. These parameters indicate to the program the plotter being used, the size and position on the plotting surface of the tree to be drawn, how the tree is to be labeled, etc. Treefile is read second and contains a description of the tree the user wishes drawn. After treefile is read, the program calculates the layout of the tree and finally writes the plotter commands to the output file, "plotfile." Plotfile may either be attached directly to the plotting device or may be a disk file that is later copied to the plotter. A second output file, the Pascal standard file "OUTPUT," is used to display messages about the current status of the program and for error messages. OUTPUT should normally be attached to the console. Another input file, "fontfile," is used to read the font descriptions used to generate the text plotted by Plotree or Plotgram. This file is attached to one of the five disk files supplied with Plotree and Plotgram, "FONT1" through "FONT5," depending on which font is to be used to label the tree. GETTING PLOTREE AND PLOTGRAM TO RUN ON YOUR COMPUTER (Users of MVSP note: PLOTGRAM has already been compiled for you so there is no need to modify the program as outlined below unless you wish to make changes. - WLK) Several steps need to be taken to get these programs to run on your computer. These steps are outlined below; many are discussed in more detail further on. If you plan on using both programs, it is a good idea to keep careful notes on the changes made to the first one so that the same changes can easily be made to the other program. These notes will also be of use in adapting future versions of the two programs. 1. Make changes, if necessary, to adapt the program to the compiler you are using. See instructions below. 2. Add code, if necessary, to drive the plotter or other graphics device you intend to use. See instructions below. 3. If your compiler cannot handle a single file of source code as long as these programs (e.g. Turbo Pascal), you will need to divide the original source file into two or three files. Consult your compiler manual. 4. Some compilers may not be able to handle procedures that are as long as some in these programs. If this happens at all, it will most likely happen in the procedure "plot." Because it is not likely that you will need (or want) to drive all the devices supported, you may delete the code pertaining to plotters you don't intend to use, or you may simply put comment delimiters ('(*' and '*)') around that code you wish ignored. The procedure "plot" can be drastically reduced in size this way. 5. After the program compiles successfully, you will need to set up the two input files, parmfile and treefile, to test your installation of the program. The parameters, which are put in parmfile, and their format are described in detail below. It is a good idea to use mostly default values of parameters at this stage. The only parameters that you may really need to set are PLOTTER, XUNITS, YUNITS, XSIZE, YSIZE, XPOSITION, YPOSITION, XOPTION, and YOPTION. For this test, use only a very simple tree description in treefile, for example 'A(B);' (the apostrophes are NOT part of the tree description). For fuller discussion of the tree description format, see below. 6. If it compiles successfully, you may still have problems running these programs because a fairly large amount of memory is required to store the fonts. You will definitely have problems if you compile with CP/M Turbo Pascal on a 64k system (e.g. an Osborne 1). This problem will probably show up as a "heap/stack collision" error during execution. In this case, you must reduce the size of the array "font" by changing the constant "fontsize" at the beginning of the program. If you reduce the size of the array "font," you must, of course, only use those fonts that will fit into the smaller array. See discussion of the FONT parameter below. You will probably not encounter problems if you have 128k or more of memory available. 7. Once the program is successfully running, you can begin drawing your own trees. Follow the specific instructions for Plotree or Plotgram as described in the documentation for that program. ADAPTING PLOTREE AND PLOTGRAM TO YOUR PASCAL COMPILER The first task is to determine what changes need to be made to the program source code. Usually these will be restricted to input- output statements in the main program, which is found at the end of the source listing. If your Pascal compiler needs "ASSIGN" statements, you will need to add them. Turbo Pascal, which is a commonly used Pascal compiler for microcomputers, needs these ASSIGN statements. Some compilers need to be told that these programs use recursive procedures, that is, procedures that call themselves. In the CP/M version of Turbo Pascal, this is done by inserting the compiler directive '(*$A-*)' as the first line of the program. (Note that the apostrophes are NOT part of the compiler directive.). This is not necessary for IBM versions of Turbo Pascal. MODIFYING PLOTREE AND PLOTGRAM TO DRIVE A NEW PLOTTER You will need to determine what plotter or plotters you will use. Versions 1.4 of Plotree and Plotgram drive Hewlett Packard, Calcomp, Tektronix, and Bausch and Lomb (Houston Instruments) plotters, as well as a variety of IBM-PC graphics adaptors, but in general, very little code needs to be added to drive other plotters. Anyone who is familiar with the requirements of the plotter and who knows a little Pascal should have no difficulty in making the necessary modifications to these programs. Many computing centers have utility programs that will accept Calcomp or Tektronix instructions as input and will drive the plotting devices available at that center. If you are planning to run these programs in a mainframe environment like this, you may not need to modify them to drive the plotter directly. Check with your computing center staff to see what options you have. If you find that you do need to modify the programs to drive your plotter, relatively few changes are necessary. Plotree and Plotgram already recognize a plotter parameter of 'O' (which stands for "other"). So, if you add your code at the appropriate places, you can specify a plotter type of 'O' and these programs will generate the plotter commands you need. The crucial change and the only change that MUST be made is the modification to the procedure "plot" that generates the device-dependent plotter commands. (The structure of each program is described in Appendix 1 in the documentation for the respective program. These appendices can be used to locate the procedures that need to be modified.) The code for your plotter should go at the place indicated near the end of procedure "plot." If your plotter needs to be placed in a standard configuration before the tree is drawn, or if a particular pen needs to be selected before any other commands are sent to the plotter, these commands can be put in procedure "initplotter." Procedure "initplotter" is called before any commands to draw are issued. In a similar way, "finishplotter" can be used to issue any commands after the tree is drawn. Procedure "changepen" can be used to change to a different pen when labeling the nodes. Fonts 2 through 5 will look better if a thinner pen is used for labeling than the pen used to draw the tree diagram itself. The standard parameters that are constant for a particular plotter can be made the default values for that plotter by inserting code in the procedure "plotrparms." The parameters XUNITS and YUNITS should be set in this way. INPUT FORMAT OF TREE DESCRIPTIONS Both programs accept tree descriptions as input from the file "treefile." The programs require a nested parentheses notation to describe the tree to be drawn. The unit in this notation might be termed a "node description" because it describes the tree at a single node. A node description consists of (1) the label of the node and (2) if there exists any immediately descendant node or nodes, a list of the node descriptions for the immediately descendant nodes. This list of node descriptions is enclosed by parentheses and the descendant node descriptions are separated by commas. It is easy to see that this notation results in a nested series of parentheses. The tree description is terminated by a ';'. Here are some trees and their notation: C D F G \ / \ / C B E B B C B C D ! \ / ! \ / \ ! / B \ / ! \ / \!/ ! \ / A A A A A Tree 1 2 3 4 5 Notation for the above trees: 1. (B)A; 2. (B,C)A; 3. (B,C,D)A; 4. (B(C)B)A; 5. ((C,D)B,(F,G)E)A; None of the nodes are required to be labeled. For example, if all of the internal nodes (that is, nodes A, B, and E) on tree 5 above were unlabeled, then the notation would be ((C,D),(F,G)); If all labels were removed from tree 5, the notation would be ((,),(,)); Labels may consist of any sequence of upper- or lower-case alphabetic characters, numeric characters, or any of these characters: .!?-*. If a blank (space) is desired within a label, an underline ('_') should be used. The programs will replace the underline with a blank (' ') when plotting the label. Other special characters will not be plotted. The present version of Plotree will truncate labels that are longer that three characters. Plotgram truncates labels that are longer than 25 characters. (This maximum length of labels is controlled by a constant "maxnch" at the beginning of each program.) More than one label may be associated with a single node, however the current version of Plotree will only plot the first label. Plotgram will transform the tree so that all labels are plotted (see Plotgram documentation). Multiple labels are separated by blanks. Lengths of internodes may also be specified. The length of an internode is associated with the node above that internode. The length follows the node label and is separated from the node label by a colon (":"). For example, the tree C B / \ / 1.5 \ / 2.0 \ / A would have the notation (B:1.5,C:2.0)A; If the tree were unlabeled it would have the notation (:1.5,:2.0); Lengths may have decimal points or not. The length may begin with a minus sign ('-') or plus sign ('+'). Blanks may appear anywhere within the tree notation except within labels or within lengths (e.g. '1. 52' is not a valid length). Any number of tree descriptions may be placed in treefile and a tree description may continue to as many lines as necessary, but each tree description must begin on a new line. HOW TO WRITE TREE DESCRIPTIONS A simple mechanical procedure can be used to generate by hand the description of a tree. The terms "ancestor," "descendant," and "sibling" must be defined for nodes on a tree. The ancestor of a node is the node immediately below it on the tree. In tree 5 above, node A is the ancestor of node B. The root of the tree is the single node that has no ancestor. A descendant of a node is a node that is immediately above it on the tree. In tree 5, node B is a descendant of node A. A node is a sibling of another node if they have the same ancestor node. In tree 5, node B and node E are siblings. In a procedure called a tree traversal, the all nodes of a tree are visited in a well-defined sequence and as we move about the tree we can generate the tree description. If we are at a particular node, we first vist any descendant node that has not yet been visited. If all descendant nodes have been visited, then we visit any sibling nodes that have not yet been visited. Only if all descendants and all siblings of the particular node have been visited, do we return to the ancestor of the particular node. Thus in this process, we visit each node only twice: once on the way up the tree to its descendants and once on the way back down the tree after all its descendants have been visited. When we move up to a descendant, we write a left parenthesis ('('). When we move over to a sibling, we write a comma (','). When we move down to an ancestor, we write a right parenthesis (')'). The last time we visit a node we write the label of the node (and the associated length or level, if appropriate). We begin the process by visiting the root of the tree, and we terminate when the root is visited the second time. The description is terminated by a semicolon (';'). The reader may wish to practice on the five trees above. USING THE PARAMETERS The action of Plotree and Plotgram is controlled by parameters that are read by the programs from a file that is separate from the tree descriptions. The user has a great deal of control over the programs by means of these parameters, but it is important to realize that most of these parameters simply alter default values that will result in generally acceptable diagrams. When first using the programs, it is advisable to set only as few parameters as necessary and to ignore the rest. The most critical parameters are those that control the plotter and determine the size and position of the diagram on the plotting surface. These are the same for both programs and are described below. The other parameters allow the user to modify details of the diagrams drawn. These parameters are described in the documentation for each program. Do not set these parameters until you are successful in getting at least one simple tree drawn without them. The parameters that need careful attention in the beginning are XUNITS YUNITS XSIZE YSIZE XPOSITION YPOSITION XOPTION YOPTION ROTATION The action of these parameters is described below. GENERAL FORMAT OF PARAMETER FILE The parameters that control Plotree and Plotgram are placed in "parmfile," a separate input file from the file that contains the tree descriptions. Each line in parmfile sets a single parameter. The name of the parameter is given first followed by the value to be given that parameter. Any number of blanks may preceed the parameter name. No blanks may occur within the parameter name. The parameter name may be in upper- or lower-case letters. At least one blank must separate the parameter name from the parameter value. The kind of values that parameters may have depends on the parameter. The legitimate parameter values are described below. If the first non-blank character is a '*', then the entire line is treated as a comment and ignored. The programs only use the first two letters of the parameter name to determine which parameter to set. However, it is recommended that the full parameter name be used for better mnemonic value. The parameters can be grouped into five major classes according to the aspect of the programs that they control: 1. Plotter parameters PLOTTER XUNITS YUNITS 2. Size parameters SIZEMODE XSIZE YSIZE MAXNODE 3. Position and rotation parameters XPOSITION YPOSITION XOPTION YOPTION ROTATION 4. Label parameters FONT PENCHANGE 5. Program control STARTMODE 1. PLOTTER PARAMETERS PLOTTER - This parameter identifies the plotter that will plot the tree and thus controls the kind of plotter commands that are produced by Plotree or Plotgram. The values PLOTTER may have are single letters. The legitimate values and the plotters they identify are 'H' - Hewlett Packard 7470 or 7475 'C' - Calcomp 'T' - Tektronix 4010 'B' - Bausch and Lomb (formerly Houston Instruments) 'S' - IBM-PC video output, CGA, EGA, VGA, or Hercules 'A' - Video Output to ATT-6300 or Compaq Portable III (640x400) 'P' - IBM-PC video output, Professional Graphics (640x480) 'R' - DEC ReGIS protocol 'L' - Postscript laser printer The PLOTTER parameter should always be the first parameter in parmfile because it changes the values for other parameters. The default plotter is Hewlett Packard. These are the default values that are set for the various plotters. Hewlett Packard: Default value XUNITS 400.0 YUNITS 400.0 XSIZE 24.0 YSIZE 18.0 XPOSITION 12.85 YPOSITION 9.55 XOPTION C YOPTION C ROTATION 0.0 Calcomp: XUNITS 39.37 YUNITS 39.37 XSIZE 25.0 YSIZE 25.0 XPOSITION 12.5 YPOSITION 0.0 XOPTION C YOPTION A ROTATION 0.0 Tektronix: XUNITS 50.0 YUNITS 50.0 XSIZE 20.46 YSIZE 15.6 XPOSITION 10.23 YPOSITION 7.8 XOPTION C YOPTION C ROTATION 0.0 Bausch and Lomb (Houston Instruments): XUNITS 100.0 YUNITS 100.0 XSIZE 24.5 YSIZE 17.5 XPOSITION 12.5 YPOSITION 9.0 XOPTION C YOPTION C ROTATION 0.0 IBM-PC video output & ATT-6300/Compaq Portable III With these options, the program detects which video adaptor is present, then chooses the highest possible resolution. The values for xunits and yunits will vary depending on the resolution. XUNITS varies YUNITS varies XSIZE 24.0 YSIZE 16.0 XPOSITION 12.5 YPOSITION 8.75 XOPTION C YOPTION C ROTATION 0.0 IBM-PC Professional Graphics video output (640x480): XUNITSPERCM 26.6 YUNITSPERCM 26.6 XSIZE 23.5 YSIZE 17.5 XPOSITION 0.0 YPOSITION 0.0 XOPTION C YOPTION C ROTATION 0.0 DEC'S ReGIS protocol: XUNITSPERCM 1.0 YUNITSPERCM 1.0 XSIZE 750.0 YSIZE 450.0 XPOSITION 399.0 YPOSITION 239.0 XOPTION C YOPTION C ROTATION 0.0 Postscript laser printer: XUNITSPERCM 28.346456693 YUNITSPERCM 28.346456693 XSIZE 15.24 YSIZE 22.86 XPOSITION 11.43 YPOSITION 13.97 XOPTION C YOPTION C ROTATION 0.0 PRINTER - The versions of PLOTGRAM and PLOTREE modifed for dot matrix printers by Joe Felsenstein use the keyword PRINTER to specify the type of printer used. The default values for the parameters are as follows: Citoh: XUNITSPERCM 28.346 YUNITSPERCM 28.346 XSIZE 19.0 YSIZE 22.0 XPOSITION 11.0 YPOSITION 0.0 XOPTION C YOPTION A ROTATION 0.0 Epson 9-pin: XUNITSPERCM 47.245 YUNITSPERCM 28.346 XSIZE 19.0 YSIZE 22.0 XPOSITION 9.5 YPOSITION 0.0 XOPTION C YOPTION A ROTATION 0.0 Okidata: XUNITSPERCM 56.692 YUNITSPERCM 28.346 XSIZE 19.0 YSIZE 22.0 XPOSITION 9.5 YPOSITION 0.0 XOPTION C YOPTION A ROTATION 0.0 Toshiba 24-pin: XUNITSPERCM 70.866 YUNITSPERCM 70.866 XSIZE 19.0 YSIZE 25.0 XPOSITION 10.5 YPOSITION 0.0 XOPTION C YOPTION A ROTATION 0.0 XUNITS, YUNITS - These two parameters describe the resolution of the plotter to be used in terms of number of plotter units (steps) per centimeter in the x-direction and y-direction respectively. Legitimate values are positive real numbers. For most plotters, those that have a one-to-one aspect ratio, these parameters will be set to the same value. Many video graphics display devices have aspect ratios that are not one-to-one, in which case the number of plotter steps required to move one centimeter in the x-direction will be different from the number of plotter steps required to move the same distance in the y-direction. If the trees you plot appear distorted and you have set XUNITS and YUNITS to the same value, then your plotting device does not have a one-to-one aspect ratio and these parameters should be set to different values. Once you have determined the correct values for your plotting device, these parameters need never be changed and you may consider modifying your version of Plotree to make them the default values for your plotter. Values need not be integers; for example, a Calcomp plotter that has 100 plotter units (steps) per inch has 39.37 units per centimeter. 2. SIZE PARAMETERS SIZEMODE - (This applies to Plotree only. SIZEMODE cannot be switched off for Plotgram.) This parameter determines whether the tree is to be drawn at the scale determined by the tree form parameters or the tree is to be drawn at the scale determined by the XSIZE and YSIZE parameters. Legitimate values are 'N', scale is determined by the tree form parameters and 'Y', scale is determined by XSIZE and YSIZE parameters. XSIZE and YSIZE are described below. The tree form parameters are described in the specific documentation for Plotree and Plotgram. XSIZE, YSIZE - These parameters describe the dimensions, in centimeters, of a box. If SIZEMODE has value 'Y', the tree will be rescaled so that it is as large as possible and still fits in a circumscribed box XSIZE by YSIZE. Legitimate values are positive real numbers. XSIZE specifies the x-dimension of the box, YSIZE, the y- dimension. The rescaled tree will not exceed XSIZE centimeters in the x-direction nor YSIZE centimenters in the y-direction and will exactly equal at least one of XSIZE or YSIZE in the appropriate direction. If SIZEMODE has value 'N', then XSIZE and YSIZE have no effect. (SIZEMODE, in effect, always has value 'Y' in Plotgram.) 3. POSITION AND ROTATION PARAMETERS XPOSITION, YPOSITION - These parameters specify the position on the plotting surface at which the tree is to be drawn. The position is indicated in centimeters from the origin of the plotting device. Legitimate values are real numbers. The exact mode of action depends on XOPTION and YOPTION; see below. These parameters allow the user to specify the normal position of a tree on the graphics device or allow the user to accurately place several trees on a single plot. XOPTION, YOPTION - These parameters specify how the XPOSITION and YPOSITION, respectively, of a tree are to be determined. Legitimate values are single upper-case letters: For XOPTION: 'O' - XPOSITION indicates the center of the root node 'C' - tree is centered in the x-direction about XPOSITION 'L' - tree lies to the left of XPOSITION, rightmost edge of tree is at XPOSITION 'R' - tree lies to the right of XPOSITION, leftmost edge of tree is at XPOSITION For YOPTION: 'O' - YPOSITION indicates the center of the root node 'C' - tree is centered in the y-direction about YPOSITION 'A' - tree lies above YPOSITION, bottom edge of tree is at YPOSITION 'B' - tree lies below YPOSITION, top edge of tree is at YPOSITION ROTATION - This parameter allows the tree to be rotated with respect to the plotter coordinate system. ROTATION specifies the angle, in degrees, through which the tree is to be rotated. Legitimate values are real numbers. Positive values indicate clockwise rotations. Some plotters have a plotting bed that is longer in the y- direction than in the x-direction. Because trees plotted by Plotree are usually taller than they are wide, it may be advisable to rotate them through 90.0 degrees, so that the top of the tree extends in the positive y-direction. Note that XPOSITION, XOPTION, and the corresponding y parameters always refer to the plotter coordinate system and are not affected by ROTATION. To center an unrotated tree about its own vertical axis, one would use an XOPTION of 'C'. A tree that has been rotated through 90.0 degrees would be centered about its own vertical axis by using a YOPTION of 'C'. 4. LABEL PARAMETERS FONT - This parameter specifies which of five character fonts will be used for labels. Legtimate values are the characters '1', '2', '3', '4', and '5'. The fonts that are used are taken from the Hershey fonts, which were created by Alan V. Hershey in the 1960s while he was working at the National Bureau of Standards. Each font includes the upper-case letters, lower-case letters, arabic numerals, period ("."), comma (","), colon (":"), exclamation point ("!"), question mark ("?"), slash("/"), parentheses ("(" and ")"), hyphen ("-"), asterisk ("*"), and blank (" "). FONT 1 specifies the single-stroke character font, simplex roman. FONT 2 specifies the double-stroke character font, duplex roman. FONT 3 specifies the multi-stroke character font, complex roman. FONT 4 specifies the double-stroke character font, duplex italic. FONT 5 specifies the triple-stroke character font, complex italic. These fonts require varying amounts of storage. FONT 1 requires 1165 integers in storage; FONT 2, 2162 integers; FONT 3, 3190 integers; FONT 4, 2173 integers; FONT 5, 3200. If necessary, the amount of storage required by Plotree can be substantially reduced by setting the constant "fontsize" at the begining of the program code to accomodate only the smallest font, FONT 1. If this is done, of course, only FONT 1 can be used. PENCHANGE - This parameter specifies whether the plotter pen is to be changed before plotting the label on plotters that allow automatic pen changes. Legitimate values are 'Y', which causes the pen to be changed before plotting the label, and 'N', which causes the plotter to use the same pen that is used to draw the nodes and internodes of the tree. Trees will look better for publication if a wider pen is used to draw the nodes and internodes that make up the tree and a narrower pen is used to draw the node labels, particularly if FONT 3 or FONT 5 is used. 5. PROGRAM CONTROL STARTMODE - This parameter determines whether the program pauses before writing commands to plotfile. If STARTMODE has the value 'Y', then the program will pause until the user hits enter (return) from the keyboard. If STARTMODE has the value 'N', then the program will not pause. The default value is 'N'. PLANS FOR FUTURE DEVELOPMENT OF PLOTREE AND PLOTGRAM For Plotree, future versions are planned that will 1. draw undirected trees, 2. put arrows on the internodes, and 3. drive video displays. For Plotgram, future versions are planned that will 1. draw a scale for the phenogram or phylogram, and 2. drive video displays. HOW USERS OF PLOTREE AND PLOTGRAM CAN HELP THEM BECOME BETTER By writing me (C. Meacham, Univ. Herbarium, Univ. of California, Berkeley, CA 94720) you can make these program more useful to you and to others. Notify me of any special problems you encounter getting them running on your system, especially if you successfully solve these problems. I can incorporate notes on potential problems and their solution into this documentation. If you develop code to drive other plotters, let me know and I can put the code in the versions I distribute or list it in this documentation. If you cannot get these programs to produce satisfactory drawings of a particular diagram, send me the tree description and describe the failings of the program. I will try to modify future versions to make them more successful in drawing the kinds of diagrams people need them for. ACKNOWLEDGMENTS The first version of Plotree was written in 1978 at the University of Michigan, first in PL/I, then in Fortran. The University of Michigan Computer Center provided free computing time. The first Pascal version was written in Joe Felsenstein's lab during the summer of 1984 while I was on leave from the University of Georgia and was subsidized by the UGA Botany Department and by a DOE grant to Felsenstein. Plotgram was written as a modified version of Plotree in December of 1984. During 1985, David Swofford and Julian Humphries made an interactive version of Plotgram and made other substantial modifications to the source code, including fixing a few bugs. Some of these modifications have been added to versions 1.3, others will be added in the future. Swofford and Humphries wrote some of the device drivers listed in Appendix 1. Also during 1985, Felsenstein produced Dotree and Dotgram, versions that drive dot matrix printers. ========================================================================= ========================================================================= ADDENDUM by Joe Felsenstein GENERAL COMMENTS ON GETTING STARTED It's a lot easier than Chris makes it sound in the documentation above. First you get the programs compiled, which is mostly the same as getting anything else in the package compiled and running, keeping in mind mostly that these programs have three input files (parmfile, treefile, and fontfile) and one output file (plotfile) which will probably need a CLOSE statement so it doesn't get lost. OK, say that's done. How do you give all the commands to run the programs. Gosh, it sounds awfully complicated, doesn't it? It isn't! Just make up the treefile containing some tree, say: ((A,B),(C,D)); and a parmfile that contains just one line (trust the defaults for now) PLOTTER H (or whatever of the plotters you have: T for Tektronix, B for Bausch and Lomb, or C for Calcomp (we still don't know if that one works)). Now run it! If it seems to have worked, try sending it to your plotter. If it has trouble reading the treefile or parmfile and gets upset and complains about end-of-lines or end-of-files, you probably have one line too many in your file. These programs are rather sensitive to that. Try deleting the blank line after the last substantive line in these files. (Or adding one if it wants it that way). If you have got out one of these (beautiful) plots, now you are ready to read everything more carefully and start playing around with the parmfile and making things more complicated. Have a look at LABELSIZE, XSIZE, YSIZE, XPOSITION, YPOSITION, ROTATION, etc. I must simply add that PLOTREE and PLOTGRAM are absolutely beautiful programs that produce marvellous results, absolutely publishable. Try them -- you'll like them. ================================================================== ================================================================== DOTREE and DOTGRAM --- all you need to know. by Joe Felsenstein (note: DOTREE pronounced DOT-TREE!) These are versions of PLOTREE and PLOTGRAM that I have prepared by modifying PLOTREE and PLOTGRAM. They work on dot matrix printers. The printers supported at the moment are: Epson printers with dot graphics, including all sorts of printers that are Epson-compatible in their graphics, such as Star Gemini family, Panasonic KP1091 etc. C. Itoh Prowriter and family -- including its sibling the NEC 8023 (and 8025), and the printers by TEC (Tokyo Electric) who actually are the ones that produce these printers. Toshiba P1350, P1351, P351, P1340, P341, etc. I meant to also include Okidata as a fourth supported family, but couldn't locate one to try it out on in time to get the code into this release, so for the moment this will have to wait for the next release. Or do it yourself! The programs take a few minutes to produce the graphics information in a file, which you then copy to your printer. I have to say that the printing speed of the Star Gemini and C. Itoh printers I tried was acceptable, but that the Toshiba printers, which are very fancy 24- dot-per-character printers, simply had so many little dots to dump to the printer that at 1200 baud it took about 20 minutes for one plot. One caution -- some operating systems change bytes as they go out to the printer. You have to stop them. Unix may give you trouble with this. Ask a "guru". For MSDOS (IBM PCDOS) you will want to COPY the file to your printer device (whatever that is) but with a /B after the filename so that the operating system is properly intimidated and does not mess with your file. On CP/M-80 you can use (if your printer is hooked to the LST: device) and the file with all the little dots in it is called PLOTFILE : PIP LST:=PLOTFILE[O] the [O] being the trick that intimidates the operating system. (MVSP users note: I have modified the dot matrix procedures so that PLOTGRAM always writes directly to the printer. I ran into problems when output was directed to a DOS file or device in that some data was being lost in transit. As a result there is no need to use the COPY command as described above. - WLK) FEATURES Almost identical to PLOTREE and PLOTGRAM! With the following exceptions: (1) No CHANGEPEN command -- because there is no pen to change! (2) You say PRINTER instead of PLOTTER. This I did so you can't mistakenly call PLOTGRAM when you mean to call DOTGRAM and not be stopped by an error message. The printer symbols are: Epson compatible E C. Itoh family C Toshibas T (3) The parameter defaults are somewhat different. See the detailed code of the PROCEDUREs initparms and printrparms to get the details, if needed. USING THE PROGRAMS Same as PLOTREE and PLOTGRAM, with the exceptions noted. HOW THEY WORK Same as PLOTREE and PLOTGRAM for working out tree coordinates. When it comes the actual printing, the program works down your page one strip one character deep at a time. For each strip the program goes through the tree and figures out if any dots in that strip need to be turned on. When it finishes drawing in the bunch of bytes that represent all the dots in that strip, the routine striprint prints the strip out, and on to the next strip. Every five strips a number (5, 10, 15, ...) is printed out just to reassure you. When all is finished, the plot file needs to be dumped to your printer. HELP! You can help me by letting me know graphics details of any other printer so we can include the code or append it to this documentation. SPECIFIC INSTRUCTIONS FOR EACH PROGRAM There aren't any. Read the instructions for PLOTREE and/or PLOTGRAM, then change PLOTTER to PRINTER, provide the proper printer code (E, C, or T) and go to it. ==================================================================== Copyright 1986 by Christopher A. Meacham. Permission is granted to copy, distribute, and modify this document provided that (1) this copyright message is not removed and (2) no fee is charged for this document. (for version 1.4 of PLOTGRAM, distributed with MVSP 2.0) SPECIFIC DOCUMENTATION FOR PLOTGRAM Christopher A. Meacham Botany Department, University of Georgia, Athens, Georgia 30602, U.S.A. Present address: University Herbarium, University of California, Berkeley, CA 94720, U.S.A. DESCRIPTION OF THE OUTPUT TREES Plotgram draws trees of three basic types: cladograms, phenograms, and phylograms. For cladograms, the lines between internodes are drawn at a slant, and the level at which a branch comes off has no special significance. A cladogram depicts only the order of branching as determined by the tree description. For phenograms and phylograms, the lines between internodes are drawn as right angles, and the position of each node (branch point) is determined by the number in the tree description that is associated with that node. For phenograms, the number is interpreted as a level, that is, the number describes how far from the base (or, alternatively, the top) of the diagram the branch point is to be placed. The tips of a phenogram are all at the same level. A phylogram is similar to a phenogram, but the number is interpreted as the length of the internode that is situated below the node on the tree. In addition, the tips of a phylogram are not necessarily all at the same level. For all three diagrams the labels are placed at the tips of the ultimate branches. Plotgram generates these three types of diagram by performing basic operations in different combinations. Exactly which operations are performed can be controlled by the user. This can enable the user to make types of tree diagrams other than the three main types described above. USING PLOTGRAM The user should first read the general documentation for Plotree and Plotgram, which describes how to get the programs running. Only after the program can successfully draw very simple diagrams with the default parameter settings, should the tree form parameters that are described below be used. (It is permissible to set the DIAGRAMTYPE parameter while testing Plotgram, though.) Keep in mind that setting these parameters is not mandatory and that Plotgram will be able to draw diagrams successfully without setting these parameters. The default values, which are obtained by simply not specifying the parameter in parmfile, will very often be completely adequate. The user should consult the general documentation for the format of the parameter file. THE PLOTGRAM PARAMETERS DIAGRAMTYPE - This parameter specifies which of the main diagram types Plotgram is to draw. Legitimate values are 'C' for cladogram, 'E' for phenogram, and 'Y' for phylogram. The default value for DIAGRAMTYPE is 'C' for cladogram. This parameter accomplishes its effect by essentially changing the default values for the other parameters described below. Default values changed by the DIAGRAMTYPE parameter 'C' - cladogram DRAWING 'S' VERTICAL 'D' HORIZONTAL 'S' TIPS 'Y' WIDTHMODE 'Y' 'E' - phenogram DRAWING 'R' VERTICAL 'V' HORIZONTAL 'N' TIPS 'Y' WIDTHMODE 'N' 'Y' - phylogram DRAWING 'R' VERTICAL 'N' HORIZONTAL 'N' TIPS 'N' WIDTHMODE 'N' The effect of selecting a DIAGRAMTYPE of 'Y' (phylogram) is identical to the effect of setting the parameter values listed above under phylogram. DRAWING - This parameter specifies whether the lines between nodes on the tree are to be drawn as slanted (diagonal) lines or as rectangular (right-angled) lines. Legitimate values are 'S' for slanted and 'R' for rectangular. / ! / ! / ! / ---------- slanted rectangular VERTICAL - This parameter specifies how the vertical positions of the nodes of the tree are to be calculated. (Note: "Vertical" here refers to the position of a node along the axis of the tree, that is, the position as measured from the level of the root of the tree. Phenograms and phylograms are customarily drawn with their root to the left and their tips to the right. For the purpose of setting this parameter, imagine the phenogram or phylogram to be drawn with the root at the bottom and the tips at the top in the same orientation as a normal cladogram.) Legitimate values are 'V' for "levels," 'N' for "lengths," 'T' for "top," 'B' for "bottom," and 'D' for "distance." The default value is 'D' for "distance." If 'V' (for levels) is specified, the number that is associated with the node in the tree description determines the level, or distance above the root of the tree, at which the node is placed. This is the typical value for a phenogram. If 'G' (for lengths) is specified, the number that is associated with the node in the tree description determines the length of the internode that is immediately below the node. Thus, the level of a node is the sum of the lengths of all the internodes that are below the node. This is the typical value for a phylogram. If 'T' (for top) is specified, the vertical position of a node depends on the number of internodes that must be traversed to reach the furthest descendant node that has no descendants itself. If a node has no descendants, it is placed at the uppermost, or zeroth, level. If a node has a descendant that in turn has no descendants, it is placed at the first level below the uppermost level. If a node has a descendant that has a descendant that has no descendants, it is placed at the second level below the uppermost level, etc. If, for example, the furthest descendant from the root node were reached by crossing five internodes, the diagram would have six levels: the zeroth level at the top through the fifth level at the bottom. The root would be at the fifth level. The numbers associated with the nodes in the tree description are ignored. This option is useful for describing the branching pattern of a tree without specific levels or lengths necessary to determine the positions of nodes. In this regard, it is similar to the "bottom" option described next. If 'B' (for bottom) is specified, the vertical position of a node depends on the number of internodes that must be traversed to reach the root. The root is placed at the bottom, or zeroth, level. The node (or nodes) that are the maximum distance (in terms of crossing internodes) from the root are at the highest level on the tree. If 'D' (for distance) is specified, the vertical position of a node is equal to the horizontal distance between the leftmost and rightmost ultimate descendants of the node in question. This is useful for cladograms. HORIZONTAL - This parameter specifies the manner in which the horizontal position of a node is determined. (For the frame of reference for "horizontal" vs. "vertical," read the beginning of the above description of the VERTICAL parameter.) Legitimate values are 'S' for "straightline," 'N' for "nearest," and 'F' for "furthest." The default value is 'S' for "straightline." If 'S' (for straightline) is specified, the nodes are positioned horizontally so that they fall along straight lines in the manner needed for cladograms. It is not necessary to describe this process here. Consult the source code for details. If 'N' (for nearest) is specified, the horizontal position of a node is calculated as exactly halfway between the horizontal positions of the leftmost and rightmost IMMEDIATE descendant nodes. This is the typical value for phenograms. If 'F' (for furthest) is specified, the horizontal position of a node is calculated as exactly halfway between the horizontal positions of the leftmost and rightmost ULTIMATE descendant nodes. TIPS - This parameter specifies whether the all the tip nodes of the tree should fall at the same level. Legitimate values are 'Y', in which case, tips are adjusted, if necessary, to fall at the same level, and 'N', in which case, no adjustments are made. The default value is 'Y'. The adjustment is achieved by increasing the level of any tip nodes that fall below the highest level so that they equal the highest level. POPMODE - This parameter specifies whether internodes should be added to the tree to move labels that are on internal nodes to tip nodes. Legitimate values are 'Y', in which case, labels are "popped" away from internal nodes, and 'N', in which case, no change is made to the tree. The default value is 'N'. Essentially, 'Y' converts a tree that is not an n-tree to an n-tree. WIDTHMODE - This parameter specifies whether the width of the tree is to be determined by the parameter TWIDTH or the width of the tree is determined by the height and spacing of the labels on the tree (see LHEIGHT and SPACING below). Legitimate parameters are 'Y', in which case, the width of the tree is determined by TWIDTH (see below), and 'N' in which case the width of the tree is determined by the height and spacing of labels. The default value is 'Y' for cladograms and 'N' for phenograms and phylograms. TWIDTH - If WIDTHMODE is 'Y', this parameter specifies the width in centimeters of the tree. Legitimate values are positive real numbers. If WIDTHMODE is 'Y', the labels will be equally spaced so that the total width of the tree is TWIDTH centimeters. THEIGHT - This parameter specifies the height in centimeters of the tree. Legitimate values are positive real numbers. LHEIGHT - This parameter specifies the height in centimeters of the labels. Legitimate values are positive real numbers. SPACING - If WIDTHMODE is 'N', this parameter specifies the distance between labels as a proportion of label height. Legitimate values are positive real numbers. GAP - This parameter specifies the distance between the labeled tips and their corresponding labels as a proportion of label height. Legitimate values are positive real numbers. LROTATION - This parameter specifies the angle in degrees through which the labels should be rotated with respect to the tree. Legitimate values are real numbers. The default value is '0.0'. The default is to have the labels oriented in the direction of the main axis ("vertical axis" as used here). REVERSALS - Added by WLK. PLOTGRAM originally would not allow negative values for the distances between two nodes. However, dendrograms produced by some of the clustering strategies of MVSP may have reversals, in which the level of one node is higher than its ancestor node, rather than lower. I have modified PLOTGRAM to allow for reversals so that a true representation of the tree is plotted. The default value is 'Y'. Note that if there are reversals in the dendrogram description but this parameter is set to 'N', then the resulting dendrogram will be suspect. If you use this version of PLOTGRAM for any other kind of diagram, such as cladograms, you should set this option to 'N'. BIOSPRINT - Added by WLK. DOTGRAM originally sent data to the dot matrix printer in the same way it would be sent to a file, thus allowing you to dump the results to a file for later printing. However, I had problems with this method; sometimes some of the data would get lost on the way to the printer and garbase would be printed. I modified PLOT14 to write directly to the printer, using the computer's BIOS (Basic Input/Output System). This was more reliable, but precluded printing to a file. Setting BIOSPRINT to N reinstates the original method of printing to dot matrix printers and will allow printing to a file.