NONMEM_plot_bw: NONMEM_visualising_tool
In jgrevel/BAST1-R-Library: BAST R function library.

Description Usage Arguments Details Value Author(s)

The tool provides a good overview of the available data for each patient and helps to identify severe outliers or programming errors. This can be useful when doing QC work upon building a new NONMEM data file. The tool was created to visualise any NONMEM data file that contains continuous type DV. The observations could be PK or PD type data, and dosing records don't necessarily have to be present. To identify potential outliers, observations for each individual can be superimposed on observations for all patients. The tool will plot observations and dosing records vs time, saving one plot for each individual or a panel of eight plots for subject-rich data files.

NONMEM_plot_bw(data, save_path, ID_col = "ID", ind_var_col = "TIME",
  DV_col = "DV", x_label = "", y_label = "", dose_marker = TRUE,
  panel = TRUE, keep_doses_after_last_obs = FALSE, calc_dose = FALSE,
  calc_occ = FALSE, calc_tad = FALSE, occ = FALSE, LLOQFLAG_col = FALSE,
  LLOQ_col = FALSE, title_label_col = "", colour_shading = 0,
  colour_range = c("gray90", "gray75", "gray60", "black"),
  background_data = FALSE, plot_IPRED = FALSE, all_same_scale_x = FALSE,
  all_same_scale_y = TRUE, file_text = "", ind_var_conversion = 1,
  extend_dose_marker = TRUE, ...)

`data`	name of the data frame containing the NONMEM-formatted data
`save_path`	path to the folder where plots will be saved
`ID_col`	Name of the column in NONMEM file which contains patient identifiers. Defaultis "ID".
`ind_var_col`	Name of the column in NONMEM file which contains the variable for use as the x-axis in plots. 'TAD' is the other main alternative for ind_var_col. Default is "TIME"
`DV_col`	Name of the column in NONMEM file which contains observations for plotting on y-axis. If dose corrected DV is to be used then set DV_col='DV_DOSE_CORRECTED'. Default is "DV".
`x_label`	Label for x-axis. Default is ""
`y_label`	Label for y-axis can be character or expression e.g. expression('Concentration (' * mu * 'g/L)') (see plotmath). Defalts to ""
`dose_marker`	Add dose marker at the top of the plot. If the AMT or DOSE column is present in the data file this marker will be coloured according to the dose size. A separate plot Legend.png will be generated with a key to colourin g of different dose sizes. Default is TRUE.
`panel`	Generate single plots for each ID when the argument is set to FALSE, or panels of 8 plots when the argument is set to TRUE. Default is TRUE
`keep_doses_after_last_obs`	When set to TRUE the x-axis of each plot will be scaled such that doses after the last observation are visualised. When set to FALSE the x-xis will only reach as far as the last observation. Default is FALSE.
`calc_dose`	Add DOSE column (showing size of most recent non-zero AMT) to the data when the argument is TRUE. Required if DOSE is not already in the data file and you set either dose_marker=TRUE or DV_col=DV_DOSE_CORRECTED. Default is FALSE.
`calc_occ`	Add OCC column if the argument is equal to TRUE. Required if OCC is not already in the data file and you want to plot data from different occasions using occ=1 or occ=2 etc. Default is FALSE.
`calc_tad`	Add TAD column if the argument is equal to TRUE. Required if TAD is not already in the data file and ind_var_col='TAD'. Default is FALSE.
`occ`	Plot data for a particular occasion. Default is FALSE which leads to plots including data from all occasions. If the argument is equal to e.g. 2 only data from second occasion is plotted. Default is FALSE.
`LLOQFLAG_col`	Name of the column in NONMEM file which indicates if an observation is BLQ (1) or has been quantified (0). BLQ observations are plotted as green circles. Set to FALSE if a LLOQFLAG column is not in the data file. Default is FALSE.
`LLOQ_col`	Name of the column in NONMEM file which contains the values of the limit of quantification. If the argument is a number (rather than text such as 'LLOQ') then the lower limit of quantification for every sample will be set to that number, and the BLQ samples will be plotted as green circles at that concentration. Default is FALSE.
`title_label_col`	Names of the columns in NONMEM file which will be used for supplying some additional information to plot titles. If title_label_col=” then no additional labels are added. For multiple dose studies the dose shown in the title will correspond to the selected occasion. If all occasions are plotted the value of the dose in the title will correspond to the first occasion. Default is "".
`colour_shading`	Sets the relationship between the dose amounts and the colour shades. Important when the range of doses is wide. Try experimenting with different values to see effect on Legend.png and the dose markers. It should be a positive number. If set to 0 then it will instead be calculated as sqrt(max(AMT)/min(AMT))/2. Default is 0.
`colour_range`	Sets the colour transitions for dose markers and background data. A minimum of 2 colours is required and plot colours will be interpolated between the members of colour_range, depending on the size of DOSE. Default isc('grey90','grey75','grey60','black')
`background_data`	If TRUE background data (data from all other individuals) are added to the plot. Default is FALSE.
`plot_IPRED`	If set to TRUE then IPRED data are added to the plots. Obviously the data file will have to be a NONMEM $TABLE file such that IPRED data are available. Default is FALSE.
`all_same_scale_x`	Determines if x-axis range should be same for all individuals (TRUE) or different for each individual (FALSE). Default is FALSE.
`all_same_scale_y`	Determines if y-axis range should be the same for all individuals (TRUE) or different for each individual (FALSE). Default is TRUE.
`file_text`	Free text that will be added to each filename. Useful when creating lots of different visualisations from the same data. Default is "".
`ind_var_conversion`	Factor to be used for converting the data in the x-axis. For example set to 1/24 to convert TIME from hours to days. Default is 1.
`extend_dose_marker`	When set to TRUE the dose markers will be extended as grey dashed lines from top to bottom of each plot. This can help determine if observations close in to time to a dose actually lie before or after the dosing event. Default is TRUE.
`...`	additional arguments passed to plot.

Only records with EVID=0 are plotted Function will accept standard arguments for the default R plot command, such as log='y' Columns 'ID', 'EVID', 'DV' and 'TIME' are expected to be present. Columns 'TAD', 'AMT', DOSE' and 'OCC' (occasion) are optional. 'TAD', 'DOSE' and 'OCC' can be added to the data file before plotting by using the following arguments: calc_tad=TRUE, calc_dose=TRUE, calc_occ=TRUE. It is assumed that DV and IPRED are on a linear scale. If not, then the user should correct this before using the NONMEM_plot function Before running the function, the user is expected to filter data file to records of interest e.g. placebo or biomarker type, through filtering based on columns such as CMT or DVID

The tool will plot observations and dosing records vs time, saving one plot for each individual or a panel of eight plots for subject-rich data files.

Rupert Austin

jgrevel/BAST1-R-Library documentation built on May 21, 2019, 10:11 a.m.