Charts Definition Language (CDL)
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 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 OUTPUT <filespec>
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.
An output file can be specified for each chart by putting OUTPUT <filename> after an ENDCHART. All charts from that point on will be written to that specified output until a new output is specified for another chart. If no output is specified at all, all charts will be written to cumuluscharts.txt (the default output)
If you are using the website it is important to know that the first chart will always be used as the chart for the Home page button and that cannot be changed (the file is always cumuluscharts.txt). If, however you specify an output on the first chart, that chart will be duplicated in the output you specify.
The output specifier gives the user the possibility to define charts as he likes and to place these in the menu wherever he likes. In the Website Generator the placements of the charts at the moment will be limited to the User Defined Menu. In modular use the user can do whatever he likes with the resulting files. In the website the charts require the datafiles to be in the current directory.
All capital written words in the Chart block section are keywords (reserved words) and have meaning.
The following PlotVariables are also 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"
The following charts are possible and can be combined within a chart except for the Scatter
Line, SpLine, Area, Scatter, Column
Explanation of the definition Keywords
- 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. 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
- ALL: Defines the variable to be taken from the 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.
- 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)
- 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.
- 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.
- 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:
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.
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 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 OUTPUT AllTempChart.txt
Chart DagelijkseRegen Title Daily rainfall of last year Plot DAILY RainFall As Column colour lightblue EndChart OUTPUT AllRainChart.txt
Chart DagelijkseZonuren Title Sunhours per day of last year Plot ALL SunHours As Column colour gold EndChart OUTPUT AllSolarChart.txt
Chart TempEVT Title Temperature and EVT historical ConnectsTo 12 23 24
PLOT ALL AverageTemp As SPline Colour #058DC7 zindex 90 LineWidth 10 PLOT ALL Evapotranspiration As Column Colour #cc0000 EndCHART OUTPUT RarityCharts.txt
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 CoolingDays Title Residual variables Plot ALL CoolingDegreeDays Plot ALL HeatingDegreeDays Plot All Evapotranspiration EndChart