Referência das funções¶

Descobrir¶

`condepe.condepe_catalog(refresh=False)` ¶

Fontes publicadas pelo Observatório.

Parameters:

Name	Type	Description	Default
`refresh`	`bool`	Ignora o catálogo em cache (válido por 6 horas) e consulta o servidor.	`False`

Returns:

Type	Description
`DataFrame`	Uma linha por fonte (`id_fonte`), com eixo, tema, descrição, órgão de origem, número de linhas, de indicadores e de localidades, e os anos cobertos. `attrs["version"]` traz a versão do catálogo e `attrs["citation"]`, a citação.

`condepe.condepe_indicators(source, refresh=False)` ¶

Indicadores de uma fonte, com unidade, cobertura e periodicidade.

Parameters:

Name	Type	Description	Default
`source`	`str`	Identificador da fonte (veja :func:`condepe_catalog`).	required
`refresh`	`bool`	Baixa a fonte de novo mesmo que haja cópia conferida em cache.	`False`

Returns:

Type	Description
`DataFrame`	Uma linha por `indicador_base`, com `unidade`, `natureza`, `mensal` (série mensal), número de observações e de localidades, e primeiro e último ano.

`condepe.condepe_localities(refresh=False)` ¶

Os 185 municípios de Pernambuco e o Estado, com código IBGE.

Tirados da fonte de estimativas de população, que cobre todos os municípios (Fernando de Noronha incluído); o Estado ("26") vem primeiro.

Parameters:

Name	Type	Description	Default
`refresh`	`bool`	Baixa a fonte de novo mesmo que haja cópia conferida em cache.	`False`

Returns:

Type	Description
`DataFrame`	`cd_municipio_ibge` e `nm_municipio`.

Obter os dados¶

`condepe.condepe_series(source, indicator, code=None, years=None, refresh=False)` ¶

Série de um ou mais indicadores, filtrada por localidade e ano se pedido.

Parameters:

Name	Type	Description	Default
`source`	`str`	Identificador da fonte (veja :func:`condepe_catalog`).	required
`indicator`	`str \| Iterable[str]`	Um ou mais valores de `indicador_base`, exatamente como listados por :func:`condepe_indicators`.	required
`code`	`str \| Iterable[str] \| None`	Códigos IBGE: 7 dígitos para municípios, `"26"` para o Estado. `None` mantém todas as localidades.	`None`
`years`	`int \| Iterable[int] \| None`	Um ano ou uma coleção de anos; `None` mantém todos.	`None`
`refresh`	`bool`	Baixa a fonte de novo mesmo que haja cópia conferida em cache.	`False`

Returns:

Type	Description
`DataFrame`	As observações que atendem aos filtros, ordenadas por localidade, ano e mês.

`condepe.condepe_data(source, refresh=False)` ¶

Uma fonte inteira (todos os indicadores, localidades e períodos).

O arquivo Parquet fica no cache em disco para a versão corrente do catálogo e é conferido pelo SHA-256 publicado no catálogo.

Parameters:

Name	Type	Description	Default
`source`	`str`	Identificador da fonte, por exemplo `"sidra_populacao_estimada"` (veja :func:`condepe_catalog`).	required
`refresh`	`bool`	Baixa de novo mesmo que haja cópia conferida em cache.	`False`

Returns:

Type Description

DataFrame

As 15 colunas do formato longo do Observatório: cd_municipio_ibge, nm_municipio, ano, mes, indicador, indicador_base, valor, unidade, natureza, id_fonte, eixo, tema, assunto, fonte_original, arquivo_origem. Séries mensais trazem o período em indicador ("… [MM/AAAA]") e em mes. attrs["citation"] traz a citação da fonte original, com o Observatório como organizador.

Citar¶

`condepe.condepe_cite(x=None)` ¶

Citação dos dados: a fonte original primeiro, o Observatório como organizador.

Os números do Observatório são das fontes originais (IBGE, Ministério da Saúde, INEP, ...); a Condepe/Fidem os coleta, padroniza e organiza.

Parameters:

Name	Type	Description	Default
`x`	`DataFrame \| str \| Iterable[str] \| None`	Um resultado de :func:`condepe_data` ou :func:`condepe_series` — também depois de filtrar ou concatenar: a citação sai das colunas `id_fonte` e `fonte_original`, uma por fonte presente; ou um ou mais identificadores de fonte, procurados no catálogo; ou nada, para a citação do acervo inteiro.	`None`

