Tutorial de funções em R

Se você está pensando em começar uma carreira em ciência de dados, quanto antes começar a programar, melhor. Não importa a linguagem que você escolheu para iniciar sua jornada, em algum momento você vai se deparar com funções. 

Funções são um conceito central em praticamente todas as linguagens modernas de programação, incluindo as queridinhas da ciência de dados, como Python, Julia e, claro, R.

Neste tutorial, vamos explorar o que são funções em R e como você pode usá-las. Ao cobrir o propósito, a sintaxe e os tipos de funções disponíveis em R, você terá tudo o que precisa para dominar esse conceito essencial de programação. E mais: você será apresentado à arte de criar funções. 

O que é uma função em R?

Em programação, funções são instruções organizadas para realizar uma tarefa específica. A ideia por trás das funções é criar blocos de código autossuficientes que podem ser chamados apenas quando necessário. 

Com funções, programadores não precisam mais escrever tudo do zero, evitando repetição e melhorando a robustez e a legibilidade do código. Por isso, como regra geral, é uma boa prática criar uma função sempre que você espera executar um mesmo conjunto de instruções mais de duas vezes no seu código.

As funções podem ter infinitas finalidades e assumir várias formas. De modo geral, a maior parte das funções recebe dados de entrada, processa e retorna um resultado. Os dados sobre os quais a função opera são informados pelos chamados argumentos, que também podem controlar ou alterar a forma como a função executa as tarefas.

Dependendo da origem, podemos distinguir três tipos principais de funções em R:

• Funções nativas (built-in)
• Funções disponíveis em pacotes de R
• Funções definidas pelo usuário (UDF)

Nas seções a seguir, vamos explicar as particularidades dos diferentes tipos de funções disponíveis em R. 

Funções nativas em R

R é uma linguagem poderosa que já vem com um amplo catálogo de funções nativas, prontas para uso a qualquer momento. Por ser orientada à matemática, R oferece várias funções para operações numéricas. Abaixo estão algumas das mais úteis:

• print(). Exibe um objeto R no console
• min(), max(). Calculam o mínimo e o máximo de um vetor numérico
• sum(). Calcula a soma de um vetor numérico
• mean(). Calcula a média de um vetor numérico
• range(). Calcula os valores mínimo e máximo de um vetor numérico
• str(). Exibe a estrutura de um objeto R
• ncol(). Retorna o número de colunas de uma matriz ou data frame
• length(). Retorna a quantidade de itens em um objeto R, como vetor, lista ou matriz.

No código abaixo, você vê como é simples usar essas funções para calcular estatísticas de um vetor:

>>> v <- c(1, 3, 0.2, 1.5, 1.7)
>>> print(v)
[1] 1.0 3.0 0.2 1.5 1.7
>>> sum(v)
[1] 7.4
>>> mean(v)
[1] 1.48
>>> length(v)
[1] 5

Você pode aprender sobre funções em R e muito mais na nossa abrangente trilha de aprendizado de R, que vai ajudar você a programar como um profissional. 

Funções em pacotes de R

Mesmo numerosas e diversas, as funções nativas não dão conta de tudo o que você pode fazer com R, desde criar visualizações incríveis até treinar modelos poderosos de machine learning. 

A grande maioria das funções para essas tarefas está disponível em pacotes (libraries) externos. Pacotes são coleções de funções, dados e código compilado em um formato bem definido, criadas para adicionar funcionalidades específicas. A maior parte pode ser usada gratuitamente e está disponível em repositórios populares, como o CRAN, que hoje reúne quase 20.000 pacotes contribuídos. 

Para usar as funções de um pacote, primeiro você precisa instalá-lo. Por exemplo, se quiser instalar o stringr, um pacote popular para trabalhar com expressões regulares, use o comando:

install.packages('stringr')

Depois de instalar, para carregar o pacote no seu ambiente R, use:

library(stringr)

Pronto: você já pode usar todas as funções disponíveis no pacote stringr. Por exemplo, vamos testar a função str_detect(), que retorna um vetor lógico com TRUE para cada elemento da string que corresponde ao padrão e FALSE caso contrário.

str_detect('DataCamp', "Data")
[1] TRUE

Se quiser saber mais sobre pacotes de R e como usá-los, confira este tutorial de pacotes em R da DataCamp.

Funções definidas pelo usuário

A melhor forma de entender como as funções em R funcionam é criar as suas próprias. As chamadas User-Defined Functions (UDF) são projetadas por programadores para executar uma tarefa específica. 

Funções em R geralmente adotam a seguinte sintaxe:

function_name <- function(argument_1, argument_2) { 
  function body
  return (output)
}

Podemos distinguir quatro elementos principais:

• Nome da função. Para criar uma UDF, primeiro atribua um nome e salve-a como um novo objeto. Depois, basta chamar esse nome sempre que quiser usar a função. 
• Argumentos. Os argumentos (também chamados de parâmetros) são informados entre parênteses. Eles são essenciais para a função saber quais dados receber como entrada e/ou como ajustar seu comportamento. 
• Corpo da função. Entre chaves fica o corpo da função, ou seja, as instruções para resolver a tarefa com base nas informações fornecidas pelos argumentos. 
• Comando de retorno (return). Use o return se quiser que o resultado das operações do corpo da função seja salvo em variáveis. 

Por exemplo, se você quiser criar uma função que calcula a média de dois números:

