pytidycensus.variables

Census variable loading and caching functionality.

Functions

`clear_cache`([cache_dir])	Clear the variables cache.
`get_table_variables`(table, year, dataset[, ...])	Get all variables for a specific table.
`list_available_datasets`(year)	List available datasets for a given year.
`load_variables`(year[, dataset, survey, ...])	Load Census variables for a given dataset and year.
`search_variables`(pattern, year, dataset[, ...])	Search for variables by pattern in labels, concepts, or names.

pytidycensus.variables.load_variables(year, dataset=None, survey=None, cache=True, cache_dir=None)[source]

Load Census variables for a given dataset and year.

Parameters:

year (int) – Census year
dataset (str, optional) – Dataset name (‘acs’, ‘dec’, ‘pep’, etc.). Provide either dataset or survey.
survey (str, optional) – Survey type (e.g., ‘acs5’, ‘acs1’, ‘sf1’, ‘pl’). If provided, the dataset will be inferred from the survey. Provide either dataset or survey, not both.
cache (bool, default True) – Whether to cache variables for faster future access
cache_dir (str, optional) – Directory for caching. Defaults to user cache directory.

Returns:

Variables with columns: name, label, concept, predicateType, group, limit

Return type:

pd.DataFrame

Examples

>>> # Load ACS 5-year variables for 2022
>>> acs_vars = load_variables(2022, "acs", "acs5")
>>>
>>> # Search for income-related variables
>>> income_vars = acs_vars[acs_vars['label'].str.contains('income', case=False)]
>>>
>>> # Load decennial census variables for 2020
>>> dec_vars = load_variables(2020, "dec", "pl")

pytidycensus.variables.search_variables(pattern, year, dataset, survey=None, field='concept')[source]

Search for variables by pattern in labels, concepts, or names.

Parameters:

pattern (str) – Search pattern (case-insensitive)
year (int) – Census year
dataset (str, optional) – Dataset name (‘acs’, ‘dec’, ‘pep’, etc.). Provide either dataset or survey.
survey (str, optional) – Survey type (e.g., ‘acs5’, ‘acs1’, ‘sf1’, ‘pl’). If provided, the dataset will be inferred from the survey. Provide either dataset or survey, not both.
field (str, default "label") – Field to search in (‘label’, ‘concept’, ‘name’, or ‘all’)

Returns:

Matching variables

Return type:

pd.DataFrame

Examples

>>> # Search for income variables in ACS
>>> income_vars = search_variables("income", 2022, "acs", "acs5")
>>>
>>> # Search for population in concepts
>>> pop_vars = search_variables("population", 2020, "dec", "pl", field="concept")

pytidycensus.variables.get_table_variables(table, year, dataset, survey=None)[source]

Get all variables for a specific table.

Parameters:

table (str) – Table code (e.g., ‘B19013’, ‘P1’)
year (int) – Census year
dataset (str) – Dataset name
survey (str, optional) – Survey type

Returns:

Variables for the specified table

Return type:

pd.DataFrame

Examples

>>> # Get all variables for median household income table
>>> b19013_vars = get_table_variables("B19013", 2022, "acs", "acs5")
>>>
>>> # Get all variables for race table in 2020 Census
>>> p1_vars = get_table_variables("P1", 2020, "dec", "pl")

pytidycensus.variables.clear_cache(cache_dir=None)[source]

Clear the variables cache.

Parameters:: cache_dir (str, optional) – Cache directory to clear. Defaults to user cache directory.
Return type:: None

pytidycensus.variables.list_available_datasets(year)[source]

List available datasets for a given year.

Parameters:: year (int) – Census year
Returns:: Available datasets and their surveys
Return type:: Dict[str, list]