% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/revisit_dsgn.R
\name{revisit_dsgn}
\alias{revisit_dsgn}
\title{Create a panel revisit design}
\usage{
revisit_dsgn(n_period, panels, begin = 1, skip = 1)
}
\arguments{
\item{n_period}{Number of time periods for the panel design. For example,
number of periods if sampling occurs once per period or number of months if
sampling occurs once per month.}

\item{panels}{List of lists where each list specifies a revisit panel
structure. Each sublist consists of four components: \code{n} - sample size for
each panel in the sublist, \code{pnl_dsgn} - a vector with an even number of
elements specifying the panel revisit schedule in terms of the number of
consecutive time periods sample units will be sampled, followed by number
of consecutive time periods skipped, and then repeated as necessary. \code{pnl_n}
- number of panels in the sublist, and \code{start_option} - option for starting
the \code{revisit_dsgn} (\code{None}, \code{Partial_Begin}, or \code{Partial_End})
which must be the same a \code{pnl_dsgn}. Three basic panel
structures are possible: a) if \code{pnl_dsgn} ends in \code{0}, then the sample units
are visited on all subsequent time periods, b) if \code{pnl_dsgn} ends in \code{NA}, then
panel follows a rotating panel structure, and c) if \code{pnl_dsgn} ends in any
number > \code{0}, then panel follows a serially alternating panel structure. See
details for further information.}

\item{begin}{Numeric name of first sampling occasion, e.g. a specific
period.}

