antclassify_workflow.knit

title: “AntClassify: An R Package for Standardized Classification of Ant Communities, Functional Guilds, Endemism, and Rarity” output: rmarkdown::html_vignette vignette: > % % %

    library(AntClassify)

## Introduction

The AntClassify package provides an integrated ecological pipeline to classify ant communities into functional guilds, identify exotic species, detect endemic and rare species of the Atlantic Forest, and quantify key ecological patterns.

This tool was developed to facilitate ecological analyses, standardize functional classification, and improve reproducibility in ant community studies. By integrating multiple ecological databases into a single workflow, AntClassify allows researchers to efficiently assess community structure, biological invasions, endemism, and rarity patterns.

The package is particularly useful for biodiversity monitoring, conservation planning, and macroecological research involving ant assemblages.

AntClassify aims to provide a standardized and reproducible framework for advancing ecological research on ant communities.

## Example dataset

    dados <- data.frame(
      Atta_sexdens = 50,
      Camponotus_atriceps = 40,
      Crematogaster_sp = 35,
      Cyphomyrmex_minutus = 30,
      Cyphomyrmex_rimosus = 28,
      Ectatomma_edentatum = 25,
      Heteroponera_mayri = 22,
      Holcoponera_striatula = 20,
      Monomorium_floricola = 18,
      Monomorium_pharaonis = 17,
      Pheidole_megacephala = 16,
      Strumigenys_emmae = 15,
      Strumigenys_rogeri = 14,
      Nylanderia_fulva = 13,
      Odontomachus_chelifer = 12,
      Oxyepoecus_reticulatus = 11,
      Pachycondyla_striata = 10,
      Apterostigma_serratum = 9,
      Brachymyrmex_delabiei = 8,
      Brachymyrmex_feitosai = 7,
      Camponotus_fallatus = 6,
      Camponotus_hermanni = 5,
      Camponotus_xanthogaster = 4,
      Pheidole_aberrans = 3,
      Pheidole_fimbriata = 3,
      Pheidole_obscurithorax = 2,
      Pheidole_subarmata = 2,
      Strumigenys_fridericimuelleri = 2,
      Heteroponera_inermis = 2,
      Oxyepoecus_browni = 2,
      Sphinctomyrmex_stali = 1,
      Strumigenys_sanctipauli = 1,
      Brachymyrmex_micromegas = 1,
      Camponotus_tripartitus = 1,
      Diaphoromyrma_sofiae = 1
    )

    colnames(dados) <- gsub("_", " ", colnames(dados))

    dados
    #>   Atta sexdens Camponotus atriceps Crematogaster sp Cyphomyrmex minutus
    #> 1           50                  40               35                  30
    #>   Cyphomyrmex rimosus Ectatomma edentatum Heteroponera mayri
    #> 1                  28                  25                 22
    #>   Holcoponera striatula Monomorium floricola Monomorium pharaonis
    #> 1                    20                   18                   17
    #>   Pheidole megacephala Strumigenys emmae Strumigenys rogeri Nylanderia fulva
    #> 1                   16                15                 14               13
    #>   Odontomachus chelifer Oxyepoecus reticulatus Pachycondyla striata
    #> 1                    12                     11                   10
    #>   Apterostigma serratum Brachymyrmex delabiei Brachymyrmex feitosai
    #> 1                     9                     8                     7
    #>   Camponotus fallatus Camponotus hermanni Camponotus xanthogaster
    #> 1                   6                   5                       4
    #>   Pheidole aberrans Pheidole fimbriata Pheidole obscurithorax
    #> 1                 3                  3                      2
    #>   Pheidole subarmata Strumigenys fridericimuelleri Heteroponera inermis
    #> 1                  2                             2                    2
    #>   Oxyepoecus browni Sphinctomyrmex stali Strumigenys sanctipauli
    #> 1                 2                    1                       1
    #>   Brachymyrmex micromegas Camponotus tripartitus Diaphoromyrma sofiae
    #> 1                       1                      1                    1

