# 1. Primeiros passos com faunabr

## Introdução

### O que é a Fauna do Brasil?

O Catálogo Taxonômico da Fauna do Brasil é resultado do esforço colaborativo de mais de 500 zoólogos especializados em diversos grupos de animais nativos do Brasil. Este banco de dados oferece descrições morfológicas detalhadas e padronizadas, informações sobre nomenclatura, distribuição geográfica e chaves de identificação para animais tanto nativos quanto não nativos encontrados no Brasil.

O pacote faunabr oferece um conjunto de funções desenvolvidas para acessar, filtrar e espacializar da Fauna do Brasil.

## Descrição geral das funções do pacote:

- `get_faunabr()`: baixa a versão mais recente ou uma versão anterior do banco de dados da Fauna do Brasil.
- `fauna_version()`: verifica se você possui a versão mais recente dos dados da Fauna do Brasil disponível em um diretório.
- `load_faunabr()`: carrega o banco de dados da Fauna do Brasil para o R.
- `translate_faunabr()`: traduz os dados de “forma de vida (lifeForm)”, “origem (origin)”, “habitat”, “ranking taxonômico (taxonRank)” e “Status Taxonômico (taxonomicStatus)” entre Português e Inglês.
- `fauna_attributes()`: exibe todas as opções disponíveis para filtrar espécies de acordo com suas características.
- `select_fauna()`: filtra espécies com base em suas características e distribuição.
- `extract_binomial()`: extrai o nome binomial (Gênero + epíteto específico) de um nome científico completo (Gênero + epíteto específico + Autor + Ano)
- `fauna_synonym()`: obtém os sinônimos para as espécies.
- `check_fauna_names()`: verifica se os nomes das espécies estão corretos.
- `subset_fauna()`: obtém um subconjunto de espécies da Fauna do Brasil.
- `fauna_spat_occ()`: obtém polígonos espaciais (SpatVectors) de espécies com base em sua distribuição.
- `filter_faunabr()`: remove ou sinaliza registros fora das áreas naturais de ocorrência das espécies.
- `fauna_pam()`: obtém uma matriz de presença-ausência de espécies com base em sua distribuição.

## Instalação

### Instalar a versão em desenvolvimento do GitHub

Você pode atual a versão do faunabr no github com:

    if(!require(remotes)){
        install.packages("remotes")
    }

    if(!require(faunabr)){
    remotes::install_github('wevertonbio/faunabr')}

    library(faunabr)

## Obtendo dados da Fauna do Brasil

Todos os dados incluídos no Fauna do Brasil (nomenclatura, forma de vida, distribuição, etc.) são armazenados em conjuntos de dados no formato Darwin Core Archive, que são atualizados frequentemente. Antes de baixar os dados disponíveis no Fauna do Brasil, precisamos criar uma pasta para salvar os dados:

    #Criando uma pasta em um diretório temporário
    #Substitua 'file.path(tempdir(), "faunabr")' por um caminho de pasta a ser
    #criada em seu computador
    my_dir <- file.path(file.path(tempdir(), "faunabr"))
    dir.create(my_dir)

Agora você pode utilizar a função `get_faunabr` para obter a versão mais recente dos dados:

    get_faunabr(output_dir = my_dir, #Pasta para salvar os dados
                data_version = "latest", #Obter a versão mais recente
                translate = FALSE, #Manter versão original em português
                overwrite = T) #Sobrescrever dados, se eles já existirem

A função levará alguns segundos para baixar os dados e alguns minutos para mesclar os conjuntos de dados em um único `data.frame.` Após a conclusão bem-sucedida, você encontrará uma pasta nomeada com a versão do Fauna do Brasil. Esta pasta contém o conjunto de dados bruto baixado (arquivos TXT em português) e um arquivo chamado CompleteBrazilianFauna.gz. Este último representa o conjunto de dados final mesclado. Por padrão, os dados são traduzidos para o inglês, mas aqui mantemos a versão original em português definindo `translate = TRUE`.

Você também tem a opção de baixar uma versão mais antiga específica do conjunto de dados da Fauna do Brasil. Para explorar as versões disponíveis, consulte este link. Para baixar uma versão específica, basta substituir `latest` pelo número da versão desejada. Por exemplo:

    get_faunabr(output_dir = my_dir, #Pasta para salvar os dados
                data_version = "1.10", #Versão 1.10, publicada em 01-02-2024
                translate = FALSE, #Manter versão original em português
                overwrite = T) #Sobrescrever dados, se eles já existirem

Como mencionado anteriormente, você encontrará uma pasta chamada ‘1.10’ dentro do diretório designado.

