\documentclass[a4paper, oneside, 10pt]{article}
\usepackage[unicode]{hyperref}
\usepackage[utf8x]{inputenc}
\usepackage[english]{babel}
\usepackage{graphicx}
\graphicspath{{media/}}
\date{\today}
\title{}
\author{}
\begin{document}



\section{\texorpdfstring{RAFAEL CHAVES}{RAFAEL CHAVES}}
\label{sec:rafael_chaves}


\includegraphics[keepaspectratio=true,width=0.8\textwidth]{bie5782/01_curso_atual/alunos/trabalho_final/rafael.chaves/foto_rbc_escocia_2015}


doutorando em Ecologia, Instituto de Biociências - USP

Estou cursando doutorado no Programa de Pós-Graduação em Ecologia - IB, e trabalho na Secretaria do Meio Ambiente do estado. Meu interesse em pesquisa gira em torno da interface entre ciência ecológica e políticas públicas ambientais, com foco em restauração de ecossistemas e ecologia da paisagem. Tenho interesse em entender os drivers locais e de paisagem para o sucesso da restauração ecológica, bem como em compreender como seus benefícios podem ser otimizados na escala da paisagem.

\begin{center}
\line(1,0){250}
\end{center}



\section{\texorpdfstring{Meus exercícios}{Meus exercicios}}
\label{sec:meus_exercicios}


