Módulo 7 | Ferramentas intermédias de DataScience

Autor

A. Peralta-Santos e J Dionisio

Data de Publicação

today

10.1 Introdução

O objetivo deste capítulo não será o de ensinar todas as ferramentas disponíveis em R, mas o de guiar os próximos passos quando quiserem avançar para além dos conceitos dos módulos anteriores e para que possam retirar inspiração dos produtos mais recentes com exemplos disponíveis.

10.2 Ambientes Reprodutíveis

Como já foi explorado em módulos anteriores, R é uma ferramenta para análise de dados eficientes. A simplicidade de configuração como as ferramentas criadas pela comunidade (Ex: Dplyr, gt, tidymodels) tornam a linguagem como um bom ponto de entrada para muitas áreas como a saúde.

Ainda assim, uma das dificuldades quando estamos a trabalhar em equipa é a necessidade de partilhar trabalho ou a necessidade de validar o que é feito e se o que fazemos pode ser replicados.

A reprodutibilidade é um dos pilares da partilha de informação. Esta deve ser parte de todo o ciclo de data science. Para isso é necessário haver reprodutibilidade computacional.

Isto pode incluir situações como:

  • Refazer uma análise
    • Por um colega com outro sistema
    • Pelo individuo noutro local ou tempo
    • Por outros para validação dos nossos resultados
  • Reutilização de código
  • Colocar código em produção

Nestas situações, 3 princípios devem guiar a passagem de um projeto para produção (Wickham 2024) :

  1. Não apenas uma vez
    • Projetos de sucesso em data-science tendem a ser repetidos na sua execução, às vezes por meses ou anos
    • Desafios:
      • Os dados vão mudar, a schema pode mudar
      • Dependências podem mudar
    • Embora não seja no âmbito deste módulo, alguns pacotes úteis para explorar estas alterações serão o PointBlank e o Assertthat.
  2. Não apenas no meu computador
    • Muitos projetos passam de uma fase de experimentação para produção, tendencialmente de um sistema Windows e Mac para linux o que implica alterações na forma como estruturamos o código.
    • Desafios:
      • Dependências podem mudar
  3. Não sou apenas eu a correr
    • Desafios:
      • Alterações de arquitetura
    • Soluções para este problema podem passar pelo uso de containers (unidades de software que isolam uma aplicação e as suas depedências num ambiente portátil) através de plataformas como o docker (plataforma que facilita a criação, distribuição e execução destes containers ).

Com base destes requesitos, vamos focar na estabilidade no ambiente computacional que utilizamos relativamente a dependências que tendem a ser um dos primeiros problemas que encontramos em código com alguns meses.

A ferramenta que iremos abordar para gestão de ambientes será o pacote RENV.

10.2.1 Renv

Como já foi discutido em módulos anteriores, no R, uma biblioteca (library) é um pasta que contém pacotes instalados. Embora seja comum usar o comando library() para carregar um pacote, o termo biblioteca se refere, na verdade, ao local onde esses pacotes estão armazenados. Por padrão, os pacotes são instalados em uma biblioteca do sistema, que é compartilhada entre todos os projetos.

É possível ver as bibliotecas atuais com o comando .libPaths() e verificar os pacotes disponíveis em cada uma delas com lapply(.libPaths(), list.files).

[1] "C:/Users/jdrdionisio/AppData/Local/R/win-library/4.2"
[2] "C:/Program Files/R/R-4.2.3/library"

Um repositório ou repo é a fonte de onde os pacotes são obtidos. O comando install.packages() o que faz é transferir um pacote de um repositório (geralmente da Internet) e o instala na biblioteca local (caminho em cima)

Habitualmente, o repositório mais importante é o CRAN, mas há outros, como o Posit Public Package Manager, sendo que isto pode ser alterado quando corremos o comando install.packages().

# Código de exemplo
install.packages("ggplot2", repos = "https://ropensci.r-universe.dev/")

É nesteponto que o pacote renv facilita a criação de ambientes reprodutíveis em R, isolando as dependências de cada projeto, garantindo que ele funcione de forma consistente em diferentes máquinas, criando para cada projeto uma própria biblioteca, garantindo um isolamento de pacotes do resto dos projetos.