Para visualizar as versões disponíveis no seu diretório especificado, execute:

    fauna_version(data_dir = my_dir)
    #> You have the following versions of Fauna do Brasil:
    #>  1.17
    #>  1.10
    #>  It includes the latest version:  1.17

## Carregando os dados

Para utilizar as outras funções do pacote, você precisa carregar os dados em seu ambiente R. Para isso, utilize a função `load_faunabr()`. Por padrão, a função buscará automaticamente pela versão mais recente disponível no seu diretório. No entanto, você tem a opção de especificar uma versão particular usando o parâmetro data_version. Além disso, você pode escolher entre duas versões dos dados: a versão resumida ‘short’ (contendo as 21 colunas necessárias para executar as outras funções do pacote) ou a versão completa ‘completa’ (com todas as 32 colunas originais). A função importa a versão ‘short’ por padrão.

    #Short version
    bf <- load_faunabr(data_dir = my_dir,
                       data_version = "latest",
                       type = "short") #resumida
    #> Loading version 393.401
    colnames(bf) #Ver colunas da versão resumida
    #>  [1] "species"             "subspecies"          "scientificName"
    #>  [4] "validName"           "kingdom"             "phylum"
    #>  [7] "class"               "order"               "family"
    #> [10] "genus"               "lifeForm"            "habitat"
    #> [13] "states"              "countryCode"         "origin"
    #> [16] "taxonomicStatus"     "nomenclaturalStatus" "vernacularName"
    #> [19] "taxonRank"           "id"                  "language"

Note que a versão completa possui 11 colunas adicionais:

    #Complete version
    bf_complete <- load_faunabr(data_dir = my_dir,
                       data_version = "latest",
                       type = "complete") #completa

    colnames(bf_complete) #Ver colunas da versão completa
    #>  [1] "id"                       "taxonID"
    #>  [3] "species"                  "subspecies"
    #>  [5] "scientificName"           "validName"
    #>  [7] "validNameUsage"           "parentNameUsage"
    #>  [9] "namePublishedInYear"      "higherClassification"
    #> [11] "kingdom"                  "phylum"
    #> [13] "class"                    "order"
    #> [15] "family"                   "genus"
    #> [17] "specificEpithet"          "infraspecificEpithet"
    #> [19] "taxonRank"                "scientificNameAuthorship"
    #> [21] "taxonomicStatus"          "nomenclaturalStatus"
    #> [23] "vernacularName"           "lifeForm"
    #> [25] "habitat"                  "origin"
    #> [27] "states"                   "countryCode"
    #> [29] "modified"                 "bibliographicCitation"
    #> [31] "relationshipOfResource"   "language"

## Traduzir atributos

Por padrão, os dados baixados do Catálogo Taxonômico da Fauna do Brasil são traduzidos para o inglês, a menos que você defina `translate = FALSE` na função `get_faunabr()`. No entanto, é possível usar a função `translate_faunabr()` para traduzir os dados carregados entre inglês e português:

    # Traduzir do português para o inglês
    bf_ingles <- translate_faunabr(data = bf, to = "en")
    # Ver formas de vida (em ingles)
    fauna_attributes(bf_ingles, "lifeForm")
    #>  $lifeForm
    #>                  lifeForm
    #> 1                colonial
    #> 2               commensal
    #> 3            ectoparasite
    #> 4          ectoparasitoid
    #> 5            endoparasite
    #> 6          endoparasitoid
    #> 7                epibiont
    #> 8                eusocial
    #> 9  free_living_individual
    #> 10              herbivore
    #> 11        hyperparasitoid
    #> 12              inquiline
    #> 13            mutualistic
    #> 14              polynizer
    #> 15               predator
    #> 16                sessile

    # Traduzir do inglês para o português
    bf_portugues <- translate_faunabr(data = bf_ingles, to = "pt_br")
    #Ver formas de vida disponíveis em portugues novamente
    fauna_attributes(bf_portugues, "lifeForm")
    #>  $lifeForm
    #>                 lifeForm
    #> 1               colonial
    #> 2               comensal
    #> 3           ectoparasito
    #> 4        ectoparasitoide
    #> 5           endoparasito
    #> 6        endoparasitoide
    #> 7              epibionte
    #> 8              eussocial
    #> 9              herbivoro
    #> 10      hiperparasitoide
    #> 11             inquilino
    #> 12                mutual
    #> 13           polinizador
    #> 14              predador
    #> 15                sessil
    #> 16 vida_livre_individual

## Salvar dados

Se você deseja salvar os conjuntos de dados para abrir com um editor externo (por exemplo, Excel), você pode salvar o data.frame como um arquivo CSV:

    write.csv(x = bf,
              file = file.path(my_dir, "BrazilianFauna.csv"),
              row.names = F)