Guia passo a passo para baixar, filtrar e analisar dados do QoG com pyqog.
Apos instalar o pyqog, voce pode baixar dados do QoG com um unico comando. Na primeira execucao, o pacote baixa os dados da internet e salva em cache local.
import pyqog
# Baixar dados basicos (time-series, versao mais recente)
df = pyqog.read_qog()
# Ver as dimensoes do DataFrame
print(f"Linhas: {df.shape[0]}, Colunas: {df.shape[1]}")
# Ver as primeiras linhas
print(df.head())Nota: O primeiro download pode levar alguns segundos dependendo da sua conexao. Os datasets maiores (Standard) podem ter mais de 2000 variaveis. Apos o download, os dados ficam em cache e o acesso e instantaneo.
O QoG disponibiliza cinco tipos principais de datasets:
Subconjunto selecionado de variaveis do QoG Standard. Ideal para iniciantes e exercicios em sala de aula.
df_basic = pyqog.read_qog(which_data="basic")Dataset completo com centenas de variaveis de diversas fontes. O mais abrangente.
df_std = pyqog.read_qog(which_data="standard")Dados especificos para paises membros da OCDE, com variaveis adicionais.
df_oecd = pyqog.read_qog(which_data="oecd")Indicadores ambientais de governanca e sustentabilidade.
df_env = pyqog.read_qog(which_data="environmental")Dados sobre politicas sociais, bem-estar e protecao social.
df_soc = pyqog.read_qog(which_data="social_policy")Para ver todos os datasets disponiveis de forma programatica:
# Listar todos os datasets
datasets = pyqog.list_datasets()
print(datasets)Cada dataset esta disponivel em dois formatos:
Dados em painel: cada linha representa um pais em um ano especifico. Permite analisar evolucao temporal de indicadores.
Identificadores: cname, ccode, year
Dados transversais: cada linha representa um pais com os valores mais recentes disponiveis para cada variavel. Ideal para comparacoes entre paises.
Identificadores: cname, ccode
# Dados time-series (padrao)
df_ts = pyqog.read_qog(which_data="basic", data_type="time-series")
print(f"Time-series: {df_ts.shape}")
# Dados cross-sectional
df_cs = pyqog.read_qog(which_data="basic", data_type="cross-sectional")
print(f"Cross-sectional: {df_cs.shape}")
Os dados do QoG usam a coluna cname para nomes de paises e ccode
para codigos numericos. Voce pode filtrar facilmente com pandas:
import pyqog
df = pyqog.read_qog()
# Filtrar dados do Brasil
brasil = df[df["cname"] == "Brazil"]
print(brasil.head())
# Filtrar multiplos paises
latam = df[df["cname"].isin(["Brazil", "Argentina", "Chile", "Colombia"])]
print(latam["cname"].value_counts())
# Ver todos os paises disponiveis
paises = df["cname"].unique()
print(f"Total de paises: {len(paises)}")
print(sorted(paises)[:20]) # Primeiros 20 em ordem alfabetica
Nos dados time-series, a coluna year indica o ano de observacao.
Importante: nao confundir com o parametro year da funcao read_qog(),
que indica a versao de publicacao do dataset.
import pyqog
df = pyqog.read_qog()
# Dados de um ano especifico
df_2020 = df[df["year"] == 2020]
print(f"Observacoes em 2020: {len(df_2020)}")
# Dados de um periodo
df_recente = df[(df["year"] >= 2015) & (df["year"] <= 2023)]
# Combinar filtros: Brasil de 2000 a 2023
brasil_recente = df[
(df["cname"] == "Brazil") &
(df["year"] >= 2000) &
(df["year"] <= 2023)
]
print(brasil_recente.shape)
Os datasets do QoG podem ter centenas de variaveis. Use search_variables() para
encontrar variaveis por padrao no nome:
import pyqog
df = pyqog.read_qog(which_data="standard")
# Buscar variaveis relacionadas a corrupcao
vars_corrupt = pyqog.search_variables(df, "corrupt")
print("Variaveis de corrupcao:", vars_corrupt)
# Buscar variaveis de democracia
vars_demo = pyqog.search_variables(df, "demo")
print("Variaveis de democracia:", vars_demo)
# Buscar variaveis do Banco Mundial (prefixo "wdi_")
vars_wdi = pyqog.search_variables(df, "wdi_")
print(f"Variaveis do World Development Indicators: {len(vars_wdi)}")
# Buscar variaveis de educacao
vars_educ = pyqog.search_variables(df, "educ")
print("Variaveis de educacao:", vars_educ)Dica: Para descricoes detalhadas de cada variavel, consulte os codebooks em PDF disponiveis na pagina de Datasets. Voce tambem pode usar o QoG Data Finder para explorar variaveis online.
O QoG mantem um arquivo com versoes anteriores dos datasets. Voce pode acessar essas
versoes usando o parametro year da funcao read_qog().
Importante: O parametro year refere-se ao ano de
publicacao do dataset, nao ao ano dos dados contidos nele.
import pyqog
# Versao mais recente (2026)
df_atual = pyqog.read_qog(year=2026)
# Versao de 2020
df_2020 = pyqog.read_qog(year=2020)
# Versao de 2015
df_2015 = pyqog.read_qog(year=2015)
# Ver versoes disponiveis para o dataset Standard
versoes = pyqog.list_versions("standard")
print("Versoes disponiveis:", versoes)
# Comparar numero de variaveis entre versoes
print(f"Versao 2026: {df_atual.shape[1]} variaveis")
print(f"Versao 2020: {df_2020.shape[1]} variaveis")
print(f"Versao 2015: {df_2015.shape[1]} variaveis")Para obter o URL do codebook de uma versao especifica:
# Codebook da versao atual
url = pyqog.get_codebook_url("standard", 2026)
print(url)
# https://www.qogdata.pol.gu.se/data/codebook_std_jan26.pdf
# Codebook de versao antiga
url_antigo = pyqog.get_codebook_url("basic", 2020)
print(url_antigo)
# https://www.qogdata.pol.gu.se/dataarchive/codebook_bas_jan20.pdfO pyqog armazena automaticamente os dados baixados em cache local, permitindo acesso offline apos o primeiro download.
# Primeiro acesso: baixa da internet e salva em cache
df = pyqog.read_qog() # cache=True por padrao
# Acessos subsequentes: le do cache local (instantaneo)
df = pyqog.read_qog() # nao baixa novamente# Forcar download mesmo que o cache exista
df = pyqog.read_qog(update_cache=True)# Baixar sem salvar em cache
df = pyqog.read_qog(cache=False)# Usar diretorio personalizado
df = pyqog.read_qog(data_dir="/meu/diretorio/dados")
# Util para projetos com dados compartilhados
df = pyqog.read_qog(data_dir="./dados_qog")
Diretorio padrao do cache: ~/.pyqog/cache/
Os arquivos sao salvos como CSV com o nome padrao: qog_{dataset}_{type}_{version}.csv
Combine os dados do QoG com bibliotecas de visualizacao do Python para criar graficos informativos.
Os exemplos abaixo usam matplotlib e seaborn.
import pyqog
import matplotlib.pyplot as plt
# Baixar dados
df = pyqog.read_qog(which_data="basic")
# Filtrar Brasil
brasil = df[df["cname"] == "Brazil"].sort_values("year")
# Plotar PIB per capita ao longo do tempo
plt.figure(figsize=(10, 6))
plt.plot(brasil["year"], brasil["wdi_gdpcappppcon2017"], marker="o", linewidth=2)
plt.title("PIB per capita do Brasil (PPP, constante 2017)")
plt.xlabel("Ano")
plt.ylabel("PIB per capita (USD)")
plt.grid(True, alpha=0.3)
plt.tight_layout()
plt.show()import pyqog
import matplotlib.pyplot as plt
df = pyqog.read_qog(which_data="basic")
# Selecionar paises e ano
paises = ["Brazil", "Argentina", "Chile", "Uruguay", "Colombia"]
for pais in paises:
dados = df[(df["cname"] == pais) & (df["year"] >= 2000)].sort_values("year")
plt.plot(dados["year"], dados["wdi_gdpcappppcon2017"], label=pais, linewidth=2)
plt.title("PIB per capita — America do Sul")
plt.xlabel("Ano")
plt.ylabel("PIB per capita (PPP, USD constante 2017)")
plt.legend()
plt.grid(True, alpha=0.3)
plt.tight_layout()
plt.show()import pyqog
import matplotlib.pyplot as plt
# Dados cross-sectional (uma observacao por pais)
df = pyqog.read_qog(which_data="basic", data_type="cross-sectional")
# Scatter: PIB per capita vs. expectativa de vida
plt.figure(figsize=(10, 7))
plt.scatter(
df["wdi_gdpcappppcon2017"],
df["wdi_lifexp"],
alpha=0.6,
edgecolors="navy",
linewidth=0.5
)
plt.xlabel("PIB per capita (PPP, USD constante 2017)")
plt.ylabel("Expectativa de vida (anos)")
plt.title("Riqueza vs. Saude — Dados QoG Cross-Sectional")
plt.grid(True, alpha=0.3)
plt.tight_layout()
plt.show()import pyqog
import seaborn as sns
import matplotlib.pyplot as plt
df = pyqog.read_qog(which_data="basic", data_type="cross-sectional")
# Selecionar variaveis numericas de interesse
vars_interesse = pyqog.search_variables(df, "wdi_")[:8]
correlacao = df[vars_interesse].corr()
plt.figure(figsize=(10, 8))
sns.heatmap(correlacao, annot=True, cmap="coolwarm", center=0, fmt=".2f")
plt.title("Correlacao entre indicadores WDI")
plt.tight_layout()
plt.show()Este exemplo demonstra um fluxo de trabalho completo de analise com pyqog:
import pyqog
import pandas as pd
import matplotlib.pyplot as plt
# 1. Baixar dados
df = pyqog.read_qog(which_data="standard", data_type="time-series")
# 2. Explorar variaveis de corrupcao
vars_corrupt = pyqog.search_variables(df, "corrupt")
print("Variaveis de corrupcao encontradas:")
for v in vars_corrupt:
print(f" - {v}")
# 3. Selecionar paises do G20
g20 = ["Argentina", "Australia", "Brazil", "Canada", "China",
"France", "Germany", "India", "Indonesia", "Italy",
"Japan", "Mexico", "Russia", "Saudi Arabia",
"South Africa", "South Korea", "Turkey",
"United Kingdom", "United States"]
df_g20 = df[df["cname"].isin(g20) & (df["year"] >= 2000)]
# 4. Analisar evolucao media do controle de corrupcao
if "wbgi_cce" in df_g20.columns:
media_anual = df_g20.groupby("year")["wbgi_cce"].mean()
plt.figure(figsize=(10, 6))
media_anual.plot(kind="line", marker="o", linewidth=2)
plt.title("Controle de Corrupcao medio — Paises do G20")
plt.xlabel("Ano")
plt.ylabel("Indice WGI de Controle de Corrupcao")
plt.grid(True, alpha=0.3)
plt.tight_layout()
plt.show()
# 5. Ver info do dataset
info = pyqog.describe_dataset("standard")
print("\nInformacoes do dataset:")
for chave, valor in info.items():
print(f" {chave}: {valor}")
# 6. Obter codebook
codebook_url = pyqog.get_codebook_url("standard", 2026)
print(f"\nCodebook: {codebook_url}")