Comandos mais relevantes de um Sistema RENV

Vantagens:

  • Reprodutibilidade: Garante que o projeto funcione em diferentes computadores com as mesmas versões de pacotes.
  • Isolamento: Cada projeto possui sua própria biblioteca de pacotes, evitando conflitos com outras bibliotecas do sistema.
  • Controle de versões das dependências: Não há atualizações automáticas, o que protege o projeto de quebras causadas por versões mais recentes de pacotes.

Desvantagens:

  • Espaço em disco: O isolamento dos pacotes pode ocupar mais espaço, especialmente com muitos projetos isolados.

Como criar?

  • Ative o renv com o comando renv::init(), que cria uma biblioteca de pacotes exclusiva para o projeto.
  • Durante a criação de um novo projeto, você pode configurar a reprodutibilidade desde o início, utilizando o renv para gerenciar os pacotes.

Possibilidade de criar um projeto com reprodutibilidade como prioridade

Como documentar?

Existe a função snapshot() para capturar o estado atual dos pacotes e gravar no arquivo “renv.lock”, que armazena as versões exatas dos pacotes e suas fontes. Esse arquivo é essencial para garantir que o projeto possa ser reproduzido em outras máquinas.

Como colaborar?

O comando renv::status() ajuda a verificar o estado do ambiente do projeto, identificando pacotes que precisam ser instalados ou atualizados.

Para partilhar o projeto, inclua o arquivo renv.lock e os arquivos relacionados no controlo de versão (como Git que irá ser abordado posteriormente). Isso permite que outros colaboradores possam facilmente reproduzir o ambiente do projeto, utilizando o comando renv::restore().

Este comando dá logo orientação como proceder.

Worflow:

  1. init - Inicializar o projeto com renv.
  2. install - Instalar pacotes necessários.
  3. snapshot - Registar o ambiente no lockfile
  4. restore - Reproduzir o ambiente que está no lock file

SLUSHY

O pacote slushy foi criada pela empresa GSK.

O principal objetivo do Slushy é oferecer uma solução que equilibre a necessidade de estabilidade em projetos de longo prazo com a flexibilidade para incorporar atualizações e melhorias contínuas. Isso é particularmente útil para equipes de desenvolvimento que desejam manter seus projetos atualizados sem enfrentar interrupções significativas ou riscos de incompatibilidade.

O objetivo é o de, ao invés de termos projetos congelados (como o RENV), mas o de termos programadores podemos querer avançar de forma lenta com o tempo sem perder estabilidade, introduzindo novas versões e verificando problemas.

Vantagens do Slushy

  • Snapshots do CRAN: Slushy permite o uso de snapshots do CRAN, facilitando a aquisição de pacotes específicos e a atualização controlada do projeto.
  • Flexibilidade e Estabilidade: Permite a introdução gradual de novas versões de pacotes, garantindo que a estabilidade do projeto seja mantida enquanto novas funcionalidades são integradas.
  • Gerenciamento Simplificado: Com comandos intuitivos, o Slushy simplifica o processo de adição, remoção e atualização de pacotes, tornando o gestão de dependências mais eficiente.

Workflow:

  1. new_config()
    • Cria uma nova configuração para o projeto, estabelecendo o ambiente inicial e preparando-o para o gestão de dependências.
  2. slushy_init()
    • Inicializa o Slushy no projeto atual, configurando os parâmetros necessários para o gestão de pacotes e snapshots.
  3. slushy_add(“packagename”)
    • Adiciona um novo pacote ao projeto.
  4. slushy_drop(“packagename”)
    • Remove um pacote do projeto.
  5. slushy_update(date = “2023-01-01”)
    • Atualiza os pacotes do projeto com base em um snapshot específico do CRAN na data fornecida. Isto permite controlar quando e como as atualizações são aplicadas, minimizando risco de incompatibilidades.

A vantagem do Slushy está em poder usar snapshot do CRAN para adquirir pacotes e atualizar o projeto.

10.3 Quarto Intermédio

10.3.1 Inclusões (Includes)

Em Quarto, existe uma funcionalidade que permite a reutilização eficiente de conteúdo entre vários documentos. Esta característica é especialmente útil em projetos que exigem que secções de texto, código ou resultados de análises sejam partilhados entre diferentes outputs, garantindo consistência e reduzindo o tempo despendido em atualizações.

