DataInfobeta3D {iNEXT.beta3D}

Data information for reference samples

Description

DataInfobeta3D provides basic data information for (1) the reference sample in each assemblage, (2) the gamma reference sample in the pooled assemblage, and (3) the alpha reference sample in the joint assemblage for TD, PD and FD.

Usage

DataInfobeta3D(
  data,
  diversity = "TD",
  datatype = "abundance",
  PDtree = NULL,
  PDreftime = NULL,
  FDdistM = NULL,
  FDtype = "AUC",
  FDtau = NULL
)

Arguments

data

(a) For datatype = "abundance", species abundance data for a single dataset can be input as a matrix/data.frame (species-by-assemblage); data for multiple datasets can be input as a list of matrices/data.frames, with each matrix representing a species-by-assemblage abundance matrix for one of the datasets.
(b) For datatype = "incidence_raw", data for a single dataset with N assemblages can be input as a list of matrices/data.frames, with each matrix representing a species-by-sampling-unit incidence matrix for one of the assemblages; data for multiple datasets can be input as multiple lists.

diversity

selection of diversity type: 'TD' = Taxonomic diversity, 'PD' = Phylogenetic diversity, and 'FD' = Functional diversity.

datatype

data type of input data: individual-based abundance data (datatype = "abundance") or species by sampling-units incidence/occurrence matrix (datatype = "incidence_raw") with all entries being 0 (non-detection) or 1 (detection).

PDtree

(required argument for diversity = "PD"), a phylogenetic tree in Newick format for all observed species in the pooled assemblage.

PDreftime

(argument only for diversity = "PD"), a numerical value specifying reference time for PD. Default is PDreftime = NULL (i.e., the age of the root of PDtree).

FDdistM

(required argument for diversity = "FD"), a species pairwise distance matrix for all species in the pooled assemblage.

FDtype

(argument only for diversity = "FD"), select FD type: FDtype = "tau_value" for FD under a specified threshold value, or FDtype = "AUC" (area under the curve of tau-profile) for an overall FD which integrates all threshold values between zero and one. Default is FDtype = "AUC".

FDtau

(argument only for diversity = "FD" and FDtype = "tau_value"), a numerical value between 0 and 1 specifying the tau value (threshold level) that will be used to compute FD. If FDtype = NULL (default), then threshold level is set to be the mean distance between any two individuals randomly selected from the pooled dataset (i.e., quadratic entropy).

Value

a data.frame including basic data information.

For abundance data, basic information shared by TD, mean-PD and FD includes dataset name (Dataset), individual/pooled/joint assemblage (Assemblage), sample size (n), observed species richness (S.obs), sample coverage estimates of the reference sample (SC(n)), sample coverage estimate for twice the reference sample size (SC(2n)). Other additional information is given below.

(1) TD: the first five species abundance frequency counts in the reference sample (f1–f5).

(2) Mean-PD: the the observed total branch length in the phylogenetic tree (PD.obs), the number of singletons (f1*) and doubletons (f2*) in the node/branch abundance set, as well as the total branch length of those singletons (g1) and of those doubletons (g2), and the reference time (Reftime).

(3) FD (FDtype = "AUC"): the minimum distance (dmin) and the maximum distance (dmax) among all non-diagonal elements in the distance matrix, and the mean distance between any two individuals randomly selected from the dataset (dmean).

(4) FD (FDtype = "tau_value"): the number of singletons (a1*) and of doubletons (a2*) among the functionally indistinct set at the specified threshold level 'Tau', as well as the total contribution of singletons (h1) and of doubletons (h2) at the specified threshold level 'Tau'.

For incidence data, the basic information for TD includes dataset name (Dataset), individual/pooled/joint assemblage (Assemblage), number of sampling units (T), total number of incidences (U), observed species richness (S.obs), sample coverage estimates of the reference sample (SC(T)), sample coverage estimate for twice the reference sample size (SC(2T)), as well as the first five species incidence frequency counts (Q1–Q5) in the reference sample. For mean-PD and FD, output is similar to that for abundance data.

Examples

## (Data Information) Taxonomic diversity for abundance data
data(Brazil_rainforests)
info_TD_abun = DataInfobeta3D(data = Brazil_rainforests, diversity = 'TD', datatype = 'abundance')
info_TD_abun


## (Data Information) Taxonomic diversity for incidence data
data(Second_growth_forests)
info_TD_inci = DataInfobeta3D(data = Second_growth_forests, diversity = 'TD',
                              datatype = 'incidence_raw')
info_TD_inci


## (Data Information) Mean phylogenetic diversity for abundance data
data(Brazil_rainforests)
data(Brazil_tree)
info_PD_abun = DataInfobeta3D(data = Brazil_rainforests, diversity = 'PD', 
                              datatype = 'abundance', PDtree = Brazil_tree, PDreftime = NULL)
info_PD_abun


## (Data Information) Functional diversity for abundance data under a specified threshold level
data(Brazil_rainforests)
data(Brazil_distM)
info_FDtau_abun = DataInfobeta3D(data = Brazil_rainforests, diversity = 'FD', 
                                 datatype = 'abundance', FDdistM = Brazil_distM, 
                                 FDtype = 'tau_value', FDtau = NULL)
info_FDtau_abun


## (Data Information) Functional diversity for abundance data when all threshold levels
## from 0 to 1 are considered
data(Brazil_rainforests)
data(Brazil_distM)
info_FDAUC_abun = DataInfobeta3D(data = Brazil_rainforests, diversity = 'FD', 
                                 datatype = 'abundance', FDdistM = Brazil_distM, FDtype = 'AUC')
info_FDAUC_abun