R: DOREMI first order analysis function

analyze.1order {doremi}

R Documentation

DOREMI first order analysis function

Description

analyze.1order estimates the coefficients of a first order differential equation of the form:

\frac{dy}{dt}(t) + \gamma (y(t) - yeq) = \gamma k*u(t)

using linear mixed-effect models. Where y(t) is the individual's signal,\gamma the decay rate (and \tau = 1/\gamma the decay time), \frac{dy(t)}{dt} is the derivative and u(t) is an external excitation perturbing the dynamics.

Usage

analyze.1order(
  data,
  id = NULL,
  input = NULL,
  time = NULL,
  signal,
  dermethod = "gold",
  derparam = 3,
  order = 1,
  verbose = FALSE
)

Arguments

`data`	Is a data frame containing at least one column, that is the signal to be analyzed.
`id`	Is a CHARACTER containing the NAME of the column of data containing the identifier of the individual. If this parameter is not entered when calling the function, a single individual is assumed and a linear regression is done instead of the linear mixed-effects regression.
`input`	Is a CHARACTER or a VECTOR OF CHARACTERS containing the NAME(s) of data column(s) containing the EXCITATION vector(s). If this parameter is not entered when calling the function, the excitation is assumed to be unknown. In this case, the linear mixed-effect regression is still carried out but no coefficient is calculated for the excitation term. The function then uses the parameters estimated by the regression to carry out an exponential fit of the signal and build the estimated curve. The function will consider as an excitation each column of data having a name contained in the input vector. The function will return a coefficient for each one of the excitation variables included in the input vector.
`time`	Is a CHARACTER containing the NAME of the column of data containing the time vector. If this parameter is not entered when calling the function, it is assumed that time steps are of 1 unit and the time vector is generated internally in the function.
`signal`	Is a CHARACTER containing the NAME of the column of the data frame containing the SIGNAL to be studied.
`dermethod`	is the derivative estimation method. default is "gold". The values are "gold","glla" and "fda", corresponding to the use of `calculate.gold`, `calculate.glla` or `calculate.fda` to estimate the derivatives
`derparam`	If dermethod "glla" or "gold" are chosen, it is the embedding number, a positive integer containing the number of points to be used for the calculation of the derivatives. Default is 3. At least two points are needed for the calculation of the first derivative. If dermethod "fda" is chosen, this parameter is spar, the parameter related to the smoothing parameter lambda used in the penalization function of the function `smooth.spline` to estimate the derivative via splines (Functional Data Analysis). In this case, the value should be between 0 and 1, see `?smooth.spline`
`order`	is the maximum order of the derivative estimated when using `calculate.gold` or `calculate.glla`. Although only the first derivative is used here, using a higher order can enhance derivative estimation (see doi: 10.1080/00273171.2015.1123138Chow et al.(2016))
`verbose`	Is a boolean that displays status messages of the function when set to 1. Useful for debugging.

Details

The analysis performs the following linear mixed-effects regression:

\dot{y_{ij}} \sim (b_{0} +b_{0j}) + (b_{1}+b_{1j}) y_{ij}+ (b_{2}+b_{2j}) u_{ij} +e_{ij}

with i accounting for the time and j for the different individuals. e_{ij} are the residuals, \dot{y_{ij}} is the derivative calculated on embedding points and y_{ij} and u_{ij} are the signal and the excitation averaged on embedding points. The fixed effect coefficients estimated from the regression are:

gamma: b_1 (\gamma from the differential equation)
kgamma: b_2 (k\gamma from the differential equation)
yeqgamma: b_0 (\gamma y_{eq} from the differential equation)

The coefficients derived to characterize the signal are calculated as follows:

the decay time, tau: \tau = \frac{1}{ b_1 } = \frac{1}{\gamma}
the gain, k: \gamma = \frac{b_2}{b_1}. It is the proportionality between the stationary increase of the signal and the excitation increase that caused it.
the equilibrium value, yeq: yeq = \frac{b_0}{b_1}. It is the stationary value reached in the absence of excitation.

The estimation is performed using the function lmer if there are several individuals or lm if there is only one. With the above estimated parameters, the estimated signal can be reconstructed for each individual by using the generate.1order function of this package (based on deSolve's ode function). The function returns five objects:

data- A data.frame including the input data, the intermediate calculations used to prepare the variables for the fit and the estimated trajectories for each individual.
1. signal_rollmean - calculation of the moving average of the signal over embedding points.
2. signal_derivate1 - calculation of the first derivative of the signal with the gold, glla or fda methods in embedding points.
3. time_derivate - calculation of the moving average of the time vector over embedding points.
4. input_rollmean - calculation of the moving average of the excitation vector over embedding points.
5. estimated - the estimated signal calculated using generate.1order with the excitation provided as input and the estimated decay time, gain and equilibrium value obtained from the regression. The initial condition y0 and t0 are the first value of the moving averaged signal (signal_rollmean) and time (time_derivate)
resultmean - A data.frame including the fixed effects of the coefficients estimated from the regression gamma, yeqgamma and the kgamma for each excitation considered, with their associated standard error gamma_stde, yeqgamma_stde and kgamma_stde, together with the derived coefficient tau (the decay time), yeq (the equilibrium value) and k (the gain)
resultid - A data.frame including, for each individual listed by id number, gamma, yeqgamma and the kgamma, together with the decay time tau, the gain k and the equilibrium value yeq
regression - A list containing the summary of the linear mixed-effects regression.

As seen in the Description section, the print method by default prints only the resultmean element. Each one of the other objects can be accessed by indicating $ and their name after the result, for instance, for a DOREMI object called "result", it is possible to access the regression summary by typing result$regression.
embedding - contains the embedding number used to generate the results (same as function input argument)
spar - contains the smoothing parameter used for the estimation of the derivatives using splines (method "fda")

SImulation presenting the statistical propoerties of the ethod can be found in doi: 10.1080/00273171.2020.1754155(Mongin et al. (2020)) Example of application of this function can be found in:

Value

Returns a summary of the fixed effect coefficients estimated by the linear regression

Examples

myresult <- analyze.1order(data = cardio,
                  id = "id",
                  input = "load",
                  time = "time",
                  signal = "hr",
                  dermethod ="gold",
                  derparam = 5)

[Package doremi version 1.0.0 Index]