Returns:

Type	Description
`Series \| str`	Uma citação por fonte, indexada pelo `id_fonte`; ou, sem `x`, a citação do acervo.

Examples:

>>> condepe_data("sidra_populacao_estimada").pipe(condepe_cite)
>>> condepe_cite("datasus_sinasc")
>>> condepe_cite()

Mapas e regiões¶

`condepe.condepe_geometry(level='municipio', source='condepe', quality='intermediaria', noronha=True, refresh=False)` ¶

Malha municipal de Pernambuco, ou dissolvida numa regionalização.

Duas origens: "condepe" (padrão), a Malha Municipal de Pernambuco publicada pela Condepe/Fidem em https://cf.pe.gov.br/dados, na edição corrente do manifesto (conferida pelo SHA-256 e guardada em cache; a versão fica em .attrs["version"]); ou "ibge", a API de malhas do IBGE na qualidade pedida. Com level, os municípios são dissolvidos na regionalização pedida (veja :func:condepe_regions), com as mesmas divisas.

Parameters:

Name	Type	Description	Default
`level`	`str`	`"municipio"` (padrão) ou uma regionalização de :func:`condepe_regions`.	`'municipio'`
`source`	`str`	`"condepe"` ou `"ibge"`.	`'condepe'`
`quality`	`str`	Só para `source="ibge"`: `"intermediaria"`, `"minima"` ou `"maxima"`.	`'intermediaria'`
`noronha`	`bool`	Se `False`, deixa de fora Fernando de Noronha (2605459), que fica a 545 km da costa e espreme o continente nos mapas do estado.	`True`
`refresh`	`bool`	Baixa de novo mesmo que haja cópia em cache.	`False`

Returns:

Type	Description
`GeoDataFrame`	`cd_municipio_ibge`, `nm_municipio` e a geometria (WGS 84); com `level`, `regiao`, `n_municipios` e a geometria.

Examples:

>>> malha = condepe_geometry(noronha=False)
>>> rd = condepe_geometry("rd", noronha=False)
>>> rd.plot(column="regiao")

`condepe.condepe_add_geometry(x, level='municipio', geometry=None, how='left', **kwargs)` ¶

Junta dados do Observatório à malha, pronta para mapear.

Recebe qualquer resultado do pacote com cd_municipio_ibge (:func:condepe_series, :func:condepe_data ou uma agregação) e devolve um GeoDataFrame com uma linha por observação. Linhas do Estado ("26") são descartadas. Para mapear regiões, agregue os dados numa coluna regiao (juntando :func:condepe_regions) e passe level.

Parameters:

Name	Type	Description	Default
`x`	`DataFrame`	DataFrame com `cd_municipio_ibge` (ou `regiao`, com `level`).	required
`level`	`str`	Como em :func:`condepe_geometry`.	`'municipio'`
`geometry`	`Any`	A malha; por padrão `condepe_geometry(level, **kwargs)`.	`None`
`how`	`str`	`"left"` (padrão) mantém as áreas sem dado, com `NaN`; `"inner"` as descarta.	`'left'`
`**kwargs`	`Any`	Repassados a :func:`condepe_geometry` quando `geometry` não é dada (por exemplo, `source="ibge"` ou `noronha=False`).	`{}`

Examples:

>>> tmi = condepe_series("datasus_mortalidade_infantil",
...     "Taxa de mortalidade infantil (por mil nascidos vivos)", years=2024)
>>> condepe_add_geometry(tmi, noronha=False).plot(column="valor")

`condepe.condepe_regions(level=None, refresh=False, offline=False)` ¶

Regionalizações dos municípios de Pernambuco.

A que região pertence cada município em doze regionalizações oficiais: rd (Regiões de Desenvolvimento da Condepe/Fidem), mesorregiao, microrregiao, regiao_intermediaria e regiao_imediata (IBGE), regiao_saude e macrorregiao_saude (SES-PE), gre (Gerências Regionais de Educação da SEE-PE; Recife Norte e Recife Sul ficam juntas, porque dividem o mesmo município), regiao_fiscal (SEFAZ-PE), dro (Diretorias Regionais de Operações do DER-PE) e rm (regiões metropolitanas).

A tabela é publicada pelo Observatório junto com os dados abertos (referencia/regioes.parquet, listada no catálogo) e é lida de lá como as fontes: endereço canônico, espelho como reserva, SHA-256 conferido e cache em disco por versão do catálogo. Sem rede, ou com offline=True, vale a cópia que vai com o pacote.

