User Guide: CreativeDynamics Library

Version: 0.9.8.1

The library offers three interfaces: Command-Line Interface (CLI, recommended), Python library (flexible integration), and FastAPI (web services).

1. Command-Line Interface (CLI)

The CLI provides standardised workflow with YAML configuration, handling column mapping and data preparation automatically.

Basic usage

# View all available options
python -m creativedynamics.cli.main --help

# Analyse CSV and save reports
python -m creativedynamics.cli.main path/to/your_data.csv -o output/cli_report

Common options

--metric: specify which metric(s) to analyse (CPC, CTR, or both)
--min-days: minimum days of data required
--threshold: change point detection sensitivity
--window-size: sliding window size for analysis
Column mapping: --item-column, --date-column, etc. for non-standard column names

2. Python library

The Python library interface provides full control over data loading and preparation. The core analysis function, analyze_all_items, operates on a dictionary of pandas DataFrames.

Example: running analysis from CSV

import pandas as pd
import os

from creativedynamics.contracts import CPC, CTR
from creativedynamics.core.analyzer import analyze_all_items
from creativedynamics.data.loader import load_data, prepare_item_time_series
from creativedynamics.reporting.generator import generate_summary_report

# Setup paths
input_csv_path = "data/betfred/betfred_casino_processed.csv"
output_dir = "output/my_python_analysis"
os.makedirs(output_dir, exist_ok=True)

# Load data - handles CSV reading, column normalisation, and metric calculation
# CTR values automatically normalised if in percentage format
print(f"Loading data from {input_csv_path}...")
master_df = load_data(db_path=input_csv_path)

# Prepare time series - groups by item, filters for data quality
print("Preparing item time series...")
item_time_series, excluded_items = prepare_item_time_series(
    data_source=master_df,
    item_col="ad_name",
    date_col="day",
    min_days=30,
    max_gap_days=7,
    min_density=0.5,
)

print(f"Prepared {len(item_time_series)} items for analysis.")
if excluded_items:
    print(f"Excluded {len(excluded_items)} items due to data quality filters.")

# Run analysis pipeline
if item_time_series:
    print("Running CreativeDynamics analysis...")
    all_results = analyze_all_items(
        item_time_series=item_time_series,
        metrics=(CTR, CPC),
        window_size=30,
        threshold=1.5,
        signature_depth=4,
        spend_column="amount_spent_gbp",
        clicks_column="link_clicks",
        plot_output_dir=output_dir,
    )

    # Generate summary report
    summary_path_base = os.path.join(output_dir, "analysis_summary")
    generate_summary_report(
        results=all_results,
        excluded_items=excluded_items,
        output_file=summary_path_base,
        min_wastage=10.0,
    )

    print(f"Analysis complete. Reports saved in: {output_dir}")
else:
    print("No items met the criteria for analysis.")

Analysis output

CreativeDynamics reports operational and financial impact metrics that are not added together:

Operational impact (primary)

engagement_gap_clicks: lost clicks relative to benchmark (primary decision metric)
Optional reference: engagement_gap_gbp_reference shown as a clearly labelled GBP reference value (not a financial loss)
CTR Trend: performance trajectory (Declining/Stable/Improving)
Creative Health Score: composite indicator (0.0-1.0)

Financial impact (secondary)

actual_overspend_gbp: actual overspend due to elevated CPC vs benchmark
actual_overspend_pct: overspend as a percentage of spend

Metric interpretation

Operational (clicks) guides creative and optimisation decisions. It is the primary view for performance impact and should be interpreted in clicks.
Financial (GBP) reflects actual spend inefficiency. It is provided as a secondary view and must not be added to the operational metric.

Coverage and exclusions

Analysis Coverage % is reported in summaries to show the proportion of creatives successfully analysed.
Exclusions are prominently listed with reasons (e.g., insufficient days, gaps, density) to prevent hidden issues.

3. FastAPI REST API

Detailed REST API with automatic documentation, validation, and async support.

Run server

# Development mode with auto-reload
uvicorn creativedynamics.api.main:app --reload --host 0.0.0.0 --port 5001

# Or using Python directly
python -m creativedynamics.api.main

Server runs on http://localhost:5001.

API documentation

Automatic interactive documentation:

Swagger UI: http://localhost:5001/docs
ReDoc: http://localhost:5001/redoc

Example API requests

Health check

curl http://localhost:5001/health

Upload and analyse data

# Upload CSV data
curl -X POST http://localhost:5001/api/v1/data/upload \
  -F "file=@data/betfred/betfred_casino_processed.csv"

# Run full analysis on all items
curl -X POST http://localhost:5001/api/v1/analyze/all \
  -H "Content-Type: application/json" \
  -d '{
    "data": [...],
    "column_mapping": {
      "item": "ad_name",
      "date": "day",
      "clicks": "link_clicks",
      "impressions": "impressions",
      "cost": "amount_spent_gbp"
    },
    "analysis_params": {
      "window_size": 30,
      "threshold": 1.5,
      "signature_depth": 4
    }
  }'

Generate reports

# Generate HTML report
curl -X POST http://localhost:5001/api/v1/report/generate \
  -H "Content-Type: application/json" \
  -d '{"analysis_results": {...}, "format": "html"}'

# Export CSV report
curl -X POST http://localhost:5001/api/v1/report/export \
  -H "Content-Type: application/json" \
  -d '{"analysis_results": {...}, "format": "csv"}' \
  -o report.csv

Detailed endpoints for data validation, signature calculation, impact analysis, and report generation with error handling and validation.