pdstools.adm.Aggregates¶
Classes¶
Aggregates. |
Module Contents¶
- class Aggregates(datamart: pdstools.adm.ADMDatamart.ADMDatamart)¶
Aggregates.
- Parameters:
datamart (pdstools.adm.ADMDatamart.ADMDatamart)
- datamart¶
- last(*, data: polars.LazyFrame | None = None, table: Literal['model_data', 'predictor_data', 'combined_data'] = 'model_data') polars.LazyFrame¶
Gets the last snapshot of the given table
This method filters the data to include only the rows from the most recent snapshot time.
- Parameters:
data (Optional[pl.LazyFrame], optional) – If provided, subsets to just that dataframe, by default None
table (Literal['model_data', 'predictor_data', 'combined_data'], optional) – If provided, specifies the table to get data from, by default “model_data”
- Returns:
A LazyFrame containing only the rows from the most recent snapshot time
- Return type:
pl.LazyFrame
- predictor_performance_pivot(*, query: pdstools.utils.types.QUERY | None = None, active_only: bool = False, by='Name', top_predictors: int | None = None, top_groups: int | None = None) polars.LazyFrame¶
Creates a pivot table of the predictor performance per ‘group’
- Parameters:
query (Optional[QUERY], optional) – A query to apply to the data before creating the pivot, by default None
active_only (bool, optional) – Whether to only include predictors with EntryType “Active”. When False, all non-classifier predictors are included, by default False
by (str, optional) – A group by which to ‘facet’, by default “Name”. If, for instance, the ‘by’ argument is set to ‘Configuration’, each row will be a distinct configuration
top_predictors (Optional[int], optional) – Specify the maximum number of predictors, by default None
top_groups (Optional[int], optional) – Specify the maximum number of ‘groups’ specified in the ‘by’ argument, by default None
- Returns:
A LazyFrame with a column for each predictor, and a row for each ‘group’. The values represent the weighted performance for that predictor
- Return type:
pl.LazyFrame
- model_summary(by: str = 'Name', query: pdstools.utils.types.QUERY | None = None) polars.LazyFrame¶
Summarize the latest model snapshot along the context hierarchy.
This aggregation backs
pdstools.adm.Plots.Plots.tree_map()and can also be used directly to compare model counts, response volumes, success rates, and performance across context groups. Grouping includes each context key up to and includingby.- Parameters:
- Returns:
A LazyFrame with one row per context-key combination. Includes model counts, response and positive totals/means/maxima, weighted success rate and performance, and percentage of models without responses.
- Return type:
pl.LazyFrame
- summary_by_channel(*, query: pdstools.utils.types.QUERY | None = None, start_date: datetime.datetime | None = None, end_date: datetime.datetime | None = None, window: int | datetime.timedelta | None = None, every: str | None = None, custom_channels: dict[str, str] | None = None, debug: bool = False, format_flags: bool = False) polars.LazyFrame¶
Summarize ADM models per channel
- Parameters:
query (Optional[QUERY], optional) – A query to apply to the data, by default None, so no filtering applied
start_date (datetime.datetime, optional) – Start date of the summary period. If None (default) uses the end date minus the window, or if both absent, the earliest date in the data
end_date (datetime.datetime, optional) – End date of the summary period. If None (default) uses the start date plus the window, or if both absent, the latest date in the data
window (int or datetime.timedelta, optional) – Number of days to use for the summary period or an explicit timedelta. If None (default) uses the whole period. Can’t be given if start and end date are also given.
every (str, optional) – Optional additional grouping by time period. Format string as in polars.Expr.dt.truncate (https://docs.pola.rs/api/python/stable/reference/expressions/api/polars.Expr.dt.truncate.html), for example “1mo”, “1w”, “1d” for calendar month, week day. Defaults to None.
custom_channels (dict[str, str], optional) – Optional dictionary mapping custom channel names to standard channel groups. Defaults to None.
debug (bool, default False) –
If True, include diagnostic columns (ResponseCount, Positives) in output. If False, these intermediate calculation columns are dropped from the results.
This parameter affects the return value structure, not logging output. For debug logging, use logging.basicConfig(level=logging.DEBUG).
format_flags (bool, default False) – If True, format boolean flag columns (usesNBAD, usesAGB) as “Yes”/”No”/”?” strings for display in reports. If False, keeps original boolean/null values.
- Returns:
Dataframe with summary per channel (and optionally a period) with the following fields:
Channel Identification: - Channel - The channel name - Direction - The direction (e.g., Inbound, Outbound) - ChannelDirection - Combined Channel/Direction (e.g., “Web/Inbound”) - ChannelDirectionGroup - Standardized channel group with direction (e.g., “Web/Inbound”)
Time and Configuration Fields: - DateRange Min - The minimum date in the summary time range - DateRange Max - The maximum date in the summary time range - Duration - The duration in seconds between the minimum and maximum snapshot times - Configuration - A comma-separated list of model configuration names
Performance Metrics: - Positives - The sum of positive responses across all models in the channel - Responses - The sum of all responses across all models in the channel - Performance - The weighted average performance across all models in the channel (50-100) - CTR - Click-through rate (Positives / Responses) in the channel - isValid - Boolean indicating if the channel has sufficient data (at least 200 positives and 1000 responses)
Action Statistics: - Actions - The total number of unique actions in the channel - Used Actions - The number of unique actions that have been used (have responses) - New Actions - The number of new actions introduced in the period - Issues - The number of unique issues - Groups - The number of unique issue/group combinations
Treatment Statistics: - Treatments - The total number of unique treatments - Used Treatments - The number of unique treatments
Omnichannel Metrics: - OmniChannel - The overlap of actions with other channels (measure of Omni Channel capability)
Technology Usage Indicators: - usesNBAD - Boolean indicating whether any standard NBAD configurations are used - usesAGB - Boolean indicating whether any Adaptive Generic Boosting (AGB) models are used - AGB Configurations - Comma-separated names of the configurations that contain AGB models (empty if none)
- Return type:
pl.LazyFrame
- channel_overview(*, query: pdstools.utils.types.QUERY | None = None) polars.DataFrame¶
Return the display-ready channel overview table.
- Parameters:
query (pdstools.utils.types.QUERY | None)
- Return type:
polars.DataFrame
- summary_by_configuration(*, query: pdstools.utils.types.QUERY | None = None) polars.LazyFrame¶
Generates a summary of the ADM model configurations.
This method provides an overview of model configurations, including information about the number of models, actions, treatments, and performance metrics.
- Parameters:
query (Optional[QUERY], optional) – A query to apply to the data, by default None, so no filtering applied
- Returns:
A Polars LazyFrame containing the configuration summary with the following fields:
Configuration Information: - Configuration - The name of the model configuration - Channel - The channel name (if available in context keys) - Direction - The direction (if available in context keys)
Model Information: - ModelID - The number of unique model IDs for this configuration
Action Statistics: - Actions - The number of unique actions in this configuration - Unique Treatments - The number of unique treatments (if available) - Used for (Issues) - A comma-separated list of issues this configuration is used for (if available)
Performance Metrics: - ResponseCount - The total number of responses for this configuration - Positives - The total number of positive responses for this configuration - ModelsPerAction - The ratio of models to actions (models per action) - Performance - The weighted average model performance
Technology Usage Indicators: - usesNBAD - Boolean indicating whether any standard NBAD configurations are used - usesAGB - Boolean indicating whether any Adaptive Generic Boosting (AGB) models are used
- Return type:
pl.LazyFrame
- configuration_overview(*, query: pdstools.utils.types.QUERY | None = None) polars.DataFrame¶
Return the display-ready configuration overview table.
- Parameters:
query (pdstools.utils.types.QUERY | None)
- Return type:
polars.DataFrame
- predictors_global_overview(*, query: pdstools.utils.types.QUERY | None = None) polars.LazyFrame¶
Generate a global overview of all predictors across all models.
This method provides a summary of predictor performance and characteristics across all models, including the number of responses, positives, and performance metrics.
- Parameters:
query (Optional[QUERY], optional) – A query to apply to the data, by default None, so no filtering applied
- Returns:
A Polars LazyFrame containing the global predictor overview with the following fields:
PredictorName - The name of the predictor
Response Count Min/Max - The total number of responses for this predictor
Positives - The total number of positive responses for this predictor
Min, Mean, Median, Max - The min, mean, median and max performance of the predictor (AUC)
- Return type:
pl.LazyFrame
- global_predictor_overview(*, query: pdstools.utils.types.QUERY | None = None) polars.DataFrame¶
Return the display-ready global predictor overview table.
- Parameters:
query (pdstools.utils.types.QUERY | None)
- Return type:
polars.DataFrame
- predictors_overview(model_id: str | None = None, additional_aggregations: list | None = None) polars.LazyFrame | None¶
Generate a summary of the last snapshot of predictor data.
This method provides an overview of predictor performance and characteristics from the most recent snapshot, either for all models or for a specific model.
- Parameters:
model_id (Optional[str], optional) – If provided, filters the data to include only predictors for the specified model ID. If None (default), includes predictors for all models.
additional_aggregations (Optional[list], optional) – Additional aggregation expressions to include in the result. These will be added to the default aggregations.
- Returns:
A Polars LazyFrame containing the predictor summary with the following fields:
Identification: - ModelID - The model ID (only if model_id parameter is None) - PredictorName - The name of the predictor
Status and Type: - EntryType - The entry type (Active, Inactive, etc.) - isActive - Boolean indicating if the predictor is active - Type - The predictor type - GroupIndex - The group index of the predictor
Performance Metrics: - Responses - The number of responses for this predictor - Positives - The number of positive responses for this predictor - Univariate Performance - The univariate performance of the predictor (AUC)
Binning Information: - Bins - The number of bins for this predictor - Missing % - The percentage of responses in the MISSING bin - Residual % - The percentage of responses in the RESIDUAL bin
Returns None if the required data is not available or an error is encountered.
- Return type:
pl.LazyFrame or None
- success_rate_intervals(*, confidence_level: float = 0.95, query: pdstools.utils.types.QUERY | None = None) polars.LazyFrame¶
Success rate of each model with a Wilson confidence interval.
Every model (last snapshot) is compared to the average success rate of the models in its own channel and direction (total positives over total responses), as base rates differ widely between channels. It is classified by its confidence interval, without any assumption on the model names. Without
ChannelandDirectioncolumns all models in scope are compared to one average.- Parameters:
- Returns:
One row per model with, next to the descriptive columns that exist in the data,
Positives,Negatives,ResponseCount,SuccessRate,SuccessRate_CI_Lower,SuccessRate_CI_Upper,AverageSuccessRateandSuccessRateCategory. The category is one of:Very low: the whole interval is below a tenth of the averageBelow average: the whole interval is below the averageAbove average: the whole interval is above the averageConsistent with average: the interval contains the average
Models without responses are left out.
- Return type:
pl.LazyFrame
- naming_review(*, columns: tuple[str, Ellipsis] = NAMING_COLUMNS, query: pdstools.utils.types.QUERY | None = None) polars.LazyFrame¶
Completeness and cleanliness of the model identifier columns.
- Parameters:
- Returns:
One row per reviewed column with
Column,Distinct Values(non-empty values),Models with Empty Value(null, empty or whitespace only),Values with Hidden CharactersandModels with Hidden Characters. Hidden characters are invisible characters such as zero-width or non-breaking spaces and leading or trailing whitespace; seehidden_character_names()for the values themselves.- Return type:
pl.LazyFrame
Model identifiers that contain invisible or control characters.
Zero-width spaces, non-breaking spaces, control characters and leading or trailing whitespace are invisible in most tools, so two names that look identical can be different values. When presentations and responses are recorded under such lookalikes they end up on different models.
- Parameters:
- Returns:
One row per affected value with
Column,Value(shown quoted with the hidden characters spelled out as[U+XXXX]),Hidden Characters(what is hidden in the value),Cleaned(the value without hidden characters, also quoted),Models(number of models with this value) andName Clashes(number of models that have the cleaned value). A non-zero clash count means the data holds two values that appear identical.- Return type:
pl.LazyFrame
- unused_agb_predictors(*, query: pdstools.utils.types.QUERY | None = None) polars.LazyFrame¶
Find predictors with zero importance in every trained AGB model.
Use the same configuration-level (global) importance as
predictor_importance(), including when identifying trained models. Models with no positive total importance are excluded. Missing predictor importance is treated as zero within trained models.- Parameters:
query (QUERY, optional) – Restrict the models in scope, for example to active models or a configuration. Only GradientBoost models are included.
- Returns:
PredictorName, PredictorCategory, Configurations, Response Count Min and Response Count Max for unused predictors, sorted by configuration count descending and predictor name ascending.
- Return type:
pl.LazyFrame
- Raises:
ValueError – If the data has no predictor importance.
- predictor_importance(*, by: Literal['PredictorName', 'PredictorCategory'] = 'PredictorName', query: pdstools.utils.types.QUERY | None = None) polars.LazyFrame¶
Share of the model importance carried by predictors or categories.
Uses the
FeatureImportancethe platform stores for the predictors. For Adaptive Gradient Boosting (AGB) models this is the only per-predictor measure: their predictors have no bin statistics and hence no univariate performance. Per model the importances are rescaled to sum to 100%, then averaged over the models of each configuration. Models without any importance (for example AGB models that have not built trees yet) are not counted.For AGB, the platform writes importance per action model and once per configuration (the global importance, in a summary model with empty context keys). Action models hold their context keys constant, so those report zero importance there. When available, the global importance and activity therefore replace the action-level values of all predictors, so each configuration reports its global importance. Model selection still uses the action models; summary models are not counted as models.
- Parameters:
by ({"PredictorName", "PredictorCategory"}, default "PredictorName") – Whether to report each predictor or each predictor category.
query (QUERY, optional) – Restricts the models in scope, for example
pl.col("ModelTechnique") == "GradientBoost".
- Returns:
Per Configuration, Channel, Direction and ModelTechnique (those present in the data) and predictor (or category):
Models(models in the group),Importance %(average share of the model importance) andActive Predictors(average number of active predictors per model).- Return type:
pl.LazyFrame
- Raises:
ValueError – If the data has no predictor importance.
- metric_over_time(metric: str = 'Performance', by: polars.Expr | str | list[str] = 'ModelID', *, every: str | datetime.timedelta = '1d', cumulative: bool = True, query: pdstools.utils.types.QUERY | None = None, facet: str | None = None) polars.LazyFrame¶
Model metric per time interval, the data behind
plot.over_time.The snapshots are grouped into
everyintervals as in Polarsgroup_by_dynamic, keeping the last snapshot of each model per interval. The models are then combined perby(andfacet) group:PerformanceandSuccessRateas response-weighted averages, other metrics as sums.- Parameters:
metric (str, default "Performance") – Model data column to trend.
by (pl.Expr, str or list of str, default "ModelID") – Grouping of the models. Several column names are combined with “ / “ into a single dimension.
every (str or datetime.timedelta, default "1d") – Interval as in Polars
group_by_dynamic, for example “1d”, “1w” or “1mo”."auto"picks daily, weekly or monthly from the snapshot date range, seeresolve_trend_interval().cumulative (bool, default True) –
If True, return the (cumulative) metric value per interval. If False, return the change per interval:
SuccessRate: positives over responses gained in the interval, from the per-model changes of the cumulativePositivesandResponseCountcounters.Performance: the change of the group value.Other metrics are treated as cumulative counters: the per-model changes are summed into
{metric}_change.
Changes across missing intervals are averaged over the elapsed intervals. A model that first appears after the start of the history counts from zero.
query (QUERY, optional) – Restricts the models in scope.
facet (str, optional) – Additional grouping column.
- Returns:
One row per interval (
SnapshotTimeis the interval start) and group. A change other thanSuccessRateis in{metric}_change. The change inSuccessRatealso hasPositivesandResponseCount(per interval),PositivesInInterval,ResponsesInInterval,PeriodsCovered(the largest gap, in intervals, of the contributing models) andTotalResponses(cumulative).- Return type:
pl.LazyFrame
- Raises:
InsufficientTrendHistoryError – If
every="auto"and there are no valid snapshot times.
- overall_summary(*, start_date: datetime.datetime | None = None, end_date: datetime.datetime | None = None, window: int | datetime.timedelta | None = None, every: str | None = None, debug: bool = False) polars.LazyFrame¶
Overall ADM models summary. Only valid data is included.
- Parameters:
start_date (datetime.datetime, optional) – Start date of the summary period. If None (default) uses the end date minus the window, or if both absent, the earliest date in the data
end_date (datetime.datetime, optional) – End date of the summary period. If None (default) uses the start date plus the window, or if both absent, the latest date in the data
window (int or datetime.timedelta, optional) – Number of days to use for the summary period or an explicit timedelta. If None (default) uses the whole period. Can’t be given if start and end date are also given.
every (str, optional) – Optional additional grouping by time period. Format string as in polars.Expr.dt.truncate (https://docs.pola.rs/api/python/stable/reference/expressions/api/polars.Expr.dt.truncate.html), for example “1mo”, “1w”, “1d” for calendar month, week day. Defaults to None.
debug (bool, default False) –
If True, include diagnostic columns (ResponseCount, Positives) in output. If False, these intermediate calculation columns are dropped from the results.
This parameter affects the return value structure, not logging output. For debug logging, use logging.basicConfig(level=logging.DEBUG).
- Returns:
Summary across all valid ADM models as a dataframe with the following fields:
Time and Configuration Fields: - DateRange Min - The minimum date in the snapshot time range - DateRange Max - The maximum date in the snapshot time range - Duration - The duration in seconds between the minimum and maximum snapshot times - Configuration - A comma-separated list of unique model configurations
Performance Metrics: - Positives Inbound - The sum of positive responses across all models in the inbound channels - Positives Outbound - The sum of positive responses across all models in the outbound channels - Responses Inbound - The sum of all responses across all models in the inbound channels - Responses Outbound - The sum of all responses across all models in the outbound channels - Performance - The weighted average performance across all models (50-100)
Action Statistics: - Actions - The total number of unique actions - Used Actions - The number of unique actions that have been used (have responses) - New Actions - The number of new actions introduced in the period - Stopped Actions - Only with
every: the number of actions last used (with responses) in the previous period; null for the first period, and in the latest period it can include actions that only paused - Issues - The number of unique issues - Groups - The number of unique issue/group combinationsTreatment Statistics: - Treatments - The total number of unique treatments - Used Treatments - The number of unique treatments that have been used
Channel Statistics: - Number of Valid Channels - The count of valid channels (channels with sufficient data) - Minimum Channel Performance - The performance of the channel with lowest performance - Channel with Minimum Performance - The channel/direction group with the lowest performance - OmniChannel - The average overlap of actions across channels (measure of Omni Channel capability)
Technology Usage Indicators: - usesNBAD - Boolean indicating whether standard NBAD configurations are used - usesAGB - Boolean indicating whether any Adaptive Gradient Boosting (AGB) models are used
Note: A channel is considered “valid” if it has at least 200 positives and 1000 responses
- Return type:
pl.LazyFrame