mean_trend: Function for Generating Various Longitudinal Mean Trends
In microbiomeDASim: Microbiome Differential Abundance Simulation

Description Usage Arguments Details Value Examples

In order to investigate different functional forms of longitudinal differential abundance we allow the mean time trend to take a variety of forms. These functional forms include linear, quadratic, cubic, M, W, L_up, or L_down. For each form the direction/concavity/fold change can be specified using the beta parameter.

mean_trend(
  timepoints,
  form = c("linear", "quadratic", "cubic", "M", "W", "L_up", "L_down"),
  beta,
  IP = NULL,
  plot_trend = FALSE
)

`timepoints`	numeric vector specifying the points to fit the functional trend.
`form`	character value specifying the type of time trend. Options include 'linear', 'quadratic', 'cubic', 'M', 'W', 'L_up', and 'L_down'.
`beta`	vector specifying the appropriate parameters for the equation. In the case of 'linear', beta should be a two-dimensional vector specifying the intercept and slope. See details for the further explanation of the beta value for each form.
`IP`	vector specifying the inflection points where changes occur for functional forms M, W, and L trends.
`plot_trend`	logical value indicating whether a plot should be produced for the time trend. By default this is set to TRUE.

Linear Form Notes:

f(x)=β_0+β_{1}x+β_{2}x^2

Sign of β_1 determines whether the trend is increasing (+) or decreasing (-)

Quadratic Form Notes:

f(x)=β_0+β_{1}x+β_{2}x^2

Critical point for quadratic function occurs at the point \frac{-β_1}{2β_2}
β_2 determines whether the quadratic is concave up (+) or concave down (-)

Cubic Form Notes:

f(x)=β_0+β_{1}x+β_{2}x^2+β_{3}x^{3}

Point of Inflection for cubic function occurs \frac{-β_{2}}{(3β_{3})}
Critical points for cubic function occur at \frac{-β_{2}\pm√{β_2^{2}-3β_{1}β_{3}}}{3β_3}
Can generate piecewise linear trends, i.e. 'V' form, by placing either one of the IP points outside of the timepoints specified

M/W Form Notes:

Must specify beta as (β_0, β_1) and IP as (IP_1, IP_2, IP_3)
This form should be specified with an initial intercept, β_0, and slope, β_1, that will connect to the first point of change (IP) specified.
Subsequent slopes are constructed such that the mean value at the second IP value and final timepoint are 0
The mean value at the third IP is set to be equal to the calculcated mean value at the first IP based on the specified intercept and slope.
β_0=intercept, i.e. timepoint when y=0
β_1=slope between β_0 and IP_1

L_up Form Notes:

The structure of this form assumes that there is no trend from t_{1} to IP_{1}. Then at the point of change specified, IP_{1}, there occurs a linearly increasing trend with slope equal to β_{slope} up to the last specified timepoint t_{q}.

Must specify beta as (β_{slope}), and must be positive
Specify a single point of change (IP) variable where positive trend will start
IP must be between [t_{1}, t_{q}]

L_down Form Notes:

Similarily, the L_down form assumes that there are two region within the range of timepoints. The first region is a decreasing trend and the second region has no trend. The decreasing trend must start with a Y intercept greater than zero, and the slope must be specified as negative. There is one point of change (IP), but this is calculated automatically based on the values of the Y intercept and slope provided, IP=-β_{yintercept}/β_{slope}.

Must specify beta as (β_{yintercept}, β_{slope}) where β_{yintercept}>0 and β_{slope}<0
IP variable should be specified as NULL, if value is provided it will be ignored.

This function returns a list of the following

form - character value repeating the form selected

trend - data.frame with the variables mu representing the estimated mean value at timepoints used for fitting the trend

beta - returning the numeric vector used to fit the functional form

#Quadratic Form
mean_trend(timepoints=seq(0, 6, length.out=20),
               form='quadratic', beta=1/4 * c(-1, 3, -0.5), plot_trend=TRUE)
#M Form
mean_trend(timepoints=seq(0, 10,length.out=100), form='M',
               beta=c(0, 5), IP=10 * c(1/4, 2/4, 3/4), plot_trend=TRUE)
#in this case the IP points are selected so that peaks are evenly
#distributed but this does not have to be true in general

#L_up Form
mean_trend(timepoints=seq(0, 10, length.out=100), form='L_up',
           beta=1, IP=5, plot_trend=TRUE)

#L_down Form
mean_trend(timepoints=seq(0, 10,length.out=100), form='L_down',
           beta=c(4, -0.5), IP=NULL, plot_trend=TRUE)