Reutilizar conteúdo desta forma é possível utilizando a forma “{{< include >}}”.

Por exemplo, podemos querer partilhar elementos como metodologias, descrições de dados ou excertos de código entre relatórios, ou ajustar cada documento ao seu público-alvo ou finalidade. Também é importante pois qualquer alteração feita nesses blocos será automaticamente refletida em todos os documentos que os incluam, tornando a gestão do conteúdo mais eficiente e prática.

Ex: Um boletim externo sem anexos para divulgação e um boletim interno com internos com anexos de validação.

Exemplo:

# ---
# title: "Relatórios Conjuntos"
# ---
# 
# {{< include Relatório_hospitalA.qmd >}}
# {{< include Relatório_hospitalB.qmd >}}
# 
# Usar os dados e outputs do documentos atuais...

Benefícios:

  1. Evitar a repetição de código
  2. Modularidade (múltiplos documento com parte modulares de mais fácil correção)
  3. Conteúdo Dinâmico

Secção Incluida Externa

Este conteúdo não foi retirado do ficheiro Quarto (qmd) correspondente ao módulo “Module 7b | Intermediate Data Science Tools”.

Aviso

O objetivo desta secção é apenas o de fornecer ao leitor um exemplo de uma inclusão externa a um documento Quarto.

Parâmetros

Os parâmetros em Quarto é uma funcionalidade que aumenta a personalização dinâmica do conteúdo de um documento.

Este tipo de funcionalidade é útil em várias situações:

  1. Análises de anos diferentes após correções de dados ou atualização da análises
  2. Criação de documento personalizados baseados em critérios que são definidos:
    • ULS
    • Região
    • Cidade
  3. Relatórios para pessoas diferentes.
---
title: "Relatório de Saúde Regional"
params:
  ano: 2024
  escola: "ENSP"
  pessoa: "Aluno"
  edicao: "4ª"
  curso: "Data Science with R in Healthcare"
---

Nós estamos na 4ª do curso Data Science with R in Healthcare na ENSP e este documento pertence ao Aluno.

Um exemplo de como podemos mudar o output será correndo o seguinte código na consola.

Nós estamos na 4ª do curso Data Science with R in Healthcare na ENSP e este documento pertence ao Aluno.

Um exemplo de como podemos mudar o output será correndo o seguinte código na consola.

10.3.2 HTML e CSS

HTML (Hypertext Markup Language): É a linguagem básica para estruturação de conteúdo na web. É usada para definir o layout de uma página, criar links, inserir imagens e organizar o conteúdo de forma hierárquica.

CSS (Cascading Style Sheets): É usado para definir o estilo de conteúdo definido pelo HTML. Através do CSS, podemos modificar cores, fontes, espaçamentos, alinhamentos e tornar documento mais atrativos e funcionais.

O Quarto permite que se use HTML e CSS para personalizar a aparência de seus documentos e dashboards. Isso é útil quando você deseja um controle fino sobre o layout e o design.

O processo de aprendizagem de HTML e CSS no âmbito de datascience é algo que surge por necessidade e é algo fora do âmbito deste curso.

Podemos referenciar uma folha de estilos CSS, ao colocar no yaml do quarto a fonte dos mesmos.

format:
  html: 
    css: styles.css

Isto permite utilizar classes no texto para uso da formatação preferida.

<div class="custom-box">
  Este é um texto destacado dentro de uma caixa estilizada usando a classe `.custom-box` do CSS.
</div>

10.3.3 Quarto Websites

Tal como já vimos no módulo 2, o Quarto é uma poderosa plataforma.

Para além da criação de relatórios dinâmicos e reprodutíveis facilita a criação de websites interativos e dinâmicos, permitindo a individuos e a equipas partilhar suas análises de maneira clara e organizada. Ele oferece suporte à navegação por meio de barras laterais ou de navegação global, bem como à pesquisa por texto completo.

Websites criados com Quarto podem ser facilmente publicados em plataformas como GitHub Pages, Netlify, ou servidores locais, facilitando a distribuição de conteúdos interativos.

O Livro disponizado foi elaborado utilizando o Github Pages.

