====== HELP - FUNÇÃO "biomap" ======
----
<code>

########################### HELP - FUNCAO "biomap" - THIAGO F. RODRIGUES 2018 ###############################

biomap               package:unknown                R Documentation

    ESPACIALIZAÇÃO E ANÁLISE DE DADOS DE OCORRÊNCIA DE ESPÉCIES

Description:

    Função para espacializar e analisar a distribuição de registros de espécies que ocorrem no Brasil,
    além de identificar potenciais lacunas de conhecimento. A função fornece um mapa com a distribuição
    de estudos no Brasil, um mapa quantificando os estudos por célula de interesse, um mapa
    quantificando a riqueza de espécies por célula de interesse e uma lista com dois níveis: o
    primero disponibiliza os dados quantificados nos mapas ao usuário e o segundo informa a lacuna de
    conhecimento acerca da distribuição dos estudos no Brasil.

Usage:

    biomap(dados, grid.size=5)

Arguments:

    dados: data.frame com três colunas na seguinte ordem, obrigatoriamente:
           1ª coluna(longitude): a longitude deve estar em graus decimais;
           2ª coluna(latitude): a latitude deve estar em graus decimais;
           3ª coluna(nome das espécies): nome das espécies.

    grid.size: número inteiro no intervalo 1 <= grid.size <= 10 indicando o tamanho das células do grid
               em graus de latitude e longitude (p.ex.: '1' indica 1 grau de latitude e longitude ~ 110km)

Details:

    Para que a função trabalhe corretamente é preciso que A LONGITUDE seja, obrigatoriamente,
    colocada na primeira coluna e A LATITUDE seja, obrigatoriamente, colocada na segunda coluna.
    Assim, a função gerará os produtos esperados.
    
    As linhas com NAs serão excluídas do data.frame.
    
    Caso grid.size não seja definido, a função padrão utiliza tamanho de grid.size = 5.
    
Value:

    Mapa do Brasil com a distribuição das coordenadas geográficas com escala. (Dispositivo de tela).
    
    Mapa do Brasil com grid definido pelo usuário e quantidade de estudos por célula num gradiente
    de cinza (quanto mais estudos, mais escuro). (Dispositivo de tela).
    
    Mapa do Brasil com grid definido pelo usuário e quantidade de espécies por célula num gradiente
    de cinza (quanto mais espécies, mais escuro). (Dispositivo de tela).
    
    Lista com dois níveis:
        
        -Nível 1: data.frame(info_map) com cinco colunas contendo informações extraídas dos mapas.
                  As colunas longitude e latitude representam coordenadas geográficas centrais de cada
                  célula do grid.
        
        -Nível 2: data.frame(lacuna_de_conhecimento) com cinco colunas contendo a quantidade de células
                  com estudo, quantidade de células sem estudo, probabilidade da área coberta com estudo,
                  valor máximo de estudo encontrada e valor máximo de riqueza encontrada.

    A lista gerada também ficará disponível como objeto no "Global Environment" para o usuário
    manipulá-la e análisá-la se desejar.
    
Warning:

    Se algum dos argumentos for inserido incorretamente, a função não é executada. Com exceção da troca
    de posição entre LONGITUDE E LATITUDE. Neste caso, a função rodará, mas NÃO gerará os produtos
    esperados.
    
    É necessário que o usuário esteja conectado à internet, pois a função faz o download de um
    shapefile do Brasil que fica disponível de maneira online.
    
    Ao executar a função, é esperado que ela demore um pouco, pois o procedimento de gerar grid
    demanda um grande processamento da memória do computador.
    
Note:

    É necessário instalar os pacotes "raster" e "sp" antes de utilizar a função.

Author:
    
    Thiago Ferreira Rodrigues - Ecologia Aplicada (ESALQ/USP)
    e-mail: thiagorodriguess@gmail.com 
    
References:

    BERNARD, E., AGUIAR, L.M.S. & MACHADO, R.B. 2010. Discovering the Brazilian bat fauna:
    a task for two centuries? Mamm. Rev 41: 23-39.
    
    HASUI, E. et al. 2018. ATLANTIC BIRDS: a data set of bird species from the Brazilian Atlantic
    Forest. ECOLOGY 99: 497-497

Examples:
    
    #Lembre-se que é necessário estar conectado à internet para rodar a função.
    
    #Exemplo1
    #Neste exemplo, vamos utilizar parte do banco de dados do datapaper publicado na Ecology 2018. 
    #Baixe o arquivo "hasui_et_al_2018_subsetdata.csv" presente no final da página principal.
    #Salve o arquivo no seu diretório de trabalho do R.
    #Importe os dados para seu ambiente de trabalho no R dentro de um objeto chamado "exemplo1".
    exemplo1 <- read.table("hasui_et_al_2018_subsetdata.csv", sep=",", header=TRUE, as.is=TRUE)
    head(exemplo1)
    
    #Leitura da funcao.
    source("biomap.r")
    
    #Roda a funcao 'default'.
    biomap(exemplo1)
    
    #Roda a funcao com diferentes tamanhos de grid.
    biomap(exemplo1, grid.size = 3)
    biomap(exemplo1, grid.size = 7)
        
    
    #Exemplo2 - Se achar mais fácil copie e cole o exemplo abaixo no R       
    # Leitura do pacote necessário para rodar o exemplo
    library("raster")
    library("sp") 
    
    # Simula 100 coordenadas geograficas dentro do mapa do brasil.
    brasil <- getData('GADM', country='BRA', level=1)
    sim.sp <- spsample(brasil, n = 100, type = "random") 
    
    # Cria data.frame com longitude (lon; repetida 10 vezes), latitude (lat; repetida 10 vezes) e especies (spp; com 1000 nomes e repeticao entre eles)
    exemplo2 <- data.frame(lon=rep(sim.sp@coords[,1], 10), 
                           lat=rep(sim.sp@coords[,2], 10), 
                           spp=paste("sp", sep = "_", sample(LETTERS, 1000, replace = TRUE)))
    
    #Leitura da funcao.
    source("biomap.r")
    
    # Roda a funcao 'default'.
    biomap(exemplo2)
    
    # Roda funcao com diferentes tamanhos de grid.
    biomap(exemplo2, grid.size = 3)
    biomap(exemplo2, grid.size = 7)
    
######################### FIM - HELP - FUNCAO "biomap" - THIAGO F. RODRIGUES #########################

</code>