Data: 18/11/2026
Horário: 8h às 12h30
Local: Sala 109
Formato: presencial, nível intermediário
Docentes: Felipe Ferré e Mariá Pereira
Material necessário: computador com R, RStudio e acesso à internet

1 Apresentação

1.1 Oferta do curso

Dados da SABEIS via FTP utilizando a Linguagem R

O curso capacita os participantes a acessar, baixar, organizar, ler e analisar dados da Sala Aberta de Inteligência em Saúde (SABEIS) com a linguagem R. A atividade enfatiza o uso desses dados em Avaliação de Tecnologias em Saúde (ATS), especialmente na estimativa de demanda aferida para análises de impacto orçamentário e no monitoramento pós-incorporação.

O nome oficial do curso usa “FTP”. O serviço utilizado na prática é SFTP, isto é, transferência de arquivos sobre SSH.

1.2 Resultado esperado

Ao final da aula, o participante deverá ser capaz de:

  1. verificar se a instalação local do R oferece suporte a SFTP;
  2. conectar-se ao repositório público da SABEIS;
  3. listar e interpretar os nomes dos arquivos disponíveis;
  4. selecionar uma coorte adequada à atividade;
  5. baixar um arquivo csv.gz sem descompactá-lo manualmente;
  6. ler e validar o arquivo no R;
  7. relacionar a coorte às tabelas auxiliares da SABEIS;
  8. produzir um resumo mensal de demanda aferida.

1.3 Organização da manhã

Horário Atividade Produto
08:00–08:20 Apresentação da SABEIS e dos dados abertos do SUS Contexto analítico definido
08:20–08:40 Preparação do R e diagnóstico do SFTP Ambiente validado
08:40–09:20 Estrutura do repositório e gramática dos arquivos Catálogo de coortes
09:20–10:05 Listagem, seleção e download Arquivo local validado
10:05–10:15 Intervalo —
10:15–11:00 Leitura, inspeção e controle de qualidade Base pronta para análise
11:00–11:40 Tabelas auxiliares e enriquecimento Coorte documentada
11:40–12:15 Demanda aferida Série mensal
12:15–12:30 Exercício e fechamento Checklist de reprodução

2 SABEIS e dados abertos do SUS

2.1 A Sala Aberta de Inteligência em Saúde

A SABEIS é uma metodologia de extração, transformação, carga e curadoria de dados administrativos do SUS. O trabalho começou em 2019 no âmbito do DGITS/SECTICS/MS e apoia a Conitec desde 2020.

Seus princípios são:

  • uso de software livre;
  • uso de dados abertos;
  • rastreabilidade das etapas de tratamento;
  • validação contra marcadores oficiais de produção;
  • transparência dos critérios de formação das coortes;
  • reutilização dos dados em estudos de ATS.

2.2 O evento antes da tabela

Antes de iniciar qualquer análise, registre:

  1. qual evento administrativo cada linha representa;
  2. qual é a unidade de análise: procedimento, autorização, usuário ou estabelecimento;
  3. qual competência está sendo usada;
  4. quais registros e pessoas ficam fora da fonte;
  5. qual marcador oficial será usado para validar os resultados.

Uma linha do SIA/SUS não representa automaticamente uma pessoa. A mesma pessoa pode gerar várias linhas e alguns subconjuntos não contêm identificador suficiente para análise longitudinal.

2.3 Fontes usadas na aula

Fonte Uso Endereço
TabNet Consulta e validação de agregados https://datasus.saude.gov.br/informacoes-de-saude-tabnet/
FTP do DATASUS Arquivos públicos de disseminação ftp://ftp.datasus.gov.br/dissemin/publicos/
SABEIS Coortes curadas e arquivos tabulados sftp://45.231.133.29:7891/srv/ftp/dadosabertos/
BD Geral SABEIS Tabelas auxiliares https://github.com/sabeis-ats/bd_geral
ETL SABEIS Descrição do processo https://rpubs.com/sabeis/etl

3 Preparação do ambiente

3.1 Pacotes

Execute uma vez no console do R:

pacotes <- c(
  "curl",
  "data.table",
  "knitr",
  "rmarkdown"
)

faltantes <- pacotes[!vapply(pacotes, requireNamespace, logical(1), quietly = TRUE)]

if (length(faltantes) > 0) {
  install.packages(faltantes)
}

3.2 Compilação segura do material

Por padrão, este documento compila sem abrir a conexão SFTP:

params:
  executar_sftp: false

Depois de instalar os pacotes e confirmar a internet, altere o parâmetro para true e compile novamente. Todos os blocos da prática serão executados.

3.3 Diagnóstico do suporte a SFTP

