KMWin Help

Introduction

Overview

KMWin (Kaplan-Meier for Windows) is a programme for graphical presentation of Kaplan-Meier plots. KMWin connects to R, sends commands to R, loads data sources and generates survival curves with R functions. KMWin is only an interface and intended to make working with R easier.

After selection of a time and a status variable from the variables list, properties of the survival curve such as colour, line width and line type can be modified. Furthermore a curve description for the legend could be specified. Optionally a factor variable can be selected, certain levels of the factor may be chosen and corresponding graphical properties can be modified. In addition, labels, min and max values of axes and step sizes of axes can be adapted. Further features comprise marking of censored times, adding an information text to the graphic, inverting the survival curve, displaying a table with cases under risk at the respective time step, adding a legend (optionally with number of cases), calculating global or pair-wise Logrank tests with description texts and adjustable p-value accuracy (see Main Window). Plots can be saved for future use and may be reloaded for additional modifications. Every setting along with the name and folder of the data source is written to a file. If the location of the data source changes, then folder and file name can be updated.

Other options are the definition of filters (see Filter Window), modification of numerous preferences (see Preferences Window) like foreground colours, background colours, frames, font types, scale factors and margins for certain components of the plot. The communication between KMWin and R is logged to a text box (see Log Window) to follow which commands and functions of R were executed.

After drawing a plot, the generated graphic can be saved to a file or copied to the clipboard by right clicking within the R plot window or by making use of the R file menu. If plenty of plots were generated and saved with KMWin, then it is cumbersome to open and redraw every plot and save the corresponding graphic one by one. For this purpose, all the saved plots can be processed in a file queue (see File Queue Window) and saved to a folder in a certain graphic format.

Remarks

Status Bar

The status bar assists in creating new plots by suggesting what to do next and shows useful hints. It is located at the bottom of the window.

Hotkeys

Hotkeys for the programme are:

• ALT+1 or ALT+m activates the Main Window.
• ALT+2 or ALT+f activates the Filter Window.
• ALT+3 or ALT+p activates the Preferences Window.
• ALT+4 or ALT+q activates the File Queue Window.
• ALT+5 or ALT+l activates the Log Window.
• ALT+d or pressing the Draw button on the Main Window or Filter Window draws the current plot.
• F1 shows this HTML file and jumps to the section which belongs to the activated window.
• Ins Key is equivalent to pressing the Add File(s) button on the File Queue Window.
• Del Key is equivalent to pressing the Remove File(s) button on the File Queue Window.
• Tab Key or Shift+Tab Key sets the focus to the next or the previous item respectively on the current window.

HTML Help

If the HTML help file kmwin.htm is located in the same folder as the KMWin binary kmwin.exe, then KMWin calls the help file and jumps to the appropriate section when an error occurs or F1 is pressed.

Communication between KMWin and R

KMWin and R communicate in a client/server environment. KMWin acts as server and sends commands to R which acts as client, e.g. KMWin orders R to open a file and to send back a list with names of variables.

Establishing a connection requires to create the temporary file .rProfile in the users temp folder. The .rProfile contains the client routine which is interpreted by R. The location of the temp folder is fetched via a system call.
If R is already running, then KMWin commands R to load .rProfile in order to establish a connection. The command is written to the Log Window and should be pasted into the R console when the latter did not work correctly.
If R is not running, then KMWin tries to fetch the install folder of R from the registry and loads R via a system call. The call is invoked from the temp folder, so the .rProfile is run automatically.
In case of problems when connecting, start first R and then KMWin.

Whenever KMWin instructs R to do something, R may respond with an error. The reasons can be multifaceted. Data sources cause problems if the file extension does not correspond to the content. Usually, variables are selected wrongly, i.e. the values of a variable do not correspond to the variable type. The input should be checked carefully or if necessary, both programmes should be restarted.

Development

KMWin has been developed by Arnd Groß, Marita Ziepert and Markus Scholz at the Institute for Medical Informatics, Statistics and Epidemiology at the University of Leipzig with the objective to support the evaluation of clinical studies.

This HTML file was last updated on March in 2012 and refers to the most recent version 1.51 of KMWin. The Software package can be downloaded from https://sourceforge.net/projects/kmwin/.

Main Window

Description

The Main Window is the primary window on which the variables for survival time analysis can be selected (time, status, optional a factor variable). Survival curves can be selected and their style can be changed. Additionally, lots of adjustments are possible. Previous to activation of certain controls, a connection to R must be established and a new plot must be created or an existing plot must be loaded.

Remark

Positions (as Pos-x or Pos-y) are in units of the R plot window, e.g. position (0,0) is the origin.

List of Controls

