% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/evidPush.R
\name{evid_}
\alias{evid_}
\title{Push a future dose or observation event from within an rxode2 model}
\usage{
evid_(time, evid, amt, cmt = 1, rate = 0, ii = 0, addl = 0, ss = 0)
}
\arguments{
\item{time}{Numeric. The time at which the event should occur.  Must
be greater than the current model time \code{t}; events in the past are
silently counted and a warning is issued after solving.}

\item{evid}{Integer event ID.  Follows NONMEM/rxode2 conventions:
\describe{
\item{\code{0}}{Observation (adds an output row, no dose).}
\item{\code{1}}{Dose (bolus or infusion depending on \code{rate}).}
\item{\code{2}}{Other type observation (passed through).}
\item{\code{3}}{Reset all compartments.}
\item{\code{4}}{Reset then dose.}
\item{\code{5}}{Replace compartment amount.}
\item{\code{6}}{Multiply compartment amount.}
\item{\code{7}}{Phantom/transit dose.}
\item{\verb{>= 100}}{Classic rxode2 internal evid; passed through verbatim.}
}}

\item{amt}{Numeric dose amount (for dose events) or \code{0} for
observations.  When \code{rate > 0} this is interpreted as the total
infusion amount and the infusion duration is \code{amt / rate}.}

\item{cmt}{Integer compartment number (1-based) to which the dose is
applied.  Default is 1}

\item{rate}{Numeric infusion rate.
\describe{
\item{\code{0}}{Bolus dose (default).}
\item{\verb{> 0}}{Fixed infusion rate; duration = \code{amt / rate}.}
\item{\code{-1}}{Rate defined by the model (\verb{rate_<cmt>} variable).}
\item{\code{-2}}{Duration defined by the model (\verb{dur_<cmt>} variable).}
}}

\item{ii}{Numeric inter-dose interval.  Used together with \code{addl} to
schedule repeat doses at \code{time}, \code{time + ii}, \code{time + 2*ii}, ...,
\code{time + addl*ii}.  Also required when \code{ss > 0}. Default 0}

\item{addl}{Integer number of \emph{additional} doses beyond the first.
The total number of doses pushed is \code{addl + 1}, spaced \code{ii} apart.
Each dose is pushed as a standalone event (not as a periodic
schedule in the event table).}

\item{ss}{Integer steady-state flag applied to the \emph{first} dose only
(\code{addl} repetitions always use \code{ss = 0}).
\describe{
\item{\code{0}}{No steady-state (default).}
\item{\code{1}}{Steady-state additive: add SS solution to current state.}
\item{\code{2}}{Steady-state replace: replace current state with SS solution.}
}}
}
\value{
This function is only meaningful inside an rxode2 model; it
returns \code{NULL} invisibly if called from R directly (after signaling
an error).
}
\description{
\code{evid_()} is a model-only function that schedules a future dosing or
observation event during ODE solving.  It is evaluated at each output
time point and inserts the requested event into the individual's event
timeline for future processing.

This function has no meaning outside an rxode2 model block and will
throw an error if called directly from R.
}
\details{
\subsection{Behavior inside a model}{

\code{evid_()} is evaluated at every output time point (when the solver is
exactly at a scheduled event time).  The pushed event is inserted into
the individual's event timeline and the solver visits it at the
specified future time.

The number of events that may be pushed per individual is limited by
the \code{maxExtra} argument of \code{\link[=rxSolve]{rxSolve()}}.  When \code{maxExtra = 0}
(the default) there is no limit.  Exceeding the limit causes an
error.

Past-time pushes (where \code{time <= t}) are silently ignored and counted;
a warning is issued after solving.
}

\subsection{Relationship to NONMEM event columns}{

The argument order and names mirror the standard NONMEM dataset
columns: \code{TIME}, \code{EVID}, \code{AMT}, \code{CMT}, \code{RATE}, \code{II}, \code{ADDL}, \code{SS}.
}
}
\examples{
\donttest{
# Push a single bolus of 50 mg to compartment 1 at t + 12
m <- rxode2({
  d/dt(depot)   <- -ka * depot
  d/dt(central) <- ka * depot - cl / vd * central
  cp <- central / vd
  if (t < 24) {
    evid_(t + 12, 1, 50, 1, 0, 0, 0, 0)
  }
})

# Push three boluses (addl = 2) at t+6, t+18, t+30 (ii = 12)
m2 <- rxode2({
  d/dt(depot)   <- -ka * depot
  d/dt(central) <- ka * depot - cl / vd * central
  cp <- central / vd
  if (t < 1) {
    evid_(t + 6, 1, 50, 1, 0, 12, 2, 0)
  }
})
}

}
\seealso{
\code{\link[=rxSolve]{rxSolve()}} for the \code{maxExtra} control argument.  Other
more convenient ways to interact with adaptive observations and
events include \code{\link[=bolus]{bolus()}} \code{\link[=infuse]{infuse()}}, \code{\link[=infuseDur]{infuseDur()}},
\code{\link[=reset]{reset()}}.
}
