mean_trend {microbiomeDASim} | R Documentation

## Function for Generating Various Longitudinal Mean Trends

### Description

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.

### Usage

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

### Arguments

`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.

### Details

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.

### Value

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

### Examples

    #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)

[Package microbiomeDASim version 1.1.7 Index]