pycancensus.visualize_vector_hierarchy

pycancensus.visualize_vector_hierarchy(vector: str | DataFrame, dataset: str | None = None, max_depth: int | None = None, show_type: bool = False, quiet: bool = False, use_cache: bool = True, api_key: str | None = None) → DataFrame[source]

Visualize a census vector hierarchy as an ASCII tree.

Displays the hierarchical structure of census vectors, helping users understand parent/child relationships when selecting variables. Mirrors R cancensus’s visualize_vector_hierarchy().

Parameters:

  • vector (str or pd.DataFrame) – A census vector code (e.g., “v_CA16_2510”) or a filtered DataFrame as returned by list_census_vectors().

  • dataset (str, optional) – The dataset to query. Only required if it cannot be inferred from the vector code.

  • max_depth (int, optional) – Maximum depth of the tree to display. Default shows the entire hierarchy. Nodes truncated by max_depth are marked with “…” rather than “(leaf)”.

  • show_type (bool, default False) – Show the type (Total/Male/Female) next to each vector.

  • quiet (bool, default False) – Suppress messages.

  • use_cache (bool, default True) – Whether to use cached data if available.

  • api_key (str, optional) – API key for CensusMapper API.

Returns:

The vectors displayed in the tree. The tree itself is printed to the console as a side effect.

Return type:

pd.DataFrame

Examples

>>> import pycancensus as pc
>>> pc.visualize_vector_hierarchy("v_CA16_2510")
>>> pc.visualize_vector_hierarchy("v_CA16_2510", max_depth=2, show_type=True)