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"
|
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: