1\name{cosinor}
2\alias{cosinor}
3\alias{circadian.mean}
4\alias{circadian.cor}
5\alias{circadian.linear.cor}
6\title{Functions for analysis of circadian or diurnal data}
7\description{Circadian data are periodic with a phase of 24 hours. These functions  find the best fitting phase angle (cosinor), the circular mean,  circular correlation with circadian data, and the linear by circular correlation}
8
9\usage{
10cosinor(angle,x=NULL,code=NULL,period=24,plot=FALSE,opti=FALSE)
11circadian.mean(angle, hours=TRUE)
12circadian.cor(angle, hours=TRUE)
13circadian.linear.cor(angle,x,hours=TRUE)
14}
15%- maybe also 'usage' for other objects documented here.
16\arguments{
17  \item{angle}{A data frame or matrix of observed values with the time of day as the first value (unless specified in code) angle can be specified either as hours or as radians)}
18  \item{code}{A subject identification variable}
19  \item{period}{Although time of day is assumed to have a 24 hour rhythm, other rhythms may be fit. }
20 \item{plot}{if TRUE, then plot the first variable (angle)}
21 \item{opti}{opti=TRUE: iterative optimization (slow) or opti=FALSE: linear fitting (fast)}
22 \item{hours}{If TRUE, measures are in 24 hours to the day, otherwise, radians}
23 \item{x}{A set of external variables to correlate with the phase angles}
24}
25\details{
26When data represent angles (such as the hours of peak alertness or peak tension during the day), we need to apply circular statistics rather than the more normal linear statistics (see Jammalamadaka (2006) for a very clear set of examples of circular statistics). The generalization of the mean to circular data is to convert each angle into a vector, average the x and y coordinates, and convert the result back to an angle. The generalization of Pearson correlation to circular statistics is straight forward and is implemented in cor.circular in the circular package and in \code{\link{circadian.cor}} here.  Just as the Pearson r is a ratio of covariance to the square root of the product of two variances, so is the circular correlation.  The circular covariance of two circular vectors is defined as the average product of the sines of the deviations from the circular mean.  The variance is thus the average squared sine of the angular deviations from the circular mean.  Circular statistics are used for data that vary over a period (e.g., one day) or over directions (e.g., wind direction or bird flight).  Jammalamadaka and Lund (2006)  give a very good example of the use of circular statistics in calculating wind speed and direction.
27
28The code from CircStats and circular was adapted to allow for analysis of data from various studies of mood over the day.
29
30The cosinor function will either iteratively fit cosines of the angle to the observed data (opti=TRUE) or use the circular by linear regression to estimate the best fitting phase angle.  If cos.t <- cos(time) and sin.t = sin(time) (expressed in hours), then beta.c and beta.s may be found by regression and the phase is \eqn{sign(beta.c) * acos(beta.c/\sqrt(beta.c^2 + beta.s^2)) * 12/pi}
31
32Simulations (see examples) suggest that with incomplete times, perhaps the optimization procedure yields slightly better fits with the correct phase than does the linear model, but the differences are very small. In the presence of noisey data, these advantages seem to reverse.  The recommendation thus seems to be to use the linear model approach (the default).
33}
34\value{
35  \item{phase }{The phase angle that best fits the data}
36  \item{fit }{Value of the correlation of the fit}
37  \item{mean.angle}{A vector of mean angles}
38  \item{R}{A matrix of circular correlations or linear by circular correlations}
39
40}
41\references{ See circular statistics
42Jammalamadaka, Sreenivasa and Lund, Ulric (2006),The effect of wind direction on ozone levels: a case study, Environmental and Ecological Statistics, 13, 287-298.
43}
44\author{William Revelle }
45
46\seealso{See the circular and CircStats packages. }
47
48\examples{
49time <- seq(1:24)
50pure <- matrix(time,24,18)
51pure <- cos((pure + col(pure))*pi/12)
52matplot(pure,type="l",main="Pure circadian arousal rhythms",xlab="time of day",ylab="Arousal")
53p <- cosinor(time,pure)
54#set.seed(42)
55noisy <- pure + rnorm(24*18)
56n <- cosinor(time,noisy)
57#small.pure <- pure[c(6:18),]
58small.pure <- pure[c(8,11,14,17,20,23),]
59#small.noisy <- noisy[c(6:18),]
60small.noisy <- noisy[c(8,11,14,17,20,23),]
61matplot(small.noisy,type="l",main="Noisy circadian arousal rhythms",xlab="time of day",ylab="Arousal")
62#sp <- cosinor(time[c(6:18)],small.pure)  #linear fit
63sp <- cosinor(time[c(8,11,14,17,20,23)],small.pure)
64spo <- cosinor(time[c(8,11,14,17,20,23)],small.pure,opti=TRUE) #iterative fit
65sn <- cosinor(time[c(8,11,14,17,20,23)],small.noisy) #linear
66sno <- cosinor(time[c(8,11,14,17,20,23)],small.noisy,opti=TRUE) #iterative
67sum.df <- data.frame(pure=p,noisy = n, small=sp,small.noise = sn, small.opt=spo,small.noise.opt=sno)
68round(sum.df,2)
69round(circadian.cor(sum.df[,c(1,3,5,7,9,11)]),2)  #compare alternatives
70round(cor(sum.df[,c(2,4,6,8,10,12)]),2)
71}
72
73\keyword{ multivariate }
74