pnadium 0.25

Pacote para download e processamento dos microdados da PNAD Contínua do IBGE.

pnadium

Pacote para download e processamento dos microdados da PNAD Contínua do IBGE, facilitando o acesso aos microdados trimestrais, que contém a pesquisa básica e os microdados anuais, que também contém pesquisas suplementares (por trimestre ou visita).

Instalação

Para instalar o pacote pnadium, você pode clonar o repositório e instalar localmente:

git clone https://github.com/ggximenez/pnadium.git
cd pnadium
pip install .

Ou, se preferir, instale diretamente via pip:

pip install pnadium

Uso

O pacote pnadium possui dois submódulos: trimestral e anual. Cada submódulo oferece funções para manipular os dados correspondentes. O submódulo trimestral se refere aos microdados de divulgação trimestral, respectivos à pesquisa básica da PNAD contínua. Já o submódulo anual se refere aos microdados de divulgação anual, que contenham pesquisas suplementares (temáticas), que são divulgados por trimestre ou por visita ao domicílio. Para saber mais, acesse aqui

Importação dos Submódulos

import pnadium

# Acessando o submódulo trimestral
from pnadium import trimestral

# Acessando o submódulo anual
from pnadium import anual

Funções Disponíveis

API principal

• listar_arquivos(tipo='trimestral'): lista arquivos disponíveis. Use tipo='trimestral', tipo='anual_trimestre' ou tipo='anual_visita'.
• mapear_arquivos(tipo='trimestral'): retorna o mapeamento interno dos arquivos disponíveis no FTP do IBGE.
• baixar_microdados(ano, periodo, tipo='trimestral', caminho=None, variaveis=None, salvar=None): baixa e processa os microdados.
• baixar_microdados_periodo(ano_inicio, periodo_inicio, ano_fim, periodo_fim, tipo='trimestral', caminho=None, variaveis=None, salvar=True, retornar_dados=False): baixa uma sequência de trimestres. Disponível apenas para tipo='trimestral'.
• consultar_variaveis(tipo='trimestral', ano=None, periodo=None, codigo=None, descricao=None, busca=None): consulta o dicionário de variáveis.

Os nomes antigos (download, map_files, consulta_arquivos, consulta_var, t, colunas e save_file) continuam disponíveis por compatibilidade.

Deflacionamento

• deflacionar(dados, rendimentos_habituais=None, rendimentos_efetivos=None, tipo='trimestral', ano_referencia=None, periodo_referencia=None, referencia='ultimo_ano', coluna_ano='Ano', coluna_periodo='Trimestre', coluna_uf='UF', sufixo='_real', incluir_deflatores=False): aplica os deflatores oficiais da PNAD Contínua, baixados diretamente do FTP do IBGE, e cria novas colunas com valores reais. Para rendimentos habituais, informe as variáveis em rendimentos_habituais; para rendimentos efetivos, informe as variáveis em rendimentos_efetivos.
• carregar_deflatores(tipo='trimestral', ano_referencia=None, periodo_referencia=None): baixa e retorna a tabela oficial de deflatores usada por deflacionar.

Os parâmetros antigos do deflacionamento (colunas_habitual, colunas_efetivo, ano_deflator, t_deflator, col_ano, col_trimestre, col_uf e manter_deflatores) também continuam funcionando.

Valores aceitos para tipo:

• 'trimestral': usa Deflatores.zip da documentação trimestral, com fatores Habitual e Efetivo.
• 'anual_trimestre' ou 't': usa os deflatores anuais por trimestre, com fatores Habitual e Efetivo.
• 'anual_visita' ou 'v': usa os deflatores anuais por visita, com fatores CO1, CO1e, CO2, CO2e e CO3. Neste caso, referencia='proprio_ano' usa CO1/CO1e; referencia='ultimo_ano' usa CO2/CO2e.

Submódulo trimestral

• map_files(): Mapeia os arquivos trimestrais disponíveis no FTP do IBGE.
• download(ano, t, caminho=None, colunas=None, save_file=None): Faz o download e processamento dos dados trimestrais para o ano (ano) e trimestre (t) especificados. Os argumentos opcionais são: caminho, colunas e save_file. caminho é uma string que indica o caminho, incluindo nome, do arquivo da base de dados a ser salvo em .parquet; colunas é uma lista de strings com os nomes das colunas de interesse, caso queira carregar apenas parte das colunas e não a base de dados integral; e save_file é uma variável bool, que quando assume o valor True salva o arquivo da base de dados, caso contrário apenas retorna o DataFrame à variável indicada.
• consulta_arquivos(): Retorna um DataFrame com os arquivos trimestrais disponíveis.
• consulta_var(cod=None, desc=None): Permite consultar o dicionário de variáveis trimestrais por código (cod) ou descrição (desc).

Submódulo anual

Observação: No submódulo anual, todas as funções requerem o argumento adicional tipo, que especifica o tipo de dados a serem manipulados. Além disso, a função consulta_var também requer os argumentos ano e t.

Argumento tipo

O argumento tipo define o tipo de arquivo anual que será utilizado. Os valores possíveis são:

• 't': Para dados por trimestre.
• 'v': Para dados por visita.

Funções

• map_files(tipo): Mapeia os arquivos anuais disponíveis no FTP do IBGE para o tipo especificado.
• download(ano, t, tipo, caminho=None, colunas=None, save_file=True): Faz o download e processamento dos dados anuais para o ano (ano), período (t) e tipo especificados. O argumento caminho é opcional. Se não for especificado o caminho, os dados serão salvos no diretório atual. O argumento opcional colunas: agora você pode passar uma lista com o código das colunas de interesse, e o DataFrame final conterá apenas as colunas de interesse e as colunas chave; e save_file é uma variável bool, que quando assume o valor True salva o arquivo da base de dados, caso contrário apenas retorna o DataFrame à variável indicada.
• consulta_arquivos(tipo): Retorna um DataFrame com os arquivos anuais disponíveis para o tipo especificado.
• consulta_var(ano, t, tipo, cod=None, desc=None): Permite consultar o dicionário de variáveis anuais para o ano (ano), período (t) e tipo especificados, podendo filtrar por código (cod) ou descrição (desc).

Exemplos de Uso

Exemplo 1: Consultar Arquivos Disponíveis

import pnadium

# Consultar arquivos trimestrais disponíveis
df_trimestral = pnadium.listar_arquivos(tipo="trimestral")
print(df_trimestral)

# Consultar arquivos anuais disponíveis por visita
df_anual_visita = pnadium.listar_arquivos(tipo="anual_visita")
print(df_anual_visita)

# Consultar arquivos anuais disponíveis por trimestre
df_anual_trimestre = pnadium.listar_arquivos(tipo="anual_trimestre")
print(df_anual_trimestre)

Exemplo 2: Fazer Download dos Dados

# Download dos dados do 1º trimestre de 2020 (dados trimestrais)
pnadium.baixar_microdados(ano=2020, periodo=1, caminho='caminho/para/salvar', salvar=True)

No caso acima, a base de dados final em arquivo .parquet será salva no caminho designado. Se quiser atribuir o DataFrame final a uma variável sem salvar a base de dados em arquivo .parquet, basta designar uma variável à função download, no caso abaixo pnad_01_20:

# Download dos dados do 1º trimestre de 2020 (dados trimestrais)
pnad_01_20 = pnadium.baixar_microdados(ano=2020, periodo=1)

Para salvar um arquivo .parquet com a base de dados e também obter os dados em uma variável, basta combinar as duas abordagens:

# Download dos dados do 1º trimestre de 2020 (dados trimestrais)
pnad_01_20 = pnadium.baixar_microdados(ano=2020, periodo=1, caminho='caminho/para/salvar', salvar=True)

Para economizar memória em seu ambiente virtual, você pode limitar o DataFrame final às colunas de interesse através do argumento colunas, descartando colunas com informações que não serão utilizadas em seu estudo. No exemplo a seguir, além das colunas necessárias para as chaves, apenas as seguintes serão carregadas:

• "V1028": Peso do domicílio e das pessoas com calibragem por projeção da população;
• "V2001": Número de pessoas no domicílio;
• "V2005": Condição da pessoa no domicílio (Responsável, cônjuge, filho(a), etc);
• "V2007": Sexo da pessoa;
• "V2009": Idade da pessoa em anos;
• "V2010": Cor ou raça da pessoa.

Assim é o código a ser executado:

# Colunas de interesse:
cols = [
"V1028",
"V2001",
"V2005",
"V2007",
"V2009",
"V2010",
]
# Download dos dados do 1º trimestre de 2020 (dados trimestrais), apenas com colunas de interesse
pnad_01_20 = pnadium.baixar_microdados(ano=2020, periodo=1, variaveis=cols)

Para baixar vários trimestres, use baixar_microdados_periodo. Por padrão, essa função é mais econômica: processa um trimestre por vez, salva um arquivo .parquet por trimestre e retorna apenas um resumo com os arquivos gerados, sem manter todos os microdados em memória.

