pdstools.utils.streamlit_utils¶

Functions¶

`is_launcher_mode`(→ bool)	True when the app is running inside the cross-app launcher.
`set_active_app`(→ None)	Mark the named app as currently active in the launcher sidebar.
`standard_page_config`(page_title[, layout])	Apply a consistent `st.set_page_config` across all pdstools apps.
`show_sidebar_branding`(title)	Display the Pega logo and an app title at the top of the sidebar.
`show_version_header`([check_latest])	Display the pdstools version, an upgrade hint, and optionally a staleness warning.
`ensure_session_data`(key[, message])	Guard that stops page execution when key is missing from session state.
`get_data_path`(→ str \| None)	Return the data path set via `--data-path` CLI flag.
`get_sample_limit`(→ str \| None)	Return the raw sample limit string set via `--sample` CLI flag.
`get_filter_specs`(→ list[str] \| None)	Return the filter specs set via `--filter` CLI flags.
`get_temp_dir`(→ str \| None)	Return the temp directory set via `--temp-dir` CLI flag.
`get_full_embed`(→ bool \| None)	Return the full-embed setting set via `--full-embed` / `--no-full-embed` CLI flag.
`parse_sample_spec`(→ dict[str, int \| float])	Parse a `--sample` flag value into keyword arguments.
`get_current_index`(options, key[, default])	Get index from session state if key exists and value is in options, else return default.
`cached_sample`()	Cached sample.
`cached_datamart`(**kwargs)	Load ADMDatamart with caching.
`cached_sample_prediction`()	Cached sample prediction.
`cached_prediction_table`(**kwargs)	Load Prediction with caching.
`import_datamart`(extract_pyname_keys[, infer_schema_length])	Import ADMDatamart data from various sources.
`from_uploaded_file`(extract_pyname_keys, codespaces[, ...])	From uploaded file.
`from_file_path`(extract_pyname_keys, codespaces[, ...])	From file path.
`model_selection_df`(df, context_keys)	Model selection df.
`filter_dataframe`(→ polars.LazyFrame)	Adds a UI on top of a dataframe to let viewers filter columns
`model_and_row_counts`(df)	Returns unique model id count and row count from a dataframe
`configure_predictor_categorization`()	Configure predictor categorization.
`convert_df`(df)	Convert df.
`st_get_latest_pdstools_version`()	St get latest pdstools version.
`show_about_page`()	Render a standardised About page with version and dependency information.

Module Contents¶

is_launcher_mode() → bool¶

True when the app is running inside the cross-app launcher.

The CLI sets PDSTOOLS_LAUNCHER_MODE=1 when invoking the launcher so per-app helpers (sidebar branding, navigation) can adapt their behaviour without each call site needing to know.

Return type:: bool

set_active_app(app_key: str) → None¶

Mark the named app as currently active in the launcher sidebar.

Each app’s home page calls this on render. In launcher mode the cross-app entry script reads the flag to decide which app’s sub-pages to register in st.navigation, keeping the sidebar short until the user has actually entered an app. A no-op (other than the session_state write) in standalone tool launches.

Triggers st.rerun() when the active app actually changes so the new sub-pages appear in the sidebar without a manual click.

Parameters:: app_key (str)
Return type:: None

standard_page_config(page_title: str, layout: Literal['centered', 'wide'] = 'wide', **kwargs)¶

Apply a consistent st.set_page_config across all pdstools apps.

Idempotent: when called more than once in the same script run (e.g. an st.navigation() entry script calls it before routing, and the routed page calls it again), the second call is a no-op rather than the StreamlitAPIException Streamlit normally raises. This lets the same page module work both standalone (direct AppTest.from_file / streamlit run pages/X.py) and inside a navigation router.

Parameters:

page_title (str) – The browser-tab title for the page.
layout (str, default "wide") – Streamlit layout mode.
**kwargs – Extra keyword arguments forwarded to st.set_page_config.

show_sidebar_branding(title: str)¶

Display the Pega logo and an app title at the top of the sidebar.

Uses st.logo for the logo and CSS injection for the title, so both render above the page navigation. Call once from the Home page; sub-pages re-apply automatically via standard_page_config or ensure_data.

