Charts Definition Language (CDL): Difference between revisions

From Cumulus Wiki
Jump to navigationJump to search
(Created page with "stub")
 
No edit summary
Line 1: Line 1:
stub
== Introduction ==
{|align=right
  |__TOC__
  |}
The Charts Definition Language gives the  user the possibility to define his  own charts on the basis of the CumulusMX infrastructure through the [[ChartsCompiler]]. This article gives the specification of that language.
 
The charts are defined in the definition file (''CutilsCharts.def'' which resides in the ''utils'' directory) which contains one or more chart specifications according to the figure below. All attributes of a plot variable are optional and if not specified have a reasonable default.
 
All white space characters are used as separators so it is easy to make a visually attractive, readable definition file.
 
The text in the ''CutilsCharts.def'' is case independent, however for clarity [https://en.wikipedia.org/wiki/Camel_case CamelCase] or a variety thereof is advised.
 
== The specification ==
[[File:ChartCompilerSpec2.jpg|upright|1300px|left|Chart Compiler Language (CDL) specification ]]
<br clear=all>
 
== The Language ==
=== The Chart block ===
CHART <id> TITLE [<word>...<word>]  CONNECTSto [1 … 24]
  [PLOT [ALL|RECENT] <Plotvariable>
            AS <Line Type>
            COLOUR <HTML Color>
            ZINDEX <Integer>
            LINEWIDTH <Integer>
            OPACITY <Integer>.<Integer>
  ]
 
  PLOT blocks repeated
    [...]
  ENDCHART
 
  CHART […] ENDCHART blocks repeated
 
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.
 
=== Keywords ===
The following PlotVariables are reserved words:
 
==== With the RECENT qualifier ====
      "InsideTemp", "Dewpoint", "ApparentTemp", "FeelsLike", "WindChill", "HeatIndex","Temperature", "Humidex",
      "WindGust", "WindSpeed",
      "Bearing", "AverageBearing",
      "UV", "SolarRadiation", "TheoreticalSolarMax",
      "RainFall", "RainRate",
      "Pressure",
      "Humidity", "InsideHumidity",
      "EvapoTranspiration"
 
==== With the ALL qualifier ====
 
      "MinTemp", "MaxTemp", "AverageTemp", "WindChill", "MaxDewpoint", "MinDewpoint","MaxFeelsLike", "MinFeelsLike",
      "MaxGust", "WindRun", "WindSpeed",
      "UV-Index", "SolarRadiation", "SunHours",
      "RainFall", "MaxRainRate",
      "MinBarometer", "MaxBarometer",
      "MinHumidity", "MaxHumidity",
      "HeatingDegreeDays","CoolingDegreeDays","EvapoTranspiration"
 
=== Graph Types ===
The following charts are possible and can be combined within a chart except for the Scatter
      Line, SpLine, Area, Scatter, Column
 
== Additional details ==
#All parameters can be combined in one graph with the corresponding axis automatically added. Only when scatter is defined as Line Type it is forbidden to combine it with one of the other possibilities. This may change in future.
#The Legend texts are implemented as translations of the PlotKeywords (the Plot Variables). You will find these in the translation file section [Compiler]. Legend entries can be multiple words (the keywords can not).
#The width of the graph container is 100% of the viewport.
#The height of the graph container can be specified in the options (not defined in the language to prevent overcharge):
  [Compiler]
  ChartContainerHeight=650 (Default)
#The Plot Variables Evapotranspiration, CoolingDegreeDays and Heating DegreeDays are not supplied by CMX in the JSONs. CumulusUtils provides those automatically when used in the definitions (on request) with the commandline parameter UserAskedData. See also [[ChartsCompiler#Operation|ChartsCompiler Operation]].
#You have to schedule this command if you wish to use the FTP frequency CMX uses for its JSON's. Note that these JSON files specific to CumulusUtils '''always reside in the website root''' of CumulusUtils, even if you have more websites and define the ''CumulusRealTimeLocation''.
#If the  user uses different locales for CMX and CumulusUtils the monthly log filenames will be according to the locale of CMX. This creates an issue which is solved by the inifile parameter:
  [General]
  MonthsOfMiracleAndWonder=jan,feb,mrt,apr,mei,jun,jul,aug,sep,okt,nov,dec
Default this variable contains the abbreviated month names according to the locale of CumulusUtils. The user may edit those names to the ones used by CMX.
 
== Example CutilsCharts.def ==
The Chart definitions below are a test version operational on meteo-wagenborgen.nl, contains Dutch descriptions and should give you a good impression of the possibilities. As the Ccompiler will develop this code will change.
 
Chart Overzicht Title Overzicht van de huidige weerstatus ConnectsTo 2 4 15 20
  PLOT Temperature Colour #058DC7 zindex 90
  PLOT DewPoint Colour #50B432 zindex 80
  PLOT pressure Colour red zindex 70
  Plot Humidity Colour #64E572 zindex 60
  Plot SolarRadiation As Area Opacity 0.2 Colour Orange zindex 20
  Plot RainFall As Area colour #33B4FF opacity 0.2 zindex 10
EndChart
 
Chart Temperature Title Temperature and Derivatives ConnectsTo 1 13 14
  Plot InsideTemp As Spline Colour #DDDF00 zIndex 100
  PLOT Temperature As SPline Colour #058DC7 zindex 90
  PLOT FeelsLike As SPline Colour #ED561B zindex 80
  PLOT DewPoint As SPline Colour #50B432 zindex 70
EndCHART
 
Chart TempEVT Title Temperature and EVT historical
  PLOT ALL AverageTemp As SPline Colour #058DC7 zindex 90 LineWidth 10
  PLOT ALL Evapotranspiration As Column Colour #cc0000
EndCHART
 
Chart TempEVTRecent Title Temperature and EVT Recently
  PLOT Temperature As SPline Colour #058DC7 zindex 90 LineWidth 10
  PLOT Evapotranspiration As Area Colour #cc0000
EndCHART
 
Chart Wind Title Wind ConnectsTo 5 8
  Plot WindGust
  Plot WindSpeed
EndCHART
 
Chart Windrichting Title Windrichting ConnectsTo 6 7
  Plot Bearing As Scatter
  Plot AverageBearing As Scatter
EndCHART
 
Chart Regen Title Regen and Regensnelheid ConnectsTo 3 21 22
  Plot RainFall As Area Colour green Opacity 0.2
  Plot RainRate zIndex 100
EndChart
 
Chart Vochtigheid Title Relatieve vochtigheid binnen en buiten ConnectsTo 11 16
  Plot Humidity
  Plot InsideHumidity
EndChart
 
Chart Zon Title (Max)Straling en UV ConnectsTo 12 23 24
  Plot UV zIndex 100
  Plot SolarRadiation As Area Opacity 0.4 Colour Orange zIndex 50
  Plot TheoreticalSolarMax As Area Colour Gold zIndex 10 Opacity 0.2
EndChart
 
CHART DagelijkseTemp TITLE Daily Average Temperature with Min/Max of last year
  PLOT DAILY AverageTemp colour green
  Plot DAILY MinTemp colour blue
  Plot DAILY MaxTemp colour red
EndChart
 
Chart DagelijkseRegen Title Daily rainfall of last year
  Plot DAILY RainFall As Column colour lightblue
EndChart
 
Chart DagelijkseZonuren Title Sunhours per day of last year
  Plot ALL SunHours As Column colour gold
EndChart
 
Chart CoolingDays Title Residual variables
  Plot ALL CoolingDegreeDays
  Plot ALL HeatingDegreeDays
  Plot All Evapotranspiration
EndChart

Revision as of 13:41, 17 April 2021

Introduction

The Charts Definition Language gives the user the possibility to define his own charts on the basis of the CumulusMX infrastructure through the ChartsCompiler. This article gives the specification of that language.

The charts are defined in the definition file (CutilsCharts.def which resides in the utils directory) which contains one or more chart specifications according to the figure below. All attributes of a plot variable are optional and if not specified have a reasonable default.

All white space characters are used as separators so it is easy to make a visually attractive, readable definition file.

The text in the CutilsCharts.def is case independent, however for clarity CamelCase or a variety thereof is advised.

The specification

Chart Compiler Language (CDL) specification


The Language

The Chart block

CHART <id> TITLE [<word>...<word>] CONNECTSto [1 … 24] 

 [PLOT [ALL|RECENT] <Plotvariable> 
            AS <Line Type> 
            COLOUR <HTML Color>
            ZINDEX <Integer>
            LINEWIDTH <Integer>
            OPACITY <Integer>.<Integer>
 ]

 PLOT blocks repeated
   [...]
 ENDCHART

 CHART […] ENDCHART blocks repeated

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.

Keywords

The following PlotVariables are reserved words:

With the RECENT qualifier

     "InsideTemp", "Dewpoint", "ApparentTemp", "FeelsLike", "WindChill", "HeatIndex","Temperature", "Humidex",
     "WindGust", "WindSpeed",
     "Bearing", "AverageBearing",
     "UV", "SolarRadiation", "TheoreticalSolarMax",
     "RainFall", "RainRate",
     "Pressure",
     "Humidity", "InsideHumidity",
     "EvapoTranspiration"

With the ALL qualifier

     "MinTemp", "MaxTemp", "AverageTemp", "WindChill", "MaxDewpoint", "MinDewpoint","MaxFeelsLike", "MinFeelsLike", 
     "MaxGust", "WindRun", "WindSpeed", 
     "UV-Index", "SolarRadiation", "SunHours",
     "RainFall", "MaxRainRate",
     "MinBarometer", "MaxBarometer",
     "MinHumidity", "MaxHumidity",
     "HeatingDegreeDays","CoolingDegreeDays","EvapoTranspiration"

Graph Types

The following charts are possible and can be combined within a chart except for the Scatter 

     Line, SpLine, Area, Scatter, Column

Additional details

  1. All parameters can be combined in one graph with the corresponding axis automatically added. Only when scatter is defined as Line Type it is forbidden to combine it with one of the other possibilities. This may change in future.
  2. The Legend texts are implemented as translations of the PlotKeywords (the Plot Variables). You will find these in the translation file section [Compiler]. Legend entries can be multiple words (the keywords can not).
  3. The width of the graph container is 100% of the viewport.
  4. The height of the graph container can be specified in the options (not defined in the language to prevent overcharge):
 [Compiler]
 ChartContainerHeight=650 (Default)
  1. The Plot Variables Evapotranspiration, CoolingDegreeDays and Heating DegreeDays are not supplied by CMX in the JSONs. CumulusUtils provides those automatically when used in the definitions (on request) with the commandline parameter UserAskedData. See also ChartsCompiler Operation.
  2. You have to schedule this command if you wish to use the FTP frequency CMX uses for its JSON's. Note that these JSON files specific to CumulusUtils always reside in the website root of CumulusUtils, even if you have more websites and define the CumulusRealTimeLocation.
  3. If the user uses different locales for CMX and CumulusUtils the monthly log filenames will be according to the locale of CMX. This creates an issue which is solved by the inifile parameter:
 [General]
 MonthsOfMiracleAndWonder=jan,feb,mrt,apr,mei,jun,jul,aug,sep,okt,nov,dec

Default this variable contains the abbreviated month names according to the locale of CumulusUtils. The user may edit those names to the ones used by CMX.

Example CutilsCharts.def

The Chart definitions below are a test version operational on meteo-wagenborgen.nl, contains Dutch descriptions and should give you a good impression of the possibilities. As the Ccompiler will develop this code will change. 

Chart Overzicht Title Overzicht van de huidige weerstatus ConnectsTo 2 4 15 20
 PLOT Temperature Colour #058DC7 zindex 90
 PLOT DewPoint Colour #50B432 zindex 80
 PLOT pressure Colour red zindex 70
 Plot Humidity Colour #64E572 zindex 60
 Plot SolarRadiation As Area Opacity 0.2 Colour Orange zindex 20
 Plot RainFall As Area colour #33B4FF opacity 0.2 zindex 10
EndChart

Chart Temperature Title Temperature and Derivatives ConnectsTo 1 13 14
 Plot InsideTemp As Spline Colour #DDDF00 zIndex 100
 PLOT Temperature As SPline Colour #058DC7 zindex 90
 PLOT FeelsLike As SPline Colour #ED561B zindex 80
 PLOT DewPoint As SPline Colour #50B432 zindex 70
EndCHART

Chart TempEVT Title Temperature and EVT historical
 PLOT ALL AverageTemp As SPline Colour #058DC7 zindex 90 LineWidth 10
 PLOT ALL Evapotranspiration As Column Colour #cc0000
EndCHART

Chart TempEVTRecent Title Temperature and EVT Recently
 PLOT Temperature As SPline Colour #058DC7 zindex 90 LineWidth 10
 PLOT Evapotranspiration As Area Colour #cc0000
EndCHART

Chart Wind Title Wind ConnectsTo 5 8
 Plot WindGust
 Plot WindSpeed
EndCHART

Chart Windrichting Title Windrichting ConnectsTo 6 7 
 Plot Bearing As Scatter
 Plot AverageBearing As Scatter
EndCHART

Chart Regen Title Regen and Regensnelheid ConnectsTo 3 21 22
 Plot RainFall As Area Colour green Opacity 0.2
 Plot RainRate zIndex 100
EndChart

Chart Vochtigheid Title Relatieve vochtigheid binnen en buiten ConnectsTo 11 16
 Plot Humidity
 Plot InsideHumidity
EndChart

Chart Zon Title (Max)Straling en UV ConnectsTo 12 23 24
 Plot	UV	zIndex 100
 Plot 	SolarRadiation As Area Opacity 0.4 Colour Orange zIndex 50 
 Plot	TheoreticalSolarMax As Area Colour Gold zIndex 10 Opacity 0.2
EndChart

CHART DagelijkseTemp TITLE Daily Average Temperature with Min/Max of last year
 PLOT DAILY AverageTemp colour green
 Plot DAILY MinTemp colour blue
 Plot DAILY MaxTemp colour red
EndChart

Chart DagelijkseRegen Title Daily rainfall of last year
 Plot DAILY RainFall As Column colour lightblue
EndChart

Chart DagelijkseZonuren Title Sunhours per day of last year
 Plot ALL SunHours As Column colour gold
EndChart

Chart CoolingDays Title Residual variables
 Plot ALL CoolingDegreeDays
 Plot ALL HeatingDegreeDays
 Plot All Evapotranspiration
EndChart
Retrieved from "https://www.cumuluswiki.org/index.php?title=Charts_Definition_Language_(CDL)&oldid=8627"