hbsir.api.load_table
Load a table for the given table name and year(s).
This function loads original survey tables as well as package tables defined in this library.
Original survey tables are available in three forms:
- 'raw' - Contains the raw survey data without any modifications
- 'cleaned' - Raw data with added labels, types, removed irrelevant values, but no changes to actual data
- 'normalized' - Standardized data form with consistent column names, value encodings and table structure applied across data from multiple survey years. Also adds useful metadata like table name and year identifiers.
Package tables are defined in this library to facilitate working with the data and are only available in normalized form.
For more details on available tables, see the documentation tables page.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
table_name |
_Table
|
The name of the table to load. |
"data"
|
years |
_Years
|
The years of data to load. |
"last"
|
form |
(normalized, cleaned, raw)
|
The form of the data to load. Options are "normalized", "cleaned", or "raw". |
"normalized"
|
Note
The years parameter accepts different input types:
- int: A single year integer like 1390 or 90
- list[int]: A list of integer years [1390, 1395, 1400]
- str: A hyphenated string range like '1390-1395'
- "all": A string indicating all available years
- "last": A string indicating only the most recent year
Other Parameters:
| Name | Type | Description |
|---|---|---|
on_missing |
(download, create, error)
|
Behavior if table is missing. "download" downloads the table, "create" generates table from raw data, "error" raises an exception. |
redownload |
bool
|
Whether to re-download table if it exists. |
save_downloaded |
bool
|
Whether to save newly downloaded data. |
recreate |
bool
|
Whether to recreate table if it exists. |
save_created |
bool
|
Whether to save newly created data. |
Returns:
| Type | Description |
|---|---|
DataFrame
|
Loaded table as a pandas DataFrame. |
Raises:
| Type | Description |
|---|---|
FileNotFoundError
|
If data is missing and on_missing='error'. |
Examples: