Referencia da API

Documentacao completa de todas as funcoes do pacote pyqog.

read_qog()

Funcao principal do pacote. Baixa e retorna um dataset do QoG como DataFrame do pandas.

Assinatura
def read_qog(
    which_data: str = "basic",
    data_type: str = "time-series",
    year: int = 2026,
    data_dir: str | None = None,
    cache: bool = True,
    update_cache: bool = False
) -> pd.DataFrame:
Parametros
Parametro Tipo Padrao Descricao
which_data str "basic" Tipo de dataset. Opcoes: "basic", "standard", "oecd", "environmental", "social_policy"
data_type str "time-series" Formato dos dados. Opcoes: "time-series" (dados em painel) ou "cross-sectional" (uma observacao por pais)
year int 2026 Ano de publicacao do dataset (NAO o ano dos dados). Exemplo: 2026 para a versao mais recente, 2020 para a versao de 2020.
data_dir str | None None Diretorio para armazenar cache. Se None, usa ~/.pyqog/cache/.
cache bool True Se True, salva o arquivo em cache e reutiliza em chamadas futuras.
update_cache bool False Se True, forca o re-download mesmo que o arquivo ja esteja em cache.
Retorno

pd.DataFrame — DataFrame do pandas contendo os dados do QoG. Colunas variam conforme o dataset e a versao.

Excecoes
  • ValueError — Se which_data ou data_type forem invalidos.
  • ValueError — Se year nao estiver disponivel para o dataset.
  • requests.ConnectionError — Se nao houver conexao com a internet e o dado nao estiver em cache.
Exemplos
import pyqog

# Uso basico: dados Basic, time-series, versao mais recente
df = pyqog.read_qog()

# Dados Standard, cross-sectional
df = pyqog.read_qog(which_data="standard", data_type="cross-sectional")

# Versao de arquivo (2020), sem cache
df = pyqog.read_qog(year=2020, cache=False)

# Dados OECD com diretorio de cache customizado
df = pyqog.read_qog(which_data="oecd", data_dir="./meus_dados")

# Forcar re-download
df = pyqog.read_qog(update_cache=True)

list_datasets()

Lista todos os datasets do QoG disponiveis no pyqog com suas descricoes.

Assinatura
def list_datasets() -> pd.DataFrame:
Parametros

Nenhum.

Retorno

pd.DataFrame — DataFrame com colunas: name (identificador do dataset), prefix (prefixo usado nas URLs), description (descricao do dataset).

Exemplo
import pyqog

datasets = pyqog.list_datasets()
print(datasets)

#         name prefix                         description
# 0      basic    bas          QoG Basic Dataset (subset)
# 1   standard    std          QoG Standard Dataset (full)
# 2       oecd   oecd         QoG OECD Dataset
# 3  environmental  ei      QoG Environmental Indicators
# 4  social_policy  soc     QoG Social Policy Dataset

list_versions()

Lista os anos de publicacao disponiveis para um dataset especifico.

Assinatura
def list_versions(which_data: str = "basic") -> list[int]:
Parametros
Parametro Tipo Padrao Descricao
which_data str "basic" Nome do dataset. Opcoes: "basic", "standard", "oecd", "environmental", "social_policy"
Retorno

list[int] — Lista de anos disponiveis em ordem decrescente (mais recente primeiro).

Exemplo
import pyqog

versoes = pyqog.list_versions("standard")
print(versoes)
# [2026, 2025, 2024, 2023, 2022, 2021, 2020, 2019, 2018, 2017, 2016, 2015]

versoes_basic = pyqog.list_versions("basic")
print(versoes_basic)
# [2026, 2025, 2024, 2023, ...]

get_codebook_url()

Retorna a URL do codebook em PDF para um dataset e versao especificos.

Assinatura
def get_codebook_url(which_data: str = "basic", year: int = 2026) -> str:
Parametros
Parametro Tipo Padrao Descricao
which_data str "basic" Nome do dataset. Opcoes: "basic", "standard", "oecd", "environmental", "social_policy"
year int 2026 Ano de publicacao. A versao atual (2026) usa o servidor principal; versoes anteriores usam o servidor de arquivo.
Retorno

str — URL completa do codebook em PDF.

Exemplos
import pyqog

# Codebook atual do Standard
url = pyqog.get_codebook_url("standard", 2026)
print(url)
# https://www.qogdata.pol.gu.se/data/codebook_std_jan26.pdf

# Codebook do Basic de 2020
url = pyqog.get_codebook_url("basic", 2020)
print(url)
# https://www.qogdata.pol.gu.se/dataarchive/codebook_bas_jan20.pdf

# Codebook OECD
url = pyqog.get_codebook_url("oecd")
print(url)
# https://www.qogdata.pol.gu.se/data/codebook_oecd_jan26.pdf

search_variables()

Busca variaveis (colunas) em um DataFrame por padrao no nome.

Assinatura
def search_variables(df: pd.DataFrame, pattern: str) -> list[str]:
Parametros
Parametro Tipo Padrao Descricao
df pd.DataFrame — DataFrame do QoG (retornado por read_qog()).
pattern str — Padrao de busca (case-insensitive). Busca correspondencias parciais nos nomes das colunas.
Retorno

list[str] — Lista de nomes de colunas que correspondem ao padrao.

Exemplos
import pyqog

df = pyqog.read_qog(which_data="standard")

# Buscar variaveis de corrupcao
pyqog.search_variables(df, "corrupt")
# ['ti_cpi', 'vdem_corr', 'wbgi_cce', ...]

# Buscar variaveis do Banco Mundial
vars_wb = pyqog.search_variables(df, "wdi_")
print(f"Encontradas {len(vars_wb)} variaveis WDI")

# Buscar variaveis de PIB
pyqog.search_variables(df, "gdp")
# ['wdi_gdpcappppcon2017', 'wdi_gdpcon2015', ...]

describe_dataset()

Retorna informacoes resumidas sobre um dataset do QoG.

Assinatura
def describe_dataset(which_data: str = "basic", year: int = 2026) -> dict:
Parametros
Parametro Tipo Padrao Descricao
which_data str "basic" Nome do dataset. Opcoes: "basic", "standard", "oecd", "environmental", "social_policy"
year int 2026 Ano de publicacao do dataset.
Retorno

dict — Dicionario com informacoes do dataset:

Chave Tipo Descricao
dataset str Nome do dataset
version int Ano de publicacao
n_rows int Numero de linhas
n_variables int Numero de variaveis (colunas)
n_countries int Numero de paises unicos
year_range tuple Intervalo de anos (min, max) — apenas time-series
codebook_url str URL do codebook em PDF
Exemplo
import pyqog

info = pyqog.describe_dataset("basic")
print(info)
# {
#     'dataset': 'basic',
#     'version': 2026,
#     'n_rows': 15000,
#     'n_variables': 70,
#     'n_countries': 194,
#     'year_range': (1946, 2023),
#     'codebook_url': 'https://www.qogdata.pol.gu.se/data/codebook_bas_jan26.pdf'
# }

info_std = pyqog.describe_dataset("standard", 2025)
print(f"Standard 2025: {info_std['n_variables']} variaveis")