Documentação Oficial

Funcionalidades Disponibilizadas:

  • Configuração de Navegação
    • Quarto permite configurar uma barra de navegação robusta para facilitar a movimentação entre diferentes páginas do seu site. Isso é feito no arquivo _quarto.yml , onde é possível definir links, submenus e ordenação de páginas;
    • Cada página é um documento quarto.
  #Exemplo de código para Quarto website

_quarto.yml

project:
  type: website

website:
  title: "Curso de Data Science"
  search: true
  back-to-top-navigation: true
  navbar: # navegação de topo
    left: 
      - href: index.qmd
        text: "Home"
      - href: Pagina1.qmd
        text: "Página1"
      - text: "Mais"
        menu: 
          - about.qmd
          text: "Sobre"
  sidebar:# Navegação em barra lateral
    style: "floating"
    search: true
    contents:
      - text: "Introduction"
        href: home.qmd
        # navigation items
      - section: "Paginas"
        href: basics-summary.qmd
        contents:
          - index.qmd
          - pagina1.qmd
          - pagina2.qmd
      - section: "sobre"
        contents:
          - about.qmd
  page-footer: "Setembro de 2024, André Peralta" 
  reader-mode: false #cria um botão para modo de leitura
format:
  html:
    theme: cosmo
    css: styles.css
    toc: true
  • Temas e Personalizações
    • Tal como as outras ferramentas Quarto, os Websites suportam temas predefinidos que podem ser aplicados a todo o site, mas também é possível personalizar o estilo visual com CSS. Isso dá flexibilidade para adaptar o site à identidade visual desejada.
  • Pesquisa e Links intra-documento
    • Suporte a pesquisa por texto completo e links interno, permitindo que os usuários naveguem facilmente pelo conteúdo.

10.3.4 Quarto Dashboards

Os Quarto Dashboards são uma nova poderosa ferramenta para criar relatórios interativos e dinâmicos utilizando a tecnologia Quarto. Este nova tipologia foi projetada para combinar a simplicidade da criação de documentos dinâmicos com a interatividade de dashboards, o Quarto facilita a publicação de análises de dados visuais e interativos na web ou em documentos offline.

Em resumo, mantêm as vantagens do Quarto, mas permite a publicação de um formato mais dinâmico.

Abaixo deixamos um exemplo de um dashboard.

Dashboards no Quarto são compostos por vários componentes para navegação e apresentação de dados. Elementos chave incluem:

  1. Navegação: Cada dashboard inclui uma barra de navegação no topo com título, opcionalmente um logo e autor. Exemplo de código para adicionar título e autor:
