Ganhe liberdade aprendendo a ler funções

Guia prático para a documentação em R

É fundamental ter liberdade para aprender. Quando estava começando a mexer no R, minhas habilidades eram bastantes limitadas. O que eu lembrava, eu fazia. Sempre que eu via algo diferente e que eu não entendia, buscava como fazer aquilo a partir de pesquisas de vídeos e de artigos na internet.

Isso deu certo por um período, mas era uma tarefa que consumia tempo.

Por vezes o vídeo demorava demais para explicar justamente a parte que eu queria, e em algumas vezes essa parte nem era citada. Os exemplos em artigos da internet não iam tão a fundo quanto eu queria. Acabava ficando à deriva da boa vontade dos outros e também do acaso. Talvez o conteúdo existisse, mas eu que não sabia encontrar.

Tudo mudou pra mim quando fiz um curso do DataCamp no qual o instrutor me ensinou algo que, na época, pensei ser simples. Ele me ensinou a ler documentação.

Photo by Patrick Tomasso on Unsplash

Sobre esse artigo

Esse artigo é para você que está começando a mexer no R e não sabe como ou onde procurar ajuda. Vou falar um pouco do que aprendi durante esse tempo e como ando procurando ajuda para responder as perguntas que surgem para mim.

Vamos utilizar um banco de dados que contém escores de depressão, ansiedade e estresse. O banco dass tem perto de 40000 casos e essas são as variáveis que vamos utilizar:

• depressao: contém escores de depressão.
• ansiedade: contém escores de ansiedade.

O objetivo não é fazer nenhuma transformação, apenas simular um processo de busca de informações e tomada de decisão. O que você vai tentar resolver é o seguinte:

Achar uma função para saber o valor da correlação entre depressão e ansiedade.

Caso você queira, faça comigo o exercício de utilizar o banco de dados DASS para responder esse exercício. Já usamos esse banco antes aqui e aqui. Se você seguir esse tutorial com R, conseguirá fazer o exercício proposto aqui no final.

Considerações iniciais

Antes de começar, vamos entender dois pontos importantes sobre a busca de informações sobre uma função.

Preciso saber inglês?

Escutando o podcast do DataHackers sobre Carreira em Data Science, escutei várias e várias vezes que saber inglês era muito importante. Isso porque a maioria do material de ajuda e documentação sobre os pacotes do R e bibliotecas do Python estão em inglês.

É bacana falar disso porque o objetivo do PsicoData — e também do DataHackers — é divulgar conteúdo em Ciências de Dados que seja em português.

Dito isso, tudo que vou mostrar aqui está em inglês e vai ser logo traduzido para o português. Aqui vai uma dica que também uso quando as coisas ficam um pouco mais complicadas: use e abuse do Google Translate.

Faça boas pesquisas

Às vezes, mesmo com o tradutor do Google, não sabemos o que um termo significa. Nesse caso, é importante pesquisar sobre ele nas línguas que você conhece. Se você possui uma literatura que considera fundamental para o que você entende, procure nessa literatura. Se não encontrou, busque no YouTube pelo significado daquilo que não sabe ou busque artigos em português no Medium com o termo.

Se você está passando por problemas específicos de código, aprenda a fazer boas perguntas com StackOverflow em português. A comunidade do StackOverflow é composta por pessoas que são desenvolvedoras e programadoras. A comunidade é bastante ativa e reage bem a boas perguntas.

Se você está começando, algo ótimo a se fazer é entrar no campo de pesquisa do StackOverflow e digitar ali a sua pergunta.

Além de uma pequena amostra de código e de um exemplo de seu banco de dados, o formato de boas perguntas para o StackOverflow incluem:

• A situação em que você está.
• O seu objetivo principal.
• O que você tentou.
• O que parece ter dado certo.
• Qual você gostaria que fosse o resultado final.

Outra dica é fazer boas pesquisas no Google. Boas pesquisas devem ser específicas o suficiente para retornarem resultados interessantes e abrangentes o suficiente para que esses resultados não sejam limitados demais.

