dbets - diffusion Breakpoint Estimation Software 5 Model Estimation Logistic Spline... 17

Transcription

1 dbets - diffusion Breakpoint Estimation Software This document describes the use of the R package dbets to the estimate the diffusion test (DIA) breakpoints from pathogen susceptibility tests. This package provides methods for visualizing the data, computing DIA breakpoints using the Error Rate Bounded (ERB) method, and computing DIA breakpoints using model-based approaches. It uses the R statistical programming language to perform the analyses, however no prior R experience is needed. This document briefly explains how to install R and the methods can be applied by slight modifications of the example code in each section. Please note the package and documentation are works in progress and there are likely to be bugs. problems or find the documentation unclear please contact Glen DePalma at gdepalma@purdue.edu. If you encounter Contents 1 Installing R 2 2 Installing Package dbets 3 3 Data preparation, importing the data, and visualization Data Preparation Data Preparation Importing the Data Data Visualization Error Rate Bounded (ERB) Methods Estimate ERB DIA Breakpoints ERB Results for Given DIA Breakpoints Assess Uncertainty - ERB Model Estimation Logistic Spline Additional Tools Logistic and Spline Comparison Probability of Correct DIA Classification Future Work 21 1

2 1 Installing R R is a free software environment for statistical computing and graphics. It can be downloaded from: r-project.org. Note if you already have R, version 2.14 or greater is required. It is also recommended (but not necessary) to download RStudio, which provides a nice interface for interacting with R. One nice feature of RStudio is the way it handles plots. All plots are temporarily saved in the program and you can easily enlarge (zoom) a plot and save the plot for future access outside of R. It is recommended to zoom all plots produced with this package. It may be helpful to read some brief introductions on R and RStudio, there are plenty on the Internet, below are two examples that may be useful: If you need additional help with R, Google can provide many answers. For example try searching for Linear Regression R. Below is the first result which walks through a simple example: 2