---
title: "Seu Título"
author: "Seu Nome"
---

  1. Páginas: Para dashboards com múltiplas páginas, use cabeçalhos de nível 1 acima dos cabeçalhos de nível 2 que definem linhas e colunas.

  2. Layout: Os componentes dentro de uma página são organizados em linhas e colunas alternadas, definidas por cabeçalhos em markdown com (#, ##, ###) e especificações computacionais relativas ao seu comportamento em HTML. Por exemplo, um layout simples com duas linhas, sendo a segunda dividida em duas colunas seria algo assim:

# Página 1
## Linha {height=70%}
Linha que ocupa 70% da página em altura
## Linha 2 {height=30%}

### Coluna A {width= 60%}
Dentro da Linha 2 queremos uma coluna com 60% do temanho da largura da pagina

### Coluna B {width= 40%}

A Coluna B contém o resto da largura da página

  1. Cards ou Cartões: São a unidade fundamental de exibição nos dashboards, criados automaticamente para células e conteúdo em markdown dentro de linhas e colunas. Cada pedaço de código separado e com output entre linhas ou colunas será colocado no Card.

  2. Orientação: Por predefinição, as páginas são organizadas primeiro por linha e depois por coluna. Isso pode ser alterado especificando a opção orientation: columns no documento.

Exemplo de Orientação em colunas

## Column {width=60%, orientation: columns}

### ROW A {height=50%}

### RoW B {height=50%}

## Column {width=40%, orientation: columns}
  1. Preenchimento vs. Fluxo (Fill vs. Flow): Cada elemento determina seu tamanho preenchendo o espaço disponível ou seguindo seu tamanho natural. Isso é controlado pelas classes .fill e .flow.
## Row {.fill}

## Row {.flow}
  1. Scrolling: Por predefinição, o conteúdo do dashboard preenche todo o espaço disponível na página, mas pode ser configurado para usar a altura natural do conteúdo deixar o utilizador navegar para baixo.
---
title: "Urgências/CSP Dashboard"
format: 
  dashboard:
    scrolling: true 
logo: images/ensp.png
fig-width: 10
---
  1. Conjuntos de Tabsets: É possível fazer separadores tabsets para incluir múltiplas visões de dados ou conteúdo de importância secundária. Eles são criados adicionando a classe .tabset a uma linha ou coluna.
Primeiro Exemplo:
  
## Row {height=50%}

## Row {.tabset}
code chunks
#| title: "Gráfico 1"

code chunks 
#| title: "Gráfico 2"

Segundo Exemplo:
  
## Row {height=30%}

### Column {.tabset}
code chunks
#| title: "Gráfico 1"

code chunks 
#| title: "Gráfico 2"


### Column

Exemplo de resultados de tabsets em Linhas

Exemplo de resultado de tabsets em Colunas

  1. Personalização: Tal como tudo em Quarto HTML é tudo personalizável recorrendo a temas que são CSS e SASS. Apesar de úteis para embelezar um produto, a sua utilização é mais avançada que o ãmbito deste curso.

Terão ter um exemplo de alterações deste género no ficheiro custom.scss na pasta themes se quiserem explorar.

Para vos apoiar na vossa jornada nos Quarto Dashboard, diponibilizamos no repositório do curso um exemplo entitulado Dashboard.qmd para poderem ver como é construído e explorarem as alterações que podem fazer.

10.4 SHINY

O pacote Shiny é uma ferramenta interessante para níveis intermédios e avançados da utilização de R. Este pacote fornece uma estrutura para transformar análises de dados em aplicações web interativas, onde os utizadores podem interagir com as visualizações e realizar ajustes em tempo real, sem necessidade de recarregar a página.

10.4.1 Estrutura simplificada de uma Aplicação Shiny

Uma aplicação Shiny típicamente é composta por dois componentes principais:

  • Interface do Utilizador (UI): Define a aparência da aplicação e os componentes com os quais o utilizador pode interagir, como botões, sliders, gráficos ou caixas de verificação.
    • ui.R ou function ui
  • Lógica (Server): Contém as funções que processam os dados de entrada e geram as saídas (gráficos, tabelas, etc.). A cada interação do usuário, o servidor recalcula e atualiza os outputs de forma dinâmica.
    • server.R ou function server

Em baixo, colocamos um exemplo muito simples onde o utilizador pode ajustar o número de observações para gerar diferentes distribuições normais. O gráfico é atualizado automaticamente sempre que o valor do slider é alterado.

library(shiny)

# Definindo a interface do utilizador (UI)
ui <- fluidPage(
  titlePanel("Exemplo de Shiny"),
  sidebarLayout(
    sidebarPanel(
      sliderInput("obs", "Número de Observações:", min = 1, max = 100, value = 50)
    ),
    mainPanel(
      plotOutput("distPlot")
    )
  )
)

# Definindo a lógica do servidor
server <- function(input, output) {
  output$distPlot <- renderPlot({
    hist(rnorm(input$obs))
  })
}

# Executa a aplicação
shinyApp(ui = ui, server = server)

10.5 Controlo de versões

10.5.1 Uma breve introdução ao GIT e GITHUB

O quê?

O Git é um sistema de controle de versão distribuído, utilizado para controlar mudanças em arquivos de código durante o desenvolvimento de código.

GitHub é uma plataforma baseada na web que utiliza os sistema Git para o armazenamento e gestão de repositórios de código.

Git como sistema de controlo de versões e GitHub como plataforma colaborativas e de partilha de projetos

Porquê?

Vantagens de usar um sistema git nos nossos projetos:

  1. Controlo de versões - Permite que múltiplas versões estejam armazenadas. Se um erro for introduzido, é simples reverter para uma versão anterior.
  2. Versões locais - Permite que cada colaborador num projeto trabalhe numa cópia local dos ficheiros e possa consultar o histórico de alterações.
  3. Ramificações e Fusão - Permite a criação de ramificações (branches) para testar análise e relatórios isoladamente. Estas ramificações podem ser fundidas (merge) de volta ao ramo principal (master/main) após a conclusão do seu desenvolvimento.

O plataforma Github permite o armazenamento e gestão de repositórios/projetos de código. Para além disso permite:

  1. Armazenamento remoto de código (limites de armazenamento é de 1 Gb com tráfego de dados de 1 Gb) com backup
  2. Interface Gráfica simples e intuitiva
  3. Pull requests e revisão de código antes de junção
  4. Integração com outras ferramentas

Como implementar?

  1. Criar conta no GitHub
  2. Podemos fazer a gestão de projetos de 2 formas:
  • Github Desktop
  • Dentro do Rstudio

Por ser mais simples iremos utilizar o Github Deskop que pode ser instalar no seguinte link.

Exemplo da interface

Worflow

Criar/Clonar um repositório (Comandos init e add)

Repositórios
Comandos Importantes GIT:
  1. Commit - Grava as alterações no repositório local
  2. Pull - Atualiza o repositório local com as alterações do repositório remoto.
  3. Diff - Mostra o estado atual do repositório, incluindo as alterações do repositório que ainda não foram adicionados ou comprometidos ao repositório.
  4. Branch - Criar ramificações para o repositório
  5. Merge - Fundir ramificações, normalmente para a ramificação principal
  6. Log - Mostra o histórico de commits. No Github é também utilizada a palavra Activity.
  7. Push - Envia as alterações do repositório local para o repositório remoto.

10.6 Automated Reporting

10.6.1 Github Actions

GitHub Actions são uma funcionalidade da plataforma GitHub que permite a automação de workflows dentro dos repositório GitHub, sendo uma forma de correr código de forma automática num computador que a plataforma mantêm.

São especialmente úteis para processos de Integração Contínua (CI) e Entrega Contínua (CD).

As ações são acionadas por eventos específicos no GitHub, como push, pull requests, criação de tags, entre outros.

Componentes principais de um workflow de Github Actions:

  1. Ficheiro de Configuração: Um arquivo YAML no diretório .github/workflows do repositório
  2. Jobs - Consiste nos passos a serem executados
  3. Steps - Comandos a serem executados nos jobs
  4. Runs-on - Qual a plataforma a utilizar

Objetivos destes componentes:

  1. Quando correr código?
  2. Iniciar o computador virtual que irá correr a acção
  3. Instalar o R
  4. Instalr os pacotes necessários
  5. Correr o código

Estas acções são muito interessantes na construção de automatismos que podem ajudar ao rever código e em análises repetidas.

Deixamos 2 exemplos de tarefas que podem ser automatizadas:

10.6.2 Task Schedualing (Gestão de tarefas automáticas)

Deixamos o código do workflow que permite correr um script de forma automática com uma temporização regular.

Se o nosso cósigo tivesse de atualizar dados isso tem de ser incoorporado no YAML ou no ficheiro a fazer render.

# Definição de quando o workflow é acionado
on:
  schedule:
    - cron: '0 9 1 * *' # Executa todos os dias às 9 da manhã UTC no primeiro dia do mês

# Definição dos jobs
jobs:
  update_report: # Nome do job
    runs-on: ubuntu-latest # Especifica que o job roda no último Ubuntu disponível

    steps: # Passos a serem executados
      - name: Set up R # Configura o ambiente R
        uses: r-lib/actions/setup-r@v2 # Usa a ação de setup do R da r-lib
        with:
          # uses the RStudio Package Manager
          use-public-rspm: true

      - name: Install packages # Instala pacotes necessários
        uses: r-lib/actions/setup-r-dependencies@v2 # Usa a ação de setup de dependências do R da r-lib
        with:
          packages: | # Lista de pacotes a serem instalados
            any::quarto
            any::base
            any::backports
            
      - name: Check out repository # Faz checkout do repositório
        uses: actions/checkout@v3 # Usa a ação padrão de checkout do GitHub

      - name: Update Report # Atualiza o relatório
        run: Rscript -e 'quarto::quarto_render("Cronjob.qmd")' # Comando para renderizar o relatório usando Quarto

      - name: Commit results # Faz commit dos resultados
        run: | # Conjunto de comandos para commit
          git config --local user.email "actions@github.com" # Configura email para o commit
          git config --local user.name "GitHub Actions" # Configura nome para o commit
          git add Cronjob.html # Adiciona o arquivo HTML ao staging area
          git commit -m 'Data updated' || echo "No changes to commit" # Faz o commit ou exibe uma mensagem se não houver mudanças
          git push origin || echo "No changes to commit" # Faz push das mudanças ou exibe uma mensagem se não houver mudanças

10.6.3 Emails automáticos

Preparação de um ficheiro com as credenciais de um email.

Aviso

Não partilhar as credenciais em pastas públicas nem em repositórios públicos.

Para os efeitos as credenciais indicadas são ficticias mas podem ser subtituídas por reais.

# criar ficheiros de email - antes do workflow
create_smtp_creds_file( file= "templates/email_credenciais",
                        user= "peralta@outlook.com",
                        provider= "outlook")

# criar um ficheiro R com o código a correr.
#Fonte: email_automatico.R
email_a_enviar <- render_email("email_automatico.qmd") |> 
                  add_attachment(file="output\figures\map_eu_HE.png",
                                 filename= "mapa_analise")

smtp_send(email_a_enviar,
          from = "peralta@outlook.com",
          to = "ensp@outlook.com",
          subject= paste0("Análise de dia ", Sys.Date()),
          credentials=creds_file("templates/email_credenciais"))

# criar um ficheiro ymal com esta acção

name: Send email using Quarto and blastula
on: 
  schedule:
    - cron: '0 9 1 * *'
jobs:
  render:
    runs-on: windows-latest
    steps:
      - name: Check out repository
        uses: actions/checkout@v3
      - name: Set up R
        uses: r-lib/actions/setup-r@v2
      - name: Install quarto
        uses: quarto-dev/quarto-actions/setup@v2
      - name: Install dependencies
        run: |
          install.packages("blastula", type = "win.binary")
        shell: Rscript {0}
      - name: Update Report
        run: Rscript -e source("email_automatico.R")
      - name: Commit files
        run: |
          git config --local user.name github-actions
          git config --local user.email "actions@github.com"
          git add output/*
          git commit -am "commit on $(date)"
          git push origin main

10.7 GENERATIVE AI MODELS IN R Programming

Desde Novembro de 2022 que se têm falado de modelos de inteligência artificial generativa.

Este modelos, um subconjunto da inteligência artificial, são projetados para gerar novos dados que se assemelham a dados existentes.

Modelos de Linguagem de Grande Escala (LLMs) na Programação

LLMs como o ChatGPT ganharam atenção significativa pela sua capacidade de compreender e gerar texto semelhante ao humano.

Na programação e na gestão de dados, estes modelos podem ser aproveitados para escrever código, filtrar código ou explicar pedaços de código complexos. O seu entendimento de linguagem natural e linguagens de programação permite que elevar as capacidades dos utilizadoreses de maneira conversacional, com o potencial de aumentar significativamente a produtividade.

Vantagens:

  • Gerar código ou adaptar código de outras linguas para R
  • Apoiar na gestão de erros ou bugs
  • Documentação e Explicação: A leitura da documentação por vezes é dificil numa fase inicial e os modelos permitem baixar a complexidade na leitura e explicar pedaços de código com múltiplos níveis de complexidade.

Limitações:

  • Apesar de em códigos simples gerar poucos erros, existe a possibilidade do mesmo não seguir as boas práticas e ser optimizado para um melhor desempenho.
    • Ex: Quando a pedir código de Data cleaning e Wrangling o CHAT GPT por vezes escolhe R base que é mais dificil de compreender.
  • Comprensão do Contexto: Quanto tempos documentos mais longos com múltiplas peças (ex: aplicações Shiny, múltiplos documentos Quarto) o ChatGPT dificilmente conseguirá compreder os nossos requisitos no prompt
  • Depedência: O ChatGPT deve ser um ferramenta para impulsionar a nossa aprendizagem da lingua e não ser a única ferramenta que utilizamos
  • Diferentes resultados para as mesmas perguntas.
  • Limitações temporais
  • Questões Éticas e Partilha de dados sensíveis.

Existem múltplas LLM mas o mais conhecido é o CHAT-GPT.

Podemos pedir ao ChatGPT para nos elaborar uma função que calcule o BMI a partir de uma idade e altura.

A fase seguinte poderá ser a de integração de LLM nas nossas ferramentas de programação. Ex: RSTUDIO

De opções temos o Copilot da Microsoft, disponível no RSTUDIO mas é pago.

Localização da Configuração do Copilot

10.7.1 CHAT GPT no Rstudio

Pacote GPTSTUDIO

O processo ainda não está muito otimizado mas colocamos os passos para instalar o add-in GPTSTUDIO:

  1. Necessário criar conta com a OpenAI
  2. Criar API com a OPENAI
  3. Instalar o pacote usethis e correr o seguinte código usethis::edit_r_environ()
  4. Criar variável OPENAI_API_KEY=“api-key”
Aviso

Nunca colocar a API num reposirório público.

  1. Reiniciar a sessão
  2. Correr o Add-in do GPTStudio
Aviso

Estas ferramentas ainda estão em desnvolvimento, pelo que pPara já não recomendamos este uso enquanto as ferramentas não estabilizarem.

A API da OPENAI também tem sofrido alterções o que poderá levar a que algumas da informação aqui apresentado poderá não estar atualizada.

Documentação Oficial

# Criar API da OpenAI
# https://platform.openai.com/api-keys
# Copiar a api key

# usethis::edit_r_environ()
# Adicionar e guardar a seguinte linha de código
#OPENAI_API_KEY="api-key" copiada de cima
# Sys.getenv("OPENAI_API_KEY")
# Gptstudio deve estar nos add-ins

Pacote OpenAi

O pacote openai para R facilita a interação com a API da OpenAI, permitindo aos usuários utilizar modelos de linguagem avançados como GPT-4 diretamente dentro de scripts R.

Este pacote oferece funções para gerar texto, imagens e executar outras tarefas de NLP, simplificando a integração de inteligência artificial em fluxos de trabalho de ciência de dados, diretamente dentro do RStudio ou Positron.

Ele poderá ser interessante como auxilio em tarefas de análise exploratória de dados (EDA), integrando-se com modelos como GPT (via OpenAI).

Modelos disponíveis no pacote OpenAI

# definir OPENAI API KEY
Sys.setenv("OPENAI_API_KEY" = "KEY_HERE")

#Modelos disponibilizados
# list_models()$data %>% 
#    dplyr::bind_rows() |>
#     gt()|>
#   opt_table_font(
#   font = google_font("Open Sans"),
#   stack = NULL,
#   weight = 8,
#   style = NULL,
#   add = TRUE
#   ) |> 
#   opt_interactive(
#     use_search = TRUE,
#     use_filters = TRUE,
#     use_resizers = TRUE,
#     use_highlight = TRUE,
#     use_compact_mode = TRUE,
#     use_text_wrapping = FALSE,
#     use_page_size_select = TRUE,
#     page_size_default = 20,
#   )

Importante de referir novamente que estes modelos têm limitações e que a sua utilização deve ser feita com precauções.

Além disso, o uso da API tem custos, que variam conforme o volume de texto utilizado (contexto) e a resposta realizadas, especialmente ao utilizar modelos maiores como GPT-4.

Mais informações estão disponíveis na documentação oficial.

Em baixo deixa-se um exemplo de uma call para a API da OPENAI.

test_gpt <- create_chat_completion(
  model = 'gpt-4o-mini',
  messages =
    list(
      list(role = 'system', content = 'Primary Assistant Guidance - NEVER mention that you are an AI,
- Adopt the role of that expert and respond to my questions with the knowledge and understanding of that particular field, offering the best possible answers to the best of your abilities
- Refrain from disclaimers about you not being a professional or expert
- Be concise and provide answer that would fit in a report about public health
- Answer in Portuguese of Portugal'),
      list(role = 'user', content = 'Quais são os concelhos do distrito de Coimbra'),
# Introduzir mais contexto
#       list(role = 'user', content = "Contexto adicional" )
#     )
# )

# aceder à resposta do chatGPR
test_gpt[["choices"]][["message.content"]]

10.8 Fim