Pext: Probability of extinction
In carlopacioni/HexSimR: An R Package For Post HexSim Simulation Analysis

Description Usage Arguments Details Value References See Also

Calculates the probability of extinction for each time step, the mean probability of extinction across all time steps (and across all replicates), and the cumulative probability of extinction (that is, the probability that a populaition goes extinct in at least one time step). Specific time step intervals can be specified. If the number of the requested scenarios is > 1, it is possible to indicate a baseline scenario and Pext will also calculate the Strictly Standardised Mean Difference (SSMD, Zhang 2007).

Pext(
  data = NULL,
  path.results,
  rda.in = "collated.census.rda",
  scenarios = "all",
  ncensus = 0,
  start = "min",
  end = "max",
  headers = "Population.Size",
  base = NULL
)

`data`	The output from `collate.census`
`path.results`	The path to the 'Results' folder
`rda.in`	The name of the .rda file where the output from `collate.census` is saved
`scenarios`	A character vector with the scenarios to be processed or "all"
`ncensus`	The number of the census to be considered
`start`	The first time step to be included
`end`	The last time step to be included
`headers`	A character vector matching exactly the headers of the census file columns that are to be used by `bin.f`
`base`	A character vector with the name of the scenario to be used as term of comparison

By default, Pext calculates the probability of extinction using the column "Population Size", however any column(s) in the census file can be passed with the argument headers. This allows to set different criteria for extinction (e.g. no females are left) or to calculate the probability of extinction for several populations at once (if these are captured in different columns in the census file, see tutorial for an example). By extension, Pext can therefore be used to calculate the probability of any trait(s) to be zero (or non-zero by calculating 1 - Pext).

Pext takes as input the output of collate.census, which can be passed as R object with data. If data=NULL, then a fully qualified file name of the .rda file saved by collate.census needs to be passed with the argument rda.in.

When start="min" (default), the first time step considered is automatically set to 1 if the first time step is zero, otherwise it will be set to the minimum Time Step > 0. When end="max", the last time step considered is set to the maximum Time Step value.

NOTE that in this function SSMD is calculated as the difference between the parameter of the base scenario minus the parameter of the alternative scenario. This means that a negative SSMD indicates an increase probability of extinction of the alternative scenario against the base scenario. See the vignette for further discussion on this point.

It is also important to note that if both standard deviations of the probabilities used to calculate the SSMD are zero (this may happen, for example, when the populations never go extinct, or always go extinct), it is impossible to calculate the SSMD (the denominator is zero) and the cells in the result file will be blank, while if the mean probabilities are the same, then SSMD=0 and p-value=0.5.

A list with seven elements:

means.Pext.time.step: A data.frame (data.table) with the mean probability of extinction for each time step, for each scenario
sds.Pext.time.step: A data.frame (data.table) with the standard deviation of the probability of extinction for each time step, for each scenario
cumul.Pext.means: A data.frame (data.table) with the mean cumulative probability of extinction from the Time Step start to end, for each scenario
cumul.Pext.sds: A data.frame (data.table) with standard deviation of the cumulative probability of extinction from the Time Step start to end, for each scenario
means.time.step.Pext: A data.frame (data.table) with the mean probability of extinction across all time steps, for each scenario
sds.time.step.Pext: A data.frame (data.table) with the standard deviation of the probability of extinction across all time steps, for each scenario
time.step.Pext: A data.frame (data.table) with the raw data (i.e. all replicates, befoe subsetting the data for the time interval selected) where the columns are a logical answering the question whether the population was extinct

These results are also saved to disk in two xls files:

Pext.time.step_census*: The mean and standard deviation for each Time Step (in two separate tabs)
Cumulative_Pext_census*: the mean and standard deviation of the cumulative probability of extinction for the selected time step interval (in two separate tabs)
Time_step_Pext_census: The mean and standard deviation of the time step probability of extinction across all time steps within the selected interval (in two separate tabs)

The results for the SSMD comparisons are carried out for the means.Pext.time.step and cumul.Pext.means only and are saved in the file starting with "SSMD_Cumul_Pext_census" or SSMD_means.time.step.Pext. The census number is appended to the name of all xls file.

Zhang, X. D. 2007. A pair of new statistical parameters for quality control in RNA interference high-throughput screening assays. Genomics 89:552-561.

collate.census

carlopacioni/HexSimR documentation built on Nov. 28, 2020, 4:12 p.m.