Para acessar meus exercícios resolvidos, clique em: \href{http://ecor.ib.usp.br./doku.php?id=05_curso_antigo:r2019:alunos:trabalho_final:rafael.chaves:exec}{.:exec}

\begin{center}
\line(1,0){250}
\end{center}



\section{\texorpdfstring{Proposta de Trabalho Final}{Proposta de Trabalho Final}}
\label{sec:proposta_de_trabalho_final}


\begin{center}
\line(1,0){250}
\end{center}



\subsection{\texorpdfstring{PLANO A - Função: vizinhos}{PLANO A  Funao vizinhos}}
\label{sec:plano_a__funao_vizinhos}


\subsubsection{\texorpdfstring{Contexto e usos potenciais}{Contexto e usos potenciais}}
\label{sec:contexto_e_usos_potenciais}


Calcular o número de vizinhos em um raio determinado a partir de múltiplos pontos permite inúmeras aplicações nas ciências biológicas.\\
No campo da restauração ecológica, no qual atuo, um sítio degradado (local) tem probabilidades mais altas de expressão de processos de regeneração natural quanto maiores forem as fontes de propágulos disponíveis (por exemplo, árvores nativas em uma paisagem dominadas por pasto). Assim, contabilizar o número de árvores em torno de um sítio em restauração, e a influência que este número pode ter na retomada de processos ecológicos importantes para a auto-sustentabilidade do ecossistema, pode ser uma ferramenta importante de análise e testes de hipóteses.\\
No entanto, diversos outros usos são possíveis. Para encontrar pontos com maiores chances de avistamento de uma espécie de ave que consome os frutos de determinada espécie de árvore, poderíamos selecionar locais candidatos a realização de ponto focal, e aplicando esta função poderíamos encontrar qual deles possui mais indivíduos da espécie de árvore em determinado raio de alcance.\\
Mesmo fora das ciências biológicas, podemos imaginar inúmeros outros usos. Por exemplo, alguém que queira se mudar e busque morar em um bairro arborizado, com uma base de dados das árvores urbanas e suas coordenadas poderia aplicar esta função a uma lista de casas potenciais, verificando qual delas tem mais árvores por perto. O mesmo poderia ser feito trocando-se as árvores por serviços úteis, na análise de proximidade.

\subsubsection{\texorpdfstring{Visão geral da tarefa}{Visao geral da tarefa}}
\label{sec:visao_geral_da_tarefa}


A função irá ranquear locais (pontos) em ordem decrescente com relação ao número de vizinhos localizados a determinado raio de distância de cada local. O croqui com a distribuição espacial dos locais ranqueados e do conjunto de vizinhos será o produto colateral da função.

\subsubsection{\texorpdfstring{Passo a passo da função}{Passo a passo da funao}}
\label{sec:passo_a_passo_da_funao}


\paragraph{\texorpdfstring{Entrada}{Entrada}}
\label{sec:entrada}

\begin{verbatim}
vizinhos(locais, vizi, raio, min.vizi, croqui)
\end{verbatim}

\begin{itemize}
  \itemlocais = Data frame com coordenadas x e y dos locais testados
  \itemvizi = Data frame com coordenadas x e y dos vizinhos encontrados
  \itemraio = Raio de abrangência no qual será computado o número de vizinhos
  \itemmin.vizi = Número mínimo de vizinhos a ser considerado para ranquear os locais e apresentá-los no croqui. Locais com número de vizinhos menor que este serão excluídos da análise
  \itemcroqui = Opção de gerar visualização gráfica da distribuição espacial dos locais e dos vizinhos
\end{itemize}


\paragraph{\texorpdfstring{Configurações padrão para os argumentos de entrada}{Configuraoes padrao para os argumentos de entrada}}
\label{sec:configuraoes_padrao_para_os_argumentos_de_entrada}

\begin{itemize}
  \itemO default para \textless min.vizi\textgreater  será 0, de modo que todos os locais aparecerão no ranking final
  \itemO default para \textless croqui\textgreater  será TRUE, gerando portanto a visualização gráfica da distribuição espacial dos locais e dos vizinhos
  \itemOs demais argumentos, \textless locais\textgreater  , \textless vizi\textgreater  e \textless raio\textgreater , não terão default, e deverão ser informados pelo usuário da função
\end{itemize}


\paragraph{\texorpdfstring{Testes de premissa}{Testes de premissa}}
\label{sec:testes_de_premissa}

\begin{itemize}
  \itemO objeto \textless locais\textgreater  deve possuir exatamente duas colunas (para coordenadas x e y), se não for, a função para e retorna a mensagem ,,número de colunas para o objeto \textless locais\textgreater  é diferente de 2"
  \itemAs duas colunas do objeto \textless locais\textgreater  devem ser da classe \textless numeric\textgreater , se não for, a função para e retorna a mensagem ,,ao menos uma das colunas do objeto \textless locais\textgreater  não é numerica"
  \itemO objeto \textless vizi\textgreater  deve possuir exatamente duas colunas (para coordenadas x e y), se não for, a função para e retorna a mensagem ,,número de colunas para o objeto \textless vizi\textgreater  é diferente de 2"
  \itemAs duas colunas do objeto \textless vizi\textgreater  devem ser da classe \textless numeric\textgreater , se não for, a função para e retorna a mensagem ,,ao menos uma das colunas do objeto \textless vizi\textgreater  não é numerica"
  \itemO objeto \textless raio\textgreater  deve ser um número maior que zero. Se o objeto for menor ou igual a zero, para a função e retorna a mensagem ,,o 'raio' informado deve ser maior que zero"
  \itemO objeto \textless min.vizi\textgreater , se informado, deve ser maior que zero. Se não for, a função para e retorna a mensagem ,, o argumento 'min.vizi' deve ser maior que zero."  (testar não no início, mas quando entrar no código)
  \itemO objeto \textless croqui\textgreater  deve ser da classe \textless logical\textgreater  (testar não no início, mas quando entrar no código)
\end{itemize}


\paragraph{\texorpdfstring{Correções dos argumentos}{Correoes dos argumentos}}
\label{sec:correoes_dos_argumentos}

\begin{itemize}
  \itemSe o objeto \textless locais\textgreater  contiver NAs, as respectivas linhas serão excluídas do objeto, e será apresentada a mensagem “as linhas de \textless locais\textgreater  contendo NA(s) foram excluídas”
  \itemSe o objeto \textless vizi\textgreater  contiver NAs, as respectivas linhas serão excluídas do objeto, e será apresentada a mensagem “as linhas de \textless vizi\textgreater  contendo NA(s) foram excluídas”
  \itemO objeto \textless min.vizi\textgreater , se informado, deve ser da classe \textless integer\textgreater . Se não for,  a função o converterá para \textless integer\textgreater  (testar não no início, mas quando entrar no código)
\end{itemize}


\paragraph{\texorpdfstring{Pseudo-código}{Pseudocodigo}}
\label{sec:pseudocodigo}

\begin{enumerate}
  \itemCriar matriz com distâncias \textless dists\textgreater  entre cada local (linhas da matriz) e cada um dos vizinhos (colunas da matriz)
  \itemCriar novo data frame \textless rank\textgreater  a partir do objeto \textless locais\textgreater  incluindo uma terceira coluna \textless n.vizi\textgreater 
  \itemAtribuir à nova coluna \textless n.vizi\textgreater  valores inteiros resultantes da soma de testes lógicos realizados entre os valores encontrados em \textless dists\textgreater  e o \textless raio\textgreater  informado, identificando quantas \textless dists\textgreater  são menores ou iguais a \textless raio\textgreater . A soma dos resultados dos testes lógicos descrita acima retornará quantos vizinhos (colunas de \textless dists\textgreater ) estão dentro do raio, para cada local (linhas de \textless dists\textgreater )
  \itemCriar critério de ordenamento para \textless rank\textgreater , em ordem decrescente para a coluna \textless n.vizi\textgreater 
  \itemReordenar \textless rank\textgreater  segundo o critério estabelecido, sobrescrevendo o objeto anterior
  \itemCaso o usuário tenha informado um valor para o argumento \textless min.vizi\textgreater , os locais com número de vizinhos inferior a \textless min.vizi\textgreater  serão excluídos do objeto \textless rank\textgreater . 
  \item Nesse caso, o novo \textless rank\textgreater , deverá sobrescrever o objeto \textless locais\textgreater  anterior.
  \itemCaso o usuário não tenha informado um valor para o argumento \textless min.vizi\textgreater , o item anterior não é executado
  \itemCaso o usuário não tenha alterado o default de \textless croqui\textgreater , que indica geração de visualização gráfica, a função deverá:

  \begin{enumerate}
    \itemplotar a totalidade dos vizinhos no gráfico
    \itemplotar, em cor ou símbolo diferente, os locais listados em \textless rank\textgreater 
    \itemplotar as circunferências dos raios de inclusão em torno de cada local
  \end{enumerate}
  \itemCaso a opção de \textless croqui\textgreater  seja pela não geração de gráfico, o item anterior não é executado
\end{enumerate}


\paragraph{\texorpdfstring{Saída}{Saida}}
\label{sec:saida}

\begin{itemize}
  \itemTabela com locais ranqueados conforme o número de vizinhos, em ordem decrescente
  \itemSe croqui=TRUE, é gerado também o gráfico de distribuição espacial dos locais ranqueados e da totalidade dos vizinhos, apresentando o raio de inclusão em torno de cada local
\end{itemize}


\paragraph{\texorpdfstring{Desafios previamente identificados para a execução do plano A}{Desafios previamente identificados para a execuao do plano A}}
\label{sec:desafios_previamente_identificados_para_a_execuao_do_plano_a}

\begin{itemize}
  \itemAprender a utilizar a função order(), ou outra similar, para ranquear a tabela que será o produto principal da função
  \itemGerar coluna com número de vizinhos abrangido pelo \textless raio\textgreater 
  \itemAprender a diferenciar graficamente pontos plotados nos argumentos \textless locais\textgreater  e \textless vizi\textgreater 
  \itemAprender a plotar o raio no entorno de cada um dos locais
\end{itemize}


\begin{center}
\line(1,0){250}
\end{center}



\subsection{\texorpdfstring{PLANO B - Função: monitoramento}{PLANO B  Funao monitoramento}}
\label{sec:plano_b__funao_monitoramento}


\subsubsection{\texorpdfstring{Contexto}{Contexto}}
\label{sec:contexto}


O Brasil possui uma importante legislação que prevê a proteção e restauração da vegetação nativa, a Lei 12.651/2012, também conhecida como Novo Código Florestal. Esta lei prevê que determinadas áreas de preservação nos imóveis rurais, marcadamente as APPs (Áreas de Presenvação Permanente) e RLs (Reservas Legais) devem ser mantidas com vegetação nativa e, caso esta vegetaçnao esteja ausente, a vegetação deve ser restaurada. No entando, a lei federal não detalha os parâmetros que devem ser observados para considerar a vegetação restaurada, ficando tal regulamentação a cargo dos estados. O primeiro estado a regulamentar estes parâmetros foi São Paulo, que estipulou três indicadores ecológicos, que nada mais são que variáveis resposta que devem ser medidas em campo, por meio de metodologia pré-estabelecida, para verificar se os projetos de restauração atendem aos resultados ecológicos mínimos esperados, indicados por valores de referência (Chaves et al. 2015). Atualmente, outros estados como Rio de Janeiro, Mato Grosso e Distrito Federal já adotam sistemas semelhantes de monitoramento, e outros estão a caminho de adotar. Em todos estes casos, são os executores de projetos que medem as variáveis em campo, informando os resultados ao órgão ambiental. No entanto, o órgão precisa realizar auditorias em uma parte dos projetos.\\
A função descrita nesta proposta poderia auxiliar a tomada de decisão para a seleção de projetos a serem auditados, auxiliando a implementação das políticas ambientais em SP e outros estados brasileiros.\\
Apesar de ser esta a inspiração para a função, ela poderia ser utilizada por quaisquer interessados em comparar valores observados com valores esperados, para uma quantidade y de variáveis resposta em uma quantidade x de observações.

\subsubsection{\texorpdfstring{Visão geral da tarefa}{Visao geral da tarefa}}
\label{sec:visao_geral_da_tarefa2}


A função irá confrontar: a) valores aferidos em campo para um conjunto de variáveis resposta; com b) valores de referência esperados. Serão aferidos: c) o número de variáveis com valores abaixo do esperado (nível crítico), e d) o índice de criticidade para identificar as observações que ficaram mais aquém dos valores esperados. Os produtos da função serão o histograma com a distribuição dos valores encontrados para o índice de criticidade e a tabela ranqueando as observações segundo o índice.