## Running the pipeline

    resultado <- antclassify(dados, validate = FALSE, plot = FALSE)
    #> *************************************************
    #> Starting AntClassify
    #> *************************************************
    #>
    #> >>> Running guild classification
    #> Step 1: Preparing community data...
    #> Step 2: Matching species to functional guilds...
    #>
    #> Guild classification results (first 6 rows):
    #>                                 species abundance percentage
    #> Atta sexdens               Atta sexdens        50  11.467890
    #> Camponotus atriceps Camponotus atriceps        40   9.174312
    #> Crematogaster sp       Crematogaster sp        35   8.027523
    #> Cyphomyrmex minutus Cyphomyrmex minutus        30   6.880734
    #> Cyphomyrmex rimosus Cyphomyrmex rimosus        28   6.422018
    #> Ectatomma edentatum Ectatomma edentatum        25   5.733945
    #>                                                                                      antclassify_guild
    #> Atta sexdens                                              Fungus-growers (soil or leaf litter nesting)
    #> Camponotus atriceps Generalist omnivores (dominant or opportunistic in soil, leaf litter, or arboreal)
    #> Crematogaster sp    Generalist omnivores (dominant or opportunistic in soil, leaf litter, or arboreal)
    #> Cyphomyrmex minutus                                       Fungus-growers (soil or leaf litter nesting)
    #> Cyphomyrmex rimosus                                       Fungus-growers (soil or leaf litter nesting)
    #> Ectatomma edentatum                  Generalist predators (dominant or cryptic in soil or leaf litter)
    #>                                               silva_guild
    #> Atta sexdens                           Unidentified Guild
    #> Camponotus atriceps                    Unidentified Guild
    #> Crematogaster sp                       Unidentified Guild
    #> Cyphomyrmex minutus                    Unidentified Guild
    #> Cyphomyrmex rimosus                    Unidentified Guild
    #> Ectatomma edentatum Generalist predatory ectaheteromorphs
    #>                                                 delabie_guild
    #> Atta sexdens                          Attini (Fungus-growers)
    #> Camponotus atriceps        Omnivorous soil-and-litter species
    #> Crematogaster sp           Omnivorous soil-and-litter species
    #> Cyphomyrmex minutus                   Attini (Fungus-growers)
    #> Cyphomyrmex rimosus                   Attini (Fungus-growers)
    #> Ectatomma edentatum Large Ponerinae (Large epigeic predators)
    #>                                                     silvestre_guild
    #> Atta sexdens                                     Unidentified Guild
    #> Camponotus atriceps              Generalist patrolling Camponotines
    #> Crematogaster sp    Small arboreal species with massive recruitment
    #> Cyphomyrmex minutus           Cryptic fungus-growing ants (Attines)
    #> Cyphomyrmex rimosus           Cryptic fungus-growing ants (Attines)
    #> Ectatomma edentatum                                 Large predators
    #> Step 3: Generating plots...
    #>
    #> ********************************************************************************
    #> IMPORTANT NOTICE:
    #> Please verify all assigned guilds. 'Unidentified Guild' indicates that the
    #> taxon was not found in the available reference databases.
    #> Guild classification in this analysis follows:
    #> - Literature-based criteria from:
    #>   Silvestre, R., Brandão, C. R. F., & Silva, R. R. (2003).
    #>   Grupos funcionales de hormigas: el caso de los gremios del Cerrado.
    #>   In F. Fernández (Ed.), *Introducción a las Hormigas de las Región Neotropical*
    #>   (pp. 113-148). Instituto Alexander Von Humboldt.
    #>   Silva, R. R., Silvestre, R., Brandão, C. R. F., Morini, M. S. C., & Delabie, J. H. C. (2015).
    #>   Grupos tróficos e guildas em formigas poneromorfas. In: Delabie, J. H. C. et al.
    #>   *As formigas poneromorfas do Brasil*. Ilhéus: Editus, 2015. p. 163-179.
    #>   Delabie, J. H. C., Agosti, D., & Nascimento, I. C. (2000).
    #>   Litter ant communities of the Brazilian Atlantic rain forest region.
    #>   *Sampling Ground-dwelling Ants: case studies from the world's rain forests.
    #>   Curtin University of Technology School of Environmental Biology Bulletin*, v. 18.
    #> - The 'AntClassify Guilds' classification corresponds to the internal
    #>   classification system implemented in the AntClassify package.
    #> ********************************************************************************
    #>
    #> >>> Checking exotic species
    #> Starting validation of species names via GBIF...
    #> Processing [1/35]: Atta sexdens
    #> Processing [2/35]: Camponotus atriceps
    #> Processing [3/35]: Crematogaster sp
    #> Processing [4/35]: Cyphomyrmex minutus
    #> Processing [5/35]: Cyphomyrmex rimosus
    #> Processing [6/35]: Ectatomma edentatum
    #> Processing [7/35]: Heteroponera mayri
    #> Processing [8/35]: Holcoponera striatula
    #> Processing [9/35]: Monomorium floricola
    #> Processing [10/35]: Monomorium pharaonis
    #> Processing [11/35]: Pheidole megacephala
    #> Processing [12/35]: Strumigenys emmae
    #> Processing [13/35]: Strumigenys rogeri
    #> Processing [14/35]: Nylanderia fulva
    #> Processing [15/35]: Odontomachus chelifer
    #> Processing [16/35]: Oxyepoecus reticulatus
    #> Processing [17/35]: Pachycondyla striata
    #> Processing [18/35]: Apterostigma serratum
    #> Processing [19/35]: Brachymyrmex delabiei
    #> Processing [20/35]: Brachymyrmex feitosai
    #> Processing [21/35]: Camponotus fallatus
    #> Processing [22/35]: Camponotus hermanni
    #> Processing [23/35]: Camponotus xanthogaster
    #> Processing [24/35]: Pheidole aberrans
    #> Processing [25/35]: Pheidole fimbriata
    #> Processing [26/35]: Pheidole obscurithorax
    #> Processing [27/35]: Pheidole subarmata
    #> Processing [28/35]: Strumigenys fridericimuelleri
    #> Processing [29/35]: Heteroponera inermis
    #> Processing [30/35]: Oxyepoecus browni
    #> Processing [31/35]: Sphinctomyrmex stali
    #> Processing [32/35]: Strumigenys sanctipauli
    #> Processing [33/35]: Brachymyrmex micromegas
    #> Processing [34/35]: Camponotus tripartitus
    #> Processing [35/35]: Diaphoromyrma sofiae
    #> Warning in validate_species_names(comm, verbose = verbose, delay = delay): 2
    #> species name(s) could not be validated by GBIF: Crematogaster sp, Apterostigma
    #> serratum
    #>
    #> *** ATTENTION: The following names were not found or are no longer current:
    #>    - Crematogaster sp
    #>    - Apterostigma serratum
    #>    Please verify these names manually before proceeding.
    #> Step 1: Preparing community data...
    #> Step 2: Generating results...
    #>
    #> ********************************************************************************
    #> EXOTIC SPECIES DETECTED:
    #>                species abundance percentage
    #> 1 Monomorium floricola        18   4.128440
    #> 2 Monomorium pharaonis        17   3.899083
    #> 3 Pheidole megacephala        16   3.669725
    #> 4    Strumigenys emmae        15   3.440367
    #> 5   Strumigenys rogeri        14   3.211009
    #>
    #> DATA SOURCE AND REFERENCE:
    #> The exotic species list used in this function is sourced from:
    #> VIEIRA, Vitoria Brunetta. 'Quem são e onde estão as formigas exóticas do Brasil?'
    #> Dissertacao (Mestrado em Entomologia) – Universidade Federal do Parana (UFPR),
    #> Curitiba, Brasil, 2025.
    #> ********************************************************************************
    #>
    #> >>> Checking Atlantic Forest endemic species
    #> Starting validation of species names via GBIF...
    #> Processing [1/35]: Atta sexdens
    #> Processing [2/35]: Camponotus atriceps
    #> Processing [3/35]: Crematogaster sp
    #> Processing [4/35]: Cyphomyrmex minutus
    #> Processing [5/35]: Cyphomyrmex rimosus
    #> Processing [6/35]: Ectatomma edentatum
    #> Processing [7/35]: Heteroponera mayri
    #> Processing [8/35]: Holcoponera striatula
    #> Processing [9/35]: Monomorium floricola
    #> Processing [10/35]: Monomorium pharaonis
    #> Processing [11/35]: Pheidole megacephala
    #> Processing [12/35]: Strumigenys emmae
    #> Processing [13/35]: Strumigenys rogeri
    #> Processing [14/35]: Nylanderia fulva
    #> Processing [15/35]: Odontomachus chelifer
    #> Processing [16/35]: Oxyepoecus reticulatus
    #> Processing [17/35]: Pachycondyla striata
    #> Processing [18/35]: Apterostigma serratum
    #> Processing [19/35]: Brachymyrmex delabiei
    #> Processing [20/35]: Brachymyrmex feitosai
    #> Processing [21/35]: Camponotus fallatus
    #> Processing [22/35]: Camponotus hermanni
    #> Processing [23/35]: Camponotus xanthogaster
    #> Processing [24/35]: Pheidole aberrans
    #> Processing [25/35]: Pheidole fimbriata
    #> Processing [26/35]: Pheidole obscurithorax
    #> Processing [27/35]: Pheidole subarmata
    #> Processing [28/35]: Strumigenys fridericimuelleri
    #> Processing [29/35]: Heteroponera inermis
    #> Processing [30/35]: Oxyepoecus browni
    #> Processing [31/35]: Sphinctomyrmex stali
    #> Processing [32/35]: Strumigenys sanctipauli
    #> Processing [33/35]: Brachymyrmex micromegas
    #> Processing [34/35]: Camponotus tripartitus
    #> Processing [35/35]: Diaphoromyrma sofiae
    #> Warning in validate_species_names(comm, verbose = verbose, delay = delay): 2
    #> species name(s) could not be validated by GBIF: Crematogaster sp, Apterostigma
    #> serratum
    #>
    #> *** ATTENTION: The following names were not found or are no longer current:
    #>    - Crematogaster sp
    #>    - Apterostigma serratum
    #>    Please verify these names manually before proceeding.
    #>
    #> **********************************************************************************
    #> ATTENTION: This function identifies endemic species of the BRAZILIAN ATLANTIC FOREST.
    #> If your data collection did not occur within this biome, this analysis may not
    #> be appropriate for your study.
    #> **********************************************************************************
    #> Step 1: Preparing community data...
    #> Step 2: Generating results...
    #>
    #> ********************************************************************************
    #> ENDEMIC SPECIES DETECTED (ATLANTIC FOREST):
    #>                 species abundance percentage
    #> 1 Apterostigma serratum         9   2.064220
    #> 2 Brachymyrmex delabiei         8   1.834862
    #> 3 Brachymyrmex feitosai         7   1.605505
    #> 4   Camponotus fallatus         6   1.376147
    #> 5   Camponotus hermanni         5   1.146789
    #>
    #> DATA SOURCE AND REFERENCE:
    #> The endemic species list is sourced from:
    #> Silva, N. S., Goncalves, D. C. de O., Wazema, C. T., Barbosa, D. A., Prado, L. P. do,
    #> Andrade-Silva, J., Fernandes, T. T., Silva, R. R., & Morini, M. S. de C. (2025).
    #> 'Endemism and vulnerability of ants in the phytophysiognomies of the Brazilian
    #> Atlantic Forest'. In: Brazilian Myrmecology: Exploring the World’s Richest Ant Fauna
    #> (Chapter 16). Editora Cientifica Digital. DOI: 10.37885/250920259.
    #> ********************************************************************************
    #>
    #> >>> Checking Atlantic Forest rarity patterns
    #> Starting validation of species names via GBIF...
    #> Processing [1/35]: Atta sexdens
    #> Processing [2/35]: Camponotus atriceps
    #> Processing [3/35]: Crematogaster sp
    #> Processing [4/35]: Cyphomyrmex minutus
    #> Processing [5/35]: Cyphomyrmex rimosus
    #> Processing [6/35]: Ectatomma edentatum
    #> Processing [7/35]: Heteroponera mayri
    #> Processing [8/35]: Holcoponera striatula
    #> Processing [9/35]: Monomorium floricola
    #> Processing [10/35]: Monomorium pharaonis
    #> Processing [11/35]: Pheidole megacephala
    #> Processing [12/35]: Strumigenys emmae
    #> Processing [13/35]: Strumigenys rogeri
    #> Processing [14/35]: Nylanderia fulva
    #> Processing [15/35]: Odontomachus chelifer
    #> Processing [16/35]: Oxyepoecus reticulatus
    #> Processing [17/35]: Pachycondyla striata
    #> Processing [18/35]: Apterostigma serratum
    #> Processing [19/35]: Brachymyrmex delabiei
    #> Processing [20/35]: Brachymyrmex feitosai
    #> Processing [21/35]: Camponotus fallatus
    #> Processing [22/35]: Camponotus hermanni
    #> Processing [23/35]: Camponotus xanthogaster
    #> Processing [24/35]: Pheidole aberrans
    #> Processing [25/35]: Pheidole fimbriata
    #> Processing [26/35]: Pheidole obscurithorax
    #> Processing [27/35]: Pheidole subarmata
    #> Processing [28/35]: Strumigenys fridericimuelleri
    #> Processing [29/35]: Heteroponera inermis
    #> Processing [30/35]: Oxyepoecus browni
    #> Processing [31/35]: Sphinctomyrmex stali
    #> Processing [32/35]: Strumigenys sanctipauli
    #> Processing [33/35]: Brachymyrmex micromegas
    #> Processing [34/35]: Camponotus tripartitus
    #> Processing [35/35]: Diaphoromyrma sofiae
    #> Warning in validate_species_names(comm, verbose = verbose, delay = delay): 2
    #> species name(s) could not be validated by GBIF: Crematogaster sp, Apterostigma
    #> serratum
    #>
    #> *** ATTENTION: The following names were not found or are no longer current:
    #>    - Crematogaster sp
    #>    - Apterostigma serratum
    #>    Please verify these names manually before proceeding.
    #>
    #> ********************************************************************************
    #> ATTENTION:
    #> This function identifies rare ant species and their rarity forms.
    #> This classification is specific to the Brazilian Atlantic Forest and
    #> may not be appropriate for other biomes.
    #> ********************************************************************************
    #> Step 1: Preparing community data and rarity database...
    #> Step 2: Generating results...
    #>
    #> ********************************************************************************
    #> RARE SPECIES DETECTED:
    #>                          species rarity_form abundance percentage
    #> 1          Brachymyrmex feitosai      Form 4         7  1.6055046
    #> 2        Brachymyrmex micromegas      Form 7         1  0.2293578
    #> 3            Camponotus atriceps      Form 2        40  9.1743119
    #> 4         Camponotus tripartitus      Form 7         1  0.2293578
    #> 5           Diaphoromyrma sofiae      Form 7         1  0.2293578
    #> 6           Heteroponera inermis      Form 4         2  0.4587156
    #> 7              Oxyepoecus browni      Form 6         2  0.4587156
    #> 8         Oxyepoecus reticulatus      Form 1        11  2.5229358
    #> 9              Pheidole aberrans      Form 2         3  0.6880734
    #> 10            Pheidole fimbriata      Form 2         3  0.6880734
    #> 11        Pheidole obscurithorax      Form 2         2  0.4587156
    #> 12            Pheidole subarmata      Form 2         2  0.4587156
    #> 13          Sphinctomyrmex stali      Form 6         1  0.2293578
    #> 14 Strumigenys fridericimuelleri      Form 3         2  0.4587156
    #> 15       Strumigenys sanctipauli      Form 6         1  0.2293578
    #>
    #> DATA SOURCE AND REFERENCE:
    #> Silva, N. S., Maciel, E. A., Prado, L. P., Silva, O. G., Barbosa, D. A.,
    #> Andrade-Silva, J., ... & Morini, M. S. (2024).
    #> 'Ant rarity and vulnerability in Brazilian Atlantic Forest fragments.'
    #> Biological Conservation, 296, 110640.
    #> ********************************************************************************
    #>
    #> ***********************************************
    #> AntClassify finished successfully
    #> *************************************************

