README.md

🇺🇸 English?

covid19-br

Esse repositório centraliza links e dados sobre boletins de número de casos das Secretarias Estaduais de Saúde (SES) sobre os casos de covid19 no Brasil (por município por dia), além de outros dados relevantes para a análise, como óbitos registrados em cartório (por estado por dia).

Tabela de Conteúdos

1. Licença e Citação
2. Sobre os dados
3. Guia de contribuição geral
4. Guia de instalação / setup do projeto (ambiente de desenvolvimento)
5. Guia de como executar os scrapers existentes
6. Guia de como criar novos scrapers
7. Guia de como atualizar os dados no Brasil.io (ambiente de produção)

Licença e Citação

A licença do código é LGPL3 e dos dados convertidos Creative Commons Attribution ShareAlike. Caso utilize os dados, cite a fonte original e quem tratou os dados e caso compartilhe os dados, utilize a mesma licença. Exemplos de como os dados podem ser citados:

• Fonte: Secretarias de Saúde das Unidades Federativas, dados tratados por Álvaro Justen e equipe de voluntários Brasil.IO
• Brasil.IO: boletins epidemiológicos da COVID-19 por município por dia, disponível em: https://brasil.io/dataset/covid19/ (última atualização pode ser conferida no site).

Dados

Depois de coletados e checados os dados ficam disponíveis de 3 formas no Brasil.IO:

• Interface Web (feita para humanos)
• API (feita para humanos que desenvolvem programas) - veja a documentação da API
• Download do dataset completo

Caso queira acessar os dados antes de serem publicados (ATENÇÃO: pode ser que não tenham sido checados), você pode acessar diretamente as planilhas em que estamos trabalhando.

Se esse programa e/ou os dados resultantes foram úteis a você ou à sua empresa, considere fazer uma doação ao projeto Brasil.IO, que é mantido voluntariamente.

FAQ SOBRE OS DADOS

Antes de entrar em contato conosco (estamos sobrecarregados) para tirar dúvidas sobre os dados, CONSULTE NOSSO FAQ.

Para mais detalhes veja a metodologia de coleta de dados.

Clipping

Quer saber quais projetos e notícias estão usando nossos dados? Veja o clipping.

Analisando os dados

Caso queira analisar os dados usando SQL, veja o script analysis.sh (ele baixa e converte os CSVs para um banco de dados SQLite e já cria índices e views que facilitam o trabalho) e os arquivos na pasta sql/.

Por padrão o script reutiliza os arquivos caso já tenha baixado; para sempre baixar a versão mais atual dos dados, execute ./analysis.sh --clean.

Leia também nossa análise dos microdados de vacinação disponíveis no OpenDataSUS.

Validando os dados

Os metadados estão descritos conforme os padrões Data Package e Table Schema do Frictionless Data. Isso significa que os dados podem ser validados automaticamente para detectar, por exemplo, se os valores de um campo estão em conformidade com a tipagem definida, se uma data é válida, se há colunas faltando ou se há linhas duplicadas.

Para fazer a verificação, ative o ambiente virtual Python e em seguida digite:

goodtables data/datapackage.json

O relatório da ferramenta Good Tables irá indicar se houver alguma inconsistência. A validação também pode ser feita online pelo site Goodtables.io.

Mais informações

Você pode ter interesse em ver também:

• Outros datasets relevantes
• Recomendações para secretarias de saúde na disponibilização de dados

Contribuindo

Você pode contribuir de diversas formas:

• Criando programas (crawlers/scrapers/spiders) para extrair os dados automaticamente (LEIA ESSE GUIA ANTES);
• Coletando links para os boletins de seu estado;
• Coletando dados sobre os casos por município por dia;
• Entrando em contato com a secretaria estadual de seu estado, sugerindo as recomendações de liberação dos dados;
• Evitando contato com humanos;
• Lavando as mãos várias vezes ao dia;
• Sendo solidário aos mais vulneráveis;

Para se voluntariar, siga estes passos.

Procure o seu estado nas issues desse repositório e vamos conversar por lá.

Instalando

Este projeto utiliza Python 3 (testado em 3.8.2) e Scrapy.

Você pode montar seu ambiente de desenvolvimento utilizando o setup padrão ou o setup com docker.

Setup Padrão

1. Instale o Python 3.8.2
2. Crie um virtualenv (você pode usar venv para isso).
3. Instale as dependências: pip install -r requirements-development.txt

Setup com Docker

Se você preferir utilizar o Docker para executar, basta usar os comandos a seguir :

make docker-build       # para construir a imagem
make docker-run-spiders # para coletar os dados

Executando os scrapers

Uma vez que seu setup estiver terminado, você pode rodar todos os scrapers usando um dos seguintes comandos no seu terminal (a depender do tipo de setup que decidiu fazer):

python covid19br/run_spider.py  # caso tenha feito o setup padrão
make docker-run-spiders         # caso esteja usando o setup com docker

Os comandos acima irão rodar os scrapers de todos os estados que temos implementado buscando os dados sobre a data de hoje e salvarão o consolidado em .csv na pasta data deste diretório (por padrão são salvos em arquivos com o nome no padrão "data/{estado}/covid19-{estado}-{data}{extra_info}.csv").

Mas essa não é a única forma de usar esse comando, você pode optar por não salvar os consolidados em um .csv (apenas exibi-los na tela) ou então rodar apenas os scrapers de alguns estados específicos ou para outros dias específicos que não são necessariamente a data de hoje.

