---

title: "AntClassify"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{antclassify_workflow}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
-------------------------

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

```{r setup}
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

```{r}
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
```

## Running the pipeline

```{r}
resultado <- antclassify(dados)
```

## Accessing results

```{r}
names(resultado)

head(resultado$guilds$table)
resultado$exotics
resultado$endemics
resultado$rarity
```

## Using individual functions

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

### Functional guild classification

```{r}
guilds <- assign_guild_ants(dados)

head(guilds$table)
guilds$plot
```

### Exotic species detection

```{r}
exotics <- check_exotic_ants(dados)
exotics
```

### Endemic species (Atlantic Forest)

```{r}
endemics <- check_endemic_atlantic_ants(dados)
endemics
```

### Rarity classification

```{r}
rarity <- check_rarity_atlantic_ants(dados)
rarity
```

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

```{r}
dados_exemplo <- data.frame(
  "Atta sexdens" = 10,
  "Camponotus atriceps" = 5
)

dados_exemplo
```

## Importing data from external files

### CSV files

```{r eval=FALSE}
dados <- read.csv("data.csv", check.names = FALSE)
```

### TXT files

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

### Excel files

```{r eval=FALSE}
# install.packages("readxl")
library(readxl)

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

### Important note

```{r eval=FALSE}
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.