## Accessing results

    names(resultado)
    #> [1] "guilds"  "exotic"  "endemic" "rarity"

    head(resultado$guilds$table)
    #>                                 species abundance percentage
    #> Atta sexdens               Atta sexdens        50  11.467890
    #> Camponotus atriceps Camponotus atriceps        40   9.174312
    #> Crematogaster sp       Crematogaster sp        35   8.027523
    #> Cyphomyrmex minutus Cyphomyrmex minutus        30   6.880734
    #> Cyphomyrmex rimosus Cyphomyrmex rimosus        28   6.422018
    #> Ectatomma edentatum Ectatomma edentatum        25   5.733945
    #>                                                                                      antclassify_guild
    #> Atta sexdens                                              Fungus-growers (soil or leaf litter nesting)
    #> Camponotus atriceps Generalist omnivores (dominant or opportunistic in soil, leaf litter, or arboreal)
    #> Crematogaster sp    Generalist omnivores (dominant or opportunistic in soil, leaf litter, or arboreal)
    #> Cyphomyrmex minutus                                       Fungus-growers (soil or leaf litter nesting)
    #> Cyphomyrmex rimosus                                       Fungus-growers (soil or leaf litter nesting)
    #> Ectatomma edentatum                  Generalist predators (dominant or cryptic in soil or leaf litter)
    #>                                               silva_guild
    #> Atta sexdens                           Unidentified Guild
    #> Camponotus atriceps                    Unidentified Guild
    #> Crematogaster sp                       Unidentified Guild
    #> Cyphomyrmex minutus                    Unidentified Guild
    #> Cyphomyrmex rimosus                    Unidentified Guild
    #> Ectatomma edentatum Generalist predatory ectaheteromorphs
    #>                                                 delabie_guild
    #> Atta sexdens                          Attini (Fungus-growers)
    #> Camponotus atriceps        Omnivorous soil-and-litter species
    #> Crematogaster sp           Omnivorous soil-and-litter species
    #> Cyphomyrmex minutus                   Attini (Fungus-growers)
    #> Cyphomyrmex rimosus                   Attini (Fungus-growers)
    #> Ectatomma edentatum Large Ponerinae (Large epigeic predators)
    #>                                                     silvestre_guild
    #> Atta sexdens                                     Unidentified Guild
    #> Camponotus atriceps              Generalist patrolling Camponotines
    #> Crematogaster sp    Small arboreal species with massive recruitment
    #> Cyphomyrmex minutus           Cryptic fungus-growing ants (Attines)
    #> Cyphomyrmex rimosus           Cryptic fungus-growing ants (Attines)
    #> Ectatomma edentatum                                 Large predators
    resultado$exotics
    #> NULL
    resultado$endemics
    #> NULL
    resultado$rarity
    #> $table
    #>                          species abundance rarity_form percentage
    #> 1          Brachymyrmex feitosai         7      Form 4  1.6055046
    #> 2        Brachymyrmex micromegas         1      Form 7  0.2293578
    #> 3            Camponotus atriceps        40      Form 2  9.1743119
    #> 4         Camponotus tripartitus         1      Form 7  0.2293578
    #> 5           Diaphoromyrma sofiae         1      Form 7  0.2293578
    #> 6           Heteroponera inermis         2      Form 4  0.4587156
    #> 7              Oxyepoecus browni         2      Form 6  0.4587156
    #> 8         Oxyepoecus reticulatus        11      Form 1  2.5229358
    #> 9              Pheidole aberrans         3      Form 2  0.6880734
    #> 10            Pheidole fimbriata         3      Form 2  0.6880734
    #> 11        Pheidole obscurithorax         2      Form 2  0.4587156
    #> 12            Pheidole subarmata         2      Form 2  0.4587156
    #> 13          Sphinctomyrmex stali         1      Form 6  0.2293578
    #> 14 Strumigenys fridericimuelleri         2      Form 3  0.4587156
    #> 15       Strumigenys sanctipauli         1      Form 6  0.2293578
    #>
    #> $plot

