Version: 0.1.0
Date: 2020-12-10
Title: Fuzzy Quantification of Common and Rare Species
Description: Fuzzy clustering of species in an ecological community as common or rare based on their abundance and occupancy. It also includes functions to compute confidence intervals of classification metrics and plot results. See Balbuena et al. (2020, <doi:10.1101/2020.08.12.247502>).
Depends: R (≥ 3.5.0)
Imports: cluster
License: GPL-3
URL: https://ligophorus.github.io/FuzzyQ/
Encoding: UTF-8
NeedsCompilation: no
LazyData: true
RoxygenNote: 7.1.1.9000
Packaged: 2021-01-04 11:06:02 UTC; balbu
Author: Juan A. Balbuena ORCID iD [aut, cre, cph], Clara Monlleó-Borrull [aut, cph], Cristina Llopis-Belenguer ORCID iD [aut, cph], Isabel Blasco-Costa ORCID iD [aut, cph], Volodimir Saraveeb ORCID iD [aut, cph], Serge Morand ORCID iD [aut, cph]
Maintainer: Juan A. Balbuena <j.a.balbuena@uv.es>
Repository: CRAN
Date/Publication: 2021-01-05 09:30:05 UTC

Abundance Occupancy Plot

Description

Plots the abundance-occupancy relationship of species in a community categorized as common or rare by fuzzyq.

Usage

AOplot(
  fq,
  col.rc = c("red", "blue"),
  opacity = 0.1,
  log.x = FALSE,
  log.y = FALSE,
  xLab = "Fraction of sites occupied",
  yLab = "Mean abundance",
  ...
)

Arguments

fq

A list of class fuzzyq returned by FuzzyQ::fuzzyq.

col.rc

A vector specifying two colors to be used to plot common and rare species. Accept any valid color specification in R.

opacity

Number within [0,1] specifying the opacity of convex hulls grouping common and rare species.

log.x

Logical. Whether or not the x axis should be in log10 scale.

log.y

Logical. Whether or not the y axis should be in log10 scale.

xLab

String. Title for the x axis.

yLab

String. Title for the y axis.

...

Other graphical parameters to be passed to plot.

Value

A scatter plot of occupancy vs. abundance of species. Convex hulls enclose common and rare species.

Examples

data(antsA)
FQAnts <- fuzzyq(antsA, sorting = TRUE)
AOplot(FQAnts) # Plor with default values

# Alternative with colors specified in Hex code, logarithmic axes and other
# point format
AOplot(FQAnts, col.rc = c("#013bad","#bd5f69"),
       log.x = TRUE, log.y = TRUE, pch = 4)

Helminth communities of so-iuy mullets from the Sea of Azov

Description

Abundance of 25 helminth species from 378 so-iuy mullets collected in the Sea of Azov and the Black Sea. Fish are grouped in 12 surveys.

Usage

data(Azov)

Format

A data frame with 378 rows and 26 columns. The first column (sample) is a survey identifier. The remaining columns correspond to species abundances. See source for species abbreviations and survey identifiers.

Source

Llopis-Belenguer, C. (2019) Replication data for: Native and invasive hosts play different roles in host-parasite networks, Harvard Dataverse, doi: 10.7910/DVN/IWIKOL.

References

Llopis-Belenguer, C., Blasco-Costa, I., Balbuena, J.A., Sarabeev, V., Stouffer, D.B. (2020), Native and invasive hosts play different roles in host-parasite networks. Ecography, 43: 559-568. doi: 10.1111/ecog.04963.

Examples

data(Azov)
# Apply the FuzzyQ algorithm to each survey:
fuzzyq.azov <- by(Azov[, -1], Azov[, "sample"], fuzzyq, rm.absent = FALSE)
# Get cluster membership, silhouette widths and commonness indices
# per sp. per survey:
sppsilw.azov <- lapply(fuzzyq.azov, function(x) x$spp)
# Get global silhouette withds, commonness indices and Dunn's normalized
# partition coefficient per survey:
global.azov <- t(sapply(fuzzyq.azov, function(x) x$global))

Helminth communities of so-iuy mullets from the Japan Sea

Description

Abundance of 21 helminth species from 192 so-iuy mullets collected in the Japan Sea. Fish are grouped in seven surveys.

Usage

data(Japan)

Format

A data frame with 192 rows and 22 columns. The first column (sample) is a survey identifier. The remaining columns correspond to species abundances. See source for species abbreviations and survey identifiers.

Source

Llopis-Belenguer, C. (2019) Replication data for: Native and invasive hosts play different roles in host-parasite networks, Harvard Dataverse, doi: 10.7910/DVN/IWIKOL.

References

