/ 
Quiq-1.220
River stage zero No dependents
/ Quiq::PlotlyJs::TimeSeries

NAME

Quiq::PlotlyJs::TimeSeries - Zeitreihen-Plot auf Basis von Plotly.js

BASE CLASS

Quiq::Hash

DESCRIPTION

Diese Klasse ist ein Perl-Wrapper für die Erzeugung für Zeitreihen-Plots auf Basis von Plotly.js.

Dokumentation und Beispiele: https://plotly.com/javascript/

Zeitformate: https://github.com/d3/d3/blob/master/API.md#time-formats-d3-time-format

Leeres Diagramm

Ein Konstuktoraufruf ohne jegliche Angaben, also auch ohne Daten, ergibt ein leeres Diagramm. Die X-Achse umfasst den (willkürlich gewählten) Zeitbereich von 2000-01-01 00:00:00 bis 2001-01-01 00:00:00. Die Y-Achse umfasst den (willkürlich gewählten) Wertebereich -1 bis 4.

Diagramm-Höhe

Die Diagramm-Höhe kann im div-Container, in der Layout-Konfiguration oder in beiden gesetzt werden. Die Auswirkungen:

  • Wird die Höhe nur beim div-Container gesetzt, füllt Plotly die Höhe immer ganz aus. Wird z.B. der Rangeslider entfernt, rendert Plotly das Diagramm neu, so dass es wieder die gesamte Höhe ausfüllt. D.h. der Plotbereich wird höher. Der Inhalt des Diagramms ist nicht statisch. Das wollen wir nicht.

  • Wird die Höhe nur in der Layout-Konfiguration gesetzt, hat der div-Container zunächst die Höhe 0, bis das Diagramm (typischerweise im ready-Handler) aufgebaut wird. Das wollen wir auch nicht.

  • Wird die Höhe im div-Container und in der Layout-Konfiguration gesetzt, ist der Bereich des Diagramms auf der Seite sofort sichtbar, der Inhalt kann aber aber statisch gehalten werden, indem beide Angaben gemeinsam geändert werden.

Unterer Rand

Im unteren Rand ist die Beschriftung der X-Achse und der Rangeslider angesiedelt. Die Beschriftung hat einen Platzbedarf von 55 Pixeln, die Dicke des Rangesliders ist auf 20% der Plothöhe eingestellt. Wir nutzen folgende Formel, um aus der Höhe des Diagramms die Höhe des unteren Rands zu berechnen:

bottomMargin = (height - 300) / 50 * 10 + 110;

Das ergibt folgende Werte (height->marginBottom):

250->100, 300->110, 350->120, 400->130, 450->140,...

Wenn wir den Rangeslider entfernen, reduzieren wir die Höhe des Diagramms und den unteren Rand um

marginBottom - 55

Titel-Positionierung

Der Diagramm-Titel wird per Default leider ungünstig positioniert, daher positionieren wir ihn selbst. Damit der Titel oberhalb des Plot-Bereichs positioniert werden kann, muss im Layout container als Bezugsbereich vereinbart werden:

title: {
    yref: 'container',
    yanchor => 'top',
    y => $y0,
}

Hierbei ist $y0 ein Wert zwischen 0 und 1, der die vertikale Position innerhalb des Diagramms festlegt. 1 -> ganz oben unter dem Rand, 0 -> ganz unten unter (!) dem Rand.

Ändert sich die Höhe des Diagramms, muss der Wert y auf die neue Höhe y1 umgerechnet werden:

y1 = 1 - (height0 * (1 - y0) / height1);

Raum unter der Achse einfärben

Ist beim Trace-Layout das Füllen unter der Achse angegeben mit

fill: 'tozeroy',
fillcolor: '#e0e0e0',

wird der Y-Wertebereich nach unten bis 0 ausgedehnt, wenn kein Y-Wertebereich explizit vorgegeben ist. Ist für die Y-Achse (Diagramm-Layout!) explizit ein Wertebereich vorgegeben

range => [900,1000],

findet die Ausdehnung bis 0 nicht statt, der Raum unter der Kurve wird dennoch wie gewünscht gefüllt.

EXAMPLE

(Folgendes Diagramm erscheint in HTML - außer auf meta::cpan, da der HTML-Code dort gestrippt wird - es zeigt 720 Messwerte einer Windgeschwindigkeits-Messung)

METHODS

Konstruktor

new() - Instantiiere Objekt

Synopsis

$plt = $class->new(@attVal);

Attributes

class => $class (Default: 'plotly-timeseries')

CSS-Klasse des div-Containers. Kann zur Definition eines Rahmens, von Außenabständen usw. genutzt werden.

color => $color (Default: '#ff0000')

Farbe der Kurve und Titel (Haupttitel, Titel Y-Achse). Alle Schreibweisen, die in CSS erlaubt sind, sind zulässig, also NAME, #XXXXXX oder rgb(NNN,NNN,NNN). Dies gilt für alle Farben.

height => $n (Default: 400)

Höhe des (gesamten) Diagramms in Pixeln.

name => $name (Default: 'plot')

Name des Plot. Der Name wird als CSS-Id für den Div-Container und als Variablenname für die JavaScript-Instanz verwendet.

title => $str

Titel des Plot. Wird über das Diagramm gesetzt. Typischerweise der Name des gemessenen Parameters.

x => \@x (Default: [])

Referenz auf Array der Zeit-Werte (bevorzugt in JavaScript-Epoch).

y => \@y (Default: [])

Referenz auf Array der Y-Werte (in Weltkoordinaten).

yTitle => $str

Beschriftung an der Y-Achse. Typischerweise die Einheit des gemessenen Parameters.

Returns

Objekt

Description

Instantiiere ein Objekt der Klasse und liefere eine Referenz auf dieses Objekt zurück.

Klassenmethoden

cdnUrl() - Liefere CDN URL

Synopsis

$url = $this->cdnUrl;

Returns

URL (String)

Description

Liefere den CDN URL der neusten Version von Plotly.js.

Example

$url = Quiq::PlotlyJs::TimeSeries->cdnUrl;
==>
https://cdn.plot.ly/plotly-latest.min.js

Objektmethoden

html() - Generiere HTML

Synopsis

$html = $ch->html($h);

Returns

HTML-Code (String)

Description

Liefere den HTML-Code der Plot-Instanz.

js() - Generiere JavaScript

Synopsis

$js = $ch->js;

Returns

JavaScript-Code (String)

Description

Liefere den JavaScript-Code für die Erzeugung Plot-Instanz.

VERSION

1.220

AUTHOR

Frank Seitz, http://fseitz.de/

COPYRIGHT

Copyright (C) 2024 Frank Seitz

LICENSE

This code is free software; you can redistribute it and/or modify it under the same terms as Perl itself.