Às vezes, digitar “stackoverflow” no final da pergunta ajuda a achar artigos interessantes do site.

Encontrando uma função do R

Para encontrar qualquer função no R, você tem três possibilidades:

• O site https://www.rdocumentation.org/
• Um pdf direto do CRAN (Comprehensive R Archive Network)
• Usar a função ??function no R.
  Exemplo: para saber sobre a função mean() , basta escrever ??mean() e rodar esse código.

A função problema

Vamos lembrar que o problema inicial era encontrar e entender uma função que fizesse um teste de correlação entre as três variáveis do nosso estudo.

Para fazer uma análise de correlação, você lembra que existe uma função chamada cor.test(). Essa função é do pacote stats do R e pode ser encontrada aqui.

Sempre que você está buscando uma função, um bom lugar para olhar é o site https://www.rdocumentation.org/

Abrindo o link acima do cor.test, você vê o seguinte:

Quanta informação! O que fazer com elas? Como interpretar e retirar dessa imagem uma informação útil? Vamos por partes.

Entendendo as partes

A primeira coisa que você deve entender é o que está sendo mostrado.

1. O nome da função e para quê ela serve. No canto direito, temos a informação de a qual pacote essa função pertence. Nesse caso, do pacote stats.
   O que fazer com essa informação? O nome do pacote nos ajuda a entender toda a documentação sobre ele. Documentação é o arquivo explicando o quê cada função do pacote faz. Para achar a documentação do pacote, em .pdf, basta procurar no Google: pacote cran pdf.
   Pesquisando sobre isso com o pacote stats, encontramos aqui o pdf. Esse documento possui todas as informações que estão no RDocumentation (sinto que a leitura é mais fácil direto na documentação).
2. Como se usa a função: os principais argumentos usados junto às suas principais opções.
   O que fazer com essa informação? Essa é a parte mais prática, que explica de maneira objetiva quais os valores necessários para colocar na função. Se você já sabe o que cada argumento faz, é só usar a fórmula que está dentro da função e adaptar para o seu banco de dados. Com o tempo, fica fácil de entender a fórmula e adaptar.
3. Argumentos: tudo o que permite que nós personalizemos as funções.
   O que fazer com essa informação? Aqui a gente entende os detalhes por trás de cada especificação da função. Fica fácil de entender o que cada argumento faz. Além disso, recebemos informações de quais valores são aceitos e quais não são. Por exemplo, em cor.test, o primeiro argumento (x, y) estão descritos como “vetores numéricos” — que, em R, podem ser tanto colunas de um dataset quanto valores numéricos concatenados, por exemplo: c(2, 5, 1) Além disso, recebemos a informação importantíssima de que x, y precisam ter o mesmo comprimento. Ou seja, devem ter um número igual de casos.

Especialmente as informações 2 e 3 mudaram muito o jeito que eu entendia as funções. Já recebi erros pois, ao invés de digitar value = list(x, y, z) , digitava value = c(x, y, z) . Com esse meu erro, a função não sabia o que fazer. E eu, sem entender, não sabia como ajeitar esse erro.

A ordem é importante

Algumas informações são importantes para entendermos logo de cara, sem pensar muito.

Em primeiro lugar, todos os argumentos que estão na função podem ser especificados com o símbolo = . Ou seja, se estou escrevendo uma função para correlacionar depressao e ansiedade, posso especificar cor.test(x = dass$depressao, y = dass$ansiedade)

A segunda especificação importante é a de que não preciso, necessariamente, especificar nenhum dos argumentos. As funções atribuem os valores recebidos na ordem em que colocamos eles. Lá na especificação de cor.test, vimos que primeiro vem o x e depois o y. Assim, podemos apenas colocar os valores, sem a necessidade de definir eles. Então, ao invés de escrever cor.test(x = dass$depressao, y = dass$ansiedade) , podemos simplificar e escrever, de cara, cor.test(dass$depressao, dass$ansiedade)

Apenas isso é o suficiente para usarmos cor.test! O resto é puramente opcional, podemos mexer ou não.

