Label Construction (Targets)

---

Kurzzusammenfassung

• Diese Seite beschreibt, wie aus einer publizierten Feature-Version (feature_set_version) und einer versionierten Label-Spezifikation (label_spec_version) ein trainingsfähiger Datensatz erzeugt wird.
• Der Schritt ist auf EOD-Daten und ein langfristiges Setup ausgelegt: Labels werden strikt forward über Trading-Day-Horizons berechnet (keine Intraday-Targets).
• Ergebnis sind (1) ein versioniertes Training-Dataset (training_dataset_version) und (2) ein Label-QA Report. Beides wird in OpenMetadata verlinkt (Lineage) und als Run-Artefakte in MLflow erfasst.
• BPMN-Leitpfad (Detail): Label Construction Triggered -> Resolve Label Spec + Load Feature Set -> Load Target Price Series -> Compute Labels -> Assemble Training Dataset -> Label-QA -> Version + Publish Training Dataset -> Update Lineage + Metadata -> Log Dataset/Artifacts (MLflow) -> Downstream Ready Signal.

Einordnung: In der Gesamtarchitektur ist Label Construction Schritt 6 (nach Feature Pipeline und vor Model Training + HPO).

Ziel

1. Labels (Targets) deterministisch und leakage-frei aus EOD-Zeitreihen ableiten.
2. Ein reproduzierbares Training-Dataset bauen, das eindeutig auf feature_set_version, dataset_version und label_spec_version referenziert.
3. Eine schlanke Label-QA liefern (inkl. Report-URI), damit Training/Backtests auf konsistenten Targets basieren.

Scope & Abgrenzung

In Scope (diese Seite / BPMN-Detailansicht):

• Übernahme der publizierten Feature-Version (Feature Store) und Normalisierung des Run-Kontexts
• Laden der Target-Zeitreihe(n) aus der Curated Zone (EOD)
• Label-Berechnung auf Basis einer versionierten Label-Spezifikation
• Zusammenführen von Features + Labels zum Training-Dataset
• Label-QA (Leakage/Completeness/Distribution) inkl. Report-Artefakt
• Versionierung + Publikation des Training-Datasets
• Lineage/Metadata Update (OpenMetadata) und Artefakt-Logging (MLflow)

Out of Scope (separate Schritte / Seiten):

• Ingestion (Extract/Load/Transform/Validate): Data Pipeline
• Gate A (Purpose/Allowed Use): Purpose + Entitlement Check
• DQ Gate (dataset quality_status PASS/WARN/FAIL): Data Quality
• Feature Engineering (Feature Pipeline selbst): Feature Pipeline
• Model Training + HPO, Backtesting, Portfolio Construction, Deployment, Scoring

Inputs

Label Construction startet erst, wenn eine Feature-Version publiziert wurde. Die Inputs sind als Contracts gedacht (klein, referenzierend, reproduzierbar).

1) Feature Set Version Contract

Kommt direkt aus der Feature Pipeline und referenziert die zu verwendende Feature-Version.

Felder (gemäss BPMN-Contract):

• feature_set_version
• dataset_version
• as_of_date
• universe_id
• qa_status
• openmetadata_entity_ref
• mlflow_run_ref

2) Run Context

Run-Kontext wird als technische Referenz weitergereicht (Traceability), ohne in diesem Schritt neue Gate-Entscheide zu treffen.

Felder (gemäss BPMN-Contract):

• run_id
• trigger_reason
• pipeline_id
• pipeline_version
• as_of_date

3) Label Spec Version Contract

Die Label-Spezifikation ist die versionierte Definition der Targets (welche Zielgrösse, welcher Horizon, welche Normalisierung/Clipping-Regeln).

Felder (gemäss BPMN-Contract):

• label_spec_version
• target_definition
• horizon_trading_days
• benchmark_id
• winsorization
• scaling

Praktischer Standard: Die Label Specs liegen als YAML/JSON im Repo (Review via PR). label_spec_version ist SemVer oder Git-Commit.

Beispiel (YAML):

label_spec_version: v1
target_definition:
  type: forward_total_return
  price_column: adj_close
  currency: USD
horizon_trading_days: 63

benchmark_id: SPY
winsorization:
  method: quantile
  lower: 0.01
  upper: 0.99
scaling: zscore

Output

1) Training Dataset Contract

Das Training-Dataset ist die materialisierte Kombination aus Features + Labels und wird versioniert veröffentlicht.

Felder (gemäss BPMN-Contract):

