\documentclass[a4paper, oneside, 10pt]{article}
\usepackage[english]{babel}
\usepackage[utf8x]{inputenc}
\usepackage{listings}
\date{\today}
\title{}
\author{}
\begin{document}

\lstset{frame=single}
\begin{lstlisting}

coex_st                             R Documentation

Coexistência espaço-temporal de linhagens no registro fóssil

Descrição:

     Cria uma série temporal de determinação de coexistência linhagens do registro fóssil,
     no espaço e no tempo

Uso:

     coex_st(df, time.series = 1, space = "polygon", plot.longs = F)

Argumentos:

	 df
	 data.frame com as ocorrências fósseis do grupo de interesse.
	 
	 time.series
	 define o vetor de série temporal a ser utilizado. Pode ser fornecido um único valor,
	 que define a frequência com que o tempo será dividido, e.g.: time.series = 1 define que 
	 o tempo será dividido de 1 em 1 milhão de anos. Também pode ser fornecido o vetor 
	 com a série temporal definida, e.g.: time.series <- c(37.8,33.9,27.82,23.03, 20.44,
	 15.97,13.82,11.63,7.246,5.333,3.6,2.58,1.8,0.781,0.126,0.0117,0); nesse caso a função
	 utilizará esses momentos no tempo para a construção da série temporal
	 
	 space
	 determina o método de coexistência espacial a ser utilizado. Aceita apenas três opções:
	 "site", "coords", "polygon". Veja detalhes para a descrição dos métodos. Default = 
	 "polygon"
	 
	 plot.longs
	 lógico, default FALSE. Se TRUE, retorna um gráfico com as longevidades das linhagens
	 e os momentos da série temporal
	 
	 
Detalhes:
     
     #Conjunto de dados
     O conjunto de dados deve ser fornecido exatamente como o proposto, com as colunas:
     "taxon_name", "collection_no", "lng", "lat", "max_ma", "min_ma", similar ao modelo
     como as ocorrências fósseis são descritas pela base de dados "Paleobiology Database",
     banco de dados referência mundial de coleções fósseis. O modelo sugerido pressupõe que
     as ocorrências estejam associadas a um intervalo de tempo estratigráfico (max_ma, 
     min_ma), um identificador de coleção (collection_no), e coordenadas geográficas (lng,
     lat). A coleção refere-se à assembléia fóssil que cada ocorrência foi encontrada, 
     enquanto que os identificadores de coordenada geralmente estão associados ao sítio
     fossilífero, ou à localidade geopolítica associada com o sítio fossilífero. Essa 
     diferença discrimina fósseis que são encontrados explicitamente juntos, na mesma camada
     estratigráfica, e mesmo horizonte fossilífero (collection), enquanto que as coordenadas
     indicam uma região associada, não necessariamente fósseis com a mesma localidade são
     encontrados no mesmo horizonte fossilífero, muito menos na mesma assembléia.     
     
     # Longevidade
     A longevidade real das linhagens é estimada com o método de intervalos de
     confiança de Marshall (1990), baseando-se no pressuposto de "range-through" 
     (Foote 2007), em que assume-se que o táxon esteve presente desde o momento de sua 
     ocorrência mais antiga à ocorrência mais recente. O método de Marshall calcula os 
     intervalos de confiança de 50% do momento real de surgimento/extinção em torno do 
     valor observado de uma leitura direta do registro fóssil (ocorrência mais antiga ou
     mais recente). Esse estimador é um  estimador não-enviesado dos momentos de 
     surgimento/extinção baseado no número de ocorrências conhecidadas para aquele táxon, 
     mas depende de uma série de premissas, como potencial de fossilização aleatório, 
     e amostragem constante do registro fóssil do grupo de interesse. Entretanto, o método
     é robusto o suficiente a violações dessas premissas para a maioria dos casos 
     Marshall 2010).
     
     # Coexistência temporal
     A coexistência no tempo é definida com base no mesmo pressuposto de "range-through": 
     se a longevidade de dois táxons se sobrepõem no mesmo momento de tempo, considera-se
     que os dois táxons estavam vivos no mesmo momento de tempo.
     
     # Coexistência espacial
     A coexistência espacial pode ser definida de 3 formas diferentes, com diferentes graus
     de permissividade. Esses diferentes graus refletem a confiança que o usuário pode ter
     na evidência de coexistência espacial, indo do mais restritivo ao mais abrangente.
     O primeiro grau, definido com o método "site", define que apenas táxons que possuem 
     ocorrências fósseis encontradas na mesma assembléia, isto é, juntos, sejam considerados
     co-ocorrentes. Esta é a evidência mais direta de coexistência. Entretanto, relaxando-se 
     essa premissa, no segundo grau, "coords", as ocorrências não necessariamente precisam
     ser encontradas juntas, mas sim estarem associadas às mesmas coordenadas geográficas. 
     O terceiro grau, "polygon", permite que o usuário reconstrua áreas de vida dos táxons
     extintos a partir do método de mínimos polígonos convexos, que é considerado bastante 
     confiável para o registro fóssil (Darroch & Saupe 2018). Táxons cujos 
     polígonos se sobrepõem serão considerados como co-ocorrentes. O método utilizado
     também permite que táxons em que não é possível construir polígonos (com menos que 3
     pontos de ocorrência geográfica) também sejam sobrepostos, e.g., se um táxon possui 
     apenas um ponto de ocorrência, mas está dentro da aréa de um polígono de outro táxon,
     ambos coexistem.
     
     # Multiplicação de matrizes
     As matrizes de coexistência temporal e espacial guardam a informação binária de
     coexistência, cada uma em uma dimensão. A multiplicação vetorial garante que apenas 
     há coexistência de fato, quando há coexistência nas duas dimensões, i.e.: 0 * 1 = 0,
     0 * 0 = 0, 1 * 1 = 1.
      