Parameters:

Name	Type	Description	Default
`level`	`str \| None`	`None` (todas, uma coluna por regionalização) ou uma delas.	`None`
`refresh`	`bool`	Baixa a tabela de novo mesmo que haja cópia conferida em cache.	`False`
`offline`	`bool`	Usa só a cópia embutida no pacote, sem rede.	`False`

Returns:

Type	Description
`DataFrame`	`cd_municipio_ibge`, `nm_municipio` e as colunas de região (ou só `regiao`, se `level` for dado). Municípios fora de uma região metropolitana ficam com `NA` em `rm`. `.attrs["version"]` diz de onde veio: a versão do catálogo ou `"embutida"`.

Examples:

>>> condepe_regions("rd", offline=True)["regiao"].nunique()
13

`condepe.condepe_roads(type=None, refresh=False)` ¶

Malha rodoviária de Pernambuco.

Os trechos das rodovias de Pernambuco como GeoDataFrame de linhas (WGS 84): as estaduais, vicinais e acessos do Sistema Rodoviário Estadual do DER-PE e as federais em Pernambuco (SNV/DNIT), cada trecho com rodovia, denominação, início e fim, quilometragem, extensão, situação física (pavimentada, duplicada, implantada, leito natural, planejada, em obra), revestimento, Diretoria Regional de Operações do DER, Região de Desenvolvimento e municípios atravessados.

A malha é publicada pelo Observatório junto com os dados abertos (referencia/rodovias.parquet, um GeoParquet listado no catálogo) e lida de lá como as fontes: endereço canônico, espelho como reserva, SHA-256 conferido e cache em disco por versão do catálogo. Diferente de :func:condepe_regions, não há cópia embutida no pacote. Precisa do geopandas (pip install "condepe[geo]").

Parameters:

Name	Type	Description	Default
`type`	`str \| list[str] \| None`	`None` (todos os trechos) ou um ou mais de `"estaduais"`, `"federais"`, `"vicinais"` e `"acessos"`.	`None`
`refresh`	`bool`	Baixa a malha de novo mesmo que haja cópia conferida em cache.	`False`

Returns:

Type	Description
`GeoDataFrame`	Uma linha por trecho (`codigo_sre`, `rodovia`, `tipo`, `situacao`, `revestimento`, `extensao_km`, `dro`, `municipios`… e a geometria `MultiLineString`), com `.attrs["version"]` igual à versão do catálogo.

Raises:

Type	Description
`CondepeError`	Se o catálogo publicado ainda não trouxer a malha rodoviária.

Examples:

>>> rodovias = condepe_roads()
>>> rodovias.plot(column="tipo", legend=True)
>>> pav = rodovias[rodovias["classificacao"] == "PAVIMENTADA"]
>>> pav.groupby("dro")["extensao_km"].sum()

`condepe.condepe_hydrography(layer, refresh=False)` ¶

Hidrografia de Pernambuco.

Camadas da Agência Nacional de Águas recortadas para Pernambuco, como GeoDataFrame (WGS 84): rios (rios e riachos, BHO nível Otto 5), rios_principais (nível 3), massas_dagua (açudes, lagoas e reservatórios), reservatorios (os acompanhados pela ANA no semiárido, pontos com capacidade e demandas) e uph (Unidades de Planejamento Hídrico que alcançam o Estado).

As camadas são publicadas pelo Observatório junto com os dados abertos (referencia/<camada>.parquet, GeoParquet listado no catálogo) e lidas de lá como as fontes: endereço canônico, espelho como reserva, SHA-256 conferido e cache em disco por versão do catálogo. Precisa do geopandas (pip install "condepe[geo]").

Parameters:

Name	Type	Description	Default
`layer`	`str`	Uma das camadas acima.	required
`refresh`	`bool`	Baixa a camada de novo mesmo que haja cópia conferida em cache.	`False`

Returns:

Type	Description
`GeoDataFrame`	As colunas publicadas e a geometria (linhas, polígonos ou pontos conforme a camada), com `.attrs["version"]` igual à versão do catálogo.

Examples:

>>> rios = condepe_hydrography("rios_principais")
>>> acudes = condepe_hydrography("reservatorios")
>>> acudes.nlargest(5, "volume_maximo_m3")[["nome", "municipio"]]