• New Plot creates a new plot after selecting a data source. Supported file formats are SPSS *.sav, text *.dat and SAS XPORT *.xpt. According to the file extension of the selected file, an appropriate method is chosen to load the data source. Therefore, other file extensions result in an error message.
  Each line of a text file (*.dat) must have the same number of columns, i.e. indicate missing values by NA. Columns must be separated by white spaces (one or more spaces or tabs). Before instructing R to open the data source, KMWin analyses the text file regarding header and decimal separator. If the first line contains any letters, then KMWin assumes that a header is present. The other lines are checked for the presence of a dot, i.e. the decimal separator is assumed to be a comma unless any dot is found.
• Draw is activated after KMWin is connected to R, a plot was loaded or created and a time and status variable were selected from the List of variables. Pushing the button instructs R to draw the survival curve.
• Reconnect to R will reconnect to R if the connection was lost, in particular when R was closed or the client routine was interrupted by pressing ESC at the R console window. If reconnection fails, then restart both programmes.
• Change Data Source allows changing the file reference of the data source if the data source was moved to a new location or was renamed. This might be necessary since only the location of the data source is saved with the plot and not the data source itself. The data source can be changed without affecting the other settings. However, the new data source must contain the same time, status, and, if applicable, factor variable. Otherwise a New plot should be created.
• Load Plot loads a plot which was previously saved as *.kmw file by pressing Save Plot. Only saved plots with the most recent data file version can be opened. Older versions are not supported due to different properties of saved data. If the user has insufficient rights for file access, then an error occurs.
• Save Plot saves a plot as *.kmw file if the same conditions are fulfilled as for Draw, i.e. the connection between KMWin and R is established and a time and status variable was chosen. If the user has not the rights to create the file or the folder is read only, then an error occurs.
• List of variables comprises two columns, namely Variable and Type. The Variable column comprises all variables of the data source after loading or creating a plot. The order of the variables is the same as in the data source. Variables can be searched by pressing the first letters of the variable name. Right clicking within the Type column shows a popup menu with three different types Time, Status (1=Event) and Factor for assignment of the variable type. Status equal to 1 represents an event. Selecting a Factor produces a curve for each level of the factor.
• List of properties If no factor variable is selected, then the list of properties contains only one row which specifies the properties of the survival curve and the column Level contains every. If a factor variable is chosen, then the list of properties contains as many rows as factor levels are present and the column Level denotes the factor levels. The number of rows differs if a filter is applied, because the filter could remove levels from the factor. Every row represents a curve and the properties of the curve can be modified by right clicking within the corresponding column as follows.
  If a factor is present, then all considered levels can be selected by setting check marks in the Level column. Right clicking within the Level column displays a menu either to select all levels (list on), deselect all levels (list off) or to invert the selection (list inverted).
  Right clicking within the Color column affects the colour of the curve and provides several preferences. A user defined colour may be chosen by clicking User defined... and selecting a new colour. This action returns a hexadecimal red, green, blue value #rrggbb.
  Right clicking within the Linewidth column determines the line width (1-10) of the curve.
  Right clicking within the Linetype column provides six different line types.
  The Description column contains the legend text of the curve and can be modified by double clicking or right clicking and selecting edit field. Changes are confirmed by the Return Key. Changes are dismissed by the Esc Key or by clicking outside of the edit box.
• x-Axis Label and y-Axis Label affect the x-Axis and y-Axis captions.
• x-Min and y-Min determine the starting point of the curves and the axes respectively.
• x-Max and y-Max define the limits of the curves and the axes respectively. If a y-Max value greater than 1 is specified, then the y-Axis is interpreted in units of percent.
• x-Step size and y-Step size determine the distance between ticks of the x-Axis and y-Axis respectively. If the step size is equal or less than zero or the Max value is equal or less than the corresponding Min value, then choosing appropriate ticks for the x-Axis and y-Axis is delegated to R.
• Mark censored times adds crosses to the curves at censored times if selected.
• Add Infotext adds an information text with the main properties of the plot to the lower margin.
  The text comprises the Data source, the Filter and the Time, Status and Factor variables.
  If the factor variable is present, then all levels are shown together with their descriptions: Factor=Level -> Description.
  If the Logrank test is selected, then all tests along with involved levels and descriptions are added: Logrank Factor=Level_i1,Level_i2,...,Level_in -> Description