Valor:

     lista com n matrizes de série temporal, para cada momento de tempo. Cada matriz 
     possui os nomes da linhas e colunas com os nomes dos táxons do grupo de interesse,
     preenchida com '1' para as combinações par a par de táxons coexistentes no tempo e
     no espaço. 

Aviso:

	 Os pacotes "plyr", "tidyverse", "rgeos" e "rgdal", são necessários para a manipulação
	 dos dados e operações subsequentes. A função carrega automaticamente os pacotes, mas
	 eles devem ser instalados pelo usuário. A qualidade taxonômica dos dados de entrada
	 também deve ser observada. O usuário pode estar interessado em utilizar apenas espécies,
	 apenas gêneros ou qualquer outro nível taxonômico, e, portanto, as entradas do conjunto
	 de dados devem ser consistentes, i.e., no mesmo nível taxonômico.

Nota:

     Da forma como a função foi implementada, ela calcula os polígonos de distribuição dos
     táxons utilizando-se todas as ocorrências, assumindo uma área constante durante a
     longevidade do táxon. Isso não necessariamente reflete a realidade, pois a área de 
     distribuição de um táxon pode mudar ao longo do tempo. Uma abordagem mais próxima
     da realidade seria construir os polígonos para momentos de diferentes do tempo, porém
     isso necessita um conhecimento mais preciso sobre a real qualidade do registro e a 
     incerteza associada à cada ocorrência do conjunto de dados, pois cada ocorrência precisa
     ser alocada à um intervalo estratigráfico de interesse.

Autor (es):

     Rodolfo Pereira Graciotti
     rodolfo.graciotti@gmail.com

Referências:

     Marshall, Charles R. "Confidence intervals on stratigraphic ranges." Paleobiology 16.1 (1990): 1-10.
     Marshall, Charles R. "Using confidence intervals to quantify the uncertainty in the end-points of stratigraphic ranges." The Paleontological Society Papers 16 (2010): 291-316.
     Foote, Michael, et al. Principles of paleontology. Macmillan, 2007.
     https://paleobiodb.org/#/
     Darroch, Simon AF, and Erin E. Saupe. "Reconstructing geographic range-size dynamics from fossil data." Paleobiology 44.1 (2018): 25-39.

Exemplo:

     # lendo o data.frame de exemplo
	 can <- read.csv("canidae_data_frame.csv", header = T) # importa o data.frame de 
	 # exemplo, apenas com espécies de Canidae
	 names(can) # conferindo se os nomes batem com o proposto

	 db.site.1 <- coex_st(df = can, time.series = 1, space = "site", plot.longs = T) 
	 # aplica a função com um vetor de 1 milhão de anos, space como "site"
	 db.coord.1 <- coex_st(df = can, time.series = 1, space = "coords", plot.longs = T) 
	 # aplica a função com um vetor de 1 milhão de anos, space como "coords"
	 db.poly.1 <- coex_st(df = can, time.series = 1, space = "polygon", plot.longs = T) 
	 # aplica a função com um vetor de 1 milhão de anos, space como "polygon"

	 db.site.v <- coex_st(df = can, 
                     time.series = c(37.2,33.9,33.3,30.8,20.43,15.97,13.6,10.3,4.9,1.8,0.3,0.0117,0), 
                     space = "site", plot.longs = T) 
                     # aplica a função com um vetor específico, space como "site"
	 db.coord.v <- coex_st(df = can, 
                      time.series = c(37.2,33.9,33.3,30.8,20.43,15.97,13.6,10.3,4.9,1.8,0.3,0.0117,0), 
                      space = "coords", plot.longs = T) 
                      # aplica a função com um vetor específico, space como "coords"
	 db.poly.v <- coex_st(df = can, 
                     time.series = c(37.2,33.9,33.3,30.8,20.43,15.97,13.6,10.3,4.9,1.8,0.3,0.0117,0), 
                     space = "polygon", plot.longs = T) 
                     # aplica a função com um vetor específico, space "polygon"


	 # caso a premissa de que os graus de coexistência espacial aumentam a permissividade 
	 # da co-ocorrência, ao comparar o resultado dos diferentes métodos com o mesmo conjunto
	 # de dados e tempo, espera-se que o número absoluto de instâncias em que há 
	 # co-ocorrência deva ser: site < coords < polygon
	 sum(sapply(db.site.1, sum))
	 sum(sapply(db.coord.1, sum))
	 sum(sapply(db.poly.1, sum))
	 sum(sapply(db.site.v, sum))
	 sum(sapply(db.coord.v, sum))
	 sum(sapply(db.poly.v, sum))
\end{lstlisting}



\end{document}