\subsubsection{\texorpdfstring{Passo a passo da função}{Passo a passo da funao}}
\label{sec:passo_a_passo_da_funao2}


\paragraph{\texorpdfstring{Entrada}{Entrada}}
\label{sec:entrada2}

\begin{verbatim}
monitora(dados, referencia, salva.hist, salva.tabela)
\end{verbatim}

\begin{itemize}
  \itemdados = Data frame composto por um número y de variáveis resposta (representados por colunas do data frame) e um número x de observações (linhas do data frame). Os nomes de cada variável resposta deverão constar como títulos de cada coluna (head=TRUE).
  \itemreferencia = Os valores de referência esperados estarão disponíveis neste argumento que deve ser um data frame de referência, com número de linhas e colunas iguais aos do argumento 1 \textless dados\textgreater 
  \itemsalva.hist = permite salvar o histograma gerado, caso o usuário necessite
  \itemsalva.tabela = permite salvar a tabela de ranqueamento, caso o usuário necessite
\end{itemize}


\paragraph{\texorpdfstring{Padrões para entrada}{Padroes para entrada}}
\label{sec:padroes_para_entrada}

\begin{itemize}
  \itemsalva.hist = NULL, indicando que não será salvo o histograma, apenas visualizado. O usuário pode alterar.
  \itemsalva.tabela = NULL, indicando que não será salva a tabela, apenas visualizada. O usuário pode alterar.
  \item\textless dados\textgreater  e \textless referência\textgreater  não terão padrão de entrada, devendo ser informados pelo usuário.
