MFx: Predict the Multiplication Factor leading to x% of reduction...
In morse: Modelling Reproduction and Survival Data in Ecotoxicology

View source: R/MFx.R

MFx	R Documentation

Predict the Multiplication Factor leading to x% of reduction in survival at a specific time.

Description

Generic method for MFx, a function denoted MF(x,t) for x% Multiplication Factor at time t.

The function MFx, x% Multiplication Factor at time t, (MF(x,t)), is used to compute the multiplication factor applied to the concentration exposure profile in order to reduce by x% (argument X) the survival probability at a specified test duration t (argument time_MFx) (default is the maximum time point of the experiment).

Mathematical definition of x% Multiplication Factor at time t (at the end of a time series T = \{0, \dots, t\}), denoted MF(x,t), is given by:

S(MF(x,t) * C_w(\tau \in T), t) = S( C_w(\tau \in T), t)*(1- x/100),

where C_w(\tau \in T) is the initial exposure profile without multiplication factor. And so the expression S(MF(x,t)* C_w(\tau \in T), t) is the survival probability after an exposure profile MF(x,t)* C_w(\tau \in T) at time t.

This is a method to replace function MFx used on survFit object when computing issues happen. MFx_ode uses the deSolve library to improve robustness. However, time to compute may be longer.

The function MFx_ode, x% Multiplication Factor at time t, (MF(x,t)), is used to compute the multiplication factor applied to the concentration exposure profile in order to reduce by x% (argument X) the survival probability at a specified test duration t (argument time_MFx) (default is the maximum time point of the experiment).

Mathematical definition of x% Multiplication Factor at time t (at the end of a time series T = \{0, \dots, t\}), denoted MF(x,t), is given by:

S(MF(x,t) * C_w(\tau \in T), t) = S( C_w(\tau \in T), t)*(1- x/100),

Usage

MFx(object, ...)

## S3 method for class 'survFit'
MFx(
  object,
  data_predict,
  X = 50,
  time_MFx = NULL,
  MFx_range = c(0, 1000),
  mcmc_size = 1000,
  hb_value = TRUE,
  spaghetti = FALSE,
  accuracy = 0.01,
  quiet = FALSE,
  threshold_iter = 100,
  hb_valueFORCED = 0,
  ode = TRUE,
  interpolate_length = NULL,
  interpolate_method = "linear",
  ...
)

MFx_ode(object, ...)

## S3 method for class 'survFit'
MFx_ode(
  object,
  data_predict,
  X = 50,
  time_MFx = NULL,
  MFx_range = c(0, 1000),
  mcmc_size = 1000,
  hb_value = TRUE,
  spaghetti = FALSE,
  accuracy = 0.01,
  quiet = FALSE,
  threshold_iter = 100,
  hb_valueFORCED = 0,
  interpolate_length = NULL,
  interpolate_method = "linear",
  ...
)

Arguments

`object`	An object of class `survFit`.
`...`	Further arguments to be passed to generic methods
`data_predict`	A dataframe with two columns `time` and `conc`.
`X`	Percentage of survival change (e.g., `50` for survival decrease of 50% , or `-50` for survival increase of 50%).The default is 50. Only time series computed during the adaptation using a binary search in `O(log(n))` are returned. However, if `NULL`, all time series computed from the vector `MFx_range` are returned.
`time_MFx`	A number giving the time at which `MF(x,t)` has to be estimated. If NULL, the latest time point of the profile is used.
`MFx_range`	A vector from which lower and upper bound of the range of the multiplication factor `MFx` are generated. The default is a vector `c(0, 1000)`. If argument `X` is `NULL`, then all the time series generated with `MFx_range` are returned.
`mcmc_size`	Can be used to reduce the number of MCMC samples in order to speed up the computation. The default is 1000.
`hb_value`	If `TRUE`, the background mortality `hb` is taken into account from the posterior. If `FALSE`, parameter `hb` is set to 0. The default is `TRUE`.
`spaghetti`	If `TRUE`, return a set of survival curves using parameters drawn from the posterior distribution.
`accuracy`	Accuracy of the multiplication factor. The default is 0.01.
`quiet`	If `FALSE`, print the evolution of accuracy.
`threshold_iter`	Threshold number of iteration.
`hb_valueFORCED`	If `hb_value` is `FALSE`, it fix `hb`.
`ode`	IF `ode` is `TRUE`, algo use predict_ode rather than predict. Default is `TRUE`.
`interpolate_length`	Length of the time sequence for which output is wanted.
`interpolate_method`	The interpolation method for concentration. See package `deSolve` for details. Default is `linear`.

Details

When class of object is survFit, see MFx.survFit.

Value

returns an object of class MFx

The function returns an object of class MFx, which is a list with the following information:

`X_prop`	Survival probability for `X` percent of reduction of the initial median survival probability at time `time_MFx`.
`X_prop_provided`	A number giving the proportion of reduction in survival.
`time_MFx`	A number giving the time at which `MF(x,t)` has to be estimated as provided in arguments or if NULL, the latest time point of the profile is used.
`df_MFx`	A `data.frame` with quantiles (median, 2.5% and 97.5%) of `MF(x,t)` at time `t`, `time_MFx`, for `x`% of survival reduction.
`df_dose`	A `data.frame` with quantiles (median, 2.5% and 97.5%) of survival probability along the computed multiplication factor and at time `time_MFx`.
`MFx_tested`	A vector of all multiplication factors computed.
`ls_predict`	A list of all object of class `survFitPredict` obtained from computing survival probability for every profiles build from the vector of multiplication factors `MFx_tested`.

The function returns an object of class MFx, which is a list with the following information:

`X_prop`	Survival probability for `X` percent of reduction of the initial median survival probability at time `time_MFx`.
`X_prop_provided`	A number giving the proportion of reduction in survival.
`time_MFx`	A number giving the time at which `MF(x,t)` has to be estimated as provided in arguments or if NULL, the latest time point of the profile is used.
`df_MFx`	A `data.frame` with quantiles (median, 2.5% and 97.5%) of `MF(x,t)` at time `t`, `time_MFx`, for `x`% of survival reduction.
`df_dose`	A `data.frame` with quantiles (median, 2.5% and 97.5%) of survival probability along the computed multiplication factor and at time `time_MFx`.
`MFx_tested`	A vector of all multiplication factors computed.
`ls_predict`	A list of all object of class `survFitPredict` obtained from computing survival probability for every profiles build from the vector of multiplication factors `MFx_tested`.