Auxiliary

auxiliary

Auxiliary data functions and convenience wrappers.

get_aux(table=None, version=None, ppp_version=None, release_version=None, api_version=API_VERSION, fmt='json', simplify=True, server=None, dataframe_type='pandas', assign_tb=False, replace=False)

Fetch an auxiliary dataset from the PIP API.

When no table is specified, returns a list of available table names. Mirrors pipr::get_aux().

Parameters:

Name	Type	Description	Default
table	str | None	Auxiliary table name (e.g. "gdp", "cpi"). If None, returns a list of available table names.	None
version	str | None	Data version string.	None
ppp_version	int | None	PPP base year.	None
release_version	str | None	Release date in YYYYMMDD format.	None
api_version	str	API version.	API_VERSION
fmt	str	Response format — "json" (default) or "csv". Arrow is not supported for auxiliary tables.	'json'
simplify	bool	If True (default), return a DataFrame.	True
server	str | None	Server target.	None
dataframe_type	Literal['pandas', 'polars']	"pandas" (default) or "polars".	'pandas'
assign_tb	bool | str	If False (default), return data normally. If True, store the table in memory under its own name. If a string, store it under that name.	False
replace	bool	If True, overwrite existing in-memory tables.	False

Returns:

Type	Description
DataFrame | list[str] | PIPResponse | bool	A list[str] of table names when table is None.
DataFrame | list[str] | PIPResponse | bool	A :class:~pandas.DataFrame when simplify is True.
DataFrame | list[str] | PIPResponse | bool	A :class:~povineq._response.PIPResponse when simplify is False.
DataFrame | list[str] | PIPResponse | bool	True when assign_tb is set and the table was stored.

Example

import povineq tables = povineq.get_aux() # list of available tables df = povineq.get_aux("gdp") # fetch GDP table povineq.get_aux("cpi", assign_tb=True) # fetch and store in memory

Source code in src/povineq/auxiliary.py

def get_aux(
    table: str | None = None,
    version: str | None = None,
    ppp_version: int | None = None,
    release_version: str | None = None,
    api_version: str = API_VERSION,
    fmt: str = "json",
    simplify: bool = True,
    server: str | None = None,
    dataframe_type: Literal["pandas", "polars"] = "pandas",
    assign_tb: bool | str = False,
    replace: bool = False,
) -> pd.DataFrame | list[str] | PIPResponse | bool:
    """Fetch an auxiliary dataset from the PIP API.

    When no *table* is specified, returns a list of available table names.
    Mirrors ``pipr::get_aux()``.

    Args:
        table: Auxiliary table name (e.g. ``"gdp"``, ``"cpi"``). If ``None``,
            returns a list of available table names.
        version: Data version string.
        ppp_version: PPP base year.
        release_version: Release date in ``YYYYMMDD`` format.
        api_version: API version.
        fmt: Response format — ``"json"`` (default) or ``"csv"``.
            Arrow is not supported for auxiliary tables.
        simplify: If ``True`` (default), return a DataFrame.
        server: Server target.
        dataframe_type: ``"pandas"`` (default) or ``"polars"``.
        assign_tb: If ``False`` (default), return data normally. If ``True``,
            store the table in memory under its own name. If a string, store
            it under that name.
        replace: If ``True``, overwrite existing in-memory tables.

    Returns:
        - A ``list[str]`` of table names when *table* is ``None``.
        - A :class:`~pandas.DataFrame` when *simplify* is ``True``.
        - A :class:`~povineq._response.PIPResponse` when *simplify* is ``False``.
        - ``True`` when *assign_tb* is set and the table was stored.

    Example:
        >>> import povineq
        >>> tables = povineq.get_aux()          # list of available tables
        >>> df = povineq.get_aux("gdp")         # fetch GDP table
        >>> povineq.get_aux("cpi", assign_tb=True)  # fetch and store in memory
    """
    params = AuxParams(
        table=table,
        version=version,
        ppp_version=ppp_version,
        release_version=release_version,
        api_version=api_version,
        format=fmt,
    )

    if table is None:
        # Return list of available tables
        query: dict[str, str] = {}
        if version is not None:
            query["version"] = version
        if release_version is not None:
            query["release_version"] = release_version

        response = build_and_execute(ENDPOINT_AUX, query, server=server, api_version=api_version)
        result = parse_response(response, simplify=simplify, dataframe_type=dataframe_type)

        if simplify and isinstance(result, pd.DataFrame) and "tables" in result.columns:
            # pd.json_normalize packs {"tables": [...]} into a single-row df;
            # the cell value is the list itself — unwrap it when needed.
            raw = result["tables"].iloc[0]
            tables_list: list[str] = raw if isinstance(raw, list) else result["tables"].tolist()
            logger.info("Available auxiliary tables", tables=tables_list)
            return tables_list

        return result  # type: ignore[return-value]

    # Fetch specific table
    query = params.to_query_params()
    query.pop("api_version", None)

    response = build_and_execute(ENDPOINT_AUX, query, server=server, api_version=api_version)
    rt = parse_response(response, simplify=simplify, dataframe_type=dataframe_type)

    if assign_tb is not False:
        tb_name: str
        if assign_tb is True:
            tb_name = table
        elif isinstance(assign_tb, str):
            tb_name = assign_tb
        else:
            raise ValueError("assign_tb must be a bool or a string.")

        if not isinstance(rt, pd.DataFrame):
            logger.warning(
                "assign_tb requires simplify=True to store the table in memory; "
                "got a PIPResponse object. The table was NOT stored."
            )
        elif isinstance(rt, pd.DataFrame):
            return set_aux(tb_name, rt, replace=replace)

    return rt  # type: ignore[return-value]