• training_dataset_version
• feature_set_version
• dataset_version
• label_spec_version
• run_id
• pipeline_version
• window_start
• window_end
• row_count
• artifact_uri
• openmetadata_entity_ref
• mlflow_run_ref

Beispiel (JSON):

{
  "training_dataset_version": "tds__fs_2026-02-14__ls_v1__win_2018-01-02_2026-02-14",
  "feature_set_version": "fs_2026-02-14T02:10Z",
  "dataset_version": "curated_market__2026-02-14T01:05Z",
  "label_spec_version": "v1",
  "run_id": "prefect-flow-run-7a19c2",
  "pipeline_version": "git:9f3c2ab",
  "window_start": "2018-01-02",
  "window_end": "2026-02-14",
  "row_count": 12873450,
  "artifact_uri": "s3://ml-artifacts/training_datasets/tds__fs_2026-02-14__ls_v1__win_2018-01-02_2026-02-14/",
  "openmetadata_entity_ref": {
    "service": "lakehouse",
    "database": "ml",
    "schema": "training",
    "table": "training_dataset__tds__fs_2026-02-14__ls_v1"
  },
  "mlflow_run_ref": "mlflow://experiments/score-model/runs/3f2c8d"
}

2) Label-QA Report Contract

Label-QA ist bewusst separat vom DQ-Gate: sie prüft targetspezifische Risiken (Leakage, Coverage, Verteilung) und erzeugt einen Report-URI.

Felder (gemäss BPMN-Contract):

• run_id
• feature_set_version
• dataset_version
• as_of_date
• label_spec_version
• qa_status
• report_uri

Beispiel (JSON):

{
  "run_id": "prefect-flow-run-7a19c2",
  "feature_set_version": "fs_2026-02-14T02:10Z",
  "dataset_version": "curated_market__2026-02-14T01:05Z",
  "as_of_date": "2026-02-14",
  "label_spec_version": "v1",
  "qa_status": "PASS",
  "report_uri": "s3://ml-artifacts/qa/labels/fs_2026-02-14/ls_v1/report.json"
}

Ablauf

BPMN-Schritte -> technische Umsetzung

BPMN-Element	Zweck	Output / Artefakte	Hinweise
StartEvent_LabelConstruction - Label Construction Triggered	Start nach publizierter feature_set_version	Run-Kontext + Input-Contracts	Keine neuen Gate-Entscheide
ScriptTask_ResolveInputs - Resolve Label Spec + Load Feature Set	Inputs standardisieren und Feature-Version reproduzierbar laden	Normalisierter Run-Kontext	Reads aus Feature Store via feature_set_version
ScriptTask_LoadTargetSeries - Load Target Price Series	Target Data Series aus Curated Zone laden	Target-Series Slice (Window + Horizon-History)	Kontext via dataset_version / as_of_date
ScriptTask_ComputeLabels - Compute Labels	Labels strikt forward berechnen (t -> t+H Trading Days)	Label-Tabelle keyed by (feature_as_of_date, instrument_id)	Letzte H Tage (ohne Label) werden entfernt/markiert
ScriptTask_AssembleTrainingDataset - Assemble Training Dataset	Features + Labels joinen	Kandidat Training-Dataset	Join: instrument_id + feature_as_of_date
BusinessRuleTask_LabelQA - Label-QA	Leakage/Coverage/Distribution prüfen	OutputContract_LabelQAReport	FAIL stoppt Publish
ServiceTask_PublishTrainingDataset - Version + Publish	Dataset versionieren + speichern	OutputContract_TrainingDataset + Artefakt-URI	Atomar publishen (Version = Identifier)
ServiceTask_OpenMetadata - Update Lineage + Metadata	Lineage + Links aktualisieren	OpenMetadata Edges + Contract-Links	dataset_version -> feature_set_version -> training_dataset_version
ServiceTask_MLflowLog - Log Dataset/Artifacts	Run-Artefakte und Referenzen loggen	MLflow Run (Contracts + QA Report)	Training konsumiert per mlflow_run_ref / artifact_uri
ThrowEvent_TrainingDatasetReady - Downstream Ready Signal	Übergabe an nächsten Main-Step	Signal "Training Dataset Ready"	Handover zu Model Training + HPO

Label-Berechnung

Zeitbezug und Leakage-Vermeidung