\end{itemize}


\paragraph{\texorpdfstring{Testes de premissa}{Testes de premissa}}
\label{sec:testes_de_premissa2}

\begin{itemize}
  \itemTanto para \textless dados\textgreater  quanto para \textless referencia\textgreater , os NAs devem ser transformados para zero nos data frames antes de serem carregados como argumentos da função
  \itemTodas as células devem ter valores numéricos
  \itemO números de linhas e colunas de \textless dados\textgreater  e \textless referencia\textgreater  devem ser iguais entre si
\end{itemize}


\paragraph{\texorpdfstring{Pseudo-código}{Pseudocodigo}}
\label{sec:pseudocodigo2}

\begin{enumerate}
  \itemCriar data frame de resultado, chamado \textless resultado\textgreater , que inicialmente será criado como uma cópia do objeto \textless dados\textgreater .
  \itemCriar nova coluna do data frame \textless resultado\textgreater  chamada \textless n.criticos\textgreater , na qual constará, para cada observação,  quantas das variáveis resposta tiveram valor observado inferior ao esperado.
  \itemCriar nova coluna do data frame \textless resultado\textgreater  chamada \textless criticidade\textgreater , na qual será calculado, para cada observação, o ,,índice de criticidade" (ver abaixo) que permitirá identificar as observações que ficaram mais aquém dos valores esperados.
  \itemEstabelecer critério de reordenamento do data frame \textless resultado\textgreater : 

  \begin{enumerate}
    \itemcritério 1: ordem crescente dos índices de criticidade,
    \itemcritério 2: ordem decrescente de n.criticos. 
  \end{enumerate}
  \itemReordenar o data frame \textless resultado\textgreater , sobrescrevendo no mesmo objeto
  \itemCaso o usuário tenha informado que quer salvar o histograma com o comando \textless salva.hist\textgreater , deverá ser aberta função para salvar a imagem do histograma
  \itemCaso o usuário tenha informado que quer salvar o histograma com o comando \textless salva.tabela\textgreater , deverá ser aberta função para salvar a tabela retornada pela função
