pdstools.adm.Aggregates ======================= .. py:module:: pdstools.adm.Aggregates Classes ------- .. autoapisummary:: pdstools.adm.Aggregates.Aggregates Module Contents --------------- .. py:class:: Aggregates(datamart: pdstools.adm.ADMDatamart.ADMDatamart) Aggregates. .. py:attribute:: datamart .. py:method:: 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. :param data: If provided, subsets to just that dataframe, by default None :type data: Optional[pl.LazyFrame], optional :param table: If provided, specifies the table to get data from, by default "model_data" :type table: Literal['model_data', 'predictor_data', 'combined_data'], optional :returns: A LazyFrame containing only the rows from the most recent snapshot time :rtype: pl.LazyFrame .. py:method:: 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' :param query: A query to apply to the data before creating the pivot, by default None :type query: Optional[QUERY], optional :param active_only: Whether to only include predictors with EntryType "Active". When False, all non-classifier predictors are included, by default False :type active_only: bool, optional :param by: 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 :type by: str, optional :param top_predictors: Specify the maximum number of predictors, by default None :type top_predictors: Optional[int], optional :param top_groups: Specify the maximum number of 'groups' specified in the 'by' argument, by default None :type top_groups: Optional[int], optional :returns: A LazyFrame with a column for each predictor, and a row for each 'group'. The values represent the weighted performance for that predictor :rtype: pl.LazyFrame .. py:method:: 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 :meth:`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 including ``by``. :param by: Last context key to include in the grouping, by default "Name". Must be part of the context keys in the ADMDatamart class. :type by: str, optional :param query: A query to apply to the data before summarization, by default None :type query: Optional[QUERY], optional :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. :rtype: pl.LazyFrame .. py:method:: 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 :param query: A query to apply to the data, by default None, so no filtering applied :type query: Optional[QUERY], optional :param start_date: 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 :type start_date: datetime.datetime, optional :param end_date: 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 :type end_date: datetime.datetime, optional :param window: 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. :type window: int or datetime.timedelta, optional :param every: 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. :type every: str, optional :param custom_channels: Optional dictionary mapping custom channel names to standard channel groups. Defaults to None. :type custom_channels: dict[str, str], optional :param debug: 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). :type debug: bool, default False :param format_flags: If True, format boolean flag columns (usesNBAD, usesAGB) as "Yes"/"No"/"?" strings for display in reports. If False, keeps original boolean/null values. :type format_flags: bool, default False :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) :rtype: pl.LazyFrame .. py:method:: channel_overview(*, query: pdstools.utils.types.QUERY | None = None) -> polars.DataFrame Return the display-ready channel overview table. .. py:method:: 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. :param query: A query to apply to the data, by default None, so no filtering applied :type query: Optional[QUERY], optional :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 :rtype: pl.LazyFrame .. py:method:: configuration_overview(*, query: pdstools.utils.types.QUERY | None = None) -> polars.DataFrame Return the display-ready configuration overview table. .. py:method:: 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. :param query: A query to apply to the data, by default None, so no filtering applied :type query: Optional[QUERY], optional :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) :rtype: pl.LazyFrame .. py:method:: global_predictor_overview(*, query: pdstools.utils.types.QUERY | None = None) -> polars.DataFrame Return the display-ready global predictor overview table. .. py:method:: 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. :param model_id: If provided, filters the data to include only predictors for the specified model ID. If None (default), includes predictors for all models. :type model_id: Optional[str], optional :param additional_aggregations: Additional aggregation expressions to include in the result. These will be added to the default aggregations. :type additional_aggregations: Optional[list], optional :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. :rtype: pl.LazyFrame or None .. py:method:: 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 ``Channel`` and ``Direction`` columns all models in scope are compared to one average. :param confidence_level: Two-sided confidence level of the Wilson interval. :type confidence_level: float, default 0.95 :param query: Restricts the models in scope. The averages are computed over the models that remain. :type query: QUERY, optional :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``, ``AverageSuccessRate`` and ``SuccessRateCategory``. The category is one of: - ``Very low``: the whole interval is below a tenth of the average - ``Below average``: the whole interval is below the average - ``Above average``: the whole interval is above the average - ``Consistent with average``: the interval contains the average Models without responses are left out. :rtype: pl.LazyFrame .. py:method:: 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. :param columns: The model columns to review. Columns absent from the data are skipped. :type columns: tuple[str, ...] :param query: Restricts the models in scope. :type query: QUERY, optional :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 Characters`` and ``Models with Hidden Characters``. Hidden characters are invisible characters such as zero-width or non-breaking spaces and leading or trailing whitespace; see :meth:`hidden_character_names` for the values themselves. :rtype: pl.LazyFrame .. py:method:: hidden_character_names(*, columns: tuple[str, Ellipsis] = NAMING_COLUMNS, query: pdstools.utils.types.QUERY | None = None) -> polars.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. :param columns: The model columns to inspect. Columns absent from the data are skipped. :type columns: tuple[str, ...] :param query: Restricts the models in scope. :type query: QUERY, optional :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) and ``Name Clashes`` (number of models that have the cleaned value). A non-zero clash count means the data holds two values that appear identical. :rtype: pl.LazyFrame .. py:method:: 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 :meth:`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. :param query: Restrict the models in scope, for example to active models or a configuration. Only GradientBoost models are included. :type query: QUERY, optional :returns: PredictorName, PredictorCategory, Configurations, Response Count Min and Response Count Max for unused predictors, sorted by configuration count descending and predictor name ascending. :rtype: pl.LazyFrame :raises ValueError: If the data has no predictor importance. .. py:method:: 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 ``FeatureImportance`` the 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. :param by: Whether to report each predictor or each predictor category. :type by: {"PredictorName", "PredictorCategory"}, default "PredictorName" :param query: Restricts the models in scope, for example ``pl.col("ModelTechnique") == "GradientBoost"``. :type query: QUERY, optional :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) and ``Active Predictors`` (average number of active predictors per model). :rtype: pl.LazyFrame :raises ValueError: If the data has no predictor importance. .. py:method:: 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 ``every`` intervals as in Polars ``group_by_dynamic``, keeping the last snapshot of each model per interval. The models are then combined per ``by`` (and ``facet``) group: ``Performance`` and ``SuccessRate`` as response-weighted averages, other metrics as sums. :param metric: Model data column to trend. :type metric: str, default "Performance" :param by: Grouping of the models. Several column names are combined with " / " into a single dimension. :type by: pl.Expr, str or list of str, default "ModelID" :param every: Interval as in Polars ``group_by_dynamic``, for example "1d", "1w" or "1mo". ``"auto"`` picks daily, weekly or monthly from the snapshot date range, see :func:`~pdstools.utils.cdh_utils.resolve_trend_interval`. :type every: str or datetime.timedelta, default "1d" :param cumulative: 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 cumulative ``Positives`` and ``ResponseCount`` counters. - ``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. :type cumulative: bool, default True :param query: Restricts the models in scope. :type query: QUERY, optional :param facet: Additional grouping column. :type facet: str, optional :returns: One row per interval (``SnapshotTime`` is the interval start) and group. A change other than ``SuccessRate`` is in ``{metric}_change``. The change in ``SuccessRate`` also has ``Positives`` and ``ResponseCount`` (per interval), ``PositivesInInterval``, ``ResponsesInInterval``, ``PeriodsCovered`` (the largest gap, in intervals, of the contributing models) and ``TotalResponses`` (cumulative). :rtype: pl.LazyFrame :raises InsufficientTrendHistoryError: If ``every="auto"`` and there are no valid snapshot times. .. py:method:: 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. :param start_date: 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 :type start_date: datetime.datetime, optional :param end_date: 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 :type end_date: datetime.datetime, optional :param window: 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. :type window: int or datetime.timedelta, optional :param every: 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. :type every: str, optional :param debug: 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). :type debug: bool, default False :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 combinations Treatment 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 :rtype: pl.LazyFrame