• Features sind immer auf einen Stichtag feature_as_of_date = t bezogen.
• Labels verwenden ausschliesslich Informationen aus der Zukunft: Preis/Return von t bis t + horizon_trading_days.
• Reihen ohne verfügbares Forward-Label (z. B. die letzten H Handelstage im Window) werden entfernt oder als nicht-trainierbar markiert.
• Wenn mehrere Horizons verwendet werden, werden Labels je Horizon separat abgeleitet (z. B. label_return_21d, label_return_63d).

Target-Definition (typisch)

Beispiele für target_definition.type (als Label Spec):

• forward_total_return (Forward Total Return über H Trading Days)
• forward_excess_return (Return minus Benchmark über H Trading Days)

Welche Spalte genutzt wird (z. B. adj_close oder eine Total-Return-Serie) ist Teil des Label Spec.

Label-QA

Label-QA ist die minimale Sicherheitsstufe für Targets. Sie ersetzt nicht das DQ-Gate, sondern ergänzt es dort, wo Targets eigene Risiken haben.

Typische Checks:

• Leakage-Guard: keine Labels, deren Enddatum <= feature_as_of_date
• Completeness: Coverage-Quote pro Datum/Instrument (z. B. "wie viele Labels fehlen?")
• Distribution-Sanity: Extremwerte, sprunghafte Verschiebungen vs. Baseline (z. B. quantile checks)
• Optional: Konsistenz zwischen Benchmark-Series und Asset-Series (wenn benchmark_id genutzt wird)

Ergebnis:

• qa_status in {PASS, WARN, FAIL}
• report_uri (Report als Artefakt; z. B. JSON + kleine Summary)

Versionierung & Reproduzierbarkeit

training_dataset_version

training_dataset_version ist ein stabiler Identifier. Er sollte deterministisch aus den Referenzen entstehen, z. B.:

• feature_set_version
• label_spec_version
• window_start, window_end

Dadurch sind Re-Runs möglich, ohne dass "zufällige" Versionen entstehen.

Artifact Layout (praktisch)

Ein bewährtes Layout ist:

• Parquet-Files (partitioniert nach as_of_date oder year)
• Manifest (Schema, row_count, checksums, label_spec_version, feature_set_version)
• QA Report als separates Artefakt

OpenMetadata & MLflow

OpenMetadata (Lineage)

Im OpenMetadata-Update werden mindestens gepflegt:

• Lineage: dataset_version -> feature_set_version -> training_dataset_version
• Links: label_spec_version, Label-QA Report URI, artifact_uri
• Owner/Tags/Description (kurz, damit Konsumenten wissen, was das Dataset ist)

MLflow (Run-Referenz)

MLflow wird genutzt, um den Run kontextuell zu verankern:

• run_id (Prefect) + pipeline_version (Git/SemVer)
• Contracts als Artefakte (Training Dataset Contract + Label-QA Report)
• Referenzen auf Storage (artifact_uri) und Katalog (openmetadata_entity_ref)

Triggering & Orchestrierung

Label Construction läuft typischerweise im Build-/Retrain-Pfad (nicht im täglichen Scoring-Pfad). In der Praxis heisst das:

• Ein Retrain-Run (zeitbasiert oder on demand) referenziert eine feature_set_version und stösst Label Construction an.
• Der Output (training_dataset_version) ist die saubere Übergabe an Model Training + HPO.

BPMN-Detailansicht

Diagramm wird geladen …

⋮⋮⋮

Glossar-Begriffe

• Feature – reproduzierbar berechnete Eingangsvariable für Modelle
• Feature Store – versionierte Verwaltung publizierter Feature-Sets
• Lineage – Nachvollziehbarkeit von Herkunft und Transformation
• OpenMetadata – zentraler Metadatenkatalog für Owner/Purpose/Lineage
• MLflow – Run-, Artefakt- und Modelltracking
• Output Contract – versionierte, prüfbare Übergabe zwischen Prozessschritten

BPMN-Kontext

• Main BPMN: Gesamtarchitektur
• Schritt (Main): Label Construction (zwischen Feature Pipeline und Model Training + HPO)
• Detail-BPMN (Process): Process_LabelConstruction
• Start: StartEvent_LabelConstruction
• Detail-Tasks: ScriptTask_ResolveInputs, ScriptTask_LoadTargetSeries, ScriptTask_ComputeLabels, ScriptTask_AssembleTrainingDataset, BusinessRuleTask_LabelQA
• Publish/Tracking: ServiceTask_PublishTrainingDataset, ServiceTask_OpenMetadata, ServiceTask_MLflowLog
• Signal: ThrowEvent_TrainingDatasetReady