NONMEM_plot: Plots data from NONMEM files
In jgrevel/BAST1-R-Library: BAST R function library.

Description Usage Arguments Details Value Note 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 can 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.

NONMEM_plot(data, save_path, ID_col = "ID", ind_var_col = "TIME",
  DV_col = "DV", x_unit = "hours", y_unit = "ug/L", dose_marker = TRUE,
  panel = TRUE, keep_doses_after_last_obs = TRUE, calc_dose = TRUE,
  calc_occ = TRUE, calc_tad = TRUE, occ = FALSE, LLOQFLAG_col = FALSE,
  LLOQ_col = FALSE, title_label_col = c("DOSE", "OCC"),
  colour_shading = 0, colour_range = c("mistyrose", "pink", "red", "red4",
  "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 = FALSE, ...)

`data`	data frame containing data in NONMEM format.
`save_path`	path to the folder where plots will be saved.
`ID_col`	name of the column in NONMEM file which contains patient identifiers.
`ind_var_col`	name of the column in NONMEM file which contains the variable for use as the x-axis in plots, usually 'TIME' or 'TAD'.
`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'.
`x_unit`	label for units on x-axis.
`y_unit`	label for units on y-axis.
`dose_marker`	logical. If TRUE, 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 colouring of different dose sizes.
`panel`	logical. If FALSE, generate single plots for each ID, or if TRUE, panels of 8 plots.
`keep_doses_after_last_obs`	logical. If TRUE, the x-axis of each plot will be scaled such that doses after the last observation are visualised. If FALSE, the x-axis will only reach as far as the last observation.
`calc_dose`	logical. If TRUE, add DOSE column (showing size of most recent non-zero AMT) to the data. Required if DOSE is not already in the data file and you set either dose_marker=TRUE or DV_col=DV_DOSE_CORRECTED.
`calc_occ`	logical. If TRUE, add OCC column to the data. 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.
`calc_tad`	logical. If TRUE, add TAD column to the data. Required if TAD is not already in the data file and ind_var_col='TAD'.
`occ`	numeric. 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.
`LLOQFLAG_col`	name of the LLOQFLAG column in NONMEM data 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.
`LLOQ_col`	name of the LLOQ column in NONMEM data 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.
`title_label_col`	vector of character strings, containing names of the columns in NONMEM data 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.
`colour_shading`	numeric. 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.
`colour_range`	vector of colour names. 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.
`plot_IPRED`	logical. If 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.
`all_same_scale_x`	logical. If TRUE, x-axis range should be equal for all individuals. If FALSE, x-axis range should be different for each individual.
`all_same_scale_y`	logical. If TRUE, y-axis range should be equal for all individuals. If FALSE, y-axis range should be different for each individual.
`file_text`	character. Free text that will be added to each filename. Useful when creating lots of different visualisations from the same data.
`ind_var_conversion`	numeric. 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.
`extend_dose_marker`	logical. If 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 time to a dose actually lie before or after the dosing event.
`backround_data`	logical. If TRUE, background data (data from all other individuals) are added to the plot.

User should consult the latest Best Practice guide at

\\BAST_SERVER\BAST_Shared_Files\QA Documents\BAST Computer Systems Validation\final_documents\Procedure_for_visualizing_NONMEM_files\

for more in-depth documentation on the use of this function.

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.

Only records with EVID=0 are plotted.

Function will accept standard arguments for the default R plot function, such as log='y'.

Columns 'ID', 'EVID', 'DV' and 'TIME' are expected to be present. Columns 'TAD', 'AMT', DOSE' and 'OCC' (occasion) are optional.

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.

Katarzyna Nurzynska

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