`condepe.condepe_layer(id, refresh=False)` ¶

Camada geográfica publicada pelo Observatório.

Lê qualquer tabela de referência com geometria publicada nos dados abertos (referencia/<id>.parquet, GeoParquet listado no catálogo) como GeoDataFrame: além das que têm função própria (:func:condepe_roads, :func:condepe_hydrography), as camadas territoriais — "terras_indigenas" (FUNAI) e "up_perh" (Unidades de Planejamento do PERH, APAC). A lista corrente está em :func:condepe_catalog (referencias).

Parameters:

Name	Type	Description	Default
`id`	`str`	Identificador da camada no catálogo.	required
`refresh`	`bool`	Baixa a camada de novo mesmo que haja cópia conferida em cache.	`False`

Returns:

Type	Description
`GeoDataFrame`	As colunas publicadas e a geometria, com `.attrs["version"]`.

Examples:

>>> tis = condepe_layer("terras_indigenas")
>>> tis[["nome", "etnia", "fase", "area_ha"]]

Cache e configuração¶

`condepe.condepe_cache_dir()` ¶

Pasta do cache em disco (CONDEPE_CACHE_DIR a substitui).

`condepe.condepe_cache_clear()` ¶

Apaga todo o cache e devolve a pasta.

`condepe.set_timeout(seconds=60.0)` ¶

Define o tempo limite, em segundos, de cada requisição HTTP.

`condepe.set_verbose(verbose)` ¶

Liga ou desliga as mensagens informativas.

Erros¶

`condepe.CondepeError` ¶

Bases: RuntimeError

Classe base dos erros do condepe.

`condepe.HttpError` ¶

Bases: CondepeError

Nem o endereço canônico nem o espelho responderam.

`condepe.IntegrityError` ¶

Bases: CondepeError

Um arquivo baixado não confere com o SHA-256 do catálogo.

Referência das funções¶

Descobrir¶

condepe.condepe_catalog(refresh=False) ¶

condepe.condepe_indicators(source, refresh=False) ¶

condepe.condepe_localities(refresh=False) ¶

Obter os dados¶

condepe.condepe_series(source, indicator, code=None, years=None, refresh=False) ¶

condepe.condepe_data(source, refresh=False) ¶

Citar¶

condepe.condepe_cite(x=None) ¶

Mapas e regiões¶

condepe.condepe_geometry(level='municipio', source='condepe', quality='intermediaria', noronha=True, refresh=False) ¶

condepe.condepe_add_geometry(x, level='municipio', geometry=None, how='left', **kwargs) ¶

condepe.condepe_regions(level=None, refresh=False, offline=False) ¶

condepe.condepe_roads(type=None, refresh=False) ¶

condepe.condepe_hydrography(layer, refresh=False) ¶

condepe.condepe_layer(id, refresh=False) ¶

Cache e configuração¶

condepe.condepe_cache_dir() ¶

condepe.condepe_cache_clear() ¶

condepe.set_timeout(seconds=60.0) ¶

condepe.set_verbose(verbose) ¶

Erros¶

condepe.CondepeError ¶

condepe.HttpError ¶

condepe.IntegrityError ¶

`condepe.condepe_catalog(refresh=False)` ¶

`condepe.condepe_indicators(source, refresh=False)` ¶

`condepe.condepe_localities(refresh=False)` ¶

`condepe.condepe_series(source, indicator, code=None, years=None, refresh=False)` ¶

`condepe.condepe_data(source, refresh=False)` ¶

`condepe.condepe_cite(x=None)` ¶

`condepe.condepe_geometry(level='municipio', source='condepe', quality='intermediaria', noronha=True, refresh=False)` ¶

`condepe.condepe_add_geometry(x, level='municipio', geometry=None, how='left', **kwargs)` ¶

`condepe.condepe_regions(level=None, refresh=False, offline=False)` ¶

`condepe.condepe_roads(type=None, refresh=False)` ¶

`condepe.condepe_hydrography(layer, refresh=False)` ¶

`condepe.condepe_layer(id, refresh=False)` ¶

`condepe.condepe_cache_dir()` ¶

`condepe.condepe_cache_clear()` ¶

`condepe.set_timeout(seconds=60.0)` ¶

`condepe.set_verbose(verbose)` ¶

`condepe.CondepeError` ¶

`condepe.HttpError` ¶

`condepe.IntegrityError` ¶