\HeaderA{complex}{Complex Vectors}{complex}
\aliasA{Arg}{complex}{Arg}
\aliasA{as.complex}{complex}{as.complex}
\aliasA{Conj}{complex}{Conj}
\aliasA{Im}{complex}{Im}
\aliasA{is.complex}{complex}{is.complex}
\aliasA{Mod}{complex}{Mod}
\aliasA{Re}{complex}{Re}
\keyword{complex}{complex}
\begin{Description}\relax
Basic functions which support complex arithmetic in R.
\end{Description}
\begin{Usage}
\begin{verbatim}
complex(length.out = 0, real = numeric(), imaginary = numeric(),
        modulus = 1, argument = 0)
as.complex(x, ...)
is.complex(x)

Re(z)
Im(z)
Mod(z)
Arg(z)
Conj(z)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{length.out}] numeric.  Desired length of the output vector,
inputs being recycled as needed.
\item[\code{real}] numeric vector.
\item[\code{imaginary}] numeric vector.
\item[\code{modulus}] numeric vector.
\item[\code{argument}] numeric vector.
\item[\code{x}] an object, probably of mode \code{complex}.
\item[\code{z}] an object of mode \code{complex}, or one of a class for which
a methods has been defined.
\item[\code{...}] further arguments passed to or from other methods.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
Complex vectors can be created with \code{complex}.  The vector can be
specified either by giving its length, its real and imaginary parts, or
modulus and argument.  (Giving just the length generates a vector of
complex zeroes.)

\code{as.complex} attempts to coerce its argument to be of complex
type: like \code{\LinkA{as.vector}{as.vector}} it strips attributes including
names. All forms of \code{NA} and \code{NaN} are coerced to a complex
\code{NA}, for which both the real and imaginary parts are \code{NA}.

Note that \code{is.complex} and \code{is.numeric} are never both
\code{TRUE}.

The functions \code{Re}, \code{Im}, \code{Mod}, \code{Arg} and
\code{Conj} have their usual interpretation as returning the real
part, imaginary part, modulus, argument and complex conjugate for
complex values.  Modulus and argument are also called the \emph{polar
coordinates}.  If \eqn{z = x + i y}{} with real \eqn{x}{} and \eqn{y}{},
for \eqn{r = \code{Mod}(z) = \sqrt{x^2 + y^2}}{}, and
\eqn{\phi = \code{Arg}(z)}{}, \eqn{x = r*\cos(\phi)}{} and
\eqn{y = r*\sin(\phi)}{}.
They are all generic functions: methods can be defined
for them individually or via the
\code{\LinkA{Complex}{Complex}} group generic.

In addition, the elementary trigonometric, logarithmic and exponential
functions are available for complex values.
\end{Details}
\begin{Section}{S4 methods}
\code{as.complex} is primitive and can have S4 methods set.

\code{Re}, \code{Im}, \code{Mod}, \code{Arg} and \code{Conj}
constitute the S4 group generic
\code{\LinkA{Complex}{Complex}} and so S4 methods can be
set for them individually or via the group generic.
\end{Section}
\begin{References}\relax
Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988)
\emph{The New S Language}.
Wadsworth \& Brooks/Cole.
\end{References}
\begin{Examples}
\begin{ExampleCode}
require(graphics)

0i ^ (-3:3)

matrix(1i^ (-6:5), nrow=4) #- all columns are the same
0 ^ 1i # a complex NaN

## create a complex normal vector
z <- complex(real = stats::rnorm(100), imaginary = stats::rnorm(100))
## or also (less efficiently):
z2 <- 1:2 + 1i*(8:9)

## The Arg(.) is an angle:
zz <- (rep(1:4,len=9) + 1i*(9:1))/10
zz.shift <- complex(modulus = Mod(zz), argument= Arg(zz) + pi)
plot(zz, xlim=c(-1,1), ylim=c(-1,1), col="red", asp = 1,
     main = expression(paste("Rotation by "," ", pi == 180^o)))
abline(h=0,v=0, col="blue", lty=3)
points(zz.shift, col="orange")
\end{ExampleCode}
\end{Examples}