\end{enumerate}


O índice de criticidade possui a seguinte fórmula preliminar:
\begin{verbatim}
Índice de criticidade = -(100^nc) + ∑ (vo-vr)
nc = número de variáveis resposta com nível crítico (abaixo do esperado)
vo = valores observados para cada variável resposta com nível crítico
vr = valores de referência para a respectiva variável resposta com nível crítico
\end{verbatim}


obs: Os elementos que sucedem o símbolo de somatório serão tantos quantas forem as colunas do argumento \textless dados\textgreater 

\paragraph{\texorpdfstring{Saída}{Saida}}
\label{sec:saida2}

\begin{itemize}
  \itemGerar histograma (produto colateral da função) com a ocorrência dos valores do índice de criticidade encontrados para cada observação
  \itemApresentar tabela final, já ordenada em ordem crescente dos índices de criticidade
\end{itemize}


\emph{\textbf{Observações}}
\begin{itemize}
  \itemA concepção do ,,índice de criticidade" foi produzido no âmbito desta proposta de trabalho final, por isso não está indicada referência bibliográfica. 
  \itemApós um tempo desenvolvendo a ideia deste plano B, percebi que aspectos que não estão claros para mim na tarefa em si podem dificultar a execução do código e help da função.
  \itemO fato do ,,índice de criticidade" ainda não ter sido testado até o momento dificulta a minha concepção, e acaba me trazendo desafios menos relacionados ao R e mais ao funcionamento do índice.
\end{itemize}


\subsubsection{\texorpdfstring{Referências}{Referencias}}
\label{sec:referencias}

\begin{itemize}
  \itemChaves RB, Durigan G, Brancalion PHS, Aronson J (2015) On the need of legal frameworks for assessing restoration projects success: new perspectives from São Paulo state (Brazil). Restoration Ecology, 23(6): 754-759
