Package {AntClassify}

Type: Package
Title: Functional Guilds, Invasion Status, Endemism, and Rarity of Ants
Version: 0.2.1
Date: 2026-05-06
Description: Provides functions for the analysis of ant communities, aiming to standardize workflows in myrmecology. The package automates the assignment of species to functional guilds based on trophic strategies, feeding habits, and foraging behavior, using established classification frameworks (Silva et al., 2015 <doi:10.7476/9788574554419>; Silvestre et al., 2003 <isbn:9588151236>; Delabie et al., 2000 https://www.researchgate.net/publication/44961742_Sampling_Ground-Dwelling_Ants_Case_Studies_from_the_World%27s_Rain_Forests), and also includes a novel classification system implemented within the package, developed from ant species occurring in urban environments. It also includes routines to flag exotic species of Brazil (Vieira, 2025, unpublished master's thesis), identify endemic species (Silva et al., 2025 <doi:10.37885/250920259>), and classify species rarity and rarity forms of the Atlantic Forest (Silva et al., 2024 <doi:10.1016/j.biocon.2024.110640>). The package reduces manual effort and improves reproducibility, supporting research and biodiversity management of Neotropical ant communities.
License: MIT + file LICENSE
URL: https://github.com/cogdebora/AntClassify
BugReports: https://github.com/cogdebora/AntClassify/issues
Encoding: UTF-8
LazyData: true
RoxygenNote: 7.3.3
Depends: R (≥ 3.5)
Imports: dplyr, ggplot2, jsonlite, magrittr, rlang, scales, stats, stringr, curl
Suggests: knitr, rmarkdown, testthat (≥ 3.0.0)
VignetteBuilder: knitr
Config/testthat/edition: 3
NeedsCompilation: no
Packaged: 2026-05-06 15:27:57 UTC; 55119
Author: Débora C. O. Gonçalves [aut, cre], Nathalia S. Silva [aut], Rony P. S. Almeida [aut], Lívia P. Prado [aut], Maria S. C. Morini [aut]
Maintainer: Débora C. O. Gonçalves <debora_cog@outlook.com>
Repository: CRAN
Date/Publication: 2026-05-07 08:02:24 UTC

Ant community example

Description

A sample community matrix of ant species abundances with 3 sites and 6 species. Rows represent sites, columns represent species.

Usage

data(ant_community)

Format

A data frame with 3 rows and 6 columns:

Atta sexdens

abundance of Atta sexdens

Camponotus atriceps

abundance of Camponotus atriceps

Pheidole megacephala

abundance of Pheidole megacephala

Wasmannia auropunctata

abundance of Wasmannia auropunctata

Solenopsis saevissima

abundance of Solenopsis saevissima

Nylanderia fulva

abundance of Nylanderia fulva

Source

Simulated data for package examples.

Examples

data(ant_community)
head(ant_community)

AntClassify Full Ecological Pipeline

Description

Runs all ecological classification functions of the package.

Usage

antclassify(comm, verbose = TRUE, plot = TRUE, validate = TRUE, delay = 0.5)

Arguments

comm

Community matrix (samples x species). Species names as columns, samples as rows.

verbose

Logical; if TRUE, displays progress messages.

plot

Logical; if TRUE, displays guild proportion plots (passed to assign_guild_ants).

validate

Logical; if TRUE, validates species names using GBIF.

delay

Numeric; seconds between API calls (if validate = TRUE).

Value

A list containing results from all analyses (guilds, exotic, endemic, rarity).

Examples

## Not run: 
# Load the built-in example dataset
data(ant_community)

# Run the full pipeline (validation disabled for speed)
resultado <- antclassify(ant_community, validate = FALSE, plot = FALSE)

# Inspect the results
names(resultado)
head(resultado$guilds$table)
resultado$exotic$table
resultado$endemic$table
resultado$rarity$table

## End(Not run)

Classify Ant Communities Across Multiple Sites

Description

Applies the AntClassify pipeline to each site (row) of a community matrix and returns aggregated guild abundance and richness matrices.

Usage

antclassify_community(comm, guild_col = "antclassify_guild", ...)

Arguments

comm

A community matrix with sites as rows and species as columns. Species names must match the nomenclature used in the internal databases.

guild_col

Character string giving the name of the guild column to use for aggregation. Must be one of "antclassify_guild", "silva_guild", "delabie_guild", or "silvestre_guild". Default is "antclassify_guild".

...

Additional arguments passed to assign_guild_ants (for example, validate, delay). Note that plot is always set to FALSE inside this function to avoid displaying one plot per site.

Value

A list with three components:

by_site

A list of length equal to nrow(comm). Each element contains the full output of assign_guild_ants for the corresponding site.

guild_abundance

A matrix of guild abundances (sites × guilds).

guild_richness

A numeric vector of length nrow(comm) giving the number of distinct guilds found at each site.

Examples

# Small community matrix with two sites and six species
comm <- matrix(c(5, 0, 2, 0, 1, 3,
                 2, 4, 0, 2, 0, 0),
               nrow = 2, byrow = TRUE,
               dimnames = list(c("Site1", "Site2"),
                               c("Atta sexdens", "Camponotus atriceps",
                                 "Pheidole megacephala", "Wasmannia auropunctata",
                                 "Solenopsis saevissima", "Nylanderia fulva")))

# Run the classification (validate = FALSE to avoid GBIF calls in examples)
res <- antclassify_community(comm, guild_col = "antclassify_guild",
                             validate = FALSE)
res$guild_abundance
res$guild_richness

Assign Functional Guilds for Ants

Description

Classifies ants into functional guilds using four different ecological databases.

Usage

assign_guild_ants(
  comm,
  verbose = TRUE,
  plot = TRUE,
  validate = TRUE,
  delay = 0.5
)

Arguments

comm

A community matrix where species are columns and samples are rows.

verbose

Logical; if TRUE, displays progress messages.

plot

Logical; if TRUE, displays guild proportion plots.

validate

Logical; if TRUE, validates species names using GBIF before analysis.

delay

Numeric; seconds to wait between GBIF API calls when validate = TRUE.

Value

Invisibly returns a list with two elements:

table

A data frame containing species, abundance, percentage, and guild assignments from each system.

plots

A list of four ggplot2 objects, one for each guild classification system.

Identify Endemic Ant Species (Atlantic Forest)

Description

Checks a community matrix for ant species endemic to the Brazilian Atlantic Forest based on Silva et al. (2025).

Usage

check_endemic_atlantic_ants(
  comm,
  verbose = TRUE,
  plot = TRUE,
  plot_type = c("status", "species"),
  validate = TRUE,
  delay = 0.5
)

Arguments

comm

A community matrix where species are columns and samples are rows.

verbose

Logical; if TRUE, displays progress messages.

plot

Logical; if TRUE, displays a plot (type controlled by plot_type).

plot_type

Character; type of plot to display. "status" (default) shows a bar plot comparing endemic vs. other species abundance proportions. "species" shows a bar plot of individual endemic species abundances as a proportion of the total community.

validate

Logical; if TRUE, validates species names using GBIF before analysis.

delay

Numeric; seconds to wait between GBIF API calls when validate = TRUE.

Value

Invisibly returns a list with two elements:

table

A data frame containing endemic species detected, with columns species, abundance, and percentage.

plot

A ggplot2 object.

Identify Exotic Ant Species (Brazil)

Description

Checks a community matrix for known exotic ant species in Brazil sourced from Vieira (2025).

Usage

check_exotic_ants(
  comm,
  verbose = TRUE,
  plot = TRUE,
  plot_type = c("status", "species"),
  validate = TRUE,
  delay = 0.5
)

Arguments

comm

A community matrix where species are columns and samples are rows.

verbose

Logical; if TRUE, displays progress messages.

plot

Logical; if TRUE, displays a plot (type controlled by plot_type).

plot_type

Character; type of plot to display. "status" (default) shows a bar plot comparing exotic vs. native abundance proportions. "species" shows a bar plot of individual exotic species abundances as a proportion of the total community.

validate

Logical; if TRUE, validates species names using GBIF before analysis.

delay

Numeric; seconds to wait between GBIF API calls when validate = TRUE.

Value

Invisibly returns a list with two elements:

table

A data frame containing exotic species detected, with columns species, abundance, and percentage.

plot

A ggplot2 object.

Identify Ant Rarity Forms (Atlantic Forest)

Description

Checks a community matrix for ant rarity forms in the Brazilian Atlantic Forest based on Silva et al. (2024).

Usage

check_rarity_atlantic_ants(
  comm,
  verbose = TRUE,
  plot = TRUE,
  plot_type = c("status", "species"),
  validate = TRUE,
  delay = 0.5
)

Arguments

comm

A community matrix where species are columns and samples are rows.

verbose

Logical; if TRUE, displays progress messages.

plot

Logical; if TRUE, displays a plot (type controlled by plot_type).

plot_type

Character; type of plot to display. "status" (default) shows a bar plot of rarity form abundance proportions. "species" shows a bar plot of individual rare species abundances as a proportion of the total community, colored by rarity form.

validate

Logical; if TRUE, validates species names using GBIF before analysis.

delay

Numeric; seconds to wait between GBIF API calls when validate = TRUE.

Value

Invisibly returns a list with two elements:

table

A data frame containing rare species detected, with columns species, rarity_form, abundance, and percentage.

plot

A ggplot2 object.

Internal datasets used by AntClassify.

Description

Internal datasets used by AntClassify.

Usage

delabie_db

endemic_db

exotic_db

generic_db

rarity_db

silva_db

silvestre_db

Format

Data frames

An object of class data.frame with 49 rows and 2 columns.

An object of class data.frame with 19 rows and 2 columns.

An object of class data.frame with 45 rows and 2 columns.

An object of class data.frame with 120 rows and 3 columns.

An object of class data.frame with 58 rows and 2 columns.

An object of class data.frame with 66 rows and 2 columns.

Validate Species Names Using GBIF API

Description

Checks species names against the GBIF taxonomic backbone. If an exact match is found, the accepted name (or canonical name) is used. If no exact match is found, the original name is kept and a warning is issued, indicating that the name may be outdated or misspelled.

Usage

validate_species_names(comm, verbose = TRUE, delay = 0.5)

Arguments

comm

A community matrix (rows = sites, columns = species).

verbose

Logical; if TRUE, displays progress messages.

delay

Numeric; seconds to wait between API calls (default 0.5).

Value

A community matrix with updated column names (accepted names when available).

Examples

## Not run: 
data(ant_community)
comm_validated <- validate_species_names(ant_community, verbose = TRUE)

## End(Not run)