mean_two_numbers <- function(num_1, num_2) {
  mean <- (num_1 + num_2) / 2
  return (mean)
}

Agora, para calcular a média de 10 e 20, basta chamar a função assim:

>>> mean_two_numbers(10,20)
[1] 15

Tipos de argumentos em funções R

Argumentos são vitais em qualquer função. Embora seja teoricamente possível escrever uma função sem parâmetros (veja o exemplo abaixo), a maioria delas tem argumentos. Faz sentido: são os argumentos que dizem à função quais dados usar como entrada. Além disso, se quisermos oferecer diferentes maneiras de executar uma tarefa, é por meio dos argumentos.

hello <- function() {
  print('hello, my friend')
}

>>> hello()
[1] "hello, my friend"

Não há limite para a quantidade de argumentos em funções R; você pode adicioná-los entre parênteses, separados por vírgulas. Em geral, funções com mais argumentos tendem a ser mais complexas.

Depois de criar uma função com parâmetros, sempre que for usá-la você precisará fornecer valores para esses parâmetros; caso contrário, o R vai lançar um erro. Por exemplo, se você não fornecer os dois números para calcular a média, nossa função não vai funcionar.

No entanto, você pode evitar esse erro usando argumentos padrão ao definir a função. Argumentos padrão fornecem um valor que será usado caso você chame a função sem informar aquele argumento. Voltando à nossa função de média de dois números, agora vamos defini-la com um valor padrão para o segundo número.

mean_two_numbers <- function(num_1, num_2 = 30) {
  mean <- (num_1 + num_2) / 2
  return (mean)
}

Se agora chamarmos a função sem informar o valor do parâmetro num_2, o R usará automaticamente o valor padrão (no caso, 30):

>>> mean_two_numbers(num_1 = 10)
[1] 20

Entendendo valores de retorno em funções R

Funções normalmente recebem dados de entrada e fornecem um resultado de saída. Em algumas linguagens, para salvar o resultado de uma função em uma variável, é preciso incluir explicitamente o comando return ao final do corpo da função. Caso contrário, o valor é apenas exibido e existe somente dentro do escopo da variável.

Esse não é o caso em R, que sempre retorna um valor que pode ser armazenado em uma variável. Porém, por questão de legibilidade, é uma boa prática incluir o return ao definir a função.

mean_two_numbers <- function(num_1, num_2) {
  # Função com return 
  mean <- (num_1 + num_2) / 2
  return (mean)
}
mean_two_numbers_2 <- function(num_1, num_2) {
  # Função sem return
  mean <- (num_1 + num_2) / 2
  mean
}

> mean_two_numbers(10,50)
[1] 30
 > mean_two_numbers_2(10,50)
[1] 30

Por fim, se você quiser que sua função retorne múltiplos valores, armazene os resultados em uma lista e inclua-a no return:

mean_sum <- function(num_1, num_2) {
  mean <- (num_1 + num_2) / 2
  sum <- num_1 + num_2
  return (list(mean, sum))
}

>>> mean_sum (10, 20)
[[1]]
[1] 15
[[2]]
[1] 30

Chamando funções em R

Nas seções anteriores, já vimos vários exemplos de como chamar uma função. Mas vale esclarecer como o R funciona nos bastidores quando passamos os argumentos. 

O R aceita duas formas de passar argumentos: por posição e por nome. Se seguirmos a primeira estratégia, precisamos informar os valores na mesma ordem dos argumentos definidos na função. 

Se passarmos por nome, precisamos especificar explicitamente os nomes dos argumentos e seus respectivos valores. Como há uma correspondência direta entre nomes e valores, a ordem não importa.

Também é possível misturar as duas estratégias. Nesse caso, os argumentos nomeados são extraídos e casados primeiro, enquanto os demais são associados por posição.

hello <- function(name, surname) {
  print(paste('Hello', name, surname))
}

# Chamando argumentos por posição
> hello('Greta','Thunberg')
[1] "Hello, Greta Thunberg"
# Chamando argumentos por nome
> hello(surname='Thunberg', name='Greta')
[1] "Hello, Greta Thunberg"
# Chamando por posição e por nome
> hello(surname='Thunberg', 'Greta')
[1] "Hello, Greta Thunberg"

Documentando funções em R

Uma boa prática ao criar funções é documentar como usá-las, especialmente quando são complexas. Uma forma informal é adicionar comentários no corpo da função. Você também pode visualizar a documentação exibindo a função sem parâmetros:

hello <- function(name, surname) {
  # Diga olá a uma pessoa informando nome e sobrenome
  print(paste('Hello', name, surname))
}

>>> hello
function(name, surname) {
  # Diga olá a uma pessoa informando nome e sobrenome
  print(paste('Hello,', name, surname))

Por outro lado, se sua função fizer parte de um pacote maior e você quiser documentá-la formalmente, escreva a documentação em um arquivo .Rd separado. Você vê o resultado dessa documentação ao abrir a ajuda de uma função, por exemplo, ?mean. 

Conclusão

Você chegou ao fim do tutorial. Parabéns! Como em muitas outras linguagens, funções são elementos vitais em R. Sejam nativas, parte de pacotes externos ou criadas por você, dominar funções é um marco importante na sua jornada de programação. Se quiser continuar desenvolvendo suas habilidades com funções em R, confira os recursos a seguir!

• Introduction to Writing Functions in R Course
• Intermediate R Course
• Tutorial da família de funções "apply" em R
• Trilha de programação em R