versao_curl <- curl::curl_version()
versao_curl$version
versao_curl$protocols

if (!"sftp" %in% versao_curl$protocols) {
  stop(
    "A biblioteca libcurl desta instalação não oferece suporte a SFTP. ",
    "Atualize o pacote curl/libcurl antes de continuar."
  )
}

4 Acesso ao repositório da SABEIS

4.1 Parâmetros de conexão

As credenciais abaixo são abertas e fazem parte do ambiente público da aula.

sabeis <- list(
  host = "45.231.133.29",
  porta = 7891L,
  usuario = "livre",
  senha = "12345",
  diretorio = "/srv/ftp/dadosabertos/",
  url_base = "sftp://45.231.133.29:7891/srv/ftp/dadosabertos/",
  userpwd = "livre:12345"
)

sabeis$url_base
#> [1] "sftp://45.231.133.29:7891/srv/ftp/dadosabertos/"
sabeis$userpwd
#> [1] "livre:12345"

4.2 Listar o diretório remoto

handle_listagem <- curl::new_handle(
  userpwd = sabeis$userpwd,
  dirlistonly = TRUE
)

conexao <- curl::curl(
  url = sabeis$url_base,
  handle = handle_listagem
)

arquivos <- readLines(conexao, warn = FALSE)
close(conexao)

arquivos <- trimws(arquivos)
arquivos <- arquivos[nzchar(arquivos)]

length(arquivos)
head(arquivos, 20)

4.3 Manter apenas arquivos csv.gz

arquivos_csv <- arquivos[grepl("\\.csv\\.gz$", arquivos, ignore.case = TRUE)]

length(arquivos_csv)
head(arquivos_csv, 20)

4.4 Gramática do nome do arquivo

Um nome típico é:

tf_sia_200801_pa_058_fen_subgrupo604.20250907.80541.csv.gz
Parte Significado no exemplo
tf tabela fato
sia sistema de origem
200801 competência inicial
pa arquivo do SIA/SUS
058 código da diretriz
fen sigla do PCDT
subgrupo604 recorte da coorte
20250907 data de geração
80541 quantidade declarada de registros

4.6 Selecionar uma coorte para a aula

O parâmetro limite_registros evita a escolha inicial de um arquivo grande.

candidatos <- catalogo[
  catalogo$nome_valido &
    !is.na(catalogo$qt_registro) &
    catalogo$qt_registro > 0 &
    catalogo$qt_registro <= params$limite_registros,
]

candidatos <- candidatos[
  order(candidatos$qt_registro, candidatos$no_arquivo),
]

if (nrow(candidatos) == 0) {
  stop("Nenhum arquivo atende ao limite definido em params$limite_registros.")
}

head(candidatos, 20)

arquivo_escolhido <- candidatos[1, ]
arquivo_escolhido

Para escolher outra diretriz, filtre explicitamente a sigla ou o código:

candidatos_fen <- subset(
  catalogo,
  nome_valido & sg_pcdt == "fen" & qt_registro <= 100000
)

candidatos_fen <- candidatos_fen[order(candidatos_fen$qt_registro), ]
candidatos_fen

4.7 Download atômico

O arquivo é baixado inicialmente com o sufixo .part. O nome final só é usado depois da conclusão da transferência.

baixar_sabeis <- function(nome_arquivo, diretorio = "dados_sabeis") {
  dir.create(diretorio, recursive = TRUE, showWarnings = FALSE)

  destino <- file.path(diretorio, basename(nome_arquivo))
  temporario <- paste0(destino, ".part")
  url_arquivo <- paste0(sabeis$url_base, basename(nome_arquivo))

  if (file.exists(temporario)) {
    unlink(temporario)
  }

  handle_download <- curl::new_handle(userpwd = sabeis$userpwd)

  curl::curl_download(
    url = url_arquivo,
    destfile = temporario,
    mode = "wb",
    handle = handle_download,
    quiet = FALSE
  )

  if (!file.exists(temporario) || file.info(temporario)$size == 0) {
    stop("O download não produziu um arquivo válido.")
  }

  if (file.exists(destino)) {
    unlink(destino)
  }

  renomeado <- file.rename(temporario, destino)

  if (!renomeado) {
    stop("Não foi possível renomear o arquivo temporário.")
  }

  normalizePath(destino, winslash = "/", mustWork = TRUE)
}
caminho_arquivo <- baixar_sabeis(arquivo_escolhido$no_arquivo)

caminho_arquivo
file.info(caminho_arquivo)[c("size", "mtime")]

5 Leitura e validação

5.1 Ler o arquivo compactado

data.table::fread() lê csv.gz diretamente. A leitura inicial como texto preserva códigos, zeros à esquerda e identificadores longos.