resumo = pnadium.baixar_microdados_periodo(
    ano_inicio=2012,
    periodo_inicio=1,
    ano_fim=2025,
    periodo_fim=4,
    caminho="dados/pnad",
    variaveis=["VD4019", "VD4020"],
)
print(resumo)

Se realmente quiser receber os DataFrames em memória, use retornar_dados=True. Essa opção pode consumir bastante RAM em períodos longos:

resumo, bases = pnadium.baixar_microdados_periodo(
    ano_inicio=2025,
    periodo_inicio=1,
    ano_fim=2025,
    periodo_fim=2,
    variaveis=["VD4019", "VD4020"],
    retornar_dados=True,
)

As colunas usadas para criar as chaves de domicílio e de pessoa serão sempre carregadas:

• "UPA": Código da Unidade Primária de Amostragem;
• "V1008": Número de seleção do domicílio;
• "V1014": Número do painel;
• "V2003": Número de ordem do morador do domicílio.

Com as colunas base são criadas duas chaves, uma para domicílio e outra para a pessoa, de acordo com a composição das chaves informada pelo IBGE :

• COD_FAM: Código do domicílio ou família, composto por "UPA" + "V1008" + "V1014";
• COD_PESSOA: Código da pessoa ou morador, composto por "UPA" + "V1008" + "V1014" + "V2003"

Assim, o DataFrame final sempre seguirá o seguinte formato:

index	UPA	V1008	V1014	V2003	COD_FAM	COD_PESSOA	Colunas de interesse...
0	110000016	01	7	01	110000016017	11000001601701	...
1	110000016	01	7	02	110000016017	11000001601702	...
...	...	...	...	...	...	...	...

Certifique-se de consultar os códigos das colunas no dicionário dos microdados de interesse. Pesquisas suplementares tem códigos distintos, sendo necessária a consulta previamente.

Exemplo 3: Consultar Variáveis

# Consultar variáveis trimestrais que contêm 'renda' na descrição
variaveis_trimestral = pnadium.consultar_variaveis(busca='renda')
print(variaveis_trimestral)

# Consultar variáveis anuais para o ano 2020, período 1, tipo 'v', pelo código 'V2009'
variaveis_anual = pnadium.consultar_variaveis(tipo="anual_visita", ano=2020, periodo=1, codigo='V2009')
print(variaveis_anual)

# Consultar variáveis anuais para o ano 2020, período 2, tipo 't', que contêm 'emprego' na descrição
variaveis_anual_emprego = pnadium.consultar_variaveis(tipo="anual_trimestre", ano=2020, periodo=2, busca='emprego')
print(variaveis_anual_emprego)

Exemplo 4: Deflacionar Rendimentos

import pnadium

cols = ["Ano", "Trimestre", "UF", "VD4019", "VD4020"]
pnad = pnadium.baixar_microdados(ano=2025, periodo=4, variaveis=cols)

pnad = pnadium.deflacionar(
    pnad,
    rendimentos_habituais=["VD4019"],
    rendimentos_efetivos=["VD4020"],
    tipo="trimestral",
)

No exemplo acima, o DataFrame final contém VD4019_real e VD4020_real. Para os microdados anuais por visita:

pnad = pnadium.deflacionar(
    pnad,
    rendimentos_habituais=["VD4019"],
    rendimentos_efetivos=["VD4020"],
    tipo="anual_visita",
    ano_referencia=2025,
    referencia="proprio_ano",
)

Detalhes sobre os argumentos

Argumento tipo no Submódulo anual

O argumento tipo determina o conjunto de dados anuais que será utilizado:

• Tipo 'v' (Visita): Refere-se aos dados coletados por visita domiciliar. São realizadas 5 visitas ao longo do ano.
• Tipo 't' (Trimestre): Refere-se aos dados agregados por trimestre.

Argumentos ano e t na Função consulta_var do Submódulo anual

A função consulta_var no submódulo anual requer os argumentos ano e t (período) porque o dicionário de variáveis pode variar de acordo com o ano e o período específico. Isso garante que a consulta retorne informações precisas para o conjunto de dados desejado.

Dependências

O pacote pnadium depende das seguintes bibliotecas:

• pandas
• numpy
• unidecode
• appdirs

Certifique-se de que elas estejam instaladas no seu ambiente Python.

Licença

Este projeto está licenciado sob a licença MIT - consulte o arquivo LICENSE para mais detalhes.

Contribuição

Contribuições são bem-vindas! Sinta-se à vontade para abrir issues ou pull requests no GitHub.

Autor

• Gustavo G. Ximenez