\name{pb}
\alias{pb}
\alias{pb.list}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{ Function to generate non-regular fractional factorial screening designs }
\description{
  The function generates Plackett-Burman designs and in some cases other screening
  designs in run numbers that are a multiple of 4. These designs are particularly suitable for screening a
  large number of factors, since interactions are not fully aliased with one main effect each
  but partially aliased. (The design in 8 runs is an exception from this rule.)
}
\usage{
pb(nruns, nfactors = nruns - 1, factor.names = if (nfactors <= 50)
     Letters[1:nfactors] else paste("F", 1:nfactors, sep = ""),
     default.levels = c(-1, 1), ncenter=0, center.distribute=NULL,
     boxtyssedal = TRUE, n12.taguchi = FALSE,
     replications = 1, repeat.only = FALSE,
     randomize = TRUE, seed = NULL, oldver = FALSE, ...)

pb.list
}
%- maybe also 'usage' for other objects documented here.
\arguments{
  \item{nruns}{ number of runs, must be a multiple of 4 }
  \item{nfactors}{ number of factors, default is nruns - 1,
   and it is recommended to retain this default.\cr
   It is possible to specify factor names for fewer factors,
   and the remaining columns will be named \code{e1}, \code{e2}, ...
   They are useful for representing error in effects plots
   (so-called dummy factors). }
  \item{factor.names}{ a character vector of factor names (length up to nfactors)
        or a list with \code{nfactors} elements;\cr
        if the list is named, list names represent factor names, otherwise default factor names are used;\cr
        the elements of the list are \cr
        EITHER vectors of length 2 with factor levels for the respective factor\cr
        OR empty strings.
        For each factor with an empty string in factor.names, the levels given in
        \code{default.levels} are used;\cr
       Default factor names are the first elements of the character vector \code{\link[DoE.base:utilities]{Letters}},
       or the factors position numbers preceded by capital F in case of more than 50 factors. }
  \item{default.levels}{ default levels (vector of length 2) for all factors for which no specific levels are given }
  \item{ncenter}{ number of center points; \code{ncenter > 0}
        is permitted, if all factors are quantitative }
  \item{center.distribute}{ the number of positions over which the center points
        are to be distributed ; if NULL (default), center points are
        distributed over end, beginning, and middle (in that order, if there are fewer than three center points)
        for randomized designs, and appended to the end for non-randomized designs.
        for more detail, see function \code{\link{add.center}}, which does the work.
        }
  \item{boxtyssedal}{ logical, relevant only for nruns=16.
               If FALSE, the geometric (=standard) 16 run plan is used.
               If TRUE, the proposal by Box and Tyssedal is used instead, which has the advantage (for screening) of aliasing each interaction with several main effects, like the other Plackett-Burman designs. }
  \item{n12.taguchi}{ logical, relevant only for nruns=12. If TRUE, the 12 run design is given in Taguchi order. }
  \item{replications}{ positive integer number. Default 1 (i.e. each row just once).
       If larger, each design run is executed replication times.
       If \code{repeat.only}, repeated measurements
       are carried out directly in sequence, i.e. no true replication takes place,
       and all the repeat runs are conducted together. It is likely that the error
       variation generated by such a procedure will be too small, so that average values
       should be analyzed for an unreplicated design.

       Otherwise (default), the full experiment is first carried out once, then
       for the second replication and so forth. In case of randomization,
       each such blocks is randomized separately. In this case, replication variance is
       more likely suitable for usage as error variance
       (unless e.g. the same parts are used for replication runs although build
       variation is important). }
  \item{repeat.only}{ logical, relevant only if replications > 1. If TRUE,
        replications of each run are grouped together
       (repeated measurement rather than true replication). The default is
       \code{repeat.only=FALSE}, i.e. the complete experiment
       is conducted in \code{replications} blocks, and each run occurs in each block. }
  \item{randomize}{ logical. If TRUE, the design is randomized. This is the default. }
  \item{seed}{ optional seed for the randomization process \cr
        In R version 3.6.0 and later, the default behavior of function \code{\link{sample}}
        has changed. If you work in a new (i.e., >= 3.6.-0) R version and want to reproduce
        a randomized design from an earlier R version (before 3.6.0),
        you have to change the RNGkind setting by\cr
        \code{RNGkind(sample.kind="Rounding")}\cr
        before running function \code{pb}.\cr
        It is recommended to change the setting back to the new recommended way afterwards:\cr
        \code{RNGkind(sample.kind="default")}\cr
        For an example, see the documentation of the example data set \code{\link[DoE.base]{VSGFS}}.
        }
  \item{oldver}{ logical. If \code{TRUE}, the column ordering from
       package versions 1.0-5 to 1.2.10 is used. This affects designs in
       40, 52, 56, 64, 76, 92, 96 and 100 runs.
       Usually, option \code{oldver} should not be set to is useful for reproducing an
       old design, or for making a design in 40, 56, 64, 88 or 96 runs with
       exactly half the number of factors resolution IV.
         }
  \item{\dots}{ currently not used }
}
\details{
  \code{pb} stands for Plackett-Burman. Plackett-Burman designs (Plackett and Burman 1946) are generally
  used for screening many variables in relatively few runs, when interest is in
  main effects only, at least initially. Different from the regular
  fractional factorial designs created by function \code{\link{FrF2}}, they
  do not perfectly confound interaction terms with main effects but distribute
  interaction effects over several main effects. The designs with number of runs
  a power of 2 are an exception to this rule: they are just the resolution III
  regular fractional factorial designs and are as such not very suitable for
  screening because of a high risk of very biased estimates for the main effects
  of the factors. Where possible, these are therefore replaced by different designs (cf. below).

  For most run numbers, function \code{pb} uses Plackett-Burman designs,
  and simply fills columns from left to right.
  The generating rows for these designs can be found in the list \code{pb.list}
  (a 0 entry indicates that the design is constructed by a different method, e.g. doubling).

  For 12 runs, the isomorphic design by Taguchi can be requested.
  For 16 runs, the default is to use the designs suggested by Box and Tyssedal (2001),
  which up to 14 factors do not suffer from perfect aliasing.
  For 32 runs, a cyclic design with generating row given in Samset and Tyssedal (1999) is used.
  For 64 runs, the 32 run design is doubled.
  For 92 runs, a design is constructed according to the Williamson construction with matrices A, B, C and D from Hedayat and Stufken (1999), p. 160.

  Designs up to 100~runs are covered.

  Usage of the 8 run design for more than 4 factors is discouraged,
  as it completely aliases main effects with individual two-factor interactions.
  It is recommended to use at least the 12 run design instead for screening more than 4 factors.
}
\value{
  Value is a data frame of S3 class \code{\link[DoE.base:class-design]{design}}
  and has attached attributes that can be accessed
  by functions \code{\link[DoE.base:class-design-methods]{desnum}},
  \code{\link[DoE.base:class-design-methods]{run.order}} and
  \code{\link[DoE.base:class-design-methods]{design.info}}.

  The data frame itself contains the design with levels coded as requested.
  If no center points have been requested, the design columns are factors with
  contrasts \code{-1} and \code{+1} (cf. also \code{\link[DoE.base]{contr.FrF2}}); in case
  of center points, the design columns are numeric.

  The following attributes are attached to it:
  \item{desnum }{Design matrix in -1/1 coding}
  \item{run.order }{three column data frame, first column contains the run number in
       standard order, second column the run number as randomized, third column the
       run number with replication number as postfix;
       useful for switching back and forth between actual and standard run
       number}
  \item{design.info }{list with entries
  \describe{
        \item{type }{ character string \dQuote{pb}, except for 8~runs with up to
           4~factors, for which a type \dQuote{FrF2} design is output}
        \item{nruns }{ number of runs (replications are not counted) }
        \item{nfactors }{ number of factors}
        \item{factor.names }{ list named with (treatment) factor names and containing as
           entries vectors of length two each with coded factor levels }
        \item{ndummies }{ number of dummy factors for error }
       \item{replication }{ option setting in call to \code{pb} }
       \item{repeat.only }{ option setting in call to \code{pb} }
       \item{randomize }{ option setting in call to \code{pb} }
       \item{seed }{ option setting in call to \code{pb} }
       \item{creator }{ call to function pb
          (or stored menu settings, if the function has been called via the R commander plugin
          \pkg{RcmdrPlugin.DoE}) }
       }
       }
}
\section{Warning}{With version 1.0-5 of package \pkg{FrF2},
   design generation for the designs based on doubling has changed (internal function
   \code{double.des}). This affected designs for 40,56,64,88,96 runs.
   With version 1.3 of package \pkg{FrF2}, this and further behaviors (52, 76) has changed
   again, in the interest of improving generalized resolution of desigs produced by function \code{pb}.

   For the affected run sizes, package versions from 1.0-5 onwards
   cannot exactly reproduce pb designs that have been created with a version before
   1.0-5. Package versions from 1.3 onwards reproduce the behavior of versions 1.0-5 to 1.2-10
   through option \code{oldver}.}