Para adaptar melhor o comando ao seu caso de uso você pode rodá-lo no terminal com as seguintes opções:

OBS: Se você estiver usando docker, basta acrescentar docker container run --rm --name covid19-br -v $(PWD)/data:/app/data covid19-br antes de qualquer um dos comandos a seguir.

# Exemplo de como raspar os dados de todos os estados em um intervalo de datas
python covid19br/run_spider.py --start-date 24/02/2021 --end-date 30/03/2021

# Caso você queira executar para datas específicas (coloque-as em lista separando-as por vírgulas):
python covid19br/run_spider.py --dates-list  15/01/2022,17/01/2022

# Para executar apenas spiders de estados específicos (coloque-os em lista e separados por vírgulas):
python covid19br/run_spider.py --states BA,PR

# Para ver quais são os estados com scrapers implementados:
python covid19br/run_spider.py --available-spiders

# Caso você não queira salvar os csv's, apenas mostrar na tela os resultados:
python covid19br/run_spider.py --print-results-only

# Você pode consultar essas e outras opções disponíveis usando:
python covid19br/run_spider.py -h

Criando novos scrapers

Estamos mudando a forma como subimos os dados para facilitar o trabalho dos voluntários e deixar o processo mais robusto e confiável e, com isso, será mais fácil que robôs possam subir também os dados; dessa forma, os scrapers ajudarão bastante no processo.

Porém, ao criar um scraper é importante que você siga algumas regras:

• Necessário fazer o scraper usando o scrapy (confira aqui as docs);
• Não usar pandas, BeautifulSoap, requests ou outras bibliotecas desnecessárias (a std lib do Python já tem muita biblioteca útil, o scrapy com XPath já dá conta de boa parte das raspagens e rows já é uma dependência desse repositório);

Para padronizar a forma que os scrapers recebem parâmetros e retornam os dados, criamos um Spider Base, que nada mais é que um spider básico do scrapy com lógica a mais para:

• Identificar para quais datas o spider deve procurar dados (essa informação é recebida como parâmetro e é guardada na classe no atributo self.requested_dates, que é um generator de valores do tipo datetime.date com as datas que precisamos raspar os dados, e deve ser usada pelo seu spider para buscar os dados como solicitado).
• Guardar os dados raspados de uma forma que sejam retornados para o sistema que chamou o scraper de forma padronizada.

Para padronizar os dados que são retornados pelos spiders, criamos a classe FullReport que representa um "relatório completo" e armazena todos os dados coletados para um determinado estado em uma data específica. Esse relatório completo é composto por vários boletins, (um para cada cidade do estado + um para casos importados/indefinidos) com o número de casos confirmados e número de mortes daquele dia.

O seu script não precisa se preocupar com a criação do objeto FullReport que será retornado, isso é responsabilidade do Spider Base, o que seu spider deve criar são os boletins com os dados que ele coletar e salvar esses boletins no relatório através do método add_new_bulletin_to_report disponibilizado pelo Spider Base.

Em resumo, ao criar um spider de um novo estado tenha em mente:

• É desejável que você crie seu spider extendendo a classe Spider Base (você pode conferir alguns exemplos de como outros spiders são implementados na pasta /covid19br/spiders).
• Um spider completo é capaz de coletar os dados:
  • De número de casos confirmados e número de mortes por cidade do estado;
  • De número de casos confirmados e número de mortes importados/indefinidos;
  • De números de casos confirmados e números de mortes totais do estado (esse valor normalmente é computado automaticamente conforme os casos acimas são obtidos, mas em casos onde a scretaria disponibiliza o valor total, nós optamos por usá-lo como "fonte da verdade").
  • Para diferentes datas (desde o início da pandemia até hoje).

  OBS: Como não há uma padronização na forma em que as secretarias disponibilizam os dados, nem sempre é possível obter todas essas informações como desejamos. Obter parte dessas informações de forma automatizada já pode ser um bom começo e uma contribuição válida! :)

• Os dados coletados devem ser salvos em boletins e adicionados no retorno do spider através do método add_new_bulletin_to_report.

Ao finalizar a implementação do seu spider, adicione-o na lista de spiders do script run_spider.py e execute-o (mais informações sobre como fazer isso na seção anterior). Se tudo correu como previsto, é esperado que seja criado um .csv na pasta /data/... com os dados raspados pelo seu spider :)

Nesse momento não temos muito tempo disponível para revisão, então por favor, só crie um pull request com código de um novo scraper caso você possa cumprir os requisitos acima.

Atualização dos Dados no Brasil.IO

Crie um arquivo .env com os valores corretos para as seguintes variáveis de ambiente:

BRASILIO_SSH_USER
BRASILIO_SSH_SERVER
BRASILIO_DATA_PATH
BRASILIO_UPDATE_COMMAND
BULLETIN_SPREADSHEET_ID

Execute o script:

./deploy.sh full

Ele irá coletar os dados das planilhas (que estão linkadas em data/boletim_url.csv e data/caso_url.csv), adicionar os dados ao repositório, compactá-los, enviá-los ao servidor e executar o comando de atualização de dataset.

Nota: o script que baixa e converte os dados automaticamente deve ser executado separadamente, com o comando python covid19br/run_spider.py.