\item{skip}{Number of time periods to skip between planned sampling
periods, e.g., sampling will occur only every 5 periods if \code{skip = 5}.}
}
\value{
A two-dimensional array of sample sizes to be sampled at each
  combination of panel and time period.
}
\description{
Create a revisit design for panels in a survey that specifies the time
periods that members of each panel will be sampled. Three basic panel design
structures may be created: always revisit panel, serially alternating panels,
or rotating panels.
}
\details{
The function creates revisit designs using the concepts in McDonald
  (2003) to specify the revisit pattern across time periods for each panel.
  The panel revisit schedule is specified by a vector. Odd positions in
  vector specify the number of consecutive time periods when panel units are
  sampled. Even positions in vector specify the number of consecutive time
  periods when panel units are not sampled.

  If last even position is a \code{"0"}, then a single panel follows an always
  revisit panel structure.  After satisfying the initial revisit schedule
  specified prior to the \code{"0"}, units in a panel are always visited for rest of
  the time periods. The simplest always revisit panel design is to revisit
  every sample unit on every time period, specified as \code{pnl_dsgn = c(1,0)} or
  using McDonald's notation [1-0].

  If the last even position is \code{NA}, the panels follow a rotating panel
  structure. For example, \code{pnl_dsgn = c(1, NA)} designates that sample units in
  a panel will be visited once and then never again, [1-n] in McDonald's
  notation. \code{pnl_dsgn =c(1, 4, 1, NA)} designates that sample units in a panel
  will be visited once, then not sampled on next four time periods, then
  sampled again once at the next time period and then never sampled again,
  [1-4-1-n] in McDonald/s notation.

  If the last even position is > \code{0}, the panels follow a serially alternating
  panel structure. For example, \code{pnl_dsgn = c(1, 4)} designates that sample
  units in a panel will be visited once, then not sampled during the next
  four time periods, then sampled once and not sampled for next four time
  periods, and that cycle repeated until end of the number of time periods,
  [1-4] in McDonald's notation. \code{pnl_dsgn = c(2, 3, 1, 4)} designates that the
  cycle has sample units in a panel being visited during two consecutive time
  periods, not sampled for three consecutive time periods, sampled for one time
  period and then not sampled on next four time periods, and the cycle is
  repeated until end of the number of time periods, [2-3-1-4] in McDonald's
  notation.

  The number of panels in a single panel design is specified by \code{pnl_n}.  For
  an always revisit panel structure, a single panel is created and \code{pnl_n} is
  ignored. For a rotating panel structure, when \code{pnl_n = NA}, the number of
  panels is equal to n_period. Note that this should only be used when the
  rotating panel structure is the only panel design, i.e., no split panel
  design (see below for split panel details). If \code{pnl_n = m} is specified for a
  rotating panel design, then then number of panels will be \code{m}.  For example,
  \code{pnl_dsgn = c( 1, 4, 1, NA)} and and \code{pnl_n = 5} means that only 5 panels will
  be constructed and the last time period to be sampled will be time period
  10. In McDonald's notation the panel design structure is [(1-4-1-n)^5].  If
  the number of time periods, \code{n_period}, is 20 and no other panel design
  structure is specified, then the last 10 time periods will not be sampled.
  For serially alternating panels, when \code{pnl_n = NA}, the number of panels will
  be the sum of the elements in pan_dsgn (ignoring \code{NA}). If \code{pnl_n} is specified
  as \code{m}, then \code{m} panels will be created.  For example, \code{pnl_dsgn = c(1, 4, 1, 4)}
  and \code{pnl_n = 3}, [(1-4-1-4)^3] in McDonald's notation, will create first three
  panels of the 510 serially alternating panels specified by \code{pnl_dsgn}.

  A serially alternating or rotating panel revisit design may not result in
  the same number of units being sampled during each time period,
  particularly during the initial start up period.  The default is to not
  specify a startup option (\code{"None"}).  Start up option \code{"Partial_Begin"}
  initiates the revisit design at the last time period scheduled for sampling
  in the first panel. For example, a [2-3-1-4] design starts at time period 6
  instead of time period 1 under the Partial_Begin option. For a serially
  alternating panel structure, start up option \code{"Partial_End"} initiates the
  revisit design at the time period that begins the second serially
  alternating pattern. For example, a [2-3-1-4] design starts at time period
  11 instead of time period 1. For a rotating panel structure design, use of
  Partial_End makes the assumption that the number of panels equals the
  number of time periods and adds units to the last "m" panels for time
  periods \code{1} to \code{"m"} as if number of time periods was extended by \code{"m"} where \code{"m"}
  is one less than then the sum of the panel design.  For example, a
  [1-4-1-4-1-n] design would result in \code{m = 10}.  Note that some designs with
  \code{pnl_n} not equal to the number of sample occasions can produce unexpected
  panel designs.  See examples.

  Different types of panel structures can be combined, these are termed split
  panels by many authors, by specifying more than one list for the panels
  parameter.  The total number of panels is the sum of the number of panels
  in each of the panel structures specified by the split panel design.
}
\examples{
# One panel of  60 sample units sampled at every time period: [1-0]
revisit_dsgn(20, panels = list(
  Annual = list(
    n = 60, pnl_dsgn = c(1, 0), pnl.n = NA,
    start_option = "None"
  )
), begin = 1)

# Rotating panels of 60 units sampled once and never again: [1-n].  Number
# of panels equal n_period.
revisit_dsgn(20,
  panels = list(
    R60N = list(n = 60, pnl_dsgn = c(1, NA), pnl_n = NA, start_option = "None")
  ),
  begin = 1
)

# Serially alternating panel with three visits to sample unit then skip
# next two time periods: [3-2]
revisit_dsgn(20, panels = list(
  SA60PE = list(
    n = 20, pnl_dsgn = c(3, 2), pnl_n = NA,
    start_option = "Partial_End"
  )
), begin = 1)

# Split panel of sample units combining above two panel designs: [1-0, 1-n]
revisit_dsgn(n_period = 20, begin = 2017, panels = list(
  Annual = list(
    n = 60, pnl_dsgn = c(1, 0), pnl.n = NA,
    start_option = "None"
  ),
  R60N = list(n = 60, pnl_dsgn = c(1, NA), pnl_n = NA, start_option = "None")
))
}
\references{
McDonald, T. (2003). Review of environmental monitoring methods: survey
  designs. \emph{Environmental Monitoring and Assessment} \bold{85},
  277-292.
}
\seealso{
\describe{
    \item{\code{\link{revisit_bibd}}}{to create a balanced incomplete block
      panel revisit design}
    \item{\code{\link{revisit_rand}}}{to create a revisit design with random
      assignment to panels and time periods}
    \item{\code{\link{pd_summary}}}{ to summarize characteristics of a
      panel revisit design}
  }
}
\author{
Tony Olsen \email{Olsen.Tony@epa.gov}
}
\keyword{survey}
