healthbR (version 0.2.0)

ans_data: Download ANS Data

Description

Downloads and returns data from the ANS (Agencia Nacional de Saude Suplementar) open data portal. Supports three data types: beneficiary counts, consumer complaints (NIP), and financial statements.

Usage

ans_data(
  year,
  type = "beneficiaries",
  uf = NULL,
  month = NULL,
  quarter = NULL,
  vars = NULL,
  cache = TRUE,
  cache_dir = NULL,
  lazy = FALSE,
  backend = c("arrow", "duckdb")
)

Value

A tibble with ANS data. Includes partition columns: year (all types), month and uf_source

(beneficiaries), quarter (financial).

Arguments

year

Integer. Year(s) of the data. Required.

type

Character. Type of data. One of:

• "beneficiaries": Consolidated beneficiary counts (default). Uses year, month, uf parameters.

• "complaints": Consumer complaints via NIP. Uses year only (national data).

• "financial": Financial statements. Uses year, quarter parameters.

uf

Character. Two-letter state abbreviation(s). Only used for type = "beneficiaries". Includes "XX" for unidentified beneficiaries. If NULL (default), downloads all 27 states.

month

Integer. Month(s) 1-12. Only used for type = "beneficiaries". If NULL (default), downloads all months. Note: 2019 starts at month 4 (April).

quarter

Integer. Quarter(s) 1-4. Only used for type = "financial". If NULL (default), downloads all 4 quarters.

vars

Character vector. Variables to keep. If NULL (default), returns all available variables. Use ans_variables() to see available variables per type.

cache

Logical. If TRUE (default), caches downloaded data for faster future access.

cache_dir

Character. Directory for caching. Default: tools::R_user_dir("healthbR", "cache").

lazy

Logical. If TRUE, returns a lazy query object instead of a tibble. Requires the arrow package. Default: FALSE.

backend

Character. Backend for lazy evaluation: "arrow" (default) or "duckdb". Only used when lazy = TRUE.

Details

Data is downloaded from the ANS open data portal at https://dadosabertos.ans.gov.br/.

Beneficiaries: Monthly per-state ZIP files containing CSV data with consolidated beneficiary counts by operator, plan type, sex, age group, and municipality. Available from April 2019.

Complaints: Annual national CSV files with consumer complaints filed through the NIP (Notificacao de Intermediacao Preliminar). Available from 2011.

Financial: Quarterly ZIP files with financial statements of health plan operators (balance sheets, income statements). Available from 2007.

See Also

ans_operators() for the operator registry, ans_variables() for variable descriptions.

Other ans: ans_cache_status(), ans_clear_cache(), ans_info(), ans_operators(), ans_variables(), ans_years()

Examples

if (FALSE) { # interactive()
# beneficiary counts for Acre, December 2023
ac <- ans_data(year = 2023, month = 12, uf = "AC")

# consumer complaints for 2022
nip <- ans_data(year = 2022, type = "complaints")

# financial statements Q1 2023
fin <- ans_data(year = 2023, type = "financial", quarter = 1)
}