Llopis-Belenguer, C., Blasco-Costa, I., Balbuena, J.A., Sarabeev, V., Stouffer, D.B. (2020), Native and invasive hosts play different roles in host-parasite networks. Ecography, 43: 559-568. doi: 10.1111/ecog.04963.

Examples

data(Azov)
# Apply the FuzzyQ algorithm to each survey:
fuzzyq.japan <- by(Japan[, -1], Japan[, "sample"], fuzzyq, rm.absent = FALSE)
# Get cluster membership, silhouette widths and commonness indices
# per sp. per survey:
spp.japan <- lapply(fuzzyq.japan, function(x) x$spp)
# Get global silhouette withds, commonness indices and Dunn's normalized
# partition coefficient per survey:
global.japan <- t(sapply(fuzzyq.japan, function(x) x$global))

Ant species abundance from Arnan et el. (2011)

Description

Abundance of 46 ant species from 99 sites sampled in the Nothern Territory (Australia). This dataset corresponds to Plot A data in Arnan et al. (2011).

Usage

data(antsA)

Format

A data frame with 99 rows (sites) and 46 variables (species abundances)

Source

Calatayud, J., Andivia, E., Escudero, A., Melian, C. J., Bernardo-Madrid, R., Stoffel, M., ... , Madrigal-Gonzalez, J.(2019) Positive associations among rare species and their persistence in ecological assemblages. Nature Ecology & Evolution, 4: 40-45. doi: 10.6084/m9.figshare.9906092.

References

Arnan, X., Gaucherel, C., Andersen, A. N. (2011) Dominance and species co-occurrence in highly diverse ant communities: a test of the interstitial hypothesis and discovery of a three-tiered competition cascade. Oecologia, 166: 783-794. doi: 10.1007/s00442-011-1919-y.

Examples

data(antsA)
FQAnts <- fuzzyq(antsA, sorting = TRUE)

Fuzzy Quantification of Common and Rare Species in Ecological Communities

Description

Perform fuzzy clustering of each species based on their abundance and occupancy.

Usage

fuzzyq(
  M,
  diss = "gower",
  rm.absent = FALSE,
  sorting = TRUE,
  keep.Diss = FALSE,
  std = FALSE,
  wgts = c(1, 1),
  ...
)

Arguments

M

A matrix or data frame of species abundances (columns). Each row represents a site.

diss

String. Specify the dissimilarity coefficient to be used. Default is "gower". See daisy in package cluster for other choices.

rm.absent

Logical. Whether or not absent species are to be removed from the calculations.

sorting

Logical. If TRUE (the default) species are sorted in the output by ascending silhouette widths within each cluster, else species are arranged in the same order as in the input matrix or data frame.

keep.Diss

Logical. Whether or not the species dissimilarity matrix shoudl be returned. The default is FALSE.

std

Logical. Whether or not the measurements of occupancy and abundance are to be standardized before calculating the dissimilarities. Measurements are standardized for each variable (column), by subtracting the variable's mean value and dividing by the variable's mean absolute deviation. It only takes effect if diss is different from "gower".

wgts

an optional numeric vector of length 2. To be used if diss = "gower", specifying weights for occupancy and abundance, respectively. Default is 1 each as in Gower's original formula.

...

Arguments to be passed to function fanny in package cluster.

Value

A list of class fuzzyq containing the following:

A_O

Abundance-occupancy information for each species.

Diss

Object of class dist with pairwise dissimilarities among species based on A_O. (only if keep.Diss = TRUE).

spp

Clustering metrics per species: Cluster membership (where 0 and 1 denote allocation to the rare and common category, respectively), Silhouette Widths and Commonness Indices).

global

Community level clustering metrics: Average silhouette widths per cluster and globally, Mean commonness indices per cluster and Normalized Dunn's coefficient.

See Also

fanny and daisy in package cluster

Examples

data(antsA)
FQAnts <- fuzzyq(antsA, sorting = TRUE)

Apply Fuzzy Quantification of Common and Rare Species to Bootstrap Replicates

Description

Produce N replicates of the original site by species matrix or dataframe by taking bootstrap samples of sites (rows) and apply fuzzyq to each replicate.

Usage

fuzzyqBoot(
  M,
  N = 1000,
  level = "spp",
  std = FALSE,
  rm.absent = FALSE,
  wgts = c(1, 1),
  ...
)

Arguments

M

A matrix or dataframe of species abundaces (columns). Each row represents a site.

N

Integer. Number of bootstrap replicates desired. Default is 1,000.

level

String. Specifiy the type of metrics to be computed for each bootstrap replicate. Either "spp" or "global", corresponding to species or community-level metrics, respectively.

std

