Introduction to using circacompare

Input data

The first part of using circacompare to analyse your data is to ensure that your data is formatted correctly. All of the functions within the circacompare package expect that your data will be of a tidy format, meaning that each row will contain only one observation, with columns to represent the time, group or subject ID for that observation.

In the simplest case, you may have a single rhythm for which you’re wanting to estimate the mesor, amplitude and phase. In this case, you only need a variable for the time of observation and the outcome which you’re wanting to model.

head(data_single)
#>   time measure
#> 1    1     5.3
#> 2    2     5.7
#> 3    3     7.9
#> 4    4    12.0
#> 5    5    14.0
#> 6    6    13.0

In the case that you have data from two groups and you’re wishing to determine the differences in mesor, amplitude, or phase between them, you will need an additional column (with two possible values) representing the groups.

head(data_grouped)
#>   time measure group
#> 1    1     1.7    g1
#> 2    2     5.6    g1
#> 3    3    10.0    g1
#> 4    4     8.8    g1
#> 5    5    11.0    g1
#> 6    6     4.0    g1
tail(data_grouped)
#>    time measure group
#> 43   19     7.8    g2
#> 44   20     9.6    g2
#> 45   21    15.0    g2
#> 46   22    14.0    g2
#> 47   23    19.0    g2
#> 48   24    15.0    g2

circa_single()

circa_single() is used to analyse a single rhythm and provide estimates of its mesor, amplitude and phase.

result <- circa_single(x=data_single, col_time="time", col_outcome="measure", period=24)

result
#> [[1]]
#> Nonlinear regression model
#>   model: measure ~ k + alpha * cos(time_r - phi)
#>    data: x
#>        k    alpha      phi 
#> -0.02479 10.66995  1.52831 
#>  residual sum-of-squares: 242.7
#> 
#> Number of iterations to convergence: 6 
#> Achieved convergence tolerance: 5.564e-07
#> 
#> [[2]]
#>         mesor amplitude  amplitude_p phase_radians peak_time_hours
#> 1 -0.02479123  10.66995 3.996067e-26      1.528313        5.837727
#> 
#> [[3]]

The fitted model is included as the first element of the results.

It fits a model: measure ~ k + alpha * cos(time_r - phi) where

The parameter estimates of time in radian-hours (time_r and phi) are converted back to hours and reported in the data.frame (second element of list) and x-axis of the graph (third item of list)

circacompare()

circacompare() is used to analyse a dataset with two groups of rhythmic data. It fits a model to estimate and statistically support differences in mesor, amplitude and phase between the two groups.

result2 <- circacompare(x=data_grouped, col_time="time", col_group="group", col_outcome="measure")

result2
#> [[1]]

#> 
#> [[2]]
#>                                   parameter         value
#> 1                 Both groups were rhythmic  1.000000e+00
#> 2  Presence of rhythmicity (p-value) for g1  6.283999e-13
#> 3  Presence of rhythmicity (p-value) for g2  9.111829e-20
#> 4                         g1 mesor estimate  8.750009e-02
#> 5                         g2 mesor estimate  3.560000e+00
#> 6                 Mesor difference estimate  3.472500e+00
#> 7              P-value for mesor difference  4.903987e-08
#> 8                     g1 amplitude estimate  9.527113e+00
#> 9                     g2 amplitude estimate  1.376314e+01
#> 10            Amplitude difference estimate  4.236029e+00
#> 11         P-value for amplitude difference  1.002484e-06
#> 12                             g1 peak time  5.899682e+00
#> 13                             g2 peak time  1.556495e-01
#> 14                Phase difference estimate -5.744033e+00
#> 15          P-value for difference in phase  4.751186e-25
#> 
#> [[3]]
#> Nonlinear regression model
#>   model: measure ~ k + k1 * x_group + (alpha + alpha1 * x_group) * cos(time_r -     (phi + phi1 * x_group))
#>    data: x
#>       k      k1   alpha  alpha1     phi    phi1 
#>  0.0875  3.4725  9.5271  4.2360  1.5445 -1.5038 
#>  residual sum-of-squares: 138.2
#> 
#> Number of iterations to convergence: 8 
#> Achieved convergence tolerance: 3.746e-08

This fits a model: measure ~ k + k1 * x_group + (alpha + alpha1 * x_group) * cos(time_r - (phi + phi1 * x_group)) where

The time-related parameter estimates (phi and phi1) are converted from radian-hours to hours before being used to report g1 peak time, g2 peak time, and phase difference estimate.

The second item of the result2 list is a data.frame containing the important results from the model. It returns estimates and for the rhythmic parameters for each group as well as the p-values associated with those which represent differences between the groups (k1, alpha1, phi1).

More detailed outputs from the model can be obtained from the model itself

nls_model <- result2[[3]]

confint(nls_model)
#> Waiting for profiling to be done...
#>              2.5%      97.5%
#> k      -0.6597294  0.8347294
#> k1      2.4157580  4.5292420
#> alpha   8.4703715 10.5838554
#> alpha1  2.7415705  5.7304881
#> phi     1.4333842  1.6556822
#> phi1   -1.6388271 -1.3687414

When to use what

If you are looking to estimate the rhythmic parameters of a single group, use circa_single(). If you are looking to estimate the differences between two rhythmic datasets, use circacompare()

If your data has a hierarchical structure, a mixed model may be more appropriate. This may be the case if you have repeated measurements from the same subjects/tissues over time, for example. In this case, consider the equivalents of the above: circa_single_mixed() and circacompare_mixed(). In addition to what has been described, these mixed models require the user to specify which parameters ought to have a random effect and the identifying column (col_id) for this hierarchical structure.