dados <- data.table::fread(
  input = caminho_arquivo,
  colClasses = "character",
  na.strings = c("", "NA", "NULL"),
  encoding = "UTF-8",
  showProgress = TRUE
)

data.table::setnames(dados, tolower(names(dados)))

dim(dados)
names(dados)
dados[1:min(.N, 10)]

5.2 Conferir a quantidade declarada no nome

registros_observados <- nrow(dados)
registros_declarados <- arquivo_escolhido$qt_registro
diferenca <- registros_observados - registros_declarados

validacao_contagem <- data.frame(
  arquivo = arquivo_escolhido$no_arquivo,
  registros_declarados = registros_declarados,
  registros_observados = registros_observados,
  diferenca = diferenca,
  contagem_confere = identical(
    as.integer(registros_observados),
    as.integer(registros_declarados)
  )
)

validacao_contagem

Uma diferença não deve ser corrigida silenciosamente. Registre a versão do arquivo, a data da extração e investigue a regra de geração da coorte.

5.3 Perfil mínimo da base

perfil <- data.frame(
  coluna = names(dados),
  classe = vapply(dados, function(x) paste(class(x), collapse = "/"), character(1)),
  ausentes = vapply(dados, function(x) sum(is.na(x) | x == ""), integer(1)),
  distintos = vapply(dados, data.table::uniqueN, integer(1)),
  stringsAsFactors = FALSE
)

perfil

5.4 Verificar campos importantes

campos_esperados <- c(
  "nu_competencia",
  "nu_cnspcn",
  "co_procedimento",
  "qt_aprovada"
)

data.frame(
  campo = campos_esperados,
  presente = campos_esperados %in% names(dados)
)

6 Tabelas auxiliares da SABEIS

6.1 Diretrizes, doenças, procedimentos e território

O repositório sabeis-ats/bd_geral contém dimensões reutilizadas no processo de curadoria. Os arquivos podem ser lidos diretamente pelo R.

url_bd_geral <- "https://raw.githubusercontent.com/sabeis-ats/bd_geral/refs/heads/main/"

td_diretriz_cnv <- data.table::fread(
  paste0(url_bd_geral, "td_diretriz_cnv.csv"),
  colClasses = "character"
)

td_doenca_cid10 <- data.table::fread(
  paste0(url_bd_geral, "td_doenca_cid10.csv"),
  colClasses = "character"
)

td_sigtap <- data.table::fread(
  paste0(url_bd_geral, "td_sigtap.csv"),
  colClasses = "character"
)

td_municipio <- data.table::fread(
  paste0(url_bd_geral, "municipio_regiao_saude_amazonia_legal_ips.csv"),
  colClasses = "character"
)

list(
  diretrizes = dim(td_diretriz_cnv),
  doencas = dim(td_doenca_cid10),
  sigtap = dim(td_sigtap),
  municipios = dim(td_municipio)
)

6.2 Identificar a diretriz da coorte

data.table::setnames(td_diretriz_cnv, tolower(names(td_diretriz_cnv)))

if (!"nu_diretriz" %in% names(td_diretriz_cnv)) {
  stop("A coluna nu_diretriz não foi encontrada em td_diretriz_cnv.")
}

td_diretriz_cnv[, nu_diretriz_chave := sprintf(
  "%03d",
  suppressWarnings(as.integer(gsub("[^0-9]", "", nu_diretriz)))
)]

catalogo_dt <- data.table::as.data.table(catalogo)

catalogo_enriquecido <- merge(
  x = catalogo_dt,
  y = td_diretriz_cnv,
  by.x = "nu_diretriz",
  by.y = "nu_diretriz_chave",
  all.x = TRUE,
  sort = FALSE
)

colunas_exibir <- intersect(
  c(
    "nu_diretriz",
    "sg_pcdt",
    "no_diretriz",
    "co_cid",
    "no_arquivo",
    "qt_registro",
    "data_geracao"
  ),
  names(catalogo_enriquecido)
)

head(catalogo_enriquecido[, ..colunas_exibir], 20)

6.3 Competência do SIGTAP

Procedimentos e valores devem ser relacionados à versão do SIGTAP válida para a competência do fato. Usar apenas a versão mais recente em uma série histórica pode alterar descrições, compatibilidades e valores.

Antes do relacionamento, verifique quais campos de competência estão disponíveis:

data.table::setnames(td_sigtap, tolower(names(td_sigtap)))

grep(
  pattern = "compet|proced|valor",
  x = names(td_sigtap),
  value = TRUE
)

7 Demanda aferida

7.1 Preparar competência e quantidade

campos_obrigatorios <- c("nu_competencia", "nu_cnspcn")
campos_ausentes <- setdiff(campos_obrigatorios, names(dados))