## Using individual functions

Although `antclassify()` runs the full pipeline, users can also apply each function separately depending on their research goals.

### Functional guild classification

    guilds <- assign_guild_ants(dados, validate = FALSE, plot = FALSE)
    #> Step 1: Preparing community data...
    #> Step 2: Matching species to functional guilds...
    #>
    #> Guild classification results (first 6 rows):
    #>                                 species abundance percentage
    #> Atta sexdens               Atta sexdens        50  11.467890
    #> Camponotus atriceps Camponotus atriceps        40   9.174312
    #> Crematogaster sp       Crematogaster sp        35   8.027523
    #> Cyphomyrmex minutus Cyphomyrmex minutus        30   6.880734
    #> Cyphomyrmex rimosus Cyphomyrmex rimosus        28   6.422018
    #> Ectatomma edentatum Ectatomma edentatum        25   5.733945
    #>                                                                                      antclassify_guild
    #> Atta sexdens                                              Fungus-growers (soil or leaf litter nesting)
    #> Camponotus atriceps Generalist omnivores (dominant or opportunistic in soil, leaf litter, or arboreal)
    #> Crematogaster sp    Generalist omnivores (dominant or opportunistic in soil, leaf litter, or arboreal)
    #> Cyphomyrmex minutus                                       Fungus-growers (soil or leaf litter nesting)
    #> Cyphomyrmex rimosus                                       Fungus-growers (soil or leaf litter nesting)
    #> Ectatomma edentatum                  Generalist predators (dominant or cryptic in soil or leaf litter)
    #>                                               silva_guild
    #> Atta sexdens                           Unidentified Guild
    #> Camponotus atriceps                    Unidentified Guild
    #> Crematogaster sp                       Unidentified Guild
    #> Cyphomyrmex minutus                    Unidentified Guild
    #> Cyphomyrmex rimosus                    Unidentified Guild
    #> Ectatomma edentatum Generalist predatory ectaheteromorphs
    #>                                                 delabie_guild
    #> Atta sexdens                          Attini (Fungus-growers)
    #> Camponotus atriceps        Omnivorous soil-and-litter species
    #> Crematogaster sp           Omnivorous soil-and-litter species
    #> Cyphomyrmex minutus                   Attini (Fungus-growers)
    #> Cyphomyrmex rimosus                   Attini (Fungus-growers)
    #> Ectatomma edentatum Large Ponerinae (Large epigeic predators)
    #>                                                     silvestre_guild
    #> Atta sexdens                                     Unidentified Guild
    #> Camponotus atriceps              Generalist patrolling Camponotines
    #> Crematogaster sp    Small arboreal species with massive recruitment
    #> Cyphomyrmex minutus           Cryptic fungus-growing ants (Attines)
    #> Cyphomyrmex rimosus           Cryptic fungus-growing ants (Attines)
    #> Ectatomma edentatum                                 Large predators
    #> Step 3: Generating plots...
    #>
    #> ********************************************************************************
    #> IMPORTANT NOTICE:
    #> Please verify all assigned guilds. 'Unidentified Guild' indicates that the
    #> taxon was not found in the available reference databases.
    #> Guild classification in this analysis follows:
    #> - Literature-based criteria from:
    #>   Silvestre, R., Brandão, C. R. F., & Silva, R. R. (2003).
    #>   Grupos funcionales de hormigas: el caso de los gremios del Cerrado.
    #>   In F. Fernández (Ed.), *Introducción a las Hormigas de las Región Neotropical*
    #>   (pp. 113-148). Instituto Alexander Von Humboldt.
    #>   Silva, R. R., Silvestre, R., Brandão, C. R. F., Morini, M. S. C., & Delabie, J. H. C. (2015).
    #>   Grupos tróficos e guildas em formigas poneromorfas. In: Delabie, J. H. C. et al.
    #>   *As formigas poneromorfas do Brasil*. Ilhéus: Editus, 2015. p. 163-179.
    #>   Delabie, J. H. C., Agosti, D., & Nascimento, I. C. (2000).
    #>   Litter ant communities of the Brazilian Atlantic rain forest region.
    #>   *Sampling Ground-dwelling Ants: case studies from the world's rain forests.
    #>   Curtin University of Technology School of Environmental Biology Bulletin*, v. 18.
    #> - The 'AntClassify Guilds' classification corresponds to the internal
    #>   classification system implemented in the AntClassify package.
    #> ********************************************************************************

    head(guilds$table)
    #>                                 species abundance percentage
    #> Atta sexdens               Atta sexdens        50  11.467890
    #> Camponotus atriceps Camponotus atriceps        40   9.174312
    #> Crematogaster sp       Crematogaster sp        35   8.027523
    #> Cyphomyrmex minutus Cyphomyrmex minutus        30   6.880734
    #> Cyphomyrmex rimosus Cyphomyrmex rimosus        28   6.422018
    #> Ectatomma edentatum Ectatomma edentatum        25   5.733945
    #>                                                                                      antclassify_guild
    #> Atta sexdens                                              Fungus-growers (soil or leaf litter nesting)
    #> Camponotus atriceps Generalist omnivores (dominant or opportunistic in soil, leaf litter, or arboreal)
    #> Crematogaster sp    Generalist omnivores (dominant or opportunistic in soil, leaf litter, or arboreal)
    #> Cyphomyrmex minutus                                       Fungus-growers (soil or leaf litter nesting)
    #> Cyphomyrmex rimosus                                       Fungus-growers (soil or leaf litter nesting)
    #> Ectatomma edentatum                  Generalist predators (dominant or cryptic in soil or leaf litter)
    #>                                               silva_guild
    #> Atta sexdens                           Unidentified Guild
    #> Camponotus atriceps                    Unidentified Guild
    #> Crematogaster sp                       Unidentified Guild
    #> Cyphomyrmex minutus                    Unidentified Guild
    #> Cyphomyrmex rimosus                    Unidentified Guild
    #> Ectatomma edentatum Generalist predatory ectaheteromorphs
    #>                                                 delabie_guild
    #> Atta sexdens                          Attini (Fungus-growers)
    #> Camponotus atriceps        Omnivorous soil-and-litter species
    #> Crematogaster sp           Omnivorous soil-and-litter species
    #> Cyphomyrmex minutus                   Attini (Fungus-growers)
    #> Cyphomyrmex rimosus                   Attini (Fungus-growers)
    #> Ectatomma edentatum Large Ponerinae (Large epigeic predators)
    #>                                                     silvestre_guild
    #> Atta sexdens                                     Unidentified Guild
    #> Camponotus atriceps              Generalist patrolling Camponotines
    #> Crematogaster sp    Small arboreal species with massive recruitment
    #> Cyphomyrmex minutus           Cryptic fungus-growing ants (Attines)
    #> Cyphomyrmex rimosus           Cryptic fungus-growing ants (Attines)
    #> Ectatomma edentatum                                 Large predators

