NAME lexis plot This module displays event history data using a Lexis pencil object. SUMMARY Name lexis plot Type Input Inputs None Outputs geom Parameters (see below for description of user interface) DESCRIPTION Displays event history data using a Lexis "pencil" object for each case history. The input event history data file contains a number of data variables any of which may be selected for the three coordinate axes. Any of the remaining variables may be used to "paint" the faces of the Lexis pencils with colours according to the value of the variable. Such dependent variables may take integral values between 0 and 15 while independent variables may take any real values. There will normally be one variable which is an index of the case histories. The resulting "geometry" is displayed in a window together with a set of axes and annotation. Many facilities exist for selecting the input data, selecting data variables to be used and for modifying the appearance of the pencils in the resulting plot. Interaction with the package is by way of the "widgets" displayed above and to the side of the Geometry viewer window. These widgets allow the user to make choices from a list of options which may be a static list or in a scrollable window, to set values for parameters using dials or sliders, and to read data files from a scrollable list. Interaction with the image displayed in the Geometry viewer window is possible via mouse operations within the window or by making selections from the Geometry viewer's own control panel. LEXIS PLOT TOP LEVEL MENU The top level menu is always displayed at the top left hand corner of the Lexis plot window. The menu items are: Read event history data file Filter data Pencil geometry Edit colours Clip geometry General features In addition there is a "Hardcopy" button which is normally displayed just beneath the top level menu. On start-up the "Read event history data file" menu is pre-selected and some of its own widgets are also displayed. On starting Lexis plot the normal action is to first select an event history data file. READ EVENT HISTORY DATA FILE MENU Reads and processes the event history data file. The first widget displayed is a file browser listing all files with extension .lexis in the data directory (specified in .avsrc in the directory from which avs is started). The first line in the event history data file contains the names of each of the data variables in the file. The names are separated by one or more spaces. Subsequent lines contain the data variable values in columns separated by one or more spaces. The values are per case history, i.e. the records for each case are contiguous and in increasing time order. One of the data variables will be an index or ID number for the case history so within each case it will have a constant value. The case history ID value is arbitary except that all IDs must be distinct and positive. Example of a lexis_plot data file: case_number female_age male_age time_since_marriage date_of_marriage child_state female_employment male_employment marriage_order 30001 22.75 21.75 .00 1961.75 3 1 1 63 30001 22.83 21.83 .08 1961.83 3 1 1 63 30001 22.92 21.92 .17 1961.92 3 1 1 63 30001 23.00 22.00 .25 1962.00 3 1 1 63 30001 23.08 22.08 .33 1962.08 3 1 1 63 30001 23.17 22.17 .42 1962.17 3 1 1 63 30001 23.25 22.25 .50 1962.25 3 1 1 63 30001 23.33 22.33 .58 1962.33 3 1 1 63 30001 23.42 22.42 .67 1962.42 3 1 1 63 30001 23.50 22.50 .75 1962.50 3 1 1 63 30001 23.58 22.58 .83 1962.58 3 1 1 63 30001 23.67 22.67 .92 1962.67 3 1 1 63 30001 23.75 22.75 1.00 1962.75 3 0 1 63 30001 23.83 22.83 1.08 1962.83 3 0 1 63 . . . Having selected the event history data file a second widget displays all the data variable names and the user is invited to select the one to be used as the case ID. Having done this there will be a delay as the remainder of the event history data file is read. A further three widgets are then displayed with an invitation to select the three variables to assign to the coordinate axes. Having selected these the filter data menu is then automatically selected. DATA RESTRICTIONS Maximum number of records in one file: 150000 Maximum number of observations in one case: 460 Maximum number of cases: 1000 Maximum number of variables in one file: 20 Maximum length of 1st record in file: 480 FILTER DATA MENU This menu determines how much of the event history data is to be displayed. CASE SELECTION Nothing is displayed until one of the alternative options "Use all cases in event history data file" or "Read case list file" is selected. If "Read case list file" is selected the user is presented with a file browser showing all files in the data directory with an extension of ".case". A case list file is simply a list of case IDs to be displayed. This list is a single column of values. Each value should be the ID of a case history from the previously selected event history data. Once a case list file or "Use all cases in event history data" is selected, those cases are then displayed as Lexis pencils with a set of axes and some descriptive annotation. If no data variables have been assigned to the pencil faces (in the Pencil geometry menu) they will all be given the colour for data value 0. REASSIGN X, Y & Z This option allows the assignment of data variables to the coordinate axes to be changed. Any change from the previous assignment will cause the geometry viewer window to be redrawn. FILTERING ACCORDING TO DEPENDENT VARIABLE VALUES In the top right hand corner is a list of options to impose or cancel filtering of the cases according to the values in a maximum of two of the dependent variables. These may or may not be variables whose values are to be displayed on the faces of the Lexis pencils. SELECT FIRST FILTER VARIABLE Once this option is selected the user then chooses the variable from the scrollable list just below. Once the variable is selected its minimum and maximum values are displayed in the pair of dials immediately below the scrollable list. These are the minimum and maximum values of that variable at the first time step only for each case in the event history data. Changing the minimum and maximum values will restrict the display to only those cases for which that variable's value at the first time step lies between the chosen minimum and maximum. SELECT SECOND FILTER VARIABLE The procedure is the same as that for the first filter variable. The constraints are compounded, i.e. the display is restricted to only those cases for which both variables at the first time step lie within the specified ranges. CANCEL FIRST FILTER VARIABLE & CANCEL SECOND FILTER VARIABLE These options remove the previously applied constraints. FILTERING ACCORDING TO INDEPENDENT VARIABLES In the bottom right hand corner are two pairs of dials for the two variables assigned to the X and Z axes. Their minimum and maximum values are displayed. The display can be restricted to only those for which the variable assigned to X and/or the variable assigned to Z lie within the specified bounds at the first time step. PENCIL GEOMETRY MENU ASSIGNING VARIABLES TO PENCIL FACES In the top right hand corner is a group of widgets to allow the user to map data variables onto the Lexis pencil faces. NO. OF FACES This dial allows the number of faces for each pencil to be changed. The default is 3 but it may be changed to any value between 1 and 8. ASSIGN FACE This dial selects a pencil face to be coloured according to a data variable's values. In the default projection face no. 1 is on the right hand side of each pencil but this may change if either the axes or the pencils are rotated. Having selected a face number the variable to be assigned to it is chosen from the scrollable list immediately below. That face is then "painted" according to the values of that variable. The assumption is that the Y axis at least measures time so that the colour will vary along the length of the pencil face as that variable's value changes with time. Each value is an entry in a colour table which is displayed in the bottom right hand corner of the Geometry viewer window. Initially a default colour table is loaded but this can be changed in the "Edit colours" menu. Colour table entries and therefore dependent variable values range from 0 to 15. PENCIL GEOMETRY A group of three dials allow the width of pencil faces, the angle between adjacent pencil faces and the angle of rotation of a pencil about its axis to be changed. The pencil face width is specified as a multiple of its default width while the angles are in degrees. PENCIL SLOPE Two pairs of choices allow the slope in both the X and Z coordinate directions to be varied. The default is that the pencils slope in both X and Z which would be consistent with both the X and Z axes being time variables. This need not necessarily be so in which case the user should cancel the pencil slope in that coordinate direction. The decision as to whether a variable is a measure of time or not cannot be done automatically so it is the user's responsibility to define the slope in a meaningful way. EDIT COLOURS MENU Four sliders allow the colours in the colour table to be changed. The first slider, labelled "Edit colour" is the number of the entry in the colour table. Its value varies between 0 and the maximum value of the data currently displayed. Move the slider to select the colour to be changed. The other three sliders define the red, green and blue components of that colour. The values of each component range from 0 for no colour to 1 for maximum intensity. If red, green and blue are all set to 1 the resulting colour is therefore white. To achieve a grey colour the red, green and blue components should be set to equal values between 0 and 1, the higher the value the lighter the shade of grey which will result. Note that by default the geometry is redrawn each time a colour component is changed. This can be very time consuming if the whole colour table is to be changed so the automatic updating can be turned off in the "General features" menu. The user should remember to turn the "Update geometry" option back on later to ensure that the display is up to date. CLIP GEOMETRY MENU Clipping the geometry differs from filtering according to data variable values in that it does not affect the list of cases to be displayed. It is simply a geometrical restriction on the extent of the pencils when displayed in the Geometry viewer window. For example increasing from 0 the minimum clip value for the variable assigned to the Y axis will simply "chop off" the bottom of each pencil. ANNOTATION OPTIONS MENU Various options are provided to modify the axis annotation. An option box allows the user to first select the axis whose annotation is to be modified. An option list selects either primary or secondary axes to be annotated. This is relevant only to the X and Z axes since there is only one Y axis displayed. Having selected the axis, sliders allow the offset of both the axis title and labels to be changed in each of the 3 coordinate directions. Dials allow the frequency of numbering and the start value. A start value of 1 means that the first axis tick is numbered, a start value of 2 means that numbering starts at the second axis tick, etc. GENERAL FEATURES MENU AXIS SCALING By default the 3 coordinate axes are scaled so that they appear the same length in the Geometry viewer window. The "X scale" and "Z scale" sliders allow the lengths of the X and Z axes to be shortened or lengthened with respect to the Y axis. TRANSPARENCY By default all pencils are opaque. Reducing the transparency from 1 will make them partially transparent. Individual pencils can then be selected within the Geometry viewer and made opaque in order to highlight them. DATASET INFORMATION DISPLAY By default a number of lines of information about the data are displayed within the Geometry viewer window. This is highly desirable since without it false assumptions might be made about the resulting geometry. However, it might be undesirable to have this information displayed in this form on a hardcopy intended for publication so the "Do not display dataset information in Geometry viewer window" option is supplied to allow it to be turned off. AXIS AND ANNOTATION COLOUR By default the Geometry viewer window has a black background and the axes and annotation are in white. This default also holds for hardcopies. The "Black axes and labels" option allows these colours to be inverted which is more suitable for hardcopies. GEOMETRY UPDATING By default the geometry is immediately updated whenever a change occurs through varying a parameter in one of the input widgets. This can be very time consuming especially when changing a number of entries in the colour table. The "Do not update geometry" option allows the automatic updating to be turned off so that a large number of changes can be accomplished in a single update. WARNING Remember to turn "Update geometry" back on again after making a series of changes or the resulting image will be wrong! HARD COPY MENU Pressing the "Hard copy" button brings up a prompt for a filename to receive a copy of the Geometry viewer window in PostScript form. As soon as the filename is entered and the mouse pointer moved away the file is created. Copies of subsequent views can be saved only by typing a new filename. The resulting PostScript is in image form so its resolution is that of the image on the screen. It will look coarse when printed. It is possible in the Geometry viewer control panel to increase the resolution of the Geometry viewer window. Increasing it to printer resolution will produce extremely large files. The file size can be reduced for grey scale images by selecting the "greyscale" option in the "image to postscript" control panel. This is normally displayed on the far left of the screen but will be obscured by the Geometry viewer control panel if that is displayed. EXAMPLE NETWORK lexis plot | | geometry viewer | | image to postscript