É opcional mudar ou não?

Como assim o resto é opcional? Vamos colocar aqui, novamente, a parte 2 do cor.test (“Usage”).

# S3 method for default 
cor.test(x, y,
    alternative = c("two.sided", "less", "greater"),
    method = c("pearson", "kendall", "spearman"),
    exact = NULL,
    conf.level = 0.95,
    continuity = FALSE, …)

Perceba que todos os outros argumentos, tirando x, y, possuem valores já definidos. Esse são valores default. Se não os mudarmos, a função será rodada com eles assim.

No caso de alternative e method, que possuem mais de um valor, o primeiro valor é o que conta.

Isso é importante porque o que o R entende quando escrevemos apenas cor.test(dass$depressao, dass$ansiedade) é o seguinte:

# O que o R entende da função acima
cor.test(dass$depressao, dass$ansiedade,
    alternative = "two.sided",
    method = "pearson",
    conf.level = 0.95,
    continuity = FALSE)

Isso porque nós não mexemos em nenhum outro valor, então ele usa os em default!

Para saber se um valor é opcional, se precisa ou não mexer nele, basta ler se ele já possui algum valor pré-definido ou se na parte 3 (“Arguments”), ele está descrito como optional.

Para entender o que cada um dos argumentos faz, basta ler “Arguments”, onde todos os valores possíveis para os argumentos estão especificados.

Neste exemplo com cor.test(), três mudanças podem ser feitas:

• alternative = 'greater'
Isso quer dizer que esperamos uma associação positiva entre depressão e ansiedade.
• method = 'spearman'
  Escolhemos o teste de Spearman ao invés do teste de Pearson, por entender que as variáveis não seguem uma distribuição normal.
• conf.level = .99
  Mudamos o nosso alfa porque temos bastante confiança de que nosso teste de hipóteses será de que existe uma correlação significativa entre depressão e ansiedade. Qualquer valor entre 0 e 1 poderia ser aceito aqui.

Assim, nossa função passa a ser:

# Nova função
cor.test(dass$depressao, dass$ansiedade,
    alternative = "greater",
    method = "spearman",
    conf.level = 0.99,
    continuity = FALSE)

O que a função retorna?

A segunda parte no RDocumentation de cor.test()fala sobre Details e Value.

• Details: especificação do que a função faz e como.
  O que fazer com essa informação? Geralmente, as informações contidas em Details ajudam a tomar melhores decisões sobre os argumentos a serem usados na função.
• Value: informa quais os valores que essa função retorna.
  O que fazer com essa informação? Essa informação pode ser útil caso queiramos armazenar o valor de cor.test() em um objeto. Por exemplo, cor_dass <- cor.test(dass$depressao, dass$ansiedade) . Logo abaixo de Value, temos a informação de que, caso criemos um novo objeto, esse objeto será da classe “htest”. Ainda, que “htest” terá valores dentro dele como statistic, parameter, p.value, estimate, etc.

Um pouco mais de liberdade?

Quando fiz o curso do DataCamp, o que acabei aprendendo era sobre a ordem de cada argumento e de valores em default.

Nesse post, tentei explicar um pouco mais sobre outras coisas que também fui reparando no meio do caminho.

Resolvi compartilhar sobre isso porque, olhando para trás, esse conhecimento foi importantíssimo para eu ter mais controle sobre as escolhas que fazia e na maneira em que fui aprendendo a ler documentação de pacotes e funções.

Às vezes ler documentação pode parecer uma tarefa desafiadora. Entretanto, é uma atividade que ajuda muito na hora de programar.

Espero que tenha ajudado você de alguma forma a ter mais liberdade quando se trata disso.

Contato

Espero que tenha gostado! Qualquer dúvida, observação ou comentário são muito bem-vindos! Fique à vontade para se manifestar e vamos aprender juntos 😄

Para falar comigo, é só entrar em qualquer um desses links.

☕️ Gostou do post e vai usar algo? Se quiser, você pode me pagar um café.