DataInfo3D {iNEXT.3D}

Data information for reference samples

Description

DataInfo3D provides basic data information for 3D diversity based on a reference sample.

Usage

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

Arguments

data

(a) For datatype = "abundance", data can be input as a vector of species abundances (for a single assemblage), matrix/data.frame (species by assemblages), or a list of species abundance vectors.
(b) For datatype = "incidence_raw", data can be input as a list of matrices/data.frames (species by sampling units); data can also be input as a single matrix/data.frame by merging all sampling units across assemblages based on species identity; in this case, the number of sampling units (nT, see below) must be specified.

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

nT

(required only when datatype = "incidence_raw" and input data in a single matrix/data.frame) a vector of positive integers specifying the number of sampling units in each assemblage. If assemblage names are not specified (i.e., names(nT) = NULL), then assemblages are automatically named as "assemblage1", "assemblage2",..., etc.

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 vector of numerical values specifying reference times for PD. Default is 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_values" for FD under specified threshold values, 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 "AUC".

FDtau

(argument only for diversity = "FD" and FDtype = "tau_values"), a numerical vector between 0 and 1 specifying tau values (threshold levels). If NULL (default), then threshold is set to be the mean distance between any two individuals randomly selected from the pooled assemblage (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 assemblage name (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 counts (f1–f5).

(2) Mean-PD: 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 among all non-diagonal elements in the distance matrix (dmin), the mean distance (dmean), and the maximum distance (dmax) in the distance matrix.

(4) FD (FDtype = "tau_values"): 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 attribute contribution of singletons (h1) and of doubletons (h2) at the specified threshold level 'Tau'.

For incidence data, the basic information for TD includes assemblage name (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). For mean-PD and FD, output is similar to that for abundance data.

Examples

# Taxonomic diversity for abundance data
data(Brazil_rainforest_abun_data)
DataInfo3D(Brazil_rainforest_abun_data, diversity = 'TD', datatype = "abundance")


# Phylogenetic diversity for abundance data
data(Brazil_rainforest_abun_data)
data(Brazil_rainforest_phylo_tree)
data <- Brazil_rainforest_abun_data
tree <- Brazil_rainforest_phylo_tree
DataInfo3D(data, diversity = 'PD', datatype = "abundance", PDtree = tree)


# Functional diversity for abundance data with FDtype = 'AUC'
data(Brazil_rainforest_abun_data)
data(Brazil_rainforest_distance_matrix)
data <- Brazil_rainforest_abun_data
distM <- Brazil_rainforest_distance_matrix
DataInfo3D(data, diversity = 'FD', datatype = "abundance", 
           FDdistM = distM, FDtype = 'AUC')
           
# Functional diversity for abundance data with FDtype = 'tau_values'
data(Brazil_rainforest_abun_data)
data(Brazil_rainforest_distance_matrix)
data <- Brazil_rainforest_abun_data
distM <- Brazil_rainforest_distance_matrix
DataInfo3D(data, diversity = 'FD', datatype = "abundance", 
           FDdistM = distM, FDtype = 'tau_values')


# Taxonomic diversity for incidence data
data(Fish_incidence_data)
DataInfo3D(Fish_incidence_data, diversity = 'TD', datatype = "incidence_raw")


# Phylogenetic diversity for incidence data
data(Fish_incidence_data)
data(Fish_phylo_tree)
data <- Fish_incidence_data
tree <- Fish_phylo_tree
DataInfo3D(data, diversity = 'PD', datatype = "incidence_raw", PDtree = tree)


# Functional diversity for incidence data with FDtype = 'AUC'
data(Fish_incidence_data)
data(Fish_distance_matrix)
data <- Fish_incidence_data
distM <- Fish_distance_matrix
DataInfo3D(data, diversity = 'FD', datatype = "incidence_raw", 
           FDdistM = distM, FDtype = 'AUC')
           
# Functional diversity for incidence data with FDtype = 'tau_values'
data(Fish_incidence_data)
data(Fish_distance_matrix)
data <- Fish_incidence_data
distM <- Fish_distance_matrix
DataInfo3D(data, diversity = 'FD', datatype = "incidence_raw", 
           FDdistM = distM, FDtype = 'tau_values')