Logical. Whether or not the measurements of occupancy and abundance are to be standardized before calculating the dissimilarities. Measurements are standardized for each variable (column), by subtracting the variable's mean value and dividing by the variable's mean absolute deviation. It only takes effect if diss is different from "gower".

rm.absent

Logical. Whether or not absent species are to be removed from the calculations.

wgts

an optional numeric vector of length 2. To be used if diss = "gower", specifying weights for occupancy and abundance, respectively. Default is c(1, 1) as in Gower's original formula.

...

Arguments to be passed to function fanny in package cluster.

Value

A list consisting of the following:

bs.rep

Matrix of estimated metrics. Replicates are arranged in rows. If level = "spp", columns represent estimates of Commonness Indices per species. If level = "global", columns represent estimates of community-level clustering metrics: Average silhouette widths per cluster and globally, Mean commonness indices per cluster and Normalized Dunn's coefficient.

level

Flag indicating whether the estimates are taken at species ("spp") or community level ("global").

Examples

data(antsA)
FQAnts <- fuzzyq(antsA, sorting = TRUE)

# Compute species Commonness Indices of species of 1,000 bootstrap
# replicates:
BS.FQAnts <- fuzzyqBoot (antsA, N = 1e3, level='spp')

# Compute global metrics of 1,000 boostrap replicates:
BS.global <- fuzzyqBoot (antsA, N = 1e3, level='global')

Compute Confidence Intervals of Clustering Metrics

Description

Computes confidence intervals of clustering metrics based on the bootstrap replicates produced by fuzzyqBoot.

Usage

fuzzyqCI(fq.bs, fq = NULL, method = "pct", c.level = 0.95)

Arguments

fq.bs

A list returned by FuzzyQ::fuzzyqBoot.

fq

A list of class fuzzyq returned by FuzzyQ::fuzzyq. Required only if method = "bc" or method = "bca".

method

String. Specify the method to compute confidence intervals. Any of the following: "pct" (percentile, the default), "bc" (bias corrected), "bca" (bias corrected and accelerated).

c.level

Number within [0,1]. Specify the confidence interval level. Default is 0.95.

Value

A matrix with upper and lower confidence interval limits of clustering metrics.

Examples

data(antsA)
FQAnts <- fuzzyq(antsA, sorting = TRUE)

# Compute species Commonness Indices of species of 1,000 bootstrap
# replicates:
BS.FQAnts <- fuzzyqBoot (antsA, N = 1e3, level='spp')

# Compute 95 % confidence intervals, percentile method, default values:
BS.sppCI1 <- fuzzyqCI(BS.FQAnts)

# Alternatively, 95 % confidence intervals, bias corrected and accelerated
# method:
BS.sppCI2 <- fuzzyqCI(BS.FQAnts, fq=FQAnts, method = "bca")

# Compute global metrics of 1,000 boostrap replicates:
BS.global <- fuzzyqBoot (antsA, N = 1e3, level='global')

# Compute 95 % confidence intervals, bias corrected and accelerated method:
BS.globalCI <- fuzzyqCI(BS.global, fq=FQAnts, method = "bca")

Sort Species by fuzzyq Clustering

Description

Sort species in a matrix or data frame to match the resulting species order of a fuzzyq object. This is useful prior to plotting Commonness Indices derived from bootstrap replicates.

Usage

sortClus(M, fq)

Arguments

M

A matrix or data frame with information of species in columns.

fq

A list of class fuzzyq returned by FuzzyQ::fuzzyq.

Value

A matrix or data frame with information of species in columns sorted according to fq$spp.

Examples

data(antsA)
FQAnts <- fuzzyq(antsA, sorting = TRUE)
# Compute species Commonness Indices of species of 1,000 bootstrap
# replicates:
BS.FQAnts <- fuzzyqBoot (antsA, N = 1e3, level='spp')

# Compute 95 % confidence intervals, percentile method, default values:
BS.sppCI1 <- fuzzyqCI(BS.FQAnts)

# Plot Commonness Indices and their respective confidence intervals:
BS.sppCI1 <- sortClus(BS.sppCI1, FQAnts)
spp <- FQAnts$spp
col.RC <- c("brown2", "turquoise3") # two colors to plot rare and common
# species
plot(spp[, 3], cex.axis = 0.8, xaxt= 'n', ylab = "Commoness index",
   ylim = c(0, max(BS.sppCI1)), xlab = "Species", col = col.RC[spp[, 1] + 1],
   pch = 16, cex = 0.8, las = 1)
ebar.int <- seq_len(nrow(spp))
arrows(ebar.int, BS.sppCI1["Lower", ], ebar.int, BS.sppCI1["Upper", ],
   length= 0, col = col.RC[spp[, 1] + 1])
axis(1, at = ebar.int, labels = rownames(spp), las = 2, cex.axis = 0.6)