\end{itemize}


\begin{center}
\line(1,0){250}
\end{center}



----

Olá Rafael. As suas duas propostas são factiveis e com um nível de dificuldade equilibrado. Eu particularmente acho a proposta A mais interessante e útil para outros usuários. Na proposta A, eu tomaria cuidado com o o nome do parâmetro (,,plot") que é o nome de uma função, isso vai confundir as pessoas e talvez até o R. Mas isso é um pequeno detalhe. Sobre os seus testes de premissa, talvez você possa deixar sua função mais robusta se você tentasse corrigir alguns erros. Por exemplo, se existe NA no data frame do plot ou do vizi, você remove os NAs e ao invés de dar erro dá um warning dizendo que rodou, mas removeu os NAs. O mesmo para numeric, vc a tenta força as informações para ser numeric e faz um teste lógico para saber se conseguiu transformar em número ou não. Se sim, dá um warning dizendo que teve que transformar, se não aí dá erro.

Acho que você não terá dificuldade em fazer essa função, mas vai te exigir um certo conhecimento sobre controle de fluxo. Seria legal se até a versão final da proposta você já conseguisse detalhar o que vai ter dentro dos for e if que você vai precisar. Mas claro, pensar nesses detalhes também faz parte do desenvolvimento da função em si. Portanto, fique a vontade para usar o tempo de fazer a função para pensar nesses detalhes. 

Boa Sorte e taca-le pau!

 --- \emph{\href{mailto:bruno.travassos@gmail.com>,}{Bruno Travassos} 2019/06/14 12:13}

\begin{center}
\line(1,0){250}
\end{center}



Oi Bruno, 
Conforme havia indicado por email, concordei com sua avaliação de que a proposta A é mais interessante, e a selecionei para desenvolver o trabalho final. 
Sendo assim, na versão final da proposta, incorporei suas sugestões:\\
\begin{enumerate}
  \item Alterar o nome do primeiro argumento de ,,plot" para ,,locais"
  \item Acrescentar algumas correções de erros dos argumentos:

  \begin{enumerate}
    \item Remoção de linhas com NAs em \texttt{locais} e \texttt{vizi}
    \item Transformar \texttt{min.vizi} na classe integer
  \end{enumerate}
  \end{enumerate}


Também incluí mensagens de aviso e refinei as premissas.\\
\texttt{locais} e \texttt{vizi} serem numéricos eu preferi manter como premissa, para que o usuário esteja consciente do que está fazendo, já que a conversão de arquivos de coordenadas que não estejam em escala absoluta (p.ex. geográficas), poderia retornar resultados errados.\\
No final achei que a função ficou menos engessada sem especificar um par(), de modo que o usuário pode inserir seus parâmetros gráficos favoritos antes de rodar a função.\\
Agradeço pelas sugestões!\\
Abraços,\\
Rafael

\begin{center}
\line(1,0){250}
\end{center}



\section{\texorpdfstring{Trabalho Final}{Trabalho Final}}
\label{sec:trabalho_final}


Para a entrega do trabalho final, decidi desenvolver a proposta A, cujo objetivo é ranquear locais quanto ao seu número de vizinhos a determinado raio, e secundariamente gerar um croqui para visualização gráfica.
Dessa forma, desenvolvi o código da função \texttt{vizinhos}, disponível no link do item \textbf{\emph{1}}, bem como a respectiva página de ajuda, disponível no link do item \textbf{\emph{2}}:
      \begin{enumerate}
  \item Código da função: \href{http://ecor.ib.usp.br./doku.php?id=05_curso_antigo:r2019:alunos:trabalho_final:rafael.chaves:funcao_vizinhos}{.:funcao_vizinhos}.
  \item Página de ajuda da função: \href{http://ecor.ib.usp.br./doku.php?id=05_curso_antigo:r2019:alunos:trabalho_final:rafael.chaves:help_vizinhos}{.:help_vizinhos}.
\end{enumerate}


\end{document}
