Help competition()

competition()   	     package:nenhum		R Documentation

Neighborhood Crowding Effect Computation

Description:
A função computa e retorna um data frame com o a magnitude do efeito de competição (neighborhood crowding effect) sobre cada indivíduo de uma comunidade arbórea em função da identidade, tamanho e distância dos seus vizinhos[1]. 
Também retorna um gráfico do tipo bubble plot expressando os valores do índice e a localização dos indivíduos.

Usage:
competition(data, coef, graphic=TRUE, NArm=TRUE, table=TRUE)

Arguments:
data: um data frame contendo as observações (indivíduos) e as variáveis necessárias para a computação do índice: código do indivíduo, espécie, tamanho, coordenada x, coordenada y. Ver Details.
coef: uma matriz contendo os coeficientes de escala espacial de efeito para todos os pares de espécies. Ver Details
graphic: se graphic = TRUE retorna um gráfico dos valores do índice e das coordenadas espaciais dos indivíduos. 
NArm: argumento que manipula o data frame para omitir valor faltantes durante os cálculos do índice.  Se NArm = TRUE, os NA’s serão omitidos. 
table: se table = TRUE exporta um arquivo com os valores do índice de competição por indivíduo para o diretório de trabalho. 

Details:
'competition' é uma função que computa e retorna um índice (Wij) que expressa a magnitude do efeito de competição sofrido por um indivíduo arbóreo i da espécie j de acordo com a sua vizinhança. O índice também é conhecido na literatura como neighborhood crowding effect [2,3]. A intensidade do efeito é uma função da identidade, do tamanho e da distância dos vizinhos do indivíduo focal i. E o valor será diretamente proporcional ao tamanho dos seus vizinhos, mas inversamente proporcional à distância deles. Ou seja, quanto maior ou mais próximo o vizinho, maior o efeito de competição. Para a computação dos valores, o usuário deve fornecer dois objetos:
1.Data frame com as seguintes variáveis:
#coluna1: variável indicando um código único para cada indivíduo;
#coluna2: variável indicando o nome ou o código referente à espécie do indivíduo;
#coluna3: variável indicando o tamanho (DAP: diâmetro à altura do peito) do indivíduo;
#coluna4: coordenada cartesiana do indivíduo no eixo horizontal (x);
#coluna5: coordenada cartesiana do indivíduo no eixo vertical (y).

2.Matriz de escala espacial de efeito (αjm):  
Informa a escala espacial dentro da qual vizinhos de uma espécie m exercem efeitos sobre as taxas vitais de vizinhos da espécie j (calculado previamente a partir de modelos de regressão). É importante ressaltar que não necessariamente αjm = αmj, exceto nos casos de indivíduos da mesma espécie (onde m = j). As espécies que exercem os efeitos (m) devem estar nas linhas e as espécies que recebem o efeito (j) devem estar nas colunas.

Value:
'competition' retorna um gráfico expressando os valores do índice e a localização dos indivíduos. 
Também retorna um objeto da classe data frame contendo as seguintes variáveis:
Individuals: código do indivíduo focal
Wij: valor do efeito competitivo sofrido pelo indivíduo focal

Notes:
A distância calculada entre os indivíduos é a distância euclidiana.

Author:
Nathalia Monalisa Francisco <nathaliamonalisa@gmail.com>


References:
¹Adler, P. B., Ellner, S. P., & Levine, J. M. (2010). Coexistence of perennial plants: An embarrassment of niches. Ecology Letters, 13(8), 1019–1029. doi:10.1111/j.1461-0248.2010.01496.x 
²Chu, C., & Adler, P. B. (2015). Large niche differences emerge at the recruitment stage to stabilize grassland coexistence. Ecological Monographs, 85(3), 373–392. doi:10.1890/14-1741.1 
³Uriarte, M. et al.(2010). Trait similarity, shared ancestry and the structure of neighbourhood interactions in a subtropical wet forest: Implications for community assembly. Ecology Letters, 13(12), 1503–1514. doi:10.1111/j.1461-0248.2010.01541.x


See Also:
'plot_ly' do pacote plotly para elaboração do gráfico de pontos (bubble plot).
'dist' do pacote stats para computar a matriz de distância de forma automatizada.

Examples:
require(plotly)

#1.Criando data frame
individuo = seq(1,300) #comunidade hipotética formada por 300 indivíduos
especies = rep(seq(1001,1050),each=6) #código fictício para nome das espécies. Riqueza = 50spp.
tamanho = rnorm(300,15,7) #distribuição de tamanhos
coordx = rpois(300,7) #coordenada x: criando valores
coordx = seq(1,10)*coordx #coordx: "bagunçando" os valores
coordy = rpois(300,7)#coordenada y: criando valores
coordy = seq(1,10)*coordy #coordy: "bagunçando" os valores

df.teste = data.frame(individuo,especies,tamanho,coordx,coordy) #juntando os vetores em um dataframe
df.teste = rbind(df.teste,rep(NA,5)) #acrescentando observações faltantes

#2.Criando matriz de escala espacial
matriz = matrix(abs(rnorm(250,0.5,0.5)),ncol=50,nrow=50,byrow=TRUE) # distribuição dos coeficientes
colnames(matriz) = seq(1001,1050) #nome das colunas
rownames(matriz) = colnames(matriz) #nome das linhas

#Função
competition(df.teste,matriz,NArm=TRUE,graphic=TRUE,table=TRUE)