3 2 Installing Package dbets dbets is available for Linux or Windows machines. Currently Mac is not supported. After R is installed on your computer the package dbets must be installed. Installing the package only needs to be done once. However each time R is opened the package needs to be loaded, this command is shown at the bottom of the page. Start a new R session by launching R or RStudio. Input the following two commands (be sure to hit enter afterwards). Feel free to copy and paste each line, R code is case sensitive. The first line is the location for where to the download the package, this can be changed to any location you prefer. > setwd("c:\temp\") > source(" In addition to the package (which can now be deleted), additional files are downloaded to the location given in the first command. example.r contains the code used in this documentation, PTZPAER.csv and tableptzpaer.csv are two data files used in this documentation. Additional simulated data files are also included, data1.csv and data2.csv. To load the package enter library(dbets) each time an R session is started. 3

4 3 Data preparation, importing the data, and visualization There are two ways to set up the data to import into R. The first is a column entry method and the second is a table entry method. The data used in this documentation are of the following (2-fold intermediate range): Agent - Piperacillin-tazobactam Organism Group - P. aeruginosa Source - CLSI June 2011 Number of isolates = 820 MIC Breakpoint S - 16 log 2 (16) = 4 = MICBrkptL MIC Breakpoint I log 2 (32, 64) = 5, 6 = Intermediate Range MIC Breakpoint R log 2 (128) = 7 = MICBrkptU 4

5 3.1 Data Preparation 1 For the column entry method, the data should be entered in a csv (comma delimited) file with two columns MIC and DIA. The first row should include these as header names. The MIC data must be entered in the first column. If a value is censored put a < or > symbol before the value, with no spaces between. No other symbols are permitted. A portion of the example data spreadsheet is shown in Figure 1 below. Figure 1: A Portion of the Example Data Spreadsheet Note the MIC data can be stored on the original scale or log 2 scale. DIA is assumed in mm. See the example file PTZPAER.csv as a reference. 5

6 3.2 Data Preparation 2 An alternative data preparation technique is to store the data in table format. The MIC values should be entered in column A and the DIA values in row 1. At both endpoints for the MIC column and DIA row censored cells should be entered indicated by < or > (include this even if there are no censored observations). No not include spaces before or after < or >, and do not include 0 s (if a count is 0 leave it blank). A portion of the example data spreadsheet is shown in Figure 2 below. Figure 2: A Portion of the Example Data Spreadsheet - Table Form See the example file tableptzpaer.csv as a reference. 6

7 3.3 Importing the Data To import the data, we use the function importdata(). The data should be saved to some variable name. This function takes the following arguments: 1. filepath - the file path of the csv file 2. MICBrkptL - the log 2 base lower MIC breakpoint 3. MICBrkptU - the log 2 base upper MIC breakpoint 4. log2convert (optional) - TRUE to convert MIC values to log 2 scale, FALSE if MIC values are already on log 2 scale, default is TRUE 5. Table (optional) - TRUE if the data are in table form (Figure 2), FALSE if not, default is FALSE. An example call to this function is shown below: datastructure = importdata ( filepath ="C:\ Temp \ PTZPAER. csv ", MICBrkptL =4, MICBrkptU =7, log2convert =TRUE, Table = FALSE ) Note the imported data is stored in a variable called datastructure, any name may be used here, however the rest of the documentation assumes the data were stored in the variable datastructure. When the function importdata() is called a graph of the data is produced as shown as in Figure 3 below. Figure 3: Plot of Imported Data Note censored values are shown at the endpoints of the axes. This plot is created using the function basicplot(). The next section provides options to use this function separately. 7

8 3.4 Data Visualization basicplot() takes the following arguments: 1. datastructure - the name of the data saved from the function importdata() 2. MICBrkptL - the log 2 base lower MIC breakpoint 3. MICBrkptU - the log 2 base upper MIC breakpoint 4. flipgraph (optional) - default plots MIC on the y-axis and DIA on the x-axis, 1 to reverse the axes An example call to this function is shown below: basicplot ( datastructure, MICBrkptL =4, MICBrkptU =7, flipgraph =1) Since flipgraph=1, the resulting plot flips the MIC and DIA. This is shown below in Figure 4. Figure 4: Plot of Data with Axes Reversed 8

9 4 Error Rate Bounded (ERB) Methods Three functions are provided to assess DIA breakpoints using the Error Rate Bounded method (ERB). The first function, findbrkptserb() finds the optimal DIA breakpoints based on user-specified discrepancy rates and displays summary information regarding these breakpoints. The second function, ERBGivenDIA(), displays summary information for a given set of DIA breakpoints. The third function, bootstraperb(), assesses the uncertainty inherent in the estimated DIA breakpoints for the ERB method based on this single data set. 9

10 4.1 Estimate ERB DIA Breakpoints The first function, findbrkptserb() finds the optimal DIA breakpoints based on a user-specified set of discrepancy percentages. Two sets of percentages are required, one set for isolates within one of the intermediate range (VM1, M1, m1), and a second set for the isolates outside one of the intermediate range (VM2, M2, m2). These percentages are converted into weights that are used in an overall discrepancy index. The function reports the breakpoints that minimize this index. Details of this index are shown at the bottom of this section. Note the default values for the percentage follows the document M23. The function findbrkptserb() takes the following arguments: 1. datastructure - the name of the data saved from the function importdata() 2. MICBrkptL - the log 2 base lower MIC breakpoint 3. MICBrkptU - the log 2 base upper MIC breakpoint 4. VM1 (optional) - Very Major percentage for within 1 of the intermediate range, default is M1 (optional) - Major percentage for within 1 of the intermediate range, default is m1 (optional) - minor percentage for within 1 of the intermediate range, default is VM2 (optional) - Very Major percentage for outside 1 of the intermediate range, default is 2 8. M2 (optional) - Major percentage for outside 1 of the intermediate range, default is 2 9. m2 (optional) - minor percentage for outside 1 of the intermediate range, default is minwidth (optional) - The minimum width of the DIA breakpoints, default is maxwidth (optional) - The maximum width of the DIA breakpoints, default is 20 An example call to this function is shown below. Here the user-specified percentages for isolates within one of the MIC intermediate range are: very major = 10%, Major = 10%, and minor = 40%. Percentages for isolates outside one of the intermediate range are: Very Major = 2%, Major = 2%, and minor = 5%. Here are two examples of what is meant by within one of the intermediate range: if the intermediate range is 0, isolates between -1 and 1 (inclusive) are considered within one of the intermediate range. For the example data set the intermediate range is 5 and 6, therefore isolates between 4 and 7 (inclusive) are considered within one of the intermediate range. findbrkptserb ( datastructure = datastructure, MICBrkptL =4, MICBrkptU =7) If one wishes to change the percentages an example call may look something like this: findbrkptserb ( datastructure = datastructure, MICBrkptL =4, MICBrkptU =7, VM1 =15, M1 =15, m2 =35, VM2 =5, M2 =5, m2 =8) In order to find the optimal DIA breakpoints for given percentages, we create weights to reflect the seriousness of classification discrepancy representative to the percentages. The algorithm first converts the given set of percentages, %, to weights, w, by: w = max(%) %. For the percentages given above the weights are: VM1=4, M1=4, m1=1, VM2=20, M2=20 and, m2=8. An index is calculated for each possible set of DIA breakpoints: index = w V M1 #V M1 + w M1 #M1 + w m1 #m1 + w V M2 #V M2 + w M2 #M2 + w m2 #m2 where w represents the weight associated with a discrepancy and #* represents the counts for a particular discrepancy. A grid search is performed for all possible DIA breakpoints (within the minwidth and maxwidth range) that minimizes the index. Once this function is called information is displayed in the console regarding the optimal the DIA breakpoints and the corresponding classification percentages. This is shown on the next page (with the default parameters). Figure 5 displays a visual summary of the estimated DIA breakpoints. 10

11 Optimal DIA Breakpoints for ERB: Number of Isolates: 820 Number of Isolates Outside One of Intermediate Range: 598 Number of Isolates Within One of Intermediate Range: 222 Index = Count (%) Range of Isolates Correct Very Major Major Minor Within One 165 (74.32) 0 (0) 0 (0) 57 (25.68) Outside One 595 (99.5) 0 (0) 0 (0) 3 (0.5) The optimal DIA breakpoints given the input percentages were 13 and 21. Figure 5: Results from ERB Method The dashed lines represent the MIC and DIA breakpoints. Colored points indicate discrepancies. 11

12 4.2 ERB Results for Given DIA Breakpoints The second function is is used to display information for a given set of DIA breakpoints. This is done through the function ERBGivenDIA(). This function takes the following arguments: 1. datastructure - the name of the data saved from the function importdata() 2. MICBrkptL - the log 2 base lower MIC breakpoint 3. MICBrkptU - the log 2 base upper MIC breakpoint 4. DIABrkptL - the lower DIA breakpoint 5. DIABrkptU - the upper DIA breakpoint 6. VM1 (optional) - Very Major percentage for within 1 of the intermediate range, default is M1 (optional) - Major percentage for within 1 of the intermediate range, default is m1 (optional) - minor percentage for within 1 of the intermediate range, default is VM2 (optional) - Very Major percentage for outside 1 of the intermediate range, default is M2 (optional) - Major percentage for outside 1 of the intermediate range, default is m2 (optional) - minor percentage for outside 1 of the intermediate range, default is flipgraph (optional) - default plots MIC on the y-axis and DIA on the x-axis, 1 to reverse the axes ERBGivenDIA ( datastructure = datastructure, MICBrkptL =4, MICBrkptU =7, DIABrkptL =15, DIABrkptU =20) Classification for DIA Breakpoints for ERB: Number of Isolates: 820 Number of Isolates Outside One of Intermediate Range: 598 Number of Isolates Within One of Intermediate Range: 222 Index = Count (%) Range of Isolates Correct Very Major Major Minor Within One 149 (67.12) 1 (0.45) 0 (0) 72 (32.43) Outside One 598 (100) 0 (0) 0 (0) 0 (0) Figure 6: Results from ERB Method The dashed lines represent the MIC and DIA breakpoints. Colored points indicate misclassification. 12

13 4.3 Assess Uncertainty - ERB The third function is used to assess the uncertainty in the DIA ERB breakpoints by re-simulating the data (statistically known as bootstrapping). This is done through the function bootstraperb(). This function takes the following arguments: 1. datastructure - the name of the data saved from the function importdata() 2. MICBrkptL - the log 2 base lower MIC breakpoint 3. MICBrkptU - the log 2 base upper MIC breakpoint 4. VM1 (optional) - Very Major percentage for within 1 of the intermediate range, default is M1 (optional) - Major percentage for within 1 of the intermediate range, default is m1 (optional) - minor percentage for within 1 of the intermediate range, default is VM2 (optional) - Very Major percentage for outside 1 of the intermediate range, default is 2 8. M2 (optional) - Major percentage for outside 1 of the intermediate range, default is 2 9. m2 (optional) - minor percentage for outside 1 of the intermediate range, default is minwidth (optional) - The minimum width of the DIA breakpoints, default is maxwidth (optional) - The maximum width of the DIA breakpoints, default is boot (optional) - Number of bootstrap samples, default is 5000 bootstraperb ( datastructure = datastructure, MICBrkptL =4, MICBrkptU =7) ======================================================================================================== DIA Breakpoints by Confidence DIABrkptL DIABrkptU Percent Cumulative_Percent Likely Breakpoints (95% Confidence) DIABrkptL: DIABrkptU: Out of the 5,000 bootstrap samples, 63.98% of the samples had DIA breakpoints of 13 and 21. Given the DIA breakpoints that make up the top 95% of selected breakpoints. We estimate the lower DIA breakpoint to be 12, 13, 14, or 15 and the upper DIA breakpoint to be 20, 21, or

14 5 Model Estimation Instead of the ERB method, a model-based approach has been shown to be a more precise estimation of the DIA breakpoints (Craig 2000). We provide DIA estimation using two types of models. The first is a four parameter logistic model. The second is a nonparametric spline model. 14

15 5.1 Logistic The function logisticfit() fits a four-parameter logistic model to the data to estimate DIA breakpoints. This function takes the following arguments: 1. datastructure - the name of the data saved from the function importdata() 2. MICBrkptL - the log 2 base lower MIC breakpoint 3. MICBrkptU - the log 2 base upper MIC breakpoint 4. minwidth (optional) - The minimum width of the DIA breakpoints, default is 4 5. maxwidth (optional) - The maximum width of the DIA breakpoints, default is flipgraph (optional) - default plots MIC on the y-axis and DIA on the x-axis, 1 to reverse the axes An example call to this function and resulting output are shown below: logisticdata = logisticfit ( datastructure, MICBrkptL =4, MICBrkptU =7, minwidth =4, maxwidth =20, flipgraph =0) Fitting Model ======================================================================================================== Computing Breakpoints ======================================================================================================== DIA Breakpoints by Probability DIABrkptL DIABrkptU Percent Cumulative_Percent Likely Breakpoints (95% Probability) DIABrkptL: DIABrkptU: 21 Figure 7: Logistic Fit 15

16 Given the results, we are most confident in DIA breakpoints 12 and 21 or breakpoints 13 and 21. Note this function will take several minutes to run. 16

17 5.2 Spline The function splinefit() fits a spline model to the data to estimate DIA breakpoints. This function takes the following arguments: 1. datastructure - the name of the data saved from the function importdata() 2. MICBrkptL - the log 2 base lower MIC breakpoint 3. MICBrkptU - the log 2 base upper MIC breakpoint 4. minwidth (optional) - The minimum width of the DIA breakpoints, default is 4 5. maxwidth (optional) - The maximum width of the DIA breakpoints, default is flipgraph (optional) - default plots MIC on the y-axis and DIA on the x-axis, 1 to reverse the axes An example call to this function and resulting output are shown below: splinedata = splinefit ( datastructure, MICBrkptL =4, MICBrkptU =7, minwidth =4, maxwidth =20, flipgraph =0) Fitting Model ======================================================================================================== Computing Breakpoints ======================================================================================================== DIA Breakpoints by Probability DIABrkptL DIABrkptU Percent Cumulative_Percent Likely Breakpoints (95% Probability) DIABrkptL: 12 DIABrkptU: 21 > Figure 8: Spline Fit Given the results, we are most confident in the breakpoints 12 and 21. Note this function will take several minutes to run. 17

18 6 Additional Tools Additional functions provide more information from either the logistic model or spline model. The function comparefits() graphically displays the logistic and spline model fits to the data. The function probdiaclass() displays information for the probabilities of correct DIA classification for two sets of DIA breakpoints given the results from either the spline or logistic model. 18

19 6.1 Logistic and Spline Comparison The function comparefits() graphically displays the logistic and spline model fits to the data. The spline model provides a more flexible fit then the logistic model. This function takes the following arguments: 1. logisticdata - the name of the data saved from the function logisticfit() 2. splinedata - the name of the data saved from the function splinefit() 3. MICBrkptL - the log 2 base lower MIC breakpoint 4. MICBrkptU - the log 2 base upper MIC breakpoint 5. flipgraph (optional) - default plots MIC on the y-axis and DIA on the x-axis, 1 to reverse the axes An example call to this function and resulting output are shown below: comparefits ( logisticdata, splinedata, MICBrkptL =4, MICBrkptU =7, flipgraph =0) Figure 9: Comparison of Logistic and Spline Fits When the function completes a graph of the two fits is shown as in Figure 9. 19

20 6.2 Probability of Correct DIA Classification The function probdiaclass() displays information on the probabilities of correct DIA classification for two sets of DIA breakpoints. This function takes the following arguments: 1. data - the name of the data saved from the function logisticfit() or splinefit() 2. MICBrkptL - the log 2 base lower MIC breakpoint 3. MICBrkptU - the log 2 base upper MIC breakpoint 4. DIABrkptL - a set of lower DIA breakpoints (example shown in the call) 5. DIABrkptU - a set upper DIA breakpoints (example shown in the call) Here we compare performance of DIA breakpoints 12 and 21 (mode- based) versus 13 and 21 (ERB). An example call to this function and resulting output are shown below: probdiaclass ( splinedata, MICBrkptL =4, MICBrkptU =7, DIABrkptL =c (12,13), DIABrkptU =c (21,21) ) DIA Breakpoints Set 1: 12, 21 Set 2: 13, 21 Probability of DIA Classification Set 1 Correct Set 2 Correct Weighted by MIC Density Probability of DIA Classification Set 1 Correct Set 2 Correct Figure 10: Probability of DIA Classification Given Two Sets of DIA Breakpoints Figure 10 displays DIA classification probabilities across MIC values. We see the probability of the model-based DIA breakpoints is higher then the ERB DIA breakpoints. 20

21 7 Future Work Ongoing work is being done to speed up the functions logisticfit() and splinefit(). We are also a constructing a GUI interface. We strongly encourage reports of suggestions/bugs. Please contact Glen DePalma at gdepalma@purdue.edu. 21