findPFw: Find Power Fraction 'w' parameter
In MarioJose/nicheApport: Tokeshi's Niche Apportionment Species Abundance Distributions Models

Description Usage Arguments Details Value Author(s) References See Also Examples

View source: R/findPFw.R

This function call fitmodel or fitmodelCl to find the Power Fraction w parameter that best fit model to data. A sequence of w value will be created and fit procedures will check fit each of this w values fit to data.

1	findPFw(x, count, ws = 0, we = 1, f = 0.01, nRand = 99, cl = TRUE, nCores = 1)

`x`	Data frame or matrix with observed species rank (ordered from largest abundance to smallest) at columns and replicates at rows. See 'Details' for more information.
`count`	Define if measure of abundance is number of individuals. See 'Details' for more information.
`ws`	Start value of Power Fraction `w` parameter.
`we`	End value of Power Fraction `w` parameter.
`f`	Number of increment to sequence of `w` values.
`nRand`	Number of simulations.
`cl`	Logical value indicating if parallel computation must be used to find best `w`. See 'Details' for more information.
`nCores`	Number indicating number of processor cores or threads to be used to simulation. See 'Details' for more information.

The observed replicates in data frame or matrix x must be in rows and ranked by abundance. First rank (column 1) will be species with largest abundance, second column with second largest abundance, and so on until the species with smallest abundance. Note that this protocol do not require species identification. First rank of replicates 1, for instance, may be not the same as first rank of replicates 2. Note too that number of species may be differ among replicates. In this case, zeros must be used to the rank(s).

The fitting use the protocol proposed by Bersier & Sugihara (1997) and modiffied by Cassey & King (2001) and ranked relative abundance recommendations by Mouillot et al. (2003), with some modifications. For more information of procedures consult documentation of fitmodel or fitmodelCl. Observed abundance fit to the model if p-value to means and variances are not significant at predetermined significance level (probability of found observed T at simulated T). The observed T value (TMobs or TVobs, see 'Value' bellow) measure how well model fits to data; better fit had smaller value (Bersier & Sugihara 1997).

If cl is TRUE the function fit model to data calling fitmodelCl for parallel computation. This function divide the number of simulations among the processor cores or threads and run the procedures simultaneously. If cl is FALSE the function call fitmodel to fit model to data. When nCores = 1 the function detect number of cores or threads automatically. If you inform incorrectly the number of cores or threads, the function will inform you to correct information or will recommend to use fitmodel. The overall process using parallel computation can be twice as fast, depending on the number of processor cores or threads used.

The findPFw function fit Power Fraction model with different w values and return information (see 'Value' bellow) to choose the w value that best fit Power Fraction to data. The criteria can be the smallest values of TMobs or TVobs (Bersier & Sugihara 1997) or higher p-value (probability of found observed T at simulated T).

Data frame with follow columns:

`w`	Squence of Power Fraction w values.
`TMobs`	Observed value of T for mean.
`TVobs`	Observed value of T for variance.
`pvalueM`	P-value for mean.
`pvalueV`	P-value for variance.

For more information about values see documentation of fitmodel or fitmodelCl.

Mario J. Marques-Azevedo

Maintainer: Mario J. Marques-Azevedo <mariojmaaz@gmail.com>

Bersier, L.-F. & Sugihara, G. 1997. Species abundance patterns: the problem of testing stochastic models. J. Anim. Ecol. 66: 769-774.

Cassey, P. & King, R. A. R. 2001. The problem of testing the goodness-of-fit of stochastic resource apportionment models. Environmetrics 12: 691-698.

Mouillot, D. et al. 2003. How parasites divide resources: a test of the niche apportionment hypothesis. J. Anim. Ecol. 72: 757-764.

Tokeshi, M. 1996. Power fraction: a new explanation of relative abundance patterns in species-rich assemblages. Oikos 75: 543-550.

For models see dominanceDecay, dominancePreemp, MacArthurFraction, randFraction, randAssort and powerFraction.

For fit models see fitmodel and fitmodelCl to fit using parellel computation.

  # Creating an (abstract) observed data
  data <- matrix(nrow = 10, ncol = 40)
  for(i in 1:length(data[ ,1])){
    data[i, ] <- powerFraction(N = 100, S = 40, w = 0.2, count = FALSE)
  }

  # Fitting Power Fraction with a range of 'w' value and show
  # statistics to choose the value that best fit to data
  findPFw(data, count = FALSE, ws = 0.16, we = 0.22, f = 0.01, nRand = 99, cl = TRUE, nCores = 2)