\references{
  Box, G.E.P. and Tyssedal, J. (2001) Sixteen Run Designs of High Projectivity for Factor Screening.
      \emph{Communications in Statistics - Simulation and Computation} \bold{30}, 217-228.

  Hedayat, A.S., Sloane, N.J.A. and Stufken, J. (1999) \emph{Orthogonal Arrays: Theory and Applications}, Springer, New York.

    Groemping, U. (2014). {R} Package {FrF2} for Creating and Analyzing Fractional
    Factorial 2-Level Designs. \emph{Journal of Statistical Software}, \bold{56},
    Issue 1, 1-56. \url{https://www.jstatsoft.org/v56/i01/}.

  Mee, R. (2009). \emph{A Comprehensive Guide to Factorial Two-Level Experimentation}.
  New York: Springer.

  Plackett, R.L.; Burman, J.P. (1946) The design of optimum multifactorial experiments. \emph{Biometrika} \bold{33}, 305-325.

  Samset, O.; Tyssedal, J. (1999) Two-level designs with good projection properties. \emph{Technical Report 12,
  Department of Mathematical Sciences, The Norwegian University of Science and Technology, Norway}.

  Williamson, J. (1946) Determinants whose elements are 0 and 1. \emph{American Mathematical Monthly} \bold{53}, 427-434.
}
\section{Warning}{
   Since R version 3.6.0, the behavior of function \code{\link{sample}} has changed
   (correction of a biased previous behavior that should not be relevant for the randomization of designs).
   For reproducing a randomized design that was produced with an earlier R version,
   please follow the steps described with the argument \code{seed}.
}
\author{ Ulrike Groemping }

\seealso{ See also \code{\link{FrF2}} for regular fractional factorial designs,
    \code{\link[DoE.base]{generalized.word.length}} for functions \code{\link[DoE.base:generalized.word.length]{length3}}
    and \code{\link[DoE.base:generalized.word.length]{length4}} used in examples}
\examples{
   pb(12,randomize=FALSE)
   pb(12,randomize=FALSE,n12.taguchi=TRUE)
   pb(20,seed=29869)
   pb(16,factor.names=list(A="",B="",C="",D=c("min","max"),
          E="",F="",G="",H="",J=c("new","old")))
   pb(8,default.levels=c("current","new"))
   test <- pb(40) ## design created by doubling the 20 run design
   pb(12, ncenter=6) ## 6 center points with default placement

   \dontrun{
   ## note: designs in 40, 56, 64, 88, and 96 runs are resolution IV,
   ## if the number of factors is up to nruns/2 - 1, e.g.:
   plan1 <- pb(40, 19)
   length3(plan1)  ## 0 generalized words of length 3
   length4(plan1)  ## 228 generalized words of length 4
   ## they can be made resolution IV by oldver=TRUE for
   ## nfactors=nruns/2, e.g.:
   plan2 <- pb(40, 20)
   plan3 <- pb(40, 20, oldver=TRUE)
   length3(plan2)  ## 9 generalized words of length 3
   length3(plan3)  ## 0 generalized words of length 3
   length4(plan3)  ## 285 generalized words of length 4

   ## note: designs in 52, 76, and 100 runs are almost resolution IV,
   ## if the number of factors is up to nruns/2 - 1, e.g.:
   plan4 <- pb(52, 25)
   GR(plan4)       ## generalized resolution 3.92

   ## note: versions >1.3 avoid complete and heavy aliasing of triples of factors
   ## for up to nruns-2 factors for 40, 52, 56, 64, 76, 88, 92 and 96 runs
   ## (the same for 100 runs, which were not implemented before version 1.3)
   plan5 <- pb(40, 38)
   plan6 <- pb(40, 38, oldver=TRUE)
   GR(plan5)       ## generalized resolution 3.4
   GR(plan6)       ## generalized resolution 3
   plan7 <- pb(52, 50)
   plan8 <- pb(52, 50, oldver=TRUE)
   GR(plan7)       ## generalized resolution 3.62
   GR(plan8)       ## generalized resolution 3.15
   }
   }
% Add one or more standard keywords, see file 'KEYWORDS' in the
% R documentation directory.
\keyword{ array }
\keyword{ design }% __ONLY ONE__ keyword per line
