Charts Definition Language (CDL): Difference between revisions

From Cumulus Wiki
Jump to navigationJump to search

Charts Definition Language (CDL) (view source)

Revision as of 10:09, 20 July 2021

703 bytes removed ,  10:09, 20 July 2021
m
→‎Explanation of the definition Keywords
(13 intermediate revisions by the same user not shown)
Line 17: Line 17:
== The Language ==
== The Language ==
=== The Chart block ===
=== The Chart block ===
CHART <id> TITLE [<word>...<word>]  CONNECTSto [1 … 24]
  CHART <id> TITLE [<word>...<word>]  CONNECTSto [1 … 24]
   [PLOT [ALL|RECENT] <Plotvariable> [EVAL '[' <Expression> ']'
 
   [ PLOT [ALL|RECENT] <Plotvariable> [ [[CDL - EVAL|EVAL]] '[' <Expression> ']' ]
             AS <Line Type>  
             AS <Line Type>  
             COLOUR <HTML Color>
             COLOUR <HTML Color>
Line 26: Line 27:
             AXIS <Axis Type>
             AXIS <Axis Type>
   ]
   ]
   [ STATS <Plotvariable> <Stats Type> ]
   [ [[CDL - STATS|STATS]] <Plotvariable> <Stats Type> ]


   PLOT blocks repeated
   PLOT blocks repeated
   STATS blocks repeated
   STATS blocks repeated
     [...]
     [...]
   ENDCHART OUTPUT <filespec>
   ENDCHART OUTPUT <filespec>


   CHART […] ENDCHART blocks repeated
   CHART […] ENDCHART blocks repeated
Line 38: Line 39:
Plot blocks can be repeated as many times as you wish but different parameters can result in many yAxis (making the plot area smaller) and the chart may become crowded and unreadable. Experiment and try-out.
Plot blocks can be repeated as many times as you wish but different parameters can result in many yAxis (making the plot area smaller) and the chart may become crowded and unreadable. Experiment and try-out.


Syntactically the Stats block can be many as well but it requires semantically the Plotvariable of which you want statistics to be plotted normally. So you can have e.g. three STATS blocks for one PLOT block.
Syntactically the [[CDL - STATS|STATS]] block can be many as well but it requires semantically the Plotvariable of which you want statistics to be plotted normally. So you can have e.g. three [[CDL - STATS|STATS]] blocks for one PLOT block.


=== Output specifier ===
=== Output specifier ===
Line 50: Line 51:
All capital written words in the Chart block section are keywords (reserved words) and have meaning.
All capital written words in the Chart block section are keywords (reserved words) and have meaning.


The following PlotVariables are also reserved words:
==== Explanation of the definition Keywords ====
#EQUATIONS: Starts an equations block. Such block only defines (partial) equations, it does not cause code generation in itself
#CHART: Starts a chart definition
#TITLE: Starts the title. All words until the next keyword comprise the title of the chart
#CONNECTSTO: The integer numbers which follow CONNECTSTO represent a pane in the realtime [[Dashboard|dashboard]]. When clicked on that pane this chart appears. This is only valid on charts in the default output. For other outputs there is no semantics for CONNECTSTO and a warning is issued in the logfile if it is specified in any second or higher output.
#PLOT: Starts the plot specification using one of the possible variables
#[[CDL - STATS|STATS]]: Starts the statistics block using one of the possible variables. Semantics demands the variable to be plotted normally as well.
#ALL: Defines the variable to be taken from the [[Dayfile.txt|Dayfile]] and all data for that variable will be plotted (Note that the CMX parameter ''ChartMaxDays'' will not be used)
#RECENT: Defines the variable to be governed by the CMX parameter ''GraphHours'' and are similar to the CMX RECENT graphs (though not equal).
#AS: Defines the type of charting for that variable.
#[[CDL - EVAL|EVAL]] [ ]: Defines an expression for the plot variable. The equation must be placed between the square brackets, space has no value here (does not act as separator).
#COLOUR: Defines the colour of that variable.
#ZINDEX: Defines the zIndex plane for that variable.
#LINEWIDTH: Defines the linewidth for that variable.
#OPACITY: Defines the opacity for that variable (important for area and column graphs)
#AXIS: Gives the user the possibility to specify an axis when using the EVAL construct otherwise an error is generated.
#ENDCHART: End the chart definition
#OUTPUT: Gives an optional name of an outputfile which starts at the chart where it is defined. Any chart after this OUTPUT specifier goes to this OUTPUT until another OUTPUT is found. Only the first OUTPUT specifier accepts click events as defined by CONNECTSTO.
 
The keywords for the actual parameters and the Graph Types speak for themselves.


==== With the RECENT qualifier ====
==== Plotvariables ====
The following PlotVariables are reserved words:
 
===== With the RECENT qualifier =====
       "InsideTemp", "Dewpoint", "ApparentTemp", "FeelsLike", "WindChill", "HeatIndex","Temperature", "Humidex",
       "InsideTemp", "Dewpoint", "ApparentTemp", "FeelsLike", "WindChill", "HeatIndex","Temperature", "Humidex",
       "WindGust", "WindSpeed",
       "WindGust", "WindSpeed",
Line 62: Line 85:
       "EvapoTranspiration"
       "EvapoTranspiration"


==== With the ALL qualifier ====
===== With the ALL qualifier =====


       "MinTemp", "MaxTemp", "AverageTemp", "WindChill", "MaxDewpoint", "MinDewpoint","MaxFeelsLike", "MinFeelsLike",  
       "MinTemp", "MaxTemp", "AverageTemp", "WindChill", "MaxDewpoint", "MinDewpoint","MaxFeelsLike", "MinFeelsLike",  
Line 72: Line 95:
       "HeatingDegreeDays","CoolingDegreeDays","EvapoTranspiration"
       "HeatingDegreeDays","CoolingDegreeDays","EvapoTranspiration"


==== Graph Types ====
==== Types ====
===== Graph Types =====
The following graphs are possible  
The following graphs are possible  
       Line, SpLine, Area, Scatter, Column, ColumnRange
       Line, SpLine, Area, Scatter, Column, ColumnRange
Line 80: Line 104:
ColumnRange only works for DAILY and ALL range specifiers. If the Max and Min lines of the range must be shown, they need to be specified as a separate line. The range can be specified for either Min or Max, the range will automatically be applied and no line will be shown. The ColumnRange is valid for all variables in the datafile with a Max/Min range: ''Temperature, Dewpoint, FeelsLike'' (and other derivatives), ''Barometer'' and ''Humidity''. Other variables will generate an error.
ColumnRange only works for DAILY and ALL range specifiers. If the Max and Min lines of the range must be shown, they need to be specified as a separate line. The range can be specified for either Min or Max, the range will automatically be applied and no line will be shown. The ColumnRange is valid for all variables in the datafile with a Max/Min range: ''Temperature, Dewpoint, FeelsLike'' (and other derivatives), ''Barometer'' and ''Humidity''. Other variables will generate an error.


==== Axis Types ====
===== Axis Types =====
The following Axis are possible.  
The following Axis are possible.  
       Temp, Wind, Distance, Hours, Solar, UV, Rain, Rrate, Pressure, Humidity, DegreeDays, EVT
       Temp, Wind, Distance, Hours, Solar, UV, Rain, Rrate, Pressure, Humidity, DegreeDays, EVT


This only has meaning if there is an EVAL with a valid expression present. As an EVAL may modify the value of the plot variable to something completely different, the original Axis belonging to that plot variable may be useless or scale wrongly. Therefore you can choose your own Axis. If there is no valid equation, a warning is given and no axis is generated.
This only has meaning if there is an [[CDL - EVAL|EVAL]] with a valid expression present. As an [[CDL - EVAL|EVAL]] may modify the value of the plot variable to something completely different, the original Axis belonging to that plot variable may be useless or scale wrongly. Therefore you can choose your own Axis. If there is no valid equation, a warning is given and no axis is generated.


In future a generic (without title or unit) Axis will selectable to accommodate plotting in combination with other variables.
In future a generic (without title or unit) Axis will selectable to accommodate plotting in combination with other variables.


==== Explanation of the definition Keywords ====
===== Other Types =====
#CHART: Starts a chart definition
For other types such as STATS types (or methods) and FUNCTION types for EVAL, see those respective pages for [[CDL - STATS|STATS]] and for [[CDL - EVAL|EVAL]].
#TITLE: Starts the title. All words until the next keyword comprise the title of the chart
#CONNECTSTO: The integer numbers which follow CONNECTSTO represent a pane in the realtime dashboard. When clicked on that pane this chart appears. This is only valid on charts in the default output. For other outputs there is no semantics for CONNECTSTO and a warning is issued in the logfile if it is specified in any second or higher output.
#PLOT: Starts the plot specification using one of the possible variables
#STATS: Starts the statistics block using one of the possible variables. Semantics demands the variable to be plotted normally as well.
#ALL: Defines the variable to be taken from the [[Dayfile.txt|Dayfile]] and all data for that variable will be plotted (Note that the CMX parameter ''ChartMaxDays'' will not be used)
#RECENT: Defines the variable to be governed by the CMX parameter ''GraphHours'' and are similar to the CMX RECENT graphs (though not equal).
#AS: Defines the type of charting for that variable.
#EVAL [ ]: Defines an expression for the plot variable. The equation must be placed between the square brackets, space has no value here (does not act as separator).
#COLOUR: Defines the colour of that variable.
#ZINDEX: Defines the zIndex plane for that variable.
#LINEWIDTH: Defines the linewidth for that variable.
#OPACITY: Defines the opacity for that variable (important for area and column graphs)
#AXIS: Gives the user the possibility to specify an axis when using the EVAL construct otherwise an error is generated.
#ENDCHART: End the chart definition
#OUTPUT: Gives an optional name of an outputfile which starts at the chart where it is defined. Any chart after this OUTPUT specifier goes to this OUTPUT until another OUTPUT is found. Only the first OUTPUT specifier accepts clickevents as defined by CONNECTSTO.
 
The keywords for the actual parameters and the Graph Types speak for themselves.
 
===== EVAL =====
The EVAL requires probably some explanation.
 
The equation is formulated between square brackets and is meant to modify a weather variable. Available to the user are functions, the weather variables and the mathematical operators +, -, * and /. Currently  the only function available is SUM which incrementally sums up all data leading to the Growing Degree Days graph. Other functions will follow.
 
The following example shows the daily average temperature modified to the Growing Degree Days with an offset of 5 °C:
 
  CHART GrowingDgreeDays TITLE TempSum with offset 5
    PLOT ALL AverageTemp colour CornflowerBlue as column
    PLOT ALL AverageTemp EVAL [ SUM(AverageTemp-5) ] colour green Axis DegreeDays
  EndChart
 
===== STATS =====
[[File:Schermafbeelding 2021-05-21 154949.jpg|right|Rain with statistics and cumulation curve]]
The STATS plots a statistic in the chart. The normal PLOT of that variable must be present. STATS implies the ALL or DAILY range specification. RECENT PLOTS have no STATS (at the moment).


The following example shows the Rain for all days (all observations). In addition the yearly cumulative curve is shown and the moving average (SMA - Simple Moving Average). See image on the right.
=== Equations ===
'''The Equations are in BETA, by the nature of all possible combinations and the recursive parsing not all possible equations have been tested (haha)'''


  CHART DailyRain TITLE Rain with statistics
See page [[CDL - EVAL]].
    PLOT ALL RainFall colour CornflowerBlue as column
    PLOT ALL RainFall EVAL [ SUM( RainFall ) ] COLOUR crimson AXIS Free
    STATS RainFall SMA colour green
  EndChart OUTPUT Statistics.txt


== The Chart Axis ==
== The Chart Axis ==
Line 150: Line 138:
#DegreeDays
#DegreeDays
#EVT
#EVT
#Free (has no title, unit or context associated with it. It just displays values)


Translations for the axis titles come from the [Website] section and should require no additional effort.
Translations for the axis titles come from the [Website] section and should require no additional effort.
Retrieved from "https://www.cumuluswiki.org/a/Special:MobileDiff/8978...9473"

Navigation menu