Modulo 3 - Analise de Dados com Python

Curso de Python para servidores da SEDUC-PI Dashboard, agrupamentos, cruzamento de bases e relatorio em PDF - de forma automatica.

---

A ideia central do curso

Primeiro entender o problema, depois o pensamento computacional, e so entao escrever o codigo (com a ajuda da IA).

Nao comecamos decorando comandos de Python. Comecamos com um problema real do nosso trabalho e o quebramos usando os 4 pilares do pensamento computacional:

1. Decomposicao - quebrar o problema grande em passos pequenos.
2. Padrao - perceber o que se repete.
3. Abstracao - separar o que importa do que e detalhe.
4. Algoritmo - escrever o passo a passo em portugues, antes do codigo.

Com esses 4 elementos na mao, fica facil pedir para a IA generativa (ChatGPT, Claude, Gemini, Copilot...) gerar o Python certo - e, principalmente, entender e conferir o que ela devolveu.

O problema-fio-condutor de hoje

Trabalhamos com tres bases de dados do Piaui (municipios, escolas, servidores) para entregar:

1. Uma base limpa e organizada a partir de dados sujos (ETL).
2. Um cruzamento das 3 bases pelo Codigo IBGE (merge).
3. Graficos de agrupamentos e totais (groupby).
4. Um relatorio em PDF com boas praticas (fonte, data, limitacoes).
5. Um dashboard interativo com Streamlit + Plotly.
6. Uma comparacao entre versoes (diff) de uma mesma base.

Fazer isso na mao e inviavel. Fazer com Python leva segundos - e serve para o seu proprio dado depois.

---

Comece por aqui (2 passos)

Passo 1 - Prepare o ambiente

Abra esta pasta no VS Code e, no terminal (menu Terminal > Novo Terminal), rode:

.\setup\preparar_ambiente.ps1

Isso cria o ambiente virtual .venv, instala as bibliotecas e roda um diagnostico. Se algo der errado, veja o passo a passo detalhado em setup/COMO_COMECAR.md.

Passo 2 - Confira se esta tudo pronto

A qualquer momento voce pode rodar o diagnostico sozinho:

python setup\preparar_ambiente.py

Ele mostra, com ✔ e ✖, a versao do Python, se voce esta no ambiente virtual e quais bibliotecas estao instaladas ou faltando - sempre com o comando exato para corrigir.

---

Roteiro da aula

Ordem	Arquivo	O que voce aprende
0	notebooks/nb_etl.ipynb	ETL: ler, explorar, limpar e salvar 3 bases sujas
1	scripts/modulo3/m3_cruzamento.py	Merge: cruzar municipios + escolas + servidores por IBGE
2	scripts/modulo3/m3_agrupamentos.py	Groupby: somas, medias, contagens e graficos
3	scripts/modulo3/m3_relatorio_reportlab.py	Relatorio PDF com mapa, tabelas e boas praticas
4	scripts/modulo3/m3_diff_versoes.py	Diff: comparar duas versoes da mesma base
5	scripts/modulo3/m3_dashboard_streamlit.py	Dashboard interativo com Streamlit + Plotly

Ordem de execucao

# 0) ETL no notebook (limpeza)
jupyter notebook notebooks/nb_etl.ipynb

# 1) Cruzamento
python scripts/modulo3/m3_cruzamento.py

# 2) Agrupamentos
python scripts/modulo3/m3_agrupamentos.py

# 3) Relatorio PDF
python scripts/modulo3/m3_relatorio_reportlab.py

# 4) Diff entre versoes
python scripts/modulo3/m3_diff_versoes.py

# 5) Dashboard (Streamlit)
streamlit run scripts/modulo3/m3_dashboard_streamlit.py

Nota: O notebook ETL (passo 0) sempre vem primeiro - ele gera as bases limpas que todos os outros consomem.

---

Os dados

Modulo 3 - 3 bases do Piaui (ficticias, para fins didaticos)

• dados/modulo3/municipios_piaui_suja.xlsx - 12 municipios com latitude/longitude
• dados/modulo3/escolas_piaui_suja.xlsx - 37 escolas com CNPJ e matricula
• dados/modulo3/servidores_piaui_suja.xlsx - servidores com CPF, cargo e remuneracao
• dados/modulo3/escolas_piaui_v1.xlsx / v2.xlsx - duas versoes para diff

Dados extras (Modulo 2)

• dados/nivelamento_anonimizado.csv - respostas reais da turma (anonimizadas)
• dados/nivelamento_bruto_exemplo.csv - planilha suja para treino de limpeza
• dados/sinteticos/notas_escolas.csv - 660 linhas de notas por escola

---

O esqueleto que se repete

ler a base  →  transformar  →  conferir  →  salvar

E para analise:

ler o cruzamento  →  groupby por categoria  →  agregar  →  grafico + planilha

---

Exercicios para os alunos

Procure por EXERCICIO e TODO(aluno) nos scripts e no notebook - cada um traz um prompt pronto para a IA e uma dica:

• nb_etl.ipynb: latitude/longitude com separador misturado, grafico proprio
• m3_cruzamento.py: testar diferentes tipos de join (inner vs left vs outer)
• m3_agrupamentos.py: inventar uma metrica nova (ex.: alunos por servidor)
• m3_diff_versoes.py: coluna campos_alterados no diff
• m3_relatorio_reportlab.py: numero de pagina, brasao no cabecalho
• m3_dashboard_streamlit.py: novo filtro, mapa de calor

---

Melhore este projeto

• Enriquecer o diff com colunas alteradas detalhadas
• Adicionar analise de desigualdade (gap salarial entre municipios)
• Gerar anexos no PDF (tabela completa de servidores)
• Conectar com dados reais do iSEDUC

---

Estrutura do repositorio

Pasta	Para que
dados/modulo3/	dados originais "sujos" - nunca altere
modelo/assets/	bandeira do Piaui para o dashboard
notebooks/	notebook ETL - comecar por aqui
scripts/modulo3/	um script por etapa da analise
saida/modulo3/	tudo gerado - pode apagar e rodar de novo
dados/	dados extras do Modulo 2 (preservados)
setup/	scripts de preparacao do ambiente