CreativeDynamics Documentation (Version 0.9.8.1)
CreativeDynamics Analysis Report Outputs¶
Detailed explanation of each column in the analysis_report.csv file generated by the CreativeDynamics analysis pipeline.
Report Columns Explained¶
Item ID¶
Type: string
Description: Unique identifier for the creative asset, ad, or other item being analysed. Taken directly from item_column in dataset.
Total Spend (GBP)¶
Type: float
Description: Total monetary spend recorded for this item over entire analysis period. Serves as baseline for calculating financial impact of performance changes.
actual_overspend_gbp¶
Type: float
Description: Actual overspend due to Cost Per Click (CPC) being higher than the established Benchmark CPC. Calculated by summing excess cost for each day where CPC was above benchmark.
Formula: SUM( max(0, Daily CPC - Benchmark CPC) * Daily Clicks ).
actual_overspend_pct¶
Type: float
Description: actual_overspend_gbp expressed as percentage of Total Spend (GBP). Helps contextualise overspend relative to the item’s budget.
Formula: (actual_overspend_gbp / Total Spend (GBP)) * 100
engagement_gap_clicks¶
Type: integer
Description: Total estimated number of clicks lost over the analysis period due to CTR being below Benchmark CTR. Primary operational metric for decision-making. A GBP reference value may be presented separately, clearly labelled as a reference, not a financial loss.
Formula: SUM( max(0, Benchmark CTR - Daily CTR) * Daily Impressions ).
engagement_gap_gbp_reference (optional)¶
Type: float
Description: Reference GBP value for engagement_gap_clicks, computed using Benchmark CPC. Provided for context only and must not be treated as a financial loss.
Formula: engagement_gap_clicks * Benchmark CPC.
CTR Trend¶
Type: string (Declining, Stable)
Description: Simplified indicator of Click-Through Rate’s performance trend. Marked as Declining if negative pattern change detected, Stable otherwise.
Creative Health Score¶
Type: float (0.0 to 1.0)
Description: Composite score from 0.0 (poor) to 1.0 (excellent) providing quick assessment of item’s overall performance. The score reflects trend stability and benchmark proximity across key metrics; it does not combine operational and financial impact into a single number.
Benchmark CPC¶
Type: float
Description: Cost Per Click value used as baseline for optimal performance. Typically calculated from longest ‘stable’ or ‘improving’ performance segment in item’s history. If no such segment exists, falls back to item’s overall average CPC.
Benchmark CTR¶
Type: float
Description: Click-Through Rate used as baseline for optimal performance. Calculated from best-performing stable or improving period.
Total Lost Clicks¶
Type: integer
Description: Legacy detail supporting engagement_gap_clicks. For most users, engagement_gap_clicks is the primary operational metric; this column may be equivalent in many configurations.
CPC Pattern Change¶
Type: boolean (True/False)
Description: Indicates whether signature analysis detected significant negative change (i.e., ‘declining’ trend) in CPC pattern. True means statistically significant negative shift was found.
CTR Pattern Change¶
Type: boolean (True/False)
Description: Indicates whether signature analysis detected significant negative change in CTR pattern. True means statistically significant negative shift was found.
Financial Impact Status¶
Type: string
Description: Status of actual_overspend_gbp calculation. Common values: Success, Success (Fallback) (if no optimal benchmark period found), or Missing Required Data.
Operational Impact Status¶
Type: string
Description: Status of engagement_gap_clicks calculation. Common values: Success or Missing Required Data.
CPC Plot¶
Type: string (file path)
Description: Relative path to PNG plot file visualising CPC analysis for this item, including time-series data, change points, and benchmark line.
CTR Plot¶
Type: string (file path)
Description: Relative path to PNG plot file visualising CTR analysis for this item.
Correlation Risk¶
Type: string (Low, Medium, High, Unknown)
Description: Context on whether CPC and CTR move inversely, which may indicate the same underlying issue manifests across metrics. This is an interpretation aid; operational and financial metrics are not combined regardless of risk level.
High: Strong negative correlation (e.g., as CTR drops, CPC rises)
Medium: Moderate negative correlation
Low: Weak or positive correlation
Unknown: Insufficient data for correlation analysis
Fatigue Detection and Actions¶
Fatigue Status¶
Type: string
Description: Overall human-readable status derived from terminal-decline and audience-exhaustion detection per metric (CTR and CPC). Typical values and meanings:
Creative Fatigued - Replace: Both a sustained terminal decline and audience exhaustion are detected; replacement is strongly recommended.
Terminal Decline Detected: Sustained below-benchmark performance with a declining trend is detected; monitor closely.
Audience Exhausted: Low recent volatility combined with poor performance implies audience saturation; consider replacing soon.
High Volatility (Healthy): Elevated recent volatility indicates active audience exploration; let it run.
Healthy Performance: No fatigue signals detected; continue monitoring.
Computed in creativedynamics/reporting/generator.py using results from creativedynamics/core/fatigue_detection.py.
Recommended Action¶
Type: string
Description: Action guidance mapped from Fatigue Status:
Creative Fatigued - Replace → “Replace this creative”
Terminal Decline Detected → “Monitor, may recover”
Audience Exhausted → “Consider replacing soon”
High Volatility (Healthy) → “Let it run - actively optimising”
Healthy Performance → “Continue monitoring”
Replacement Recommended¶
Type: boolean
Description: True when both conditions are met in the recent window (default 14 days): sustained terminal decline and audience exhaustion (low volatility + poor performance vs benchmark). Source: detect_terminal_decline().
CTR Terminal Decline, CPC Terminal Decline¶
Type: boolean
Description: True if, in the recent analysis window, the metric shows sustained poor performance relative to its benchmark and a declining trend (CTR slope < 0; CPC slope > 0). Source: detect_terminal_decline().
CTR Audience Exhausted, CPC Audience Exhausted¶
Type: boolean
Description: True if performance is below benchmark and recent volatility (coefficient of variation) is below the threshold (default 0.15), indicating audience saturation. Source: detect_terminal_decline().
CTR Fatigue Confidence, CTR Fatigue Reason¶
Type: string
Description: Detector-provided confidence level (High/Medium/Low) and brief rationale for CTR fatigue assessment over the recent window. CPC equivalents may be present depending on configuration. Source: detect_terminal_decline().
Reporting Start Date¶
Type: date
Description: First date included in the reporting window for this item.
Status Computation Flow¶
Overview: Fatigue and action fields are derived by combining detector outputs (per metric) with reporting logic.
Computation steps:
Detector evaluates recent performance vs benchmark and volatility per metric (CTR, CPC).
Flags produced:
is_terminal_decline,audience_exhausted,replacement_recommended, plusconfidenceandreason.Reporting maps flags to
Fatigue Status,Recommended Action, and boolean columns.
Source files:
Detector:
creativedynamics/core/fatigue_detection.py(detect_terminal_decline())Reporting mapper:
creativedynamics/reporting/generator.py
![digraph G {
rankdir=LR;
node [shape=box];
A [label="Input time series"];
B [label="Detector: detect_terminal_decline()"];
C [label="Flags", shape=diamond];
D [label="CTR/CPC Terminal Decline"];
E [label="CTR/CPC Audience Exhausted"];
F [label="Replacement Recommended"];
G [label="Reporting generator"];
H [label="Fatigue Status"];
I [label="Recommended Action"];
J [label="Confidence / Reason"];
A -> B;
B -> C [label="per metric (CTR/CPC)"];
C -> D [label="is_terminal_decline"];
C -> E [label="audience_exhausted"];
C -> F [label="replacement_recommended"];
D -> G;
E -> G;
F -> G;
G -> H;
G -> I;
G -> J;
}](_images/graphviz-bbcb780cfb0d8fa577e91f1e9d05261fe413a5f0.png)
Compatibility and Legacy Columns¶
Some reports may include legacy columns retained for backward compatibility. These are documented here for clarity. New implementations should rely on the non-additive impact metrics (engagement_gap_clicks and actual_overspend_gbp).
CPC Wastage (GBP)¶
Type: float
Description (legacy): Historical calculation of excess CPC spend vs benchmark. Superseded by actual_overspend_gbp.
CPC Wastage %¶
Type: float
Description (legacy): CPC Wastage (GBP) as a percentage of total spend. Superseded by actual_overspend_pct.
CTR Decline %¶
Type: float
Description (legacy): Percentage decline from benchmark CTR. Operational impact is now expressed primarily as engagement_gap_clicks (with optional GBP reference).
Lost Clicks per Day¶
Type: integer
Description (legacy): Average lost clicks per day due to CTR underperformance. The primary operational metric is engagement_gap_clicks over the analysis period.
Double Counting Risk¶
Type: string
Description (legacy): Prior label for correlation context when CTR and CPC move inversely. Replaced by Correlation Risk. Metrics are not combined regardless of risk level.
Engagement Gap (Clicks) and Reference Value (GBP)¶
Type: integer, float
Description: Column names equivalent to engagement_gap_clicks and its optional GBP reference value (engagement_gap_gbp_reference). The reference is a context value only and not a financial loss.
CPC Status, CTR Status¶
Type: string
Description: Compatibility labels equivalent to Financial Impact Status (CPC) and Operational Impact Status (CTR).
See Also¶
Visual interpretation: Visualization Guide
Concepts and methodology: Impact Concepts, Methodology
Detector logic (code):
creativedynamics/core/fatigue_detection.pyReport generator (code):
creativedynamics/reporting/generator.py