display_aux(version=None, ppp_version=None, release_version=None, api_version=API_VERSION, fmt='json', simplify=True, server=None)

Display available auxiliary tables.

Fetches the list of auxiliary tables and prints them. Mirrors pipr::display_aux().

Parameters:

Name	Type	Description	Default
version	str | None	Data version string.	None
ppp_version	int | None	PPP base year.	None
release_version	str | None	Release date in YYYYMMDD format.	None
api_version	str	API version.	API_VERSION
fmt	str	Response format.	'json'
simplify	bool	Passed to :func:get_aux.	True
server	str | None	Server target.	None

Returns:

Type	Description
DataFrame | list[str]	List of available table name strings.

Example

import povineq povineq.display_aux()

Source code in src/povineq/auxiliary.py

def display_aux(
    version: str | None = None,
    ppp_version: int | None = None,
    release_version: str | None = None,
    api_version: str = API_VERSION,
    fmt: str = "json",
    simplify: bool = True,
    server: str | None = None,
) -> pd.DataFrame | list[str]:
    """Display available auxiliary tables.

    Fetches the list of auxiliary tables and prints them. Mirrors
    ``pipr::display_aux()``.

    Args:
        version: Data version string.
        ppp_version: PPP base year.
        release_version: Release date in ``YYYYMMDD`` format.
        api_version: API version.
        fmt: Response format.
        simplify: Passed to :func:`get_aux`.
        server: Server target.

    Returns:
        List of available table name strings.

    Example:
        >>> import povineq
        >>> povineq.display_aux()
    """
    result = get_aux(
        table=None,
        version=version,
        ppp_version=ppp_version,
        release_version=release_version,
        api_version=api_version,
        fmt=fmt,
        simplify=simplify,
        server=server,
    )

    if isinstance(result, list):
        logger.info("Available auxiliary tables", tables=result)
        return result

    return result  # type: ignore[return-value]

call_aux(table=None)

Retrieve a previously stored auxiliary table from memory.

Mirrors pipr::call_aux().

Parameters:

Name	Type	Description	Default
table	str | None	Table name to retrieve. If None, lists all stored tables.	None

Returns:

Type	Description
DataFrame | list[str]	The stored DataFrame, or a list of stored table names.

Raises:

Type	Description
KeyError	If the requested table is not in the store.

Example

import povineq povineq.get_aux("gdp", assign_tb=True) df = povineq.call_aux("gdp")

Source code in src/povineq/auxiliary.py

def call_aux(table: str | None = None) -> pd.DataFrame | list[str]:
    """Retrieve a previously stored auxiliary table from memory.

    Mirrors ``pipr::call_aux()``.

    Args:
        table: Table name to retrieve. If ``None``, lists all stored tables.

    Returns:
        The stored DataFrame, or a list of stored table names.

    Raises:
        KeyError: If the requested table is not in the store.

    Example:
        >>> import povineq
        >>> povineq.get_aux("gdp", assign_tb=True)
        >>> df = povineq.call_aux("gdp")
    """
    return _call_aux_store(table)