Datenvalidierung und Qualitätsprüfungen

Damit Ihre Design- und Analyseeingaben fundiert sind und das Risiko von Datenfehlern reduziert wird, bietet Meridian GeoX integrierte Funktionen zur Überprüfung Ihres Prozesses. Die Bibliothek wertet Ihre Daten mithilfe von zwei separaten Modulen aus: Datenvalidierungsprüfungen und Datenqualitätsprüfungen.

Arten von Datenprüfungen

Es ist wichtig zu verstehen, wie die Bibliothek mit unterschiedlichen Arten von Datenproblemen umgeht:

• Validierungsprüfungen: Mit diesen Prüfungen wird sichergestellt, dass Ihre Daten bestimmte Anforderungen erfüllen. Wenn eine Validierungsprüfung fehlschlägt, löst die Bibliothek einen ValueError aus und stoppt die Ausführung.

• Qualitätsprüfungen: Diese Prüfungen identifizieren Anomalien, die sich negativ auf die Qualität der Ergebnisse auswirken könnten, stoppen die Code-Ausführung jedoch nicht. Stattdessen werden Warnmeldungen in der Konsole protokolliert und detailliertere Informationen in einem strukturierten Objekt vom Typ QualityCheckResult zurückgegeben.

  Hinweis: Die Schwellenwerte für Qualitätsprüfungen (maximal 30 % fehlende Tage oder maximal 500 geografische Einheiten) sind hartcodiert und können nicht angepasst werden. Dadurch wird Konsistenz gewährleistet und verhindert, dass Parameter auf Nutzerseite zu stark variiert werden, um gezielt bestimmte Ergebnisse zu erzwingen.

Grundlegende Validierungsprüfungen

Bevor die Bibliothek gezielt spezifische Algorithmen anwendet, führt sie grundlegende Validierungen für alle Eingabedaten durch:

• Schemakonformität: Die Daten müssen date (keine Nullwerte), location (keine leeren Strings und keine Nullwerte) und conversions (keine Nullwerte) enthalten. Wenn spend angegeben ist, müssen die Werte nicht-negativ und ungleich null sein.
• Positive Conversions: Die Summe der Spalte conversions über das gesamte Dataset hinweg muss strikt größer als 0 sein.
• Datengranularität: Die Daten müssen auf Tagesbasis erhoben werden. Auf Wochenbasis erhobene Datasets werden nicht unterstützt und sind blockiert.

Prüfungen in der Designphase

Wenn Sie geox.run_design() ausführen, wertet die Bibliothek die Vortestdaten aus, um sicherzustellen, dass ein aussagekräftiger Kandidatenpool für die Studie generiert werden kann.

Validierungsprüfungen

In der Designphase werden die folgenden Validierungsprüfungen durchgeführt:

• Erhebungszeitraum der Vortestdaten: Die Daten müssen eindeutige Datumswerte enthalten, die mindestens dem Dreifachen des Werts für experiment_duration entsprechen.
• Verfügbarkeit der geografischen Einheiten: Nach dem Entfernen aller nutzerseitig ausgeschlossenen geografischen Einheiten muss der verbleibende Pool mindestens 2 * (cell_count + 1) geografische Einheiten enthalten. Dabei ist cell_count die Anzahl der Testzellen.
• Überschneidungen bei den Einschränkungen: Die Gruppe der ausgeschlossenen geografischen Einheiten darf sich nicht mit der Kontrollgruppe der zwingend einzubeziehenden Einheiten überschneiden.
• Alpha- und Power-Grenzwerte: Die Werte für alpha und power müssen strikt zwischen 0 und 1 liegen.
• Testspezifische Anforderungen: Die Bibliothek erzwingt je nach Testtyp strikte Daten- und Parameteranforderungen:
  • GO_DARK und HEAVY_UP: Ihr Dataset muss eine tagesbezogene Spalte spend enthalten. Für Studien mit einer einzelnen Zelle oder die erste Zelle von Studien mit mehreren Zellen wird eine Spalte mit dem Namen spend oder spend_cell_1 erwartet. Für nachfolgende Zellen wird eine entsprechende Spalte erwartet (zum Beispiel spend_cell_2).
  • HOLDBACK: Zeitreihendaten zu Ausgaben sind nicht erforderlich. Der Parameter für die Kosten pro inkrementeller Conversion (cost_per_incremental_conversion) muss jedoch größer als 0 sein. Hinweis: Der Standardwert für cost_per_incremental_conversion ist 1.0. Diese Validierung schlägt also nur fehl, wenn Sie den Parameter explizit auf 0 oder einen negativen Wert festlegen oder wenn Sie beim Übergeben eines Dictionary mit mehreren Zellen eine spezifische Holdback-Zelle weglassen.
• Conversions maximieren: Der Wert max_conversions_percent muss kleiner als 0.5 sein.

Qualitätsprüfungen

In der Designphase werden die folgenden Qualitätsprüfungen durchgeführt:

• Warnungen zur Budgetkonfiguration: Die Bibliothek warnt Sie, wenn Ihre Parameter vom Typ constraints nicht zu Ihrem Testtyp passen. Bei GO_DARK oder HEAVY_UP erwartet die Bibliothek eine prozentuale Änderung (budget_pct) und gibt eine Warnung aus, falls ein absolutes Budget angegeben ist. Bei HOLDBACK wird ein absolutes Budget erwartet und Sie werden gewarnt, falls ein Prozentsatz angegeben ist.
• Ausreißer isolieren: Die Bibliothek sucht nach geografischen Einheiten mit Ausgaben größer 0, aber ohne aufgezeichnete Conversions. Standardmäßig (exclude_geos_no_response=True) werden solche Einheiten von der Bibliothek automatisch aus den Kandidatengruppen ausgeschlossen.
• Geringe Datendichte: Es werden Warnungen protokolliert, wenn der Anteil der fehlenden Conversion-Tage 30 % überschreitet oder wenn der Anteil der fehlenden Ausgabentage für aktive GO_DARK- oder HEAVY_UP-Testzellen 30 % überschreitet. Außerdem wird eine Warnung protokolliert, wenn der Gesamtanteil an Null-Conversions 50 % überschreitet.
• Hohe Kardinalität: Es wird eine Warnung protokolliert, wenn die Anzahl der eindeutigen geografischen Einheiten 500 überschreitet, da bei zu hoher Granularität Populationsbewegungen zwischen geografischen Einheiten in der Regel die Steigerungsschätzungen verfälschen.
• Doppelte Einträge: Wenn mehrere Einträge für dasselbe Datum und denselben Standort vorhanden sind, wird eine Warnung protokolliert und die Einträge werden automatisch aggregiert.

Prüfungen in der Analysephase

Wenn Sie nach dem Test eine Analyse mit geox.analyze() ausführen, erzwingt die Bibliothek eine strikte Synchronisierung mit dem ursprünglichen Vortest-Studiendesign.

Validierungsprüfungen

In der Analysephase werden die folgenden Validierungsprüfungen durchgeführt:

• Konsistenz der geografischen Einheiten: Die Standorte im hochgeladenen Analyse-Dataset müssen exakt mit der Gesamtheit der geografischen Kontroll- und Testeinheiten übereinstimmen, die in der Designphase festgelegt wurden (nachdem ausgeschlossene Einheiten entfernt wurden).
• Dauer des Vortests: Der Vortestzeitraum in Ihren Analysedaten muss mindestens dreimal so lang sein wie der Wert für experiment_duration.
• Keine Überschneidung: Das Enddatum des Vortests (falls festgelegt) muss strikt vor dem Startdatum der Analyse liegen.

Qualitätsprüfungen

Während der Analyse führt die Bibliothek die nachfolgend beschriebenen Qualitätsprüfungen durch. Die Auswertung wird dabei gezielt auf den Vortestzeitraum beschränkt, um Post-Test-Bias zu vermeiden:

• Ausreißer isolieren: Die Bibliothek sucht nach geografischen Einheiten mit Ausgaben größer 0, aber ohne aufgezeichnete Conversions.
• Geringe Datendichte: Es werden Warnungen protokolliert, wenn der Anteil der fehlenden Conversion-Tage 30 % überschreitet oder wenn der Anteil der fehlenden Ausgabentage für aktive GO_DARK- oder HEAVY_UP-Testzellen 30 % überschreitet. Außerdem wird eine Warnung protokolliert, wenn der Gesamtanteil an Null-Conversions 50 % überschreitet.
• Hohe Kardinalität: Es wird eine Warnung protokolliert, wenn die Anzahl der eindeutigen geografischen Einheiten 500 überschreitet.
• Doppelte Einträge: Wenn mehrere Einträge für dasselbe Datum und denselben Standort vorhanden sind, wird eine Warnung protokolliert und die Einträge werden automatisch aggregiert.

Qualitätsprüfungen konfigurieren und ansehen

Sie können das Verhalten der automatischen Filterung mit dem Objekt QualityCheckConfig steuern und die Ergebnisse der Evaluierung mit dem Objekt QualityCheckResult aufrufen.

Eine vollständige Liste der Parameter, Standardschwellenwerte und zurückgegebenen Datentypen finden Sie in der API-Referenz im Abschnitt Datenqualitätsmodul.

Das folgende Beispiel zeigt, wie Sie das automatische Filterverhalten konfigurieren:

# Configure automatic filtering behavior
import meridian_geox as geox

quality_config = geox.QualityCheckConfig(
    # Automatically excludes geos with spend but no conversions (design phase
    # only)
    exclude_geos_no_response=True,
    exclude_outlier_dates=True,  # Automatically excludes outlier dates
)

# QualityCheckResult is returned as part of your design or analysis outputs.
# It contains:
# - quality_metrics (pd.DataFrame with metric, value, message, and threshold)
# - outlier_geos (Set of identified outlier locations)
# - outlier_dates (Set of identified outlier dates)