### Exotic species detection

    exotics <- check_exotic_ants(dados, validate = FALSE, plot = FALSE)
    #> Step 1: Preparing community data...
    #> Step 2: Generating results...
    #>
    #> ********************************************************************************
    #> EXOTIC SPECIES DETECTED:
    #>                species abundance percentage
    #> 1 Monomorium floricola        18   4.128440
    #> 2 Monomorium pharaonis        17   3.899083
    #> 3 Pheidole megacephala        16   3.669725
    #> 4    Strumigenys emmae        15   3.440367
    #> 5   Strumigenys rogeri        14   3.211009
    #>
    #> DATA SOURCE AND REFERENCE:
    #> The exotic species list used in this function is sourced from:
    #> VIEIRA, Vitoria Brunetta. 'Quem são e onde estão as formigas exóticas do Brasil?'
    #> Dissertacao (Mestrado em Entomologia) – Universidade Federal do Parana (UFPR),
    #> Curitiba, Brasil, 2025.
    #> ********************************************************************************
    exotics
    #> $table
    #>                species abundance percentage origin
    #> 1 Monomorium floricola        18   4.128440 Exotic
    #> 2 Monomorium pharaonis        17   3.899083 Exotic
    #> 3 Pheidole megacephala        16   3.669725 Exotic
    #> 4    Strumigenys emmae        15   3.440367 Exotic
    #> 5   Strumigenys rogeri        14   3.211009 Exotic
    #>
    #> $plot

