3. HistoryPanel (historisches Datenpanel)

In diesem Kapitel wird HistoryPanel vorgestellt: Aufbauend auf einem Verständnis von DataType zeigt es, wie historische Daten aus mehreren Zielen, Metriken und derselben Zeitachse in einem einzigen „Panel“ konsolidiert und in der Strategieforschung, Backtesting-Vorbereitung und Visualisierung wiederverwendet werden können. Zum Lesen dieses Kapitels ist keine vorherige Lektüre von Lokale Datenquelle erforderlich. Wenn Sie Ihre lokale Datenquelle jedoch noch nicht mit Daten gefüllt haben, schließen Sie bitte den Download und die Konfiguration ab, bevor Sie „get_history_data“ zum Abrufen von Daten verwenden.

Im vorherigen Kapitel haben wir gesehen, dass „qteasy“ DataType verwendet, um die „Rohspalten in der Datentabelle“ in Informationen zu abstrahieren, die direkt von der Strategie und dem Backtesting verwendet werden können. Wenn diese Informationen mit mehreren Zielen und verschiedenen Datentypen (wie OHLC, Volumen, MACD usw.) auf dieselbe Zeitachse ausgerichtet werden müssen, ist die manuelle Verkettung mehrerer „DataFrames“ nicht nur fehleranfällig, sondern behindert auch die Wiederverwendung derselben Datenstruktur zwischen dem Strategiecode und dem Visualisierungscode.

HistoryPanel ist ein Container, der für dieses Szenario entwickelt wurde: Intern organisiert er Daten in einer dreidimensionalen Struktur aus Aktien × Index × htypes, sodass Sie Aktien oder Metriken mithilfe einer einheitlichen Schnittstelle aufteilen und filtern und dasselbe Objekt für nachfolgende Backtests, Strategielogiken oder Plots wiederverwenden können. Für die meisten Benutzer müssen Sie sich keine Gedanken darüber machen, wie das Panel intern mit der lokalen Datenquelle interagiert. Nachdem Sie den HistoryPanel über bekannte Arbeitsabläufe wie get_history_data erhalten haben, können Sie ihn als „zeitlich ausgerichteten, mehrfach geteilten, multimetrischen Datensatz“ verwenden.

In diesem Kapitel werden die Kernkonzepte und allgemeinen Verwendungszwecke von HistoryPanel erläutert. Das nächste Kapitel, HistoryPanel Visualization, baut darauf auf und stellt vor, wie man hp.plot() verwendet, um dasselbe Panel direkt als statisches oder interaktives Diagramm darzustellen. Die Datenabruf-API-Funktionen auf niedrigerer Ebene werden in API-Referenz nur kurz aufgeführt, um Verwechslungen mit gängigen Pfaden zu vermeiden.

3.1. Kernkonzepte: 3D-Struktur und shape

Der HistoryPanel entspricht einem dreidimensionalen „numpy.ndarray“ im Speicher, mit den drei Achsen wie folgt:

Achse

Bedeutung

Gemeinsame Eigenschaften

第 0 维

Ziel (Bestandscode usw.)

shares、level_count

第 1 维

Zeit (historisches Datum oder Moment)

hdates、row_count

第 2 维

Datentypen (z. B. open, close, vol)

htypes、column_count

„Shape“ gibt (Anzahl der Ziele, Zeitdauer, Anzahl der Datentypen) zurück, in der gleichen Reihenfolge wie oben. Es kann wie folgt verstanden werden: Viele zweidimensionale Tabellen von „Zeit × Metrik“ werden in der Zielrichtung übereinander gestapelt; Innerhalb desselben Panels werden die Ziele und Kennzahlen zeitlich aufeinander abgestimmt.

Im Vergleich zu einer Single-Index-Breittabelle „DataFrame“ (Zeilen sind Zeit, Spalten sind Indizes) platziert HistoryPanel Multi-Index explizit in der 0. Dimension, was Stapeloperationen und indexbasiertes Slicing erleichtert, ohne dass mehrere „MultiIndex“-Spalten verwaltet werden müssen.

(Anschauliches Diagramm: Der „3D-Block“ kann als L-Ebenenindex × R-Zeilenzeit × C-Spaltenindex verstanden werden; eine Illustration kann bei Bedarf in einer späteren Version hinzugefügt werden.)

3.2. So erhalten Sie HistoryPanel

Der empfohlene Ansatz ist die Verwendung von **qt.get_history_data(..., as_data_frame=False): Vorausgesetzt, die erforderlichen Daten sind bereits in der lokalen Datenquelle verfügbar, können Sie das ausgerichtete HistoryPanel erhalten, indem Sie htype_names (im Einklang mit der DataType-Benennung, siehe vorheriges Kapitel) zusammen mit shares, dem Zeitbereich oder rows angeben.

Standardmäßig setzt „get_history_data“ „as_data_frame“ auf „True“ und gibt ein nach Index gruppiertes dict[str, DataFrame] zurück, das für die schnelle Anzeige von Einzelindexdaten geeignet ist. Wenn ein 3D-Panel erforderlich ist, müssen Sie unbedingt „as_data_frame=False“ übergeben. Vollständige Informationen zu Parametern, Häufigkeit und Gewichtung finden Sie unter Historische Daten-API.

Das folgende Beispiel ist nicht auf das Netzwerk angewiesen und verwendet ein kleines Array zum Aufbau des Panels, was das Verständnis der „Form“ und Beschriftungen erleichtert; In der tatsächlichen Arbeit kann „get_history_data“ stattdessen verwendet werden, um es aus einer lokalen Datenquelle zu füllen.

