syntable: Synoptic tables and calculation of group-wise frequencies, fidelity and differential species character

Description

Synoptic tables summarize previously defined plant community groups, e.g., from cluster analysis, classification methods, or pre-defined strata, such as spatial distribution units. They help identify characteristic species patterns by calculating group-wise percentage/absolute frequencies, mean/median cover, fidelity indices or differential species character.

syntable calculates synoptic tables from vegetation data and a vector of group identities. The vegetation data can be provided as a species-sample matrix (default) or as long-format vegetation data (one row per species occurrence) (long = TRUE).

The unordered output table can be sorted with synsort function.

Usage

syntable(
  vegdata,
  groups = NULL,
  abund = "percentage",
  type = "percfreq",
  digits = NULL,
  long = FALSE,
  group_col = NULL,
  phi_method = "default",
  phi_standard = "none",
  phi_target_size = NULL,
  phi_alpha = NULL
)

Value

The function returns an (invisible) list of result components.

$syntable: unordered synoptic table for given species and groups
$samplesize: total number of samples per group

Additionally for differential species character calculation:

$onlydiff: Synoptic table only with differential species
$others: List of non-differential species
$differentials: Lists differential species for each group

Arguments

vegdata

A data-frame-like object. Either:

default: a species-sample matrix with species in columns and samples in rows. Species names must be column names, sample (row) names are optional.
with long = TRUE: a long-format table with at least three columns: sample ID, taxon name, and abundance/cover (these must be the first three columns).

Missing values (NA) are converted to 0. If non-numeric abundance values are present, the matrix will be transformed to presence/absence with all non-zero values defined as 1.

groups

Group identities for samples. For wide data (default): a vector/factor of length nrow(vegdata) (one group per sample/row). For long data: either a per-row vector (length nrow(vegdata)), a per-sample vector (named by sample IDs, or in the order of first appearance of samples), or NULL when group_col is used. Within each sample, exactly one group must be defined.

abund

Type of abundances: percentage cover ("percentage", default) or presence/absence ("pa" with values 0/1). Use cov2per to transform cover-abundance scales to percentage cover if needed.

type

Output type. One of c("percfreq","totalfreq","mean","median","diffspec","phi"). See Details.

digits

Integer indicating the number of decimal places to be displayed in result tables (default 0; for phi 3)

long

Logical. If TRUE, vegdata is treated as long-format data; otherwise as species-sample matrix (default)

group_col

(Long data only) Optional name of a column in vegdata that contains the group labels. When supplied, groups may be NULL.

phi_method

Fidelity measure when type = "phi": "default" (binary phi), "uvalue" (hypergeometric $u$), or "ochiai" (Ochiai coefficient).

phi_standard

Group-size equalization when type = "phi": "none" (no equalization), "target" (equalize the evaluated group to a chosen percentage of plots; other groups remain as observed outside the target), "all" (equalize the evaluated group to the chosen percentage and distribute the remaining percentage equally among the other groups so totals remain $N$).

phi_target_size

Numeric percentage in (0, 100) giving the conceptual size of the target group used by phi_standard. If NULL, defaults to equal sizes (i.e., $100 / G$, where $G$ is the number of groups).

phi_alpha

Optional significance level for Fisher’s exact test when type = "phi". If NULL (default), no test is performed. If a numeric value in (0, 1) is given, a Fisher exact p-value is computed for each species×group cell on the original 2×2 presence table; cells with $p \ge$ phi_alpha are set to 0 in the output fidelity table.

Author

Friedemann von Lampe, Jenny Schellenberg

Details

For synoptic table calculation, six types are available.

type = "percfreq" : percentage frequency of occurrence per group (default)
type = "totalfreq" : absolute frequency (number of plots with presence) per group
type = "mean" mean cover per group (abund = "percentage" only)
type = "median" median cover per group (abund = "percentage" only)
type = "phi" species fidelity. The default corresponds to the binary phi coefficient (= $\phi = \frac{u}{\sqrt{N - 1}}$; Sokal & Rohlf 1995, Bruelheide 2000) with values between -1 and 1, expressing the avoidance or preference of a species for the target site group. Alternatively, the hypergeometric $u$-value (see Chytrý et al., 2002), or the Ochiai coefficient (see de Cáceres et al, 2008) can be selected via phi_method. Optional group-size equalization follows Tichý & Chytrý (2006) via phi_standard and phi_target_size. A significance level for an optional zero-out of non-significant cells based on Fisher's exact test can be provided via phi_alpha.
type = "diffspec" differential character of species according to Tsiripidis et al. 2009: p = positive, n = negative, pn = positive- negative, or none (-). Consider that differential character is always restricted to some and not necessarily all of the other units, thus considering percentage frequency is essential for correct interpretation of the diagnostic species character. Requires $\ge 3$ groups and is available for wide data only.

For sorting the output synoptic table, use synsort function, providing several options.

References

Bruelheide, H. (2000): A new measure of fidelity and its application to defining species groups. Journal of Vegetation Science 11: 167-178. tools:::Rd_expr_doi("10.2307/3236796")

Chytrý, M., Tichý, L., Holt, J., Botta-Dukat, Z. (2002): Determination of diagnostic species with statistical fidelity measures. Journal of Vegetation Science 13: 79-90. tools:::Rd_expr_doi("10.1111/j.1654-1103.2002.tb02025.x")

de Cáceres, M., Font, X., & Oliva, F. (2008). Assessing species diagnostic value in large data sets: A comparison between phi‐coefficient and Ochiai index. Journal of Vegetation Science, 19(6), 779–788. tools:::Rd_expr_doi("10.3170/2008-8-18446")

Sokal, R.R. & Rohlf, F.J. (1995): Biometry. 3rd edition Freemann, New York.

Tichý, L., & Chytrý, M. (2006). Statistical determination of diagnostic species for site groups of unequal size. Journal of Vegetation Science, 17(6), 809–818. tools:::Rd_expr_doi("10.1111/j.1654-1103.2006.tb02504.x")

Tsiripidis, I., Bergmeier, E., Fotiadis, G. & Dimopoulos, P. (2009): A new algorithm for the determination of differential taxa. Journal of Vegetation Science 20: 233-240. tools:::Rd_expr_doi("10.1111/j.1654-1103.2009.05273.x")

Examples

Run this code

## Synoptic table of Scheden vegetation data
library(cluster)
pam1 <- pam(schedenveg, 4)  # PAM clustering with 4 clusters output


## 1) Unordered synoptic percentage frequency table
percfreq <- syntable(schedenveg, pam1$clustering, abund = "percentage",
                         type = "percfreq")
percfreq                   # view results


## 2) Differential species analysis
differential <- syntable(schedenveg, pam1$clustering, abund = "percentage",
                             type = "diffspec")
# show complete table with differential character of species
differential$syntable
# list differential species for second cluster
differential$differentials[2]


## 3) Synoptic table with phi fidelity
phitable <- syntable(schedenveg, pam1$clustering, abund = "percentage",
                         type = "phi")
phitable


## 3b) Hypergeometric u-value and standardisation of group sizes
phiu <- syntable(schedenveg, pam1$clustering, abund = "percentage",
                 type = "phi", phi_method = "uvalue", phi_standard = "all")
phiu


## 4) Synoptic percentage frequency table based on historical classification from 1997
percfreq <- syntable(schedenveg, schedenenv$comm, abund = "percentage",
                         type = "percfreq")
percfreq

Run the code above in your browser using DataLab