### Endemic species (Atlantic Forest)

    endemics <- check_endemic_atlantic_ants(dados, validate = FALSE, plot = FALSE)
    #>
    #> **********************************************************************************
    #> ATTENTION: This function identifies endemic species of the BRAZILIAN ATLANTIC FOREST.
    #> If your data collection did not occur within this biome, this analysis may not
    #> be appropriate for your study.
    #> **********************************************************************************
    #> Step 1: Preparing community data...
    #> Step 2: Generating results...
    #>
    #> ********************************************************************************
    #> ENDEMIC SPECIES DETECTED (ATLANTIC FOREST):
    #>                 species abundance percentage
    #> 1 Apterostigma serratum         9   2.064220
    #> 2 Brachymyrmex delabiei         8   1.834862
    #> 3 Brachymyrmex feitosai         7   1.605505
    #> 4   Camponotus fallatus         6   1.376147
    #> 5   Camponotus hermanni         5   1.146789
    #>
    #> DATA SOURCE AND REFERENCE:
    #> The endemic species list is sourced from:
    #> Silva, N. S., Goncalves, D. C. de O., Wazema, C. T., Barbosa, D. A., Prado, L. P. do,
    #> Andrade-Silva, J., Fernandes, T. T., Silva, R. R., & Morini, M. S. de C. (2025).
    #> 'Endemism and vulnerability of ants in the phytophysiognomies of the Brazilian
    #> Atlantic Forest'. In: Brazilian Myrmecology: Exploring the World’s Richest Ant Fauna
    #> (Chapter 16). Editora Cientifica Digital. DOI: 10.37885/250920259.
    #> ********************************************************************************
    endemics
    #> $table
    #>                 species abundance percentage       status
    #> 1 Apterostigma serratum         9   2.064220 Endemic (AF)
    #> 2 Brachymyrmex delabiei         8   1.834862 Endemic (AF)
    #> 3 Brachymyrmex feitosai         7   1.605505 Endemic (AF)
    #> 4   Camponotus fallatus         6   1.376147 Endemic (AF)
    #> 5   Camponotus hermanni         5   1.146789 Endemic (AF)
    #>
    #> $plot

### Rarity classification

    rarity <- check_rarity_atlantic_ants(dados, validate = FALSE, plot = FALSE)
    #>
    #> ********************************************************************************
    #> ATTENTION:
    #> This function identifies rare ant species and their rarity forms.
    #> This classification is specific to the Brazilian Atlantic Forest and
    #> may not be appropriate for other biomes.
    #> ********************************************************************************
    #> Step 1: Preparing community data and rarity database...
    #> Step 2: Generating results...
    #>
    #> ********************************************************************************
    #> RARE SPECIES DETECTED:
    #>                          species rarity_form abundance percentage
    #> 1          Brachymyrmex feitosai      Form 4         7  1.6055046
    #> 2        Brachymyrmex micromegas      Form 7         1  0.2293578
    #> 3            Camponotus atriceps      Form 2        40  9.1743119
    #> 4         Camponotus tripartitus      Form 7         1  0.2293578
    #> 5           Diaphoromyrma sofiae      Form 7         1  0.2293578
    #> 6           Heteroponera inermis      Form 4         2  0.4587156
    #> 7              Oxyepoecus browni      Form 6         2  0.4587156
    #> 8         Oxyepoecus reticulatus      Form 1        11  2.5229358
    #> 9              Pheidole aberrans      Form 2         3  0.6880734
    #> 10            Pheidole fimbriata      Form 2         3  0.6880734
    #> 11        Pheidole obscurithorax      Form 2         2  0.4587156
    #> 12            Pheidole subarmata      Form 2         2  0.4587156
    #> 13          Sphinctomyrmex stali      Form 6         1  0.2293578
    #> 14 Strumigenys fridericimuelleri      Form 3         2  0.4587156
    #> 15       Strumigenys sanctipauli      Form 6         1  0.2293578
    #>
    #> DATA SOURCE AND REFERENCE:
    #> Silva, N. S., Maciel, E. A., Prado, L. P., Silva, O. G., Barbosa, D. A.,
    #> Andrade-Silva, J., ... & Morini, M. S. (2024).
    #> 'Ant rarity and vulnerability in Brazilian Atlantic Forest fragments.'
    #> Biological Conservation, 296, 110640.
    #> ********************************************************************************
    rarity
    #> $table
    #>                          species abundance rarity_form percentage
    #> 1          Brachymyrmex feitosai         7      Form 4  1.6055046
    #> 2        Brachymyrmex micromegas         1      Form 7  0.2293578
    #> 3            Camponotus atriceps        40      Form 2  9.1743119
    #> 4         Camponotus tripartitus         1      Form 7  0.2293578
    #> 5           Diaphoromyrma sofiae         1      Form 7  0.2293578
    #> 6           Heteroponera inermis         2      Form 4  0.4587156
    #> 7              Oxyepoecus browni         2      Form 6  0.4587156
    #> 8         Oxyepoecus reticulatus        11      Form 1  2.5229358
    #> 9              Pheidole aberrans         3      Form 2  0.6880734
    #> 10            Pheidole fimbriata         3      Form 2  0.6880734
    #> 11        Pheidole obscurithorax         2      Form 2  0.4587156
    #> 12            Pheidole subarmata         2      Form 2  0.4587156
    #> 13          Sphinctomyrmex stali         1      Form 6  0.2293578
    #> 14 Strumigenys fridericimuelleri         2      Form 3  0.4587156
    #> 15       Strumigenys sanctipauli         1      Form 6  0.2293578
    #>
    #> $plot

