Fetch Rolling Quarter Series from SIDRA

Downloads PNADC labor market indicators from IBGE's SIDRA API. These series are published as rolling quarterly averages (trimestre movel), with 12 observations per year.

Usage

fetch_sidra_rolling_quarters(
  series = "all",
  theme = NULL,
  theme_category = NULL,
  subcategory = NULL,
  exclude_derived = FALSE,
  use_cache = FALSE,
  verbose = TRUE,
  retry_failed = TRUE,
  max_retries = 3
)

Arguments

series: Character vector of series names to fetch, or "all" (default) for all available series. Use get_sidra_series_metadata()$series_name to see available names.
theme: Character vector of themes to filter by. Valid options: "labor_market", "earnings", "demographics", "social_protection", "prices". Use NULL for no filter.
theme_category: Character vector of theme categories to filter by. Use NULL for no filter.
subcategory: Character vector of subcategories to filter by. Use NULL for no filter.
exclude_derived: Logical. If TRUE, exclude series marked as derived (is_derived = TRUE in metadata). Default FALSE for backward compatibility. Derived series (rates) are computed from other series during mensalization, so excluding them saves API calls when fetching for mensalization.
use_cache: Logical. Use cached data if available? Default FALSE. When TRUE, shows the date when data was cached (may be outdated). Use clear_sidra_cache to force fresh download.
verbose: Logical. Print progress messages? Default TRUE.
retry_failed: Logical. Retry failed series downloads? Default TRUE.
max_retries: Integer. Maximum retry attempts per series. Default 3.

Value

A data.table with columns:

anomesfinaltrimmovel: Integer. YYYYMM of rolling quarter end month
mesnotrim: Integer. Month position in quarter (1, 2, or 3)
<series_name>: Numeric. One column per requested series

Details

Rolling quarters are labeled by their ending month:

201201 = Nov 2011 - Jan 2012 (mesnotrim = 1)
201202 = Dec 2011 - Feb 2012 (mesnotrim = 2)
201203 = Jan - Mar 2012 (mesnotrim = 3)
201204 = Feb - Apr 2012 (mesnotrim = 1)
etc.

The mesnotrim column indicates the month's position within its rolling quarter, which is essential for the mensalization algorithm.

Rate Limiting

SIDRA API may have rate limits. The function includes automatic retry logic with exponential backoff for failed requests.

Internet Resource Behaviour

Per CRAN policy, this function fails gracefully when the SIDRA API is unreachable: it emits an informative message() (no warning, no error) and returns NULL invisibly when no series could be fetched. Partial failures (some series succeeded) are also reported via message(), and the result includes only the successful series.

Examples

# \donttest{
rq <- fetch_sidra_rolling_quarters(
  series = c("taxadesocup", "popocup", "popdesocup")
)
#> Fetching 3 series from SIDRA API...
#> This may take a few minutes on first run.
#>   [ 33%] Fetching popocup...
#>   [ 67%] Fetching popdesocup...
#>   [100%] Fetching taxadesocup...
#> Successfully fetched 3/3 series
#>   Rolling quarters: 201203 to 202603 (169 observations)
head(rq)
#> Key: <anomesfinaltrimmovel>
#>    anomesfinaltrimmovel mesnotrim popocup popdesocup taxadesocup
#>                   <int>     <num>   <num>      <num>       <num>
#> 1:               201203         3   87713       7613         8.0
#> 2:               201204         1   88535       7493         7.8
#> 3:               201205         2   89059       7403         7.7
#> 4:               201206         3   89318       7319         7.6
#> 5:               201207         1   89445       7245         7.5
#> 6:               201208         2   89732       7116         7.3
# }

# \donttest{
rq_labor <- fetch_sidra_rolling_quarters(theme = "labor_market")
#> Fetching 46 series from SIDRA API...
#> This may take a few minutes on first run.
#>   [  2%] Fetching taxapartic...
#>   [  4%] Fetching nivelocup...
#>   [  7%] Fetching niveldesocup...
#>   [  9%] Fetching popnaforca...
#>   [ 11%] Fetching popocup...
#>   [ 13%] Fetching popdesocup...
#>   [ 15%] Fetching popforadaforca...
#>   [ 17%] Fetching taxadesocup...
#>   [ 20%] Fetching perccontribprev...
#>   [ 22%] Fetching taxacombdesosub...
#>   [ 24%] Fetching taxacombdesopot...
#>   [ 26%] Fetching taxacompsubutlz...
#>   [ 28%] Fetching taxasubocuphoras...
#>   [ 30%] Fetching percdesalento...
#>   [ 33%] Fetching subocuphoras...
#>   [ 35%] Fetching forcapotencial...
#>   [ 37%] Fetching forcaampliada...
#>   [ 39%] Fetching desalentado...
#>   [ 41%] Fetching empregado...
#>   [ 43%] Fetching empregpriv...
#>   [ 46%] Fetching empregprivcomcart...
#>   [ 48%] Fetching empregprivsemcart...
#>   [ 50%] Fetching empregpubl...
#>   [ 52%] Fetching empregpublcomcart...
#>   [ 54%] Fetching empregpublsemcart...
#>   [ 57%] Fetching estatutmilitar...
#>   [ 59%] Fetching domestico...
#>   [ 61%] Fetching domesticocomcart...
#>   [ 63%] Fetching domesticosemcart...
#>   [ 65%] Fetching empregador...
#>   [ 67%] Fetching empregadorcomcnpj...
#>   [ 70%] Fetching empregadorsemcnpj...
#>   [ 72%] Fetching contapropria...
#>   [ 74%] Fetching contapropriacomcnpj...
#>   [ 76%] Fetching contapropriasemcnpj...
#>   [ 78%] Fetching trabfamauxiliar...
#>   [ 80%] Fetching agropecuaria...
#>   [ 83%] Fetching industria...
#>   [ 85%] Fetching construcao...
#>   [ 87%] Fetching comercio...
#>   [ 89%] Fetching transporte...
#>   [ 91%] Fetching alojaliment...
#>   [ 93%] Fetching infcomfinimobadm...
#>   [ 96%] Fetching adminpublica...
#>   [ 98%] Fetching outroservico...
#>   [100%] Fetching servicodomestico...
#> Successfully fetched 46/46 series
#>   Rolling quarters: 201203 to 202603 (169 observations)
# }