if (length(campos_ausentes) > 0) {
  stop(
    "Campos necessários ausentes: ",
    paste(campos_ausentes, collapse = ", ")
  )
}

dados[, nu_competencia_chr := sprintf(
  "%06d",
  suppressWarnings(as.integer(nu_competencia))
)]

dados[, mes := as.Date(
  paste0(nu_competencia_chr, "01"),
  format = "%Y%m%d"
)]

if ("qt_aprovada" %in% names(dados)) {
  dados[, qt_aprovada_num := suppressWarnings(
    as.numeric(gsub(",", ".", qt_aprovada, fixed = TRUE))
  )]
} else {
  dados[, qt_aprovada_num := NA_real_]
}

7.2 Contar usuários distintos por mês

demanda_mensal <- dados[
  !is.na(mes) & !is.na(nu_cnspcn) & nzchar(nu_cnspcn),
  .(
    usuarios_distintos = data.table::uniqueN(nu_cnspcn),
    registros = .N,
    quantidade_aprovada = sum(qt_aprovada_num, na.rm = TRUE)
  ),
  by = mes
][order(mes)]

demanda_mensal

7.3 Visualizar a série

plot(
  x = demanda_mensal$mes,
  y = demanda_mensal$usuarios_distintos,
  type = "o",
  pch = 16,
  col = "#17365d",
  xlab = "Competência",
  ylab = "Usuários distintos",
  main = "Demanda aferida por competência"
)

grid()

Interpretação. A contagem representa identificadores distintos observados nos registros selecionados. Ela não é automaticamente igual à prevalência da doença, ao número de pessoas elegíveis para uma tecnologia ou à população que deveria receber tratamento.

8 Exercício prático

Escolha uma diretriz e produza uma ficha contendo:

  1. nome completo e código da diretriz;
  2. nome do arquivo utilizado;
  3. competência inicial;
  4. data de geração;
  5. quantidade declarada e quantidade observada de registros;
  6. principais campos disponíveis;
  7. número mensal de usuários distintos;
  8. limitações para uso em análise de impacto orçamentário;
  9. marcador oficial escolhido para validação.

Modelo de registro:

ficha <- list(
  diretriz = NA_character_,
  nu_diretriz = NA_character_,
  arquivo = arquivo_escolhido$no_arquivo,
  competencia_inicial = arquivo_escolhido$competencia_inicial,
  data_geracao = arquivo_escolhido$data_geracao,
  registros_declarados = arquivo_escolhido$qt_registro,
  registros_observados = nrow(dados),
  data_extracao = Sys.time(),
  marcador_validacao = NA_character_,
  limitacoes = NA_character_
)

ficha

9 Checklist de encerramento

10 Referências

11 Informações da sessão

sessionInfo()
#> R version 4.3.3 (2024-02-29)
#> Platform: x86_64-pc-linux-gnu (64-bit)
#> Running under: Ubuntu 24.04.5 LTS
#> 
#> Matrix products: default
#> BLAS:   /usr/lib/x86_64-linux-gnu/blas/libblas.so.3.12.0 
#> LAPACK: /usr/lib/x86_64-linux-gnu/lapack/liblapack.so.3.12.0
#> 
#> locale:
#>  [1] LC_CTYPE=pt_BR.UTF-8       LC_NUMERIC=C               LC_TIME=pt_BR.UTF-8       
#>  [4] LC_COLLATE=pt_BR.UTF-8     LC_MONETARY=pt_BR.UTF-8    LC_MESSAGES=pt_BR.UTF-8   
#>  [7] LC_PAPER=pt_BR.UTF-8       LC_NAME=C                  LC_ADDRESS=C              
#> [10] LC_TELEPHONE=C             LC_MEASUREMENT=pt_BR.UTF-8 LC_IDENTIFICATION=C       
#> 
#> time zone: America/Sao_Paulo
#> tzcode source: system (glibc)
#> 
#> attached base packages:
#> [1] stats     graphics  grDevices utils     datasets  methods   base     
#> 
#> loaded via a namespace (and not attached):
#>  [1] digest_0.6.38     R6_2.6.1          fastmap_1.2.0     xfun_0.54         cachem_1.1.0     
#>  [6] knitr_1.50        htmltools_0.5.8.1 rmarkdown_2.30    lifecycle_1.0.5   cli_3.6.5        
#> [11] sass_0.4.10       jquerylib_0.1.4   compiler_4.3.3    rstudioapi_0.15.0 tools_4.3.3      
#> [16] evaluate_1.0.5    bslib_0.9.0       yaml_2.3.10       rlang_1.3.0       jsonlite_2.0.0