% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/PM_data.R
\name{PMcheck}
\alias{PMcheck}
\title{Check Pmetrics Inputs for Errors}
\usage{
PMcheck(data, path = ".", fix = FALSE, quiet = FALSE)
}
\arguments{
\item{data}{The name of a Pmetrics .csv matrix file in the current working directory,
the full path to one not in the current working directory, or a data.frame containing
the output of a previous \link{PMreadMatrix} command.}

\item{path}{The path of the data if originally a file}

\item{fix}{Boolean operator; if \code{TRUE}, Pmetrics will attempt to fix errors in the data file.
Default is \code{FALSE}.}

\item{quiet}{Boolean operator to suppress printed output.  Default is false.}
}
\value{
If \code{fix=TRUE}, then \link{PMcheck} returns
\itemize{
\item The original data if no errors are found, or
\item A PMmatrix data object which has been
cleaned of errors as much as possible, displaying a report on the console.
}

If \code{fix=FALSE}, then \link{PMcheck} creates a file in the working directory called "errors.xlsx".
This file can be opened by Microsoft Excel or any other program that is capable of reading .xlsx files.  This file
contains highlighted areas that are erroneous, with clarifying comments.  You can correct the errors in the file
and then re-save as a .csv file.

When \code{fix=FALSE}, the function also returns a list of objects of class \emph{PMerr}.  Each object is itself a list whose
first object (\verb{$msg}) is a character vector with "OK" plus a brief description if there is no error, or the error.
The second object (\verb{$results}) is a vector of the row numbers that contain that error.
\itemize{
\item colorder The first 14 columns must be named id, evid, time, dur, dose, addl, ii, input, out, outeq, c0, c1, c2, and c3 in that order.
\item maxcharCol All column names should be less than or equal to 11 characters.
\item maxcharID All id values should be less than or equal to 11 characters.
\item missEVID Ensure that all rows have an EVID value.
\item missTIME Ensure that all rows have a TIME value.
\item doseDur Make sure all dose records are complete, i.e. contain a duration.
\item doseDose Make sure all dose records are complete, i.e. contain a dose.
\item doseInput Make sure all dose records are complete, i.e. contain an input number.
\item obsOut Make sure all observation records are complete, i.e. contain an output.
\item obsOuteq Make sure all observation records are complete, i.e. contain and outeq number.
\item T0 Make sure each subject's first time=0.
\item covT0 Make sure that there is an non-missing entry for each covariate at time=0 for each subject.
\item timeOrder Ensure that all times within a subject ID are monotonically increasing.
\item contigID Ensure that all subject IDs are contiguous.
\item nonNum Ensure that all columns except ID are numeric.
\item noObs Ensure that all subjects have at least one observation, which could be missing, i.e. -99.
\item mal_NA Ensure that all NA values are ".", not ". ", " .", "..", or other malformations.
}
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#superseded}{\figure{lifecycle-superseded.svg}{options: alt='[Superseded]'}}}{\strong{[Superseded]}}

This function is largely superseded as it is called automatically when
data are initialized as a \link{PM_data} object. It can still be called
independently of this route and will check for data errors.
}
\details{
It  will check the data for errors
which would cause the analysis to fail.  Note that as of
Pmetrics Version 2, this function is called automatically when a new \link{PM_data}
object is created, and users generally no longer need to call the function directly.
In \code{PM_data$new()}, the data object is first standardized to contain all required columns,
since only "ID", "TIME", "DOSE" and "OUT" are required at minimum, and then checked with PMcheck.

If calling PMcheck directly, either a filename or a Pmetrics data object in memory are accepted as \code{data}.
Because there is no standardization with direct calls, in this case the format of the .csv matrix file is fairly rigid.
It must have the following features.  Text is case-sensitive.
\itemize{
\item A header in row 1 with the appropriate version, currently "POPDATA DEC_11"
\itemize{
\item Column headers in row 2.  These headers are: #ID, EVID, TIME, DUR, DOSE, ADDL, II, INPUT, OUT, CENS, OUTEQ,
C0, C1, C2, C3.
}
\item No cell should be empty.  It should either contain a value or "." as a placeholder.
\itemize{
\item Columns after C3 are interpreted as covariates.
\item All subject records must begin with TIME=0.
}
\item All dose events (EVID=1) must have entries in ID, EVID, TIME, DUR, DOSE and INPUT.  ADDL and II are optional, but if ADDL is not 0 or
missing, then II is mandatory.
\item All observation events (EVID=0) must have entries in ID, EVID, TIME, OUT, OUTEQ.
If an observation is missing, use -99; otherwise use a "." as a placeholder
in cells that are not required (e.g. INPUT for an observation event).
\item If covariates are present in the data, there must be an entry for every covariate at time 0 for each subject.
\item All covariates must be numeric.
\item All times within a subject ID must be monotonically increasing.
\item All subject IDs must be contiguous.
\item All rows must have EVID and TIME values.
\item All columns must be numeric except ID which may be alpha-numeric.
\item All subjects must have at least one observation, which could be missing, i.e. -99.
\item Cells which are not needed (e.g. dose on an observation event, EVID=0), should contain ".".
}

To use this function, see the example below.

After running PMcheck and looking at the errors in the \emph{errors.xlsx} file, you can fix the
errors manually directly in the \emph{errors.xlsx} file and resave it as a .csv file.
Alternatively, you could then try to fix the problem(s) with \code{mdata2 <- PMcheck(mdata,fix=T)}.  Note that we are now returning
a PMmatrix data object called mdata2 (hopefully cleaned of errors) rather than the PMerr object returned when \code{fix=FALSE}.
Pmetrics handles each of the errors in the following ways.
\itemize{
\item If the columns are simply out of order, they will be reordered.  If some are missing, the fix must
be done by the user, i.e. manually.
\item All id and covariate values are truncated to 11 characters.
\item Missing observations are set to -99 (not ".").
\item Incomplete dose records are flagged for the user to fix manually.
\item Incomplete observation records are flagged for the user to fix manually.
\item Subjects without an EVID=1 as first event are flagged for the user to fix manually.
\item Subjects with TIME != 0 as first event have dummy dose=0 events inserted at time 0.
\item Subjects with a missing covariate at time 0 are flagged for the user to fix manually.
\item Non-numeric covariates are converted to numeric (via \code{\link[=factor]{factor()}}).
\item Non-ordered times are sorted within a subject if there are no EVID=4 events; otherwise the
user must fix manually.
\item Non-contiguous subject ID rows are combined and sorted if there are no EVID=4 events; otherwise the
user must fix manually.
\item Rows missing an EVID are assigned a value of 0 if DOSE is  missing, 1 otherwise.
\item Rows missing a TIME value are flagged for the user to fix manually.
\item Cells with malformed NA values are attempted to be fixed.
\item Columns that are non-numeric which must be numeric are flagged for the user to fix manually.
These are all columns except ID.
Covariate columns are fixed separately (see above).
\item Dose events with censoring will be set to uncensored, with a warning to the user.
}
}
\examples{
\dontrun{
err <- PMcheck(badData)
# look at the errors.xlsx file in the working directory
# try to automatically fix what can be fixed
goodData <- PMcheck(badCSV, fix = T)
PMcheck(goodData)
# you have to fix manually problems which require data entry
}
}
\seealso{
\link{PMwriteMatrix}, \link{PMreadMatrix}
}
\author{
Michael Neely and Patrick Nolain
}