##Multi‑site analysis with antclassify_community

When the study involves several sampling units, the function antclassify_community() applies the full classification pipeline to each row of a community matrix and returns aggregated site‑by‑guild information. This avoids manual loops and ensures consistent classification across all sites.

The package includes a small built‑in dataset, ant_community, that can be used to test this function.

    data(ant_community)

    # Run the pipeline on the built‑in dataset
    res_com <- antclassify_community(ant_community, guild_col = "antclassify_guild",
                                     validate = FALSE)
    #> Step 1: Preparing community data...
    #> Step 2: Matching species to functional guilds...
    #>
    #> Guild classification results (first 6 rows):
    #>                                     species abundance percentage
    #> Atta sexdens                   Atta sexdens        10         50
    #> Camponotus atriceps     Camponotus atriceps         3         15
    #> Pheidole megacephala   Pheidole megacephala         2         10
    #> Solenopsis saevissima Solenopsis saevissima         1          5
    #> Nylanderia fulva           Nylanderia fulva         4         20
    #>                                                                                        antclassify_guild
    #> Atta sexdens                                                Fungus-growers (soil or leaf litter nesting)
    #> Camponotus atriceps   Generalist omnivores (dominant or opportunistic in soil, leaf litter, or arboreal)
    #> Pheidole megacephala                       Leaf litter omnivores and scavengers (cryptic or non-cryptic)
    #> Solenopsis saevissima                      Leaf litter omnivores and scavengers (cryptic or non-cryptic)
    #> Nylanderia fulva      Generalist omnivores (dominant or opportunistic in soil, leaf litter, or arboreal)
    #>                              silva_guild                      delabie_guild
    #> Atta sexdens          Unidentified Guild            Attini (Fungus-growers)
    #> Camponotus atriceps   Unidentified Guild Omnivorous soil-and-litter species
    #> Pheidole megacephala  Unidentified Guild Omnivorous soil-and-litter species
    #> Solenopsis saevissima Unidentified Guild Omnivorous soil-and-litter species
    #> Nylanderia fulva      Unidentified Guild                 Unidentified Guild
    #>                                          silvestre_guild
    #> Atta sexdens                          Unidentified Guild
    #> Camponotus atriceps   Generalist patrolling Camponotines
    #> Pheidole megacephala             Dominant soil omnivores
    #> Solenopsis saevissima            Dominant soil omnivores
    #> Nylanderia fulva                      Unidentified Guild
    #> Step 3: Generating plots...
    #>
    #> ********************************************************************************
    #> IMPORTANT NOTICE:
    #> Please verify all assigned guilds. 'Unidentified Guild' indicates that the
    #> taxon was not found in the available reference databases.
    #> Guild classification in this analysis follows:
    #> - Literature-based criteria from:
    #>   Silvestre, R., Brandão, C. R. F., & Silva, R. R. (2003).
    #>   Grupos funcionales de hormigas: el caso de los gremios del Cerrado.
    #>   In F. Fernández (Ed.), *Introducción a las Hormigas de las Región Neotropical*
    #>   (pp. 113-148). Instituto Alexander Von Humboldt.
    #>   Silva, R. R., Silvestre, R., Brandão, C. R. F., Morini, M. S. C., & Delabie, J. H. C. (2015).
    #>   Grupos tróficos e guildas em formigas poneromorfas. In: Delabie, J. H. C. et al.
    #>   *As formigas poneromorfas do Brasil*. Ilhéus: Editus, 2015. p. 163-179.
    #>   Delabie, J. H. C., Agosti, D., & Nascimento, I. C. (2000).
    #>   Litter ant communities of the Brazilian Atlantic rain forest region.
    #>   *Sampling Ground-dwelling Ants: case studies from the world's rain forests.
    #>   Curtin University of Technology School of Environmental Biology Bulletin*, v. 18.
    #> - The 'AntClassify Guilds' classification corresponds to the internal
    #>   classification system implemented in the AntClassify package.
    #> ********************************************************************************
    #> Step 1: Preparing community data...
    #> Step 2: Matching species to functional guilds...
    #>
    #> Guild classification results (first 6 rows):
    #>                                       species abundance percentage
    #> Atta sexdens                     Atta sexdens         5  41.666667
    #> Pheidole megacephala     Pheidole megacephala         4  33.333333
    #> Wasmannia auropunctata Wasmannia auropunctata         2  16.666667
    #> Nylanderia fulva             Nylanderia fulva         1   8.333333
    #>                                                                                         antclassify_guild
    #> Atta sexdens                                                 Fungus-growers (soil or leaf litter nesting)
    #> Pheidole megacephala                        Leaf litter omnivores and scavengers (cryptic or non-cryptic)
    #> Wasmannia auropunctata Generalist omnivores (dominant or opportunistic in soil, leaf litter, or arboreal)
    #> Nylanderia fulva       Generalist omnivores (dominant or opportunistic in soil, leaf litter, or arboreal)
    #>                               silva_guild                      delabie_guild
    #> Atta sexdens           Unidentified Guild            Attini (Fungus-growers)
    #> Pheidole megacephala   Unidentified Guild Omnivorous soil-and-litter species
    #> Wasmannia auropunctata Unidentified Guild Omnivorous soil-and-litter species
    #> Nylanderia fulva       Unidentified Guild                 Unidentified Guild
    #>                                                        silvestre_guild
    #> Atta sexdens                                        Unidentified Guild
    #> Pheidole megacephala                           Dominant soil omnivores
    #> Wasmannia auropunctata Small arboreal species with massive recruitment
    #> Nylanderia fulva                                    Unidentified Guild
    #> Step 3: Generating plots...
    #>
    #> ********************************************************************************
    #> IMPORTANT NOTICE:
    #> Please verify all assigned guilds. 'Unidentified Guild' indicates that the
    #> taxon was not found in the available reference databases.
    #> Guild classification in this analysis follows:
    #> - Literature-based criteria from:
    #>   Silvestre, R., Brandão, C. R. F., & Silva, R. R. (2003).
    #>   Grupos funcionales de hormigas: el caso de los gremios del Cerrado.
    #>   In F. Fernández (Ed.), *Introducción a las Hormigas de las Región Neotropical*
    #>   (pp. 113-148). Instituto Alexander Von Humboldt.
    #>   Silva, R. R., Silvestre, R., Brandão, C. R. F., Morini, M. S. C., & Delabie, J. H. C. (2015).
    #>   Grupos tróficos e guildas em formigas poneromorfas. In: Delabie, J. H. C. et al.
    #>   *As formigas poneromorfas do Brasil*. Ilhéus: Editus, 2015. p. 163-179.
    #>   Delabie, J. H. C., Agosti, D., & Nascimento, I. C. (2000).
    #>   Litter ant communities of the Brazilian Atlantic rain forest region.
    #>   *Sampling Ground-dwelling Ants: case studies from the world's rain forests.
    #>   Curtin University of Technology School of Environmental Biology Bulletin*, v. 18.
    #> - The 'AntClassify Guilds' classification corresponds to the internal
    #>   classification system implemented in the AntClassify package.
    #> ********************************************************************************
    #> Step 1: Preparing community data...
    #> Step 2: Matching species to functional guilds...
    #>
    #> Guild classification results (first 6 rows):
    #>                                       species abundance percentage
    #> Camponotus atriceps       Camponotus atriceps         2  18.181818
    #> Pheidole megacephala     Pheidole megacephala         1   9.090909
    #> Wasmannia auropunctata Wasmannia auropunctata         3  27.272727
    #> Solenopsis saevissima   Solenopsis saevissima         5  45.454545
    #>                                                                                         antclassify_guild
    #> Camponotus atriceps    Generalist omnivores (dominant or opportunistic in soil, leaf litter, or arboreal)
    #> Pheidole megacephala                        Leaf litter omnivores and scavengers (cryptic or non-cryptic)
    #> Wasmannia auropunctata Generalist omnivores (dominant or opportunistic in soil, leaf litter, or arboreal)
    #> Solenopsis saevissima                       Leaf litter omnivores and scavengers (cryptic or non-cryptic)
    #>                               silva_guild                      delabie_guild
    #> Camponotus atriceps    Unidentified Guild Omnivorous soil-and-litter species
    #> Pheidole megacephala   Unidentified Guild Omnivorous soil-and-litter species
    #> Wasmannia auropunctata Unidentified Guild Omnivorous soil-and-litter species
    #> Solenopsis saevissima  Unidentified Guild Omnivorous soil-and-litter species
    #>                                                        silvestre_guild
    #> Camponotus atriceps                 Generalist patrolling Camponotines
    #> Pheidole megacephala                           Dominant soil omnivores
    #> Wasmannia auropunctata Small arboreal species with massive recruitment
    #> Solenopsis saevissima                          Dominant soil omnivores
    #> Step 3: Generating plots...
    #>
    #> ********************************************************************************
    #> IMPORTANT NOTICE:
    #> Please verify all assigned guilds. 'Unidentified Guild' indicates that the
    #> taxon was not found in the available reference databases.
    #> Guild classification in this analysis follows:
    #> - Literature-based criteria from:
    #>   Silvestre, R., Brandão, C. R. F., & Silva, R. R. (2003).
    #>   Grupos funcionales de hormigas: el caso de los gremios del Cerrado.
    #>   In F. Fernández (Ed.), *Introducción a las Hormigas de las Región Neotropical*
    #>   (pp. 113-148). Instituto Alexander Von Humboldt.
    #>   Silva, R. R., Silvestre, R., Brandão, C. R. F., Morini, M. S. C., & Delabie, J. H. C. (2015).
    #>   Grupos tróficos e guildas em formigas poneromorfas. In: Delabie, J. H. C. et al.
    #>   *As formigas poneromorfas do Brasil*. Ilhéus: Editus, 2015. p. 163-179.
    #>   Delabie, J. H. C., Agosti, D., & Nascimento, I. C. (2000).
    #>   Litter ant communities of the Brazilian Atlantic rain forest region.
    #>   *Sampling Ground-dwelling Ants: case studies from the world's rain forests.
    #>   Curtin University of Technology School of Environmental Biology Bulletin*, v. 18.
    #> - The 'AntClassify Guilds' classification corresponds to the internal
    #>   classification system implemented in the AntClassify package.
    #> ********************************************************************************

    # Abundance matrix (sites × guilds)
    res_com$guild_abundance
    #>       Fungus-growers (soil or leaf litter nesting)
    #> Site1                                           10
    #> Site2                                            5
    #> Site3                                            0
    #>       Generalist omnivores (dominant or opportunistic in soil, leaf litter, or arboreal)
    #> Site1                                                                                  7
    #> Site2                                                                                  3
    #> Site3                                                                                  5
    #>       Leaf litter omnivores and scavengers (cryptic or non-cryptic)
    #> Site1                                                             3
    #> Site2                                                             4
    #> Site3                                                             6

    # Guild richness per site
    res_com$guild_richness
    #> [1] 3 3 2

## Input data format

The package expects a community matrix where:

Rows represent sampling units (or a single community)

Columns represent species

Values represent abundance (or presence/absence)

Species names must be provided as column names..

### Example structure

The built‑in dataset ant_community demonstrates the expected format:

    data(ant_community)
    ant_community
    #>       Atta sexdens Camponotus atriceps Pheidole megacephala
    #> Site1           10                   3                    2
    #> Site2            5                   0                    4
    #> Site3            0                   2                    1
    #>       Wasmannia auropunctata Solenopsis saevissima Nylanderia fulva
    #> Site1                      0                     1                4
    #> Site2                      2                     0                1
    #> Site3                      3                     5                0

## Importing data from external files

### CSV files

    dados <- read.csv("data.csv", check.names = FALSE)

### TXT files

    dados <- read.table("data.txt", header = TRUE, sep = "\t", check.names = FALSE)

### Excel files

    # install.packages("readxl")
    library(readxl)

    dados <- read_excel("data.xlsx")
    dados <- as.data.frame(dados)

### Important note

    colnames(dados) <- gsub("_", " ", colnames(dados))

This step guarantees compatibility with the internal species name standardization used in AntClassify.

## Final considerations

The AntClassify package provides a flexible workflow that can be used either as a fully automated pipeline or through modular functions, allowing users to adapt analyses to different ecological questions.

By integrating functional classification, invasion biology, endemism, and rarity into a single framework, the package enhances reproducibility and facilitates ecological interpretation of ant communities.