import numpy as np
import pandas as pd
from qteasy import HistoryPanel

# 2 只标的、4 个交易日、3 种数据类型 → shape (2, 4, 3)
values = np.array(
    [
        [[1.0, 1.1, 100], [1.2, 1.3, 110], [1.15, 1.2, 105], [1.25, 1.28, 120]],
        [[10.0, 10.5, 200], [10.2, 10.8, 210], [10.1, 10.4, 205], [10.3, 10.9, 215]],
    ],
    dtype=float,
)
hp = HistoryPanel(
    values=values,
    levels=['000001.SZ', '000002.SZ'],
    rows=pd.date_range('2025-01-02', periods=4, freq='B'),
    columns=['open', 'high', 'vol'],
)
print(hp.shape)          # (2, 4, 3)
print(hp.shares)         # 标的列表
print(hp.htypes)         # 数据类型列表

Wenn bereits lokale Marktdaten verfügbar sind, können diese wie folgt geändert werden:

import qteasy as qt

hp = qt.get_history_data(
    htype_names='open, high, low, close, vol',
    shares='000001.SZ',
    rows=60,
    as_data_frame=False,
)
print(hp.shape, hp.shares, hp.htypes)

3.3. Grundoperationen: Zeitbereich, Ziel und Indikatorteilmenge

Die folgenden Methoden grenzen Ihren aktuellen Fokus ein, ohne die Datenabrufsemantik zu ändern; Der Rückgabewert ist immer noch „HistoryPanel“ (außer bei leeren Panels).

  • Nach Datumsbereich: segment(start_date, end_date), alle Zeitzeilen innerhalb des geschlossenen Bereichs; Die Daten können mit der Granularität in „hdates“ übereinstimmen (tägliche Häufigkeit, Intraday usw.).

  • Nach Zeilennummernbereich: „isegment(start_index, end_index)“ eignet sich ähnlich wie das Python-Slicing zum Extrahieren von Segmenten nach Position.

  • **Zuletzt aktuelle Zeilen: head(n) / tail(n).

  • Filtern nach Ziel- und/oder Indikatorname: slice(shares='A, B', htypes='close, vol'), entweder eine Zeichenfolge oder eine Liste ist akzeptabel.

Wenn Sie eine pandas-Analyse für Einzelindex- oder Multi-Index-Daten durchführen, können Sie „to_share_frame(share)“ verwenden, um einen „DataFrame“ für diesen Index zu erhalten (mit time als Index und „htypes“ als Spalten). Weitere Informationen zum Exportieren von Multi-Index-Daten finden Sie in der API-Dokumentation für „to_df_dict“ und anderen zugehörigen Dokumentationen.

Im „Operator“- und Backtesting-Prozess werden historische Daten häufig in Gruppen während der Planungsphase der Strategieausführung eingefügt; Spezifische Parameter und Zeitplankonfigurationen finden Sie im entsprechenden Kapitel von „Erstellung und Betrieb von Handelsstrategien“. Hier reicht es aus, Folgendes festzulegen: Strategien und Visualisierungen können sich beide um denselben HistoryPanel (oder seine Slices) drehen, wodurch die sich wiederholende Organisation „eines Datensatzes in mehreren Formaten“ reduziert wird.

3.4. Metriken und Spaltenerweiterungen (kline usw.)

Aufbauend auf der bestehenden Preisklasse „htypes“ können Sie über den Accessor hp.kline auf gängige abgeleitete Spalten wie gleitende Durchschnitte, MACD und Bollinger-Bänder zugreifen. Diese Methoden geben normalerweise ein neues „HistoryPanel“ zurück: Anhängen von Indikatorspalten an die dritte Dimension, ohne das ursprüngliche Objekt zu ändern und wobei „Shares“ und „hdates“ mit dem ursprünglichen Panel konsistent bleiben. Angepasste Spaltennamen (z. B. „close|b“) werden in neueren Versionen an die Parsing-Logik von „kline“, „returns“ usw. angepasst; Wenn im Panel sowohl rohe als auch angepasste Spaltennamen vorhanden sind, wird empfohlen, die Verhaltensbeschreibung in der HistoryPanel API zu lesen.

Ausführlichere Beispiele für faktorbasierte Methoden (Renditen, Volatilität, „apply_ta“ usw.) finden Sie im Tutorial Verwenden von HistoryPanel zum Bearbeiten und Analysieren historischer Daten.

3.5. Zusammenfassung und nächste Schritte

  • HistoryPanel bietet einen einheitlichen Container von (Ziel × Zeit × Datentyp), der für die Recherche und Backtesting-Vorbereitung mit mehreren Zielen, mehreren Metriken und Zeitausrichtung geeignet ist.

  • Die Funktion „get_history_data(…, as_data_frame=False)“ wird üblicherweise zum Abrufen des Datenrahmens verwendet. Standardmäßig können Sie zuerst das vorherige Kapitel über die Benennung von DataType und „get_dtype_map()“ lesen.

  • Slices und Teilmengen: segment / isegment / head / tail / slice; Exportieren eines einzelnen Frames: to_share_frame.

  • Nächstes Kapitel HistoryPanel Visualization: Verwenden von hp.plot() zum Erstellen statischer oder interaktiver Diagramme.

  • Wenn lokale Daten nicht bereit sind, lesen Sie bitte zuerst Lokale Datenquelle und Datenabruf und Kanäle.