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


\begin{itemize}
  \item \href{http://ecor.ib.usp.br./doku.php?id=02_tutoriais:tutorial11:start}{ Tutorial}
  \item \href{http://ecor.ib.usp.br./doku.php?id=01_curso_atual:exertexto}{ Exercícios} 
  \item  Apostila
\end{itemize}


\section{\texorpdfstring{Edição de Texto}{Ediao de Texto}}
\label{sec:ediao_de_texto}


Em muitos casos e aplicações as informações que queremos manipular ou analisar não são numéricas. Elas são compostas por caracteres de texto. Essas informações vão desde variáveis categóricas (e.g. ,,sim" ou ,,não") até campos de texto livre, contendo descrições associadas a uma dada observação. Em ecologia e ciências florestais, um caso muito comum desse tipo de informação é o nome da espécie do qual foi tomada uma certa medida ou realizada uma certa contagem.

Se o nosso conjunto de dados é pequeno, editar manualmente o texto pode ser a solução mais direta ou simples. Mas à medida que o conjunto de dados cresce e a complexidade das edições aumenta, aprender técnicas básicas de manipulação de texto podem poupar muito tempo de trabalho.

Assim como outras linguagens de programação, o R está preparado e possui várias funções disponíveis para manipular texto. Mas, ele também possui as suas particularidades e conhecê-las é um importante passo para atingir a proficiência nessa linguagem. Assim, neste tutorial iremos apresentar conceitos básicos e alguns exemplos práticos de manipulação e edição de texto no R:  
\begin{enumerate}
  \item Vetores de texto no R
  \item Operando vetores de texto
  \item Funções básicas de manipulação
  \item Manipulação de texto usando expressões regulares
  \item Exemplos práticos no R
\end{enumerate}


\section{\texorpdfstring{Vetores de texto no R}{Vetores de texto no R}}
\label{sec:vetores_de_texto_no_r}


Informações de texto no R são armazenadas em objetos que são vetores da classe \texttt{character}, que podem ser vazios ou ter comprimento 1 ou mais.

O R possui uma função para gerar vetores nulos ou vários de texto, a função \texttt{character()} que possui apenas um argumento \texttt{length} que define o tamanho do vetor. Por exemplo:\lstset{frame=single, language=rsplus}
\begin{lstlisting}

vetor <- character(length = 5)
vetor

class(vetor)
is.character(vetor)
 
\end{lstlisting}



Frequentemente, o vetor de texto é obtido a partir de um arquivo contendo o conjunto de dados. Para esse tutorial, iremos gerar um pequeno vetor de texto com nomes fictícios de espécies para mostrar como vetores de texto podem ser operados usando algumas funcionalidades básicas do R para vetores com outras classes de elementos (e.g. numéricos ou lógicos)\lstset{frame=single, language=rsplus}
\begin{lstlisting}

texto <- c("esp A", "esp C", "esp B", "esp B", "esp B1", "Esp D10")
sort(texto)
sample(x = texto, size = 2)
duplicated(texto)

\end{lstlisting}



Veja que a função \texttt{sort} organiza tanto vetores númericos quanto de texto, este último que são organizados em ordem alfabética. Da mesma maneira as funções \texttt{sample} e \texttt{duplicated} (e várias outras) também funcionam para vetores de texto. Obviamente, nem todas as funções irão funcionar, em especial aquelas relacionadas a operações exclusivas para números (e.g. matemáticas).\lstset{frame=single, language=rsplus}
\begin{lstlisting}

sum(texto)
## Erro...
\end{lstlisting}



\section{\texorpdfstring{Funções básicas de manipulação texto}{Funoes basicas de manipulaao texto}}
\label{sec:funoes_basicas_de_manipulaao_texto}


Assim como existem funções específicas para manipular vetores numéricos, existem funções para manipular vetores de texto.

\subsection{\texorpdfstring{Número de elementos e caracteres}{Numero de elementos e caracteres}}
\label{sec:numero_de_elementos_e_caracteres}


As funções \texttt{length} e \texttt{nchar} funcionam para vetores numéricos e para vetores de texto. A primeira retorna o comprimento do vetor, enquanto que a segunda retorna o número de caracteres de cada elemento do vetor. \lstset{frame=single, language=rsplus}
\begin{lstlisting}

length(texto) 
## 6
nchar(texto) 
## 5 5 5 5 6 7
\end{lstlisting}



\subsection{\texorpdfstring{Capitalização}{Capitalizaao}}
\label{sec:capitalizaao}


As funcionalidades básicas relacionadas a tornar letras de vetores em maiúsculas ou minúsculas são: \texttt{toupper}, \texttt{tolower} e \texttt{casefold}. Esta última função é mais flexível e pode transformar as letras tanto em maiúsculas quanto minúsculas \lstset{frame=single, language=rsplus}
\begin{lstlisting}

tolower(texto) # o mesmo que:
casefold(texto, upper = FALSE)

toupper(texto) # o mesmo que:
casefold(texto, upper = TRUE)
\end{lstlisting}



\subsection{\texorpdfstring{Colagem e concatenação}{Colagem e concatenaao}}
\label{sec:colagem_e_concatenaao}


Duas funções muito úteis ao trabalho com vetores de texto são as funções \texttt{paste} e \texttt{cat}. A primeira concatena elementos um ou mais vetores e o resultado dela pode ser salvo em um objeto ou imprimir o resultado da operação no console do R.

A segunda é mais usada apenas para concatenar e imprimir o resultado no console do R, sendo muito usado dentro de funções e dos ciclos de iteração (i.e. loops) que vimos anteriormente.

Uma variante da função \texttt{paste} é a função \texttt{paste0}, que funciona de maneira parecida porém não possui opções sobre como separar os elementos colados.\lstset{frame=single, language=rsplus}
\begin{lstlisting}

paste(texto, "- area 1")
paste0(texto, "-area", 1:length(texto))

cat("As espécies encontradas foram:", texto)

\end{lstlisting}



\subsection{\texorpdfstring{Localização e substituição}{Localizaao e substituiao}}
\label{sec:localizaao_e_substituiao}


Duas funções muito úteis são as funções de localização \texttt{grep} e \texttt{grepl}. A primeira retorna apenas a posição dos elementos que contém a busca desejada (no nosso exemplo a palavra maiúscula 'C'). Já a função \texttt{grepl} retorno o vetor lógico de mesmo tamanho com 'TRUE' nas posições que contém a busca desejada.\lstset{frame=single, language=rsplus}
\begin{lstlisting}

grep("C", texto)
grepl("C", texto)

\end{lstlisting}



Além de localizar é possível substituir caracteres de texto usando as funções \texttt{chartr} ou \texttt{sub} e \texttt{gsub}. A função \texttt{chartr} faz substituições caractere a caractere. Já as funções \texttt{sub} e \texttt{gsub} (de substituição e substituição global) são mais versáteis.\lstset{frame=single, language=rsplus}
\begin{lstlisting}

chartr("C", "E", texto)
chartr("C", "E1", texto) # não era bem isso que queríamos

sub("C", "E1", texto)
gsub("C", "E1", texto)
\end{lstlisting}



\subsection{\texorpdfstring{Divisão, corte e abreviação}{Divisao corte e abreviaao}}
\label{sec:divisao_corte_e_abreviaao}


É possível ainda dividir ou ,,quebrar" vetores de texto baseado em letras, espaços, pontuação ou qualquer outro caractere desejado. Para usamos a função \texttt{strsplit}. 

No exemplo abaixo, fazemos a separação por espaço, com o intuito de separar as duas partes dos nossos nomes fictícios de espécie. Note que a função não retorna um vetor e sim uma lista de mesmo comprimento com o resultado da operação.\lstset{frame=single, language=rsplus}
\begin{lstlisting}

strsplit(texto, split = " ")
\end{lstlisting}



É possível extrair caracteres dos vetores de texto. Isso pode ser feito extraindo um número fixo do início de cada elemento usando a função \texttt{strtrim} ou usando comprimentos variáveis e mais flexíveis tanto no início quanto no fim de cada elemento  usando as funções \texttt{substr} ou \texttt{substring}.\lstset{frame=single, language=rsplus}
\begin{lstlisting}

strtrim(texto, width = 2)
substr(texto, start = 1, stop = 2)
substring(texto, first = 1, last = 2)
\end{lstlisting}



Por último é possível abreviar vetores de texto usando a função \texttt{abbreviate} e seu argumento \texttt{minlength} para escolher o número ideal de caracteres que cada elemento do resultado deve ter.\lstset{frame=single, language=rsplus}
\begin{lstlisting}

abbreviate(texto, minlength = 4)
\end{lstlisting}



\section{\texorpdfstring{Expressões regulares}{Expressoes regulares}}
\label{sec:expressoes_regulares}


Os exemplos e funcionalidades que vimos acima dependiam de buscas exatas. Ou seja, a função só identificava, localizava, substituía ou dividia o texto baseado em caracteres de busca únicos e explicitamente definidos (e.g. \texttt{sub(,,C", ,,E1", texto)}). Nesse formato, cada operação é específica e, de certa forma, limitada.

Para aproveitar todo o potencial da manipulação de texto devemos usar as chamadas Expressões Regulares (ou 'RegExp' do inglês). Usadas em quase todas as linguagens de programação (e.g. Java, Python, Ruby, etc.) essas expressões permitem identificar caracteres (ou cadeias de caracteres) de interesse de maneira mais flexível, concisa e generalizável. 

'RegExp' é praticamente uma linguagem à parte e nem sempre é fácil de criar ou entender ou traduzir uma expressão regular. Alguns sites podem ajudar nessa tarefa (e.g. \href{http://www.regextranslator.com}{www.regextranslator.com}). Mas entender o básico já é muito útil para tornar a manipulação do texto ainda mais poderosa.

Por exemplo, podemos usar 'RegExp' para identificar qualquer elemento em um vetor de texto que termina com letras maiúsculas. Para isso, podemos usar a seguinte expressão regular (ou padrão de busca):\lstset{frame=single, language=rsplus}
\begin{lstlisting}

grepl('[A-Z]$', texto)
\end{lstlisting}



Em bom português, a expressão \texttt{[A-Z]\$} que dizer: 'identifique o elemento contendo qualquer letra maiúscula de A a Z (o componente \texttt{[A-Z]}) no final da cadeia de caracteres (componente \texttt{\$})'.

\subsection{\texorpdfstring{Padrões individuais e âncoras}{Padroes individuais e ancoras}}
\label{sec:padroes_individuais_e_ancoras}


Na expressão acima introduzimos dois elementos básicos: as sequências ou intervalos de caracteres de busca (declarados usando os colchetes \texttt{[]}) e as âncoras, que podem ser usadas para identificar o fim da cadeia de caracteres (declarado usando \texttt{\$}) ou no ínicio (declarado usando \texttt{\textasciicircum{}}).

O resultado da busca é bem distinto se usarmos a âncora de início, pois nenhum dos elementos começam com uma letra maiúscula. O resultado também depende da sequência de letras declaradas. Por exemplo, poderíamos buscar apenas vogais maiúsculas ao invés de todas as letras maiúsculas:\lstset{frame=single, language=rsplus}
\begin{lstlisting}

grepl('^[A-Z]', texto)
grepl('[AEIOU]$', texto)
\end{lstlisting}



Existem muitos outros padrões e âncoras para expressões regulares, mas os mais usuais são:
\begin{verbatim}

* ''\\d'' ou ''[:digit:]'': qualquer digito/número (oposto ''\\D'')
* ''\\s'' ou ''[:space:]'': qualquer espaço (oposto ''\\S'')
* ''\\b'': início e fim (limites) de palavras (oposto ''\\B'')
* ''\\w'' ou ''[:alnum:]'': qualquer letra ou dígito (oposto ''\\W'')
* ''[:alpha:]'': qualquer letra
* ''[:lower:]'': qualquer letra minúscula
* ''[:upper:]'': qualquer letra maiúscula
* ''[:punct:]'': qualquer pontuação
* ''[:ascii:]'': qualquer caracteres ASCII

\end{verbatim}


\subsection{\texorpdfstring{Alternância}{Alternancia}}
\label{sec:alternancia}


E se eu quiser identificar qualquer elemento de texto que termina ou começa com letras maiúsculas? Você pode combinar duas expressões com o sinal de 'ou' que no R é representado pelo operador \texttt{|} (barra vertical).\lstset{frame=single, language=rsplus}
\begin{lstlisting}

grepl('[A-Z]$', texto) | grepl('^[A-Z]', texto)
\end{lstlisting}



Ou você pode usar alternância dentro da própria expressão usando o mesmo operador \texttt{|}, que permite buscar dois ou mais padrões de busca de uma vez só. \lstset{frame=single, language=rsplus}
\begin{lstlisting}

grepl('[A-Z]$|^[A-Z]', texto)
\end{lstlisting}



\subsection{\texorpdfstring{Agrupamento}{Agrupamento}}
\label{sec:agrupamento}


Além de identificar podemos também substituir padrões usando RegExp. Por exemplo, vamos substituir todo elemento de texto que termine em um espaço seguido por letras maiúsculas, que pode ser traduzido para RegExp usando o padrão \texttt{' [A-Z]\$}'. Iremos substituir esse padrão por um elemento vazio, o que equivale a um apagador.\lstset{frame=single, language=rsplus}
\begin{lstlisting}

gsub(' [A-Z]$', '', texto)
\end{lstlisting}



Note que, como o padrão não é identificado nos últimos elementos do vetor \texttt{texto}, a substituição não é feita.

É possível ainda fazer substituições mais arrojadas. Por exemplo, substituir espaços por traços e letras finais maiúsculas por minúsculas, usando agrupamento. Nesse caso específico, precisamos definir o argumento \texttt{perl} como \texttt{TRUE}, para ativarmos a compatibilidade com expressões regulares em linguagem Perl (mas não se preocupem com isso agora). \lstset{frame=single, language=rsplus}
\begin{lstlisting}

gsub('( )([A-Z]$)', '-\\L\\2', texto, perl = TRUE)
\end{lstlisting}



O agrupamento é feito usando '()' (parênteses) e o seu uso permite isolar os elementos que queremos identificar (i.e. o escopo). No exemplo acima, em português, estamos identificando dois grupos: um espaço \texttt{'( )}' seguido de uma letra final maiúscula de A a Z \texttt{'([A-Z]\$)}'.

Note que ao usar agrupamento, podemos fazer substituições para cada grupo. No exemplo acima estamos substituindo o primeiro grupo (o espaço) por um traço (\texttt{-}) e transformamos o segundo grupo (\texttt{[A-Z]\$}, identificado por \texttt{\textbackslash{}\textbackslash{}2} na substituição) em letras minúsculas, usando o \texttt{\textbackslash{}\textbackslash{}L} (L representa a plavra em inglês 'lower').

\subsection{\texorpdfstring{Quantificadores}{Quantificadores}}
\label{sec:quantificadores}


Usando 'RegExp' é possível também especificar a quantidade de vezes que queremos identificar ou operar caracteres de texto, usando os chamados 'quantificadores'. Eles vem logo após o padrão em si e eles especificam buscas de um padrão pelo menos uma vez, todas as vezes ou o número de vezes que você quiser!

Os quantificadores em R e seus significados são:
\begin{verbatim}

* ''?'' (interrogação): identifica o padrão no máximo 1 vez (i.e. zero ou 1)
* ''*'' (aterisco): identifica o padrão zero ou mais vezes
* ''+'' (sinal de adição): identifica o padrão pelo menos 1 vez
* ''{n}'' : identifica o padrão exatamente n vezes
* ''{n,}'' : identifica o padrão pelo menos n vezes
* ''{n,m}'' : identifica o padrão pelo menos n e no máximo m vezes

\end{verbatim}


Vamos aos exemplos para deixar os quantificadores mais palpáveis. Para isso, vamos usar um vetor de nomes de pessoas como exemplo (para facilitar).

Primeiro, vamos identificar os elementos que contém zero ou 1 letra 'm'\lstset{frame=single, language=rsplus}
\begin{lstlisting}

nomes <- c("renato", "maria", "mohammed", "luís 4", "luís 15")
grep(pattern= "m+", nomes, value = TRUE) # pelo menos 1 'm'
grep(pattern= "m{2}", nomes, value = TRUE) # pelo menos 1 'mm'
grep(pattern= "m+.h", nomes, value = TRUE) # pelo menos 1 'm' e 'h'
grep(pattern= "\\d", nomes, value = TRUE) # nomes com digitos
grep(pattern= "\\d{2}", nomes, value = TRUE) # pelo menos 2 digitos

\end{lstlisting}



\subsection{\texorpdfstring{Funções específicas para RegEx no R}{Funoes especificas para RegEx no R}}
\label{sec:funoes_especificas_para_regex_no_r}


Se você quiser extrair o resultado das buscas, ao invés de apenas listar quais elementos contém a busca, você pode usar as funções do R que são específicas para o uso de expressões regulares. Por exemplo, as funções \texttt{regexpr()} e \texttt{regexec()} fazem a busca e a função \texttt{regmatches()} uso o resultado dessas funções para fazer a extração. A diferença entre as duas funções de busca é na maneira que elas retornam a busca (vetor ou lista).\lstset{frame=single, language=rsplus}
\begin{lstlisting}

regmatches(nomes, m = regexpr('m{2}', nomes))
regmatches(nomes, m = regexec('m{2}', nomes))
\end{lstlisting}



\section{\texorpdfstring{Para saber mais}{Para saber mais}}
\label{sec:para_saber_mais}


Pronto, você já sabe o básico para poder manipular vetores de texto no R. Veja abaixo algumas sugestões para você se aprofundar no assunto.
\begin{itemize}
  \item veja o help do próprio R usando \texttt{?regexp}
  \item site do wikipedia em português (\url{https://pt.wikipedia.org/wiki/Express\%C3\%A3o_regular})
  \item ,,Handling and Processing Strings in R" (\url{https://gotellilab.github.io/Bio381/Scripts/Feb07/HandlingAndProcessingStringsInR.pdf})
  \item um tutorial do datacamp (\url{https://www.datacamp.com/pt/tutorial/regex-r-regular-expressions-guide}) mais focado em RegExp usando o pacote contribuído \texttt{stringr}
\end{itemize}


\end{document}
