Package 'FuzzyQ' reference manual

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>).
Authors:	Juan A. Balbuena [aut, cre, cph] , Clara Monlleó-Borrull [aut, cph], Cristina Llopis-Belenguer [aut, cph] , Isabel Blasco-Costa [aut, cph] , Volodimir Saraveeb [aut, cph] , Serge Morand [aut, cph]
Maintainer:	Juan A. Balbuena <[email protected]>
License:	GPL-3
Version:	0.1.0
Built:	2024-11-20 04:19:35 UTC
Source:	https://github.com/ligophorus/fuzzyq

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

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

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

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

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

Examples

data(antsA)
FQAnts <- fuzzyq(antsA, sorting = TRUE)
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),
  ...
)
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')
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)
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")

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

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

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

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

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

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)

Package 'FuzzyQ'

Help Index

Ant species abundance from Arnan et el. (2011)

Description

Usage

Format

Source

References

Examples

Abundance Occupancy Plot

Description

Usage

Arguments

Value

Examples

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

Description

Usage

Format

Source

References

Examples

Fuzzy Quantification of Common and Rare Species in Ecological Communities

Description

Usage

Arguments

Value

See Also

Examples

Apply Fuzzy Quantification of Common and Rare Species to Bootstrap Replicates

Description

Usage

Arguments

Value

Examples

Compute Confidence Intervals of Clustering Metrics

Description

Usage

Arguments

Value

Examples

Helminth communities of so-iuy mullets from the Japan Sea

Description

Usage

Format

Source

References

Examples

Sort Species by fuzzyq Clustering

Description

Usage

Arguments

Value

Examples