In launcher mode (PDSTOOLS_LAUNCHER_MODE=1) the brand is forced to "pdstools" and the supplied title is rendered as a subtitle, so every page in the multi-app launcher shows a consistent top-level brand even when the active sub-app re-applies its own title.

Parameters:: title (str) – Application title shown below the logo in the sidebar.

show_version_header(check_latest: bool = True)¶

Display the pdstools version, an upgrade hint, and optionally a staleness warning.

Parameters:: check_latest (bool, default True) – If True, queries PyPI for the latest version and shows an upgrade warning when the installed version is outdated.

ensure_session_data(key: str, message: str | None = None)¶

Guard that stops page execution when key is missing from session state.

Parameters:

key (str) – The st.session_state key to check.
message (str or None) – Custom warning text. Falls back to a generic “Please load data on the Home page.”

get_data_path() → str | None¶

Return the data path set via --data-path CLI flag.

Returns None when no path was configured.

Return type:: str | None

get_sample_limit() → str | None¶

Return the raw sample limit string set via --sample CLI flag.

Returns None when no sampling was requested.

Return type:: str | None

get_filter_specs() → list[str] | None¶

Return the filter specs set via --filter CLI flags.

Returns None when no filters were configured.

Return type:: list[str] | None

get_temp_dir() → str | None¶

Return the temp directory set via --temp-dir CLI flag.

Returns None when no temp directory was configured.

Return type:: str | None

get_full_embed() → bool | None¶

Return the full-embed setting set via --full-embed / --no-full-embed CLI flag.

Returns None when the flag was not provided (caller should apply its own default).

Return type:: bool | None

parse_sample_spec(value: str) → dict[str, int | float]¶

Parse a --sample flag value into keyword arguments.

Supports absolute counts ("100000"), percentages ("10%"), and human-readable notation ("100k", "1M").

Returns:: Either {"n": <int>} or {"fraction": <float>}.
Return type:: dict
Parameters:: value (str)

get_current_index(options, key, default=0)¶: Get index from session state if key exists and value is in options, else return default.

cached_sample()¶: Cached sample.

cached_datamart(**kwargs)¶

Load ADMDatamart with caching.

Parameters:: **kwargs – Arguments passed to ADMDatamart.from_ds_export

cached_sample_prediction()¶: Cached sample prediction.

cached_prediction_table(**kwargs)¶

Load Prediction with caching.

Parameters:: **kwargs – Arguments passed to Prediction.from_ds_export

import_datamart(extract_pyname_keys: bool, infer_schema_length: int = 10000)¶

Import ADMDatamart data from various sources.

Parameters:

extract_pyname_keys (bool) – Whether to extract additional keys from pyName column
infer_schema_length (int, default 10000) – Number of rows to scan for schema inference when reading CSV/JSON files. For large production datasets, increase this value (e.g., 200000) if columns are not being detected correctly.

from_uploaded_file(extract_pyname_keys, codespaces, infer_schema_length=10000)¶: From uploaded file.

from_file_path(extract_pyname_keys, codespaces, infer_schema_length=10000)¶: From file path.

model_selection_df(df: polars.LazyFrame, context_keys: list)¶

Model selection df.

Parameters:

df (polars.LazyFrame)
context_keys (list)

filter_dataframe(df: polars.LazyFrame, schema: dict | None = None, queries: list | None = None) → polars.LazyFrame¶

Adds a UI on top of a dataframe to let viewers filter columns

Parameters:

df (pl.DataFrame) – Original dataframe
schema (dict | None)
queries (list | None)

Returns:

The filtered LazyFrame

Return type:

pl.LazyFrame

model_and_row_counts(df: pdstools.utils.types.ANY_FRAME)¶

Returns unique model id count and row count from a dataframe

Parameters:: df (Union[pl.DataFrame, pl.LazyFrame]) – The input dataframe
Returns:: unique model count row count
Return type:: Tuple[int, int]

configure_predictor_categorization()¶: Configure predictor categorization.

convert_df(df)¶: Convert df.

st_get_latest_pdstools_version()¶: St get latest pdstools version.

show_about_page()¶

Render a standardised About page with version and dependency information.

Mirrors the Credits section of the Quarto ADM Health Check report. Call this from a Streamlit page to display pdstools version info, platform details, and an expandable dependency listing.