• Invert causes the 1-Survial curve to be drawn if checked.
• Add number under risk adds a table with the number of cases under risk at the corresponding time points. The description is obtained from the List of Properties.
• Pos-y (Table number under risk) defines the y-coordinate of the upper margin of this table.
• Show legend adds a legend to the plot. On the left hand side, lines are drawn in the same style as used for the corresponding curves (Color, Linewidth, Linetype). On the right hand side, the description is displayed which is obtained from the List of Properties. Optionally, the number of cases is presented in parentheses.
• Pos-x and Pos-y (Legend) determine the coordinates of the lower left corner of the legend.
• Add number of cases shows the number of cases in parentheses if selected.
• Logrank List is enabled unless None is selected in the Logrank Test box. If Global Logrank test is selected, then the Logrank list owns only one row. All levels which are included into the test are enumerated in the Logrank column. Levels of the factor are included if not filtered. If Pair is chosen, then all possible pairs of levels are shown in the Logrank list. All desired pairs can be selected. Right clicking within the Logrank column shows a menu to select all pairs (list on), deselect all pairs (list off) or to invert the selection (list inverted).
  The Description column contains the legend text, which can be modified in the same way as the descriptions in the List of Properties (see above).
• Logrank Test is disabled unless a factor is selected. Different types of tests are provided. None does not carry out any Logrank test, Global performs a global test, Pair calculates pair-wise tests and displays p-values for selected pairs of the Logrank list.
• Pos-x and Pos-y (Logrank Test) specifies the coordinates of the lower left corner of the box with p-values of the Logrank test(s).
• Accuracy of p restricts the number of positions after the decimal point for p-values. In cases were values would be rounded to zero, <value is printed for the smallest positive value with selected accuracy.

Filter Window

Description

Filtering survival time data prior to analysis can be achieved by applying a filter string on this window.

List of Controls

• Variables comprises a list of all variables from the data source and is comparable to the List of variables on the Main Window. In contrast to the Main Window, properties cannot be modified, but the variable name may be copied to the Filter String edit box by double clicking on the variable name or by pressing Return after the desired variable was selected. Variables can be searched by pressing the first letters of the variable name.
• Filter String is an edit box to enter a filter string which consists of variables, numbers, mathematical operators, logical operators and bracketing. See Panel for more details.
• Apply Filter/Reapply Filter is a button to set a filter. If no filter is set, then the button is labelled Apply Filter and it is named Reapply Filter otherwise. After pushing the button, KMWin checks the syntactic correctness of the filter string. An error is displayed when indicated, otherwise the filter is sent to R. R can also refuse the filter for some reason. If the filter results in an empty set, then an error message is shown.
• Remove Filter recovers the original data but does not remove the filter string from the edit box. The Filter String edit box keeps the most recent filter without having an impact on the data. Furthermore, the label of the Reapply Filter button is renamed to Apply Filter.
• Draw causes the plot to be drawn and is comparable to the Draw button on the Main Window.
• Panel comprises a set of buttons to insert character strings into the Filter String edit box. Provided are numerals from 0 to 9 and a decimal point to build floating point numbers. Available mathematical operators are +, -, *, / and ** for exponentials. Logical operators are applicable such as & (and), | (or) and ! (negation). Bracketing can be used with ( ). If text is selected in the Filter String edit box, then the text of the selection is parenthesized, otherwise only ( ) is inserted into the edit box. Relations are provided as <, <=, >, >=, == (equal) and != (unequal). Clear removes the filter string from the edit box.

Preferences Window

Description

The general settings of the plot such as colours, frames, font types, scales or margins can be modified on the preferences window. The settings are saved in the registry when closing KMWin and are stored along with other properties when saving a plot. The most recent settings are restored when restarting KMWin or when loading a plot.

List of Controls

• Item is a list of seven elements for which style settings can be modified. The list comprises
  • Plain - plotting plane and coordinate system,
  • Axes - numbers at the axes,
  • Label - labelling of the axes,
  • Legend and Logrank - text boxes of the legend and Logrank test respectively,
  • Infotext - information text which could be added to the plot and
  • Under Risk - table with cases under risk.
  Accordant to the properties of the selected item up to four additional lists (Color, Background Color, Boxtype, Font) and one scroll list (Scale Factor) are active or not.
• Color and Background Color specify the foreground and background colour of the selected item. Several presettings are available. A user defined colour may be chosen by selecting User defined... or if a user defined colour was already picked by clicking at #rrggbb. Here, #rrggbb corresponds to the hexadecimal red, green and blue values of the most recent user defined colour.
• Boxtype defines the frame of the selected item. Available are two types open-no frame and closed-with a frame. If Plain is selected, then open means a coordinate system with only crossed axes and closed means a box which completes the axes by a rectangle. If Legend or Logrank is chosen, Boxtype causes drawing a box around the text or not. The colour of the frame is defined by the Color property of the Plain item.
• Font selects the font type. Provided are four types plain-normal, bold, italic and bold italic.
• Scale Factor determines how the font of an item is scaled. The Scale Factor property of the Plain item controls the scaling of all fonts. In contrast, the Scale Factor property of all other items impacts only the associated item and is relative to the Scale Factor of Plain.
• Margins adds margins in units of text lines below, left, above and right to the plot. The margins should be selected sufficiently large to avoid chopping of objects near margins, e.g. the legend or the table of the Logrank test.
• Linewidth sets the line width for frames and axes. This includes frames of the legend and the table of the Logrank test when indicated, the line width of the coordinate system and the censoring marks.
• Linetype controls the box line type of the legend and the table of the Logrank test. Six different types are provided.
• Last session/Saved session (time stamp) is only visible if the preferences of the Last session are restored from the registry or the preferences are restored from a Saved session when a plot is loaded. In both cases, the time stamp shows the time when the last session ended or when the plot was saved.
• Preferences of last session is enabled unless the preferences were not successfully saved at the end of the Last session. Otherwise, the preferences are restored when starting KMWin and are set again when pressing this button.
• Preferences of saved session can be selected if a plot was loaded. Clicking this button restores the preferences which were saved together with other properties of the plot.
• Draw causes the plot to be drawn and is comparable to the Draw button on the Main Window.
• Default preferences restores the defaults. The defaults are also set if the preferences of the Last session could not be restored. Currently, the default is white text on blue background which is suitable for slides.

File Queue Window

Description

This window supports sequential processing of a list of previously saved plots and generating updates of them. Three different graphic output formats are available: Metafile (*.emf), Bitmap (*.bmp) or Jpeg (*.jpg). The file name of the output is the same as the file name of the saved plot. Only the file extension is substituted, e.g. example.emf is created from example.kmw.

List of Controls

• Input Files represents a list of saved plots (*.kmw files) from which new plots should be generated. Plots can be saved with Save Plot on the Main Window. With Add File(s) plots can be added to the list.
• Add File(s) opens a window to select plots (*.kmw files) which will be added to the Input Files list.
• Remove File(s) removes selected files from the Input Files list.
• Clear List removes every item from the Input Files list.
• Output Directory is a text box and shows the folder in which the graphics will be saved. The folder can be changed with the Change directory button. When closing KMWin, the folder is stored in the registry and restored at the next start of KMWin.
• Change Directory opens a window to select a new folder as Output Directory for graphic files.
• New Data Source is a text box and contains the file name of the data source which is used for the items in the Input Files list. The data source can be changed with the Change data source button, which opens a window to select a new data source file. If one wants to use the original data sources which belong to each plot (default), then press Cancel on the window, which is opened after pressing Change data source. Make sure that the data source is compatible with all plots of the Input Files list, because the settings of every saved plot will be applied to the new data source. If this fails, then errors occur.
• Change Data Source opens a window to select a new data source, which is shown in New Data Source. Selecting Cancel on the opened window resets the data source to the original setting.
• Output Format is a selection box and determines the output format of the graphic files.
• Width (px) and Height (px) are edit boxes to determine the width and height of the graphic output in pixels (px). The choice is only available for Bitmap and Jpeg graphics, because Metafile is a vector format for which dimensions are not important.
• Quality (%); is a slider which controls the percent of output quality of graphic files and is only available for Jpeg. Higher graphic quality results in bigger output files.
• Run starts the sequential generation of graphics from saved plots in the Input Files list.
• Cancel cancels the processing of plots, which has been started by Run. The process will stop after finishing the current plot.
• Clear Log clears the Log edit box.
• Log is an edit box and specifies the plot which is currently processed with Processing plot.kmw on its last line. When indicated, a warning or an error is displayed next to the file name. After finishing, the keyword Finish is written to the box.

Log Window

Description

The whole communication between KMWin and R is logged into this text box. The output shows which R commands and functions were used. There are different keywords referring to the connection status and transferred data.

Keywords

• ACCEPT indicates that the network connection between KMWin and R is established.
• CLOSE reports that the network connection is closed.
• REWRITE shows that a data package was sent again.
• READ status text task connected resend indicates that data text was received from R. If status=0 or 1, then text refers to an error message. If status=2, then text refers to a valid response, e.g. to requested variable names. See below for explanation of task, connected and resend.
• WRITE text task connected resend indicates that data text was sent to R. See below for explanation of task, connected and resend.
• SKIP nbytes task connected resend reports that nbytes of received data were skipped. This happens when more data is received than can be stored to the input buffer of KMWin, e.g. files with thousands of variables. See below for explanation of task, connected and resend.

• 0: no response expected
• 1: initiate connection
• 2: file test (data source)
• 3: draw
• 4: get variables
• 5: get factor levels
• 6: filter data