---
title: "2. Selecionar e filtrar espécies"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{2. Selecionar e filtrar espécies}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

### Selecionar uma lista de espécies
Selecionar uma lista de espécies-alvo é uma tarefa comum em estudos macroecológicos e de conservação. Por exemplo, um pesquisador pode desejar modelar a distribuição de mamíferos arborícolas que ocorrem em um estado específico.

Aplicando diferentes filtros ao banco de dados, podemos obter uma lista verificada das espécies de animais brasileiros para qualquer estado brasileiro ou país. Além disso, o filtro pode ser aplicado para selecionar espécies por filo, classe, ordem, família, gênero, forma de vida, habitat, origem e status taxonômico.
Neste tutorial, vamos ver como utilizar o pacote *faunabr* para selecionar uma lista de espécies com base nessas características.

## Carregando os dados
Antes de começar, utilize a função `load_faunabr()` para carregar os dados. Para informações mais detalhadas sobre como obter e carregar os dados, consulte [Primeiros passos com faunabr](https://wevertonbio.github.io/faunabr/articles/primeiros_passos.html)

```{r}
library(faunabr)
#Carregar dados
bf <- load_faunabr(data_dir = my_dir, #Pasta onde foi salvo o arquivo com get_faunabr()
                   data_version = "latest", #Versão mais recente
                   type = "short") #Versão resumida
#> Loading version 1.3
```

Aqui, vamos utilizar os dados baixados em português (`translate = FALSE` em `get_faunabr()`).

## Como selecionar uma lista de espécies?

Um dos principais objetivos deste pacote é auxiliar na seleção de uma lista de espécies com base na classificação taxonômica, características e distribuição. Especificamente, você pode filtrar por:

* filo, classe, ordem, família e gênero;
* forma de vida e habitat;
* estados brasileiros e países com ocorrências confirmadas;
* origem;
* status taxonômico.

Para explorar todas as opções disponíveis para cada filtro, utilize a função `fauna_attributes()` com os atributos desejados. Esta função fornecerá uma lista de data.frames com as opções disponíveis para usar na função `select_fauna()`:

```{r}
#Obter as opções disponíveis para filtrar por forma de vida, habitat e origem
fauna_at <- fauna_attributes(data = bf,
                             attribute = c("lifeForm", "habitat", "origin"))
head(fauna_at$lifeForm)
#>          lifeForm
#> 1        colonial
#> 2       comensal
#> 3    ectoparasito
#> 4 ectoparasitoide
#> 5    endoparasito
#> 6  endoparasitoide

head(fauna_at$habitat)
#> habitat
#> 1          agua_doce
#> 2 aguas_subterraneas
#> 3            arboreo
#> 4        cavernicola
#> 5          fossorial
#> 6         hiporreico

head(fauna_at$origin)
#>         origin
#> 1 criptogenica
#> 2      exotica
#> 3       nativa
```

Como exemplo, vamos considerar o cenário em que desejamos obter uma lista de todos os insetos arbóreos nativos com ocorrências confirmadas no Rio de Janeiro:

```{r}
insects_rj <- select_fauna(data = bf, include_subspecies = FALSE,
                           phylum = "all",
                           class = "Insecta", #Insetos
                           order = "all",
                           family = "all",
                           genus = "all",
                           lifeForm = "all", filter_lifeForm = "in",
                           habitat = "arboreo", filter_habitat = "in",
                           states = "RJ", #Rio de Janeiro
                           filter_states = "in", #Que ocorrem NO RJ
                           country = "all", filter_country = "in",
                           origin = "nativa",
                           taxonomicStatus = "valido")
nrow(insects_rj)
#> [1] 114
```

O filtro retornou 114 espécies que atendem aos critérios especificados. É importante notar que essas seleções incluem espécies com ocorrências confirmadas no Rio de Janeiro, e algumas delas também podem ter ocorrências confirmadas em outros estados.

```{r}
#Primeiros 7 valores únicos de Estados onde as espécies ocorrem
unique(insects_rj$states)[1:7]
#> [1] "AC;AM;AP;BA;CE;DF;ES;GO;MA;MG;MS;MT;PA;PE;RJ;RN;RO;RR;SE;SP;TO"
#> [2] "BA;MA;MG;MT;PR;RJ;RS;SC;SP"                                    
#> [3] "ES;MG;PE;PR;RJ;RS;SP"                                          
#> [4] "ES;PR;RJ;SP"                                                   
#> [5] "RJ"                                                            
#> [6] "RJ;SP"                                                         
#> [7] "ES;MG;RJ;RS;SC;SP" 
```

Se você deseja selecionar espécies com ocorrências confirmadas apenas no Rio de Janeiro, e não em nenhum outro estado, modifique o parâmetro *filter_state* para "only":

```{r}
insects_rj_only <- select_fauna(data = bf, include_subspecies = FALSE,
                           phylum = "all",
                           class = "Insecta", #Insetos
                           order = "all",
                           family = "all",
                           genus = "all",
                           lifeForm = "all", filter_lifeForm = "in",
                           habitat = "arboreo", filter_habitat = "in",
                           states = "RJ", #Rio de Janeiro
                           filter_states = "only", #Com ocorrência APENAS no RJ
                           country = "all", filter_country = "in",
                           origin = "nativa",
                           taxonomicStatus = "valido")
nrow(insects_rj_only)
#> [1] 22
unique(insects_rj_only$states)
#> [1] "RJ"
```

Agora, o filtro retornou 22 espécies, todas exclusivamente confinadas ao Rio de Janeiro.

Além disso, o pacote oferece a flexibilidade de combinar vários filtros (consulte `?select_fauna` para mais detalhes). Por exemplo, considere o cenário em que desejamos compilar uma lista de insetos nativos com ocorrências confirmadas nos estados do Paraná (PR), Santa Catarina (SC) e Rio Grande do Sul (RS):

```{r}
insects_south <- select_fauna(data = bf, include_subspecies = FALSE,
                           phylum = "all",
                           class = "Insecta", #Insetos
                           order = "all",
                           family = "all",
                           genus = "all",
                           lifeForm = "all", filter_lifeForm = "in",
                           habitat = "all", filter_habitat = "in",
                           states = c("PR", "SC", "RS"), #Estados do Sul do Brasil
                           filter_states = "in", #EM qualquer um dos estados
                           country = "all", filter_country = "in",
                           origin = "nativa",
                           taxonomicStatus = "valido")
nrow(insects_south)
#> [1] 11461

#Primeiros 10 valores únicos de Estados onde as espécies ocorrem
unique(insects_south$states)[1:10]
#> [1] "PR;SP" 
#> [2] "BA;MT;RJ;RS" 
#> [3] "RS"   
#> [4] "PR"   
#> [5] "PR;RS"  
#> [6] "GO;PA;RO;RR;SC"
#> [7] "MG;PR;SP"    
#> [8] "GO;MG;PR;RS;SC"
#> [9] "GO;RJ;SC"       
#> [10] "AC;AL;AM;AP;BA;CE;DF;ES;GO;MA;MG;MS;MT;PA;PB;PE;PI;PR;RJ;RN;RO;RR;RS;SC;SE;SP;TO"
```

Como utilizamos *filter_state = "in"*, nossa seleção englobou espécies que ocorrem nos três estados, mas também aquelas presentes apenas em dois ou mesmo em um deles, além de outros estados. Para impor um critério mais rigoroso, selecionando apenas as espécies com ocorrências confirmadas em todos os três estados, podemos usar *filter_state = "and"*:

```{r}
insects_south_and <- select_fauna(data = bf, include_subspecies = FALSE,
                           phylum = "all",
                           class = "Insecta", #Insetos
                           order = "all",
                           family = "all",
                           genus = "all",
                           lifeForm = "all", filter_lifeForm = "in",
                           habitat = "all", filter_habitat = "in",
                           states = c("PR", "SC", "RS"), 
                           filter_states = "and", #PR & SC & RS
                           country = "all", filter_country = "in",
                           origin = "nativa",
                           taxonomicStatus = "valido")
nrow(insects_south_and)
#> [1] 1924

#Primeiros 10 valores únicos de Estados onde as espécies ocorrem
unique(insects_south_and$states)[1:10]
#> [1] "GO;MG;PR;RS;SC"  
#> [2] "AC;AL;AM;AP;BA;CE;DF;ES;GO;MA;MG;MS;MT;PA;PB;PE;PI;PR;RJ;RN;RO;RR;RS;SC;SE;SP;TO"
#> [3] "AC;AM;MG;MS;MT;PA;PE;PR;RO;RS;SC;SP" 
#> [4] "AM;BA;CE;DF;ES;GO;MG;MS;MT;PA;PE;PR;RJ;RS;SC;SP" 
#> [5] "AC;AM;AP;BA;CE;DF;ES;GO;MG;MS;MT;PA;PE;PR;RJ;RO;RR;RS;SC;SE;SP;TO"
#> [6] "BA;ES;MG;PR;RJ;RS;SC;SP"
#> [7] "AM;DF;ES;GO;PR;RJ;RR;RS;SC;SP"  
#> [8] "ES;GO;MG;PR;RJ;RS;SC;SP"     
#> [9] "AC;AM;AP;BA;CE;ES;GO;MA;MG;MT;PA;PR;RJ;RO;RS;SC;SP;TO" 
#> [10] "GO;MG;MS;PR;RO;RS;SC;SP"
```

Agora, nossa seleção consistiu exclusivamente em espécies com ocorrências confirmadas em todos os estados especificados. No entanto, ao utilizar o argumento *"and"*, permitimos que o filtro incluísse espécies com ocorrências em estados adicionais. Para limitar o filtro a espécies com ocorrências confirmadas exclusivamente nos três estados, sem ocorrências em outros lugares, podemos usar *filter_state = "only"*:

```{r}
insects_south_only <- select_fauna(data = bf, include_subspecies = FALSE,
                           phylum = "all",
                           class = "Insecta", #Insetos
                           order = "all",
                           family = "all",
                           genus = "all",
                           lifeForm = "all", filter_lifeForm = "in",
                           habitat = "all", filter_habitat = "in",
                           states = c("PR", "SC", "RS"), 
                           filter_states = "only", #Apenas no PR & SC & RS
                           country = "all", filter_country = "in",
                           origin = "nativa",
                           taxonomicStatus = "valido")
nrow(insects_south_only)
#> [1] 134

#Valor único de Estados onde as espécies ocorrem
unique(insects_south_only$states)
#> [1] "PR;RS;SC"
```
Agora, o filtro retornou apenas 134 espécies, todas ocorrendo em PR, SC e RS; sem registros de ocorrências em qualquer outro estado.

## Checagem de nomes científicos e subseleção de espécies

### Extraindo o nome binomial
Além de selecionar uma lista de espécies com base em suas características, o pacote também inclui uma função para subselecionar espécies por nome. A função funciona exclusivamente com nomes binomiais (Gênero + Epíteto específico), como *Panthera onca*, e não funciona com nomes científicos completos (incluindo Autor ou Epíteto infraespecífico), como *Panthera onca (Linnaeus, 1758)*.

Se você tiver uma lista de espécies com nomes científicos completos, pode extrair os nomes binomiais usando a função `get_binomial()`. Não se preocupe com espaços excessivos entre as palavras, a função removerá quaisquer espaços extras dos nomes.

```{r}
complete_names <- c("Pantera onca (Linnaeus, 1758)",
                    "Zonotrichia capensis subtorquata Swainson, 1837",
                    "Mazama bororo Duarte, 1996",
                    "Mazama jucunda Thomas, 1913",
                    "Arrenurus tumulosus intercursor",
                    "Araucaria angustifolia")
#Panthera onca com erros de digitação para ilustrar como a próxima função os corrige
#Araucaria angustifolia (uma planta) foi usada apenas como um exemplo que será utilizado para ilustrar a próxima função
binomial_names <- extract_binomial(species_names = complete_names)
binomial_names
#> [1] "Pantera onca"                         "Zonotrichia capensis" 
#> [3] "Mazama bororo"                        "Mazama jucunda" 
#> [5] "Arrenurus tumulosus"                  "Araucaria angustifolia" 
```
### Checando se os nomes das espécies estão corretos
Vamos agora verificar a ortografia, o status nomenclatural e o status taxonômico dos nomes das espécies usando a função `check_fauna_names()`. Se a função não conseguir localizar o nome de uma espécie no banco de dados (devido a um erro tipográfico, por exemplo), ela pode sugerir nomes potenciais com base em similaridades com outras entradas no banco de dados.
Para ver como a função funciona, vamos utilizar o dataset *binomial_names* criado anteriormente:

```{r}
#Checar nomes
checked_names <- check_fauna_names(data = bf, 
                             species = binomial_names,
                             include_subspecies = FALSE,
                             max_distance = 0.1)
tibble::tibble(checked_names) #Exibir tabela como tibble
#> # A tibble: 6 x 9
#>   input_name               Spelling           Suggested_name       Distance taxonomicStatus nomenclaturalStatus validName   family        matches
#>   <chr>                    <chr>              <chr>                   <dbl> <chr>           <chr>               <chr>          <chr>         <chr>  
#> 1 "Zonotrichia capensis"   Correct            Zonotrichia capensis        0 valido    NA                  NA             Passerellidae single 
#> 2 "Mazama bororo"          Correct            Mazama bororo               0 sinonimo        NA                  Mazama jucunda Cervidae      single 
#> 3 "Mazama jucunda"         Correct            Mazama jucunda              0 valido     NA                  NA             Cervidae      single 
#> 4 "Arrenurus tumulosus"    Correct            Arrenurus tumulosus         0 valido     NA                  NA             Arrenuridae   single 
#> 5 "Pantera onca"           Probably_incorrect Panthera onca               2 valido     NA                  NA             Felidae       single 
#> 6 "Araucaria angustifolia" Not_found          NA                         NA NA              NA                  NA             NA            none   
```

Podemos ver que *Zonotrichia capensis*, *Mazama jucunda* e *Arrenurus tumulosus* estão escritos corretamente e são nomes validos. *Mazama bororo* está escrito corretamente, mas é um sinônimo de *Mazama jucunda*.
No caso de *Pantera onca*, a ortografia parece estar potencialmente incorreta (já que o nome não foi encontrado no banco de dados); no entanto, um nome semelhante, *Panthera onca*, é sugerido pela função. A coluna 'Distance' indica a distância de edição de Levenshtein entre a entrada e o nome sugerido.
*Araucaria angustifolia* foi marcada como Not_found (como esperado, dado que *Araucaria angustifolia* não é um animal!). Consequentemente, o nome não foi localizado no banco de dados e não havia nomes comparáveis disponíveis.

### Subselecionando espécies

Para obter informações sobre espécies do banco de dados Fauna do Brasil a partir de uma lista de espécies pré-definida, utilize a função `subset_species()`. Para obter um desempenho ideal, recomendamos fortemente o uso das funções `get_binomial()` e `check_names()` previamente. Isso garante que você esteja trabalhando exclusivamente com espécies presentes no banco de dados da Fauna do Brasil.
Para ver como a função funciona, vamos usar os nomes validos em *checked_names* criados anteriormente:

```{r}
#Obter apenas nomes validos
valids <- unique(checked_names$validName)
valids <- na.omit(valids) #Remove NAs

#Subselecionar especies
my_sp <- subset_fauna(data = bf, species = valids,
                      include_subspecies = FALSE)
tibble::tibble(my_sp)
# A tibble: 4 x 21
#>   species           subspecies scientificName validName kingdom phylum class order family genus lifeForm habitat states countryCode origin
#>   <chr>             <chr>      <chr>          <chr>        <chr>   <chr>  <chr> <chr> <chr>  <chr> <chr>    <chr>   <chr>  <chr>       <chr> 
#> 1 Panthera onca     NA         Panthera onca~ NA           Animal~ Chord~ Mamm~ Carn~ Felid~ Pant~ "vida_l~ "terre~ AC;AM~ AR;BO;BR;B~ nativa
#> 2 Arrenurus tumulo~ NA         Arrenurus (In~ NA           Animal~ Arthr~ Arac~ Trom~ Arren~ Arre~ ""       ""      NA     NA          NA    
#> 3 Mazama jucunda    NA         Mazama jucund~ NA           Animal~ Chord~ Mamm~ Arti~ Cervi~ Maza~ "herbiv~ "terre~ BA;ES~ BR          nativa
#> 4 Zonotrichia cape~ NA         Zonotrichia c~ NA           Animal~ Chord~ Aves  Pass~ Passe~ Zono~ ""       ""      NA     NA          nativa  
# i 5 more variables: nomenclaturalStatus <chr>, vernacularName <chr>, taxonRank <chr>, id <int>, language <chr>
```
Também podemos incluir subespécies e/ou variedades:

```{r}
my_sp2 <- subset_fauna(data = bf, species = valids,
                      include_subspecies = TRUE)
tibble::tibble(my_sp2) #print data.frame as tibble
#> # A tibble: 14 × 19
#>    species      subspecies scientificName validName kingdom phylum class order family genus lifeForm habitat states countryCode #> origin
#>    <chr>        <chr>      <chr>          <chr>        <chr>   <chr>  <chr> <chr> <chr>  <chr> <chr>    <chr>   <chr>  <chr>       #> <chr> 
#>  1 Panthera on… ""         Panthera onca… ""           Animal… Chord… Mamm… Carn… Felid… Pant… "free_l… "terre… AC;AM… argentina;… #> "nati…
#>  2 Arrenurus (… ""         Arrenurus (In… ""           Animal… Arthr… Arac… Trom… Arren… Arre… ""       ""      NA     brazil      "" #>    
#>  3 Arrenurus (… "Arrenuru… Arrenurus (In… ""           Animal… Arthr… Arac… Trom… Arren… Arre… ""       ""      NA     brazil      "" #>    
#>  4 Arrenurus (… "Arrenuru… Arrenurus (In… ""           Animal… Arthr… Arac… Trom… Arren… Arre… ""       ""      NA     brazil      "" #>    
#>  5 Mazama jucu… ""         Mazama jucund… ""           Animal… Chord… Mamm… Arti… Cervi… Maza… "herbiv… "terre… BA;ES… brazil      #> "nati…
#>  6 Zonotrichia… ""         Zonotrichia c… ""           Animal… Chord… Aves  Pass… Passe… Zono… "free_l… ""      AL;AP… brazil      #> "nati…
#>  7 Zonotrichia… "Zonotric… Zonotrichia c… ""           Animal… Chord… Aves  Pass… Passe… Zono… "free_l… ""      AP     brazil      #> "nati…
#>  8 Zonotrichia… "Zonotric… Zonotrichia c… ""           Animal… Chord… Aves  Pass… Passe… Zono… "free_l… ""      RR     brazil      #> "nati…
#>  9 Zonotrichia… "Zonotric… Zonotrichia c… ""           Animal… Chord… Aves  Pass… Passe… Zono… "free_l… ""      RR     brazil      #> "nati…
#> 10 Zonotrichia… "Zonotric… Zonotrichia c… ""           Animal… Chord… Aves  Pass… Passe… Zono… "free_l… ""      BA;MA… brazil      #> "nati…
#> 11 Zonotrichia… "Zonotric… Zonotrichia c… ""           Animal… Chord… Aves  Pass… Passe… Zono… "free_l… ""      PA     brazil      #> "nati…
#> 12 Zonotrichia… "Zonotric… Zonotrichia c… ""           Animal… Chord… Aves  Pass… Passe… Zono… "free_l… ""      AP;PA… brazil      #> "nati…
#> 13 Zonotrichia… "Zonotric… Zonotrichia c… ""           Animal… Chord… Aves  Pass… Passe… Zono… "free_l… ""      ES;MG… brazil      #> "nati…
#> 14 Zonotrichia… "Zonotric… Zonotrichia c… ""           Animal… Chord… Aves  Pass… Passe… Zono… "free_l… ""      TO     brazil      #> "nati…
#> # ℹ 4 more variables: taxonomicStatus <chr>, nomenclaturalStatus <chr>, vernacularName <chr>, taxonRank <chr>
#> 
```

### Obtendo sinônimos

Podemos obter todos os sinônimos de uma lista de espécies. Isso pode ser particularmente útil, por exemplo, ao buscar registros de uma espécie e todos os seus sinônimos (conforme listado na Fauna do Brasil) em bancos de dados online como o GBIF. Para isso, utilize a função `fauna_synonym()`. Como exemplo, vamos buscar os sinônimos de três espécies:
```{r}
spp <- c("Panthera onca", "Mazama jucunda", "Subulo gouzoubira")
spp_syn <- fauna_synonym(data = bf, species = spp)
spp_syn
#>               validName               synonym   taxonomicStatus
#> 49343     Panthera onca                  <NA>    valido
#> 60523    Mazama jucunda         Mazama bororo    sinonimo
#> 61168 Subulo gouzoubira    Mazama gouazoubira    sinonimo
```
Podemos ver que *Mazama jucunda* possui o sinônimo *Mazama bororo*; enquanto *Subulo gouzoubira* possui o sinônimo *Mazama gouazoubira*. *Panthera onca* não possui nenhum sinônimo listado na base de dados.
