Charts
Introduction
One of the most important modules of CumulusUtils is the charting module as it gives insight in your weather data. A picture says more than a thousand words. The charting is subdivided in five sections: Rain charts, Temperature charts, Solar charts and Wind charts. Miscellaneous completes the charts.
And if you run the Website Generator, the Home page shows the charts similar (almost equal) to the charts which default to the CumulusMX Recent Charts page and CumulusMX Historic Charts page. From end of 2020 CumulusUtils begins to deviate in charting approach from CumulusMX with respect to those default charts.
This page describes only the common features and requirements, the graphs themselves are discussed on their own page. Please note that the words chart and graph are used interchangably. Within CumulusUtils however in a stricter sense mostly graph is intended.
The charts are created using HighCharts using their non-commercial license. If you want to use the charts or the Website Generator of CumulusUtils, please make yourself acquainted with this license.
Operation
This module is included in the website. When needed as a single output the following command is given:
utils/bin/cumulusutils.exe graphs
The Home page charts of the website will be described there.
Output
The output consists of five files: graphstemp.txt, graphsrain.txt, graphswind.txt, graphssolar.txt and graphsmisc.txt.
These files contain, embedded in HTML code, both the menu code in javascript (each file has its own selection menu) and the Highcharts code in javascript for the charts and the data.
Inifile parameters
The charting module is second in place of modules with the most parameters (the Website Generator being first) and also require more explanation. Note that the charts on the Home page of the Website have their own explicit colour specifications. When useful or required, these descriptions will be repeated on
All parameters belong to the section [graphs]:
[Graphs]
All charts can be individually selected to be present or not. If the value of the following parameters is false the chart and its data will be generated to the output, but the menu choice will not be present so the user can't select.
Rain graphs:
DailyRain=true MonthlyRain=true YearRainstats=true YearMonthRainstats=true
Temperature charts:
MonthlyTemp=true YearTempstats=true YearMonthTempstats=true WarmerDays=true HeatMap=true
Wind charts:
WindRose=true Windrun=true
Solar charts:
SolarHours=true SolarEnergy=true SolarHoursYearMonth=true SolarEnergyYearMonth=true
Miscellaneous charts:
TempSum=true GrowingDegreeDays=true Seasons=true => For the Thermal Seasons chart DailyEVT=true MonthlyEVT=true AverageClash=true
Chart parameters:
UseHighchartsBoostModule=true | false UseNormalTempReference=both | Normal | StationAverage (default = Normal) UseNormalRainReference=both | Normal | StationAverage (default = Normal) MaxNrOfSeriesVisibileInGraph=3 (default = 2) PeriodMovingAverage=365 (default = 180) WindRoseNrOfWindforceClasses=6 (default = 6) WindRoseMaxWindSpeed=60 (default = 60) WindRoseInversed=false | true (default = false) WindrunClassWidth=75 (default = 75) HeatmapNumberOfYearsPerPage=10 (default = 10) GrowingDegreeDaysReferenceTemp=5 (default = 5) WinterToSpringTemperatureLimit=0 (default = 0) SpringToSummerTemperatureLimit=10 (default =10)
Map Colour parameters (see Charts behaviour)
GraphColors= ;GraphColors=['#058DC7', '#50B432', '#ED561B', '#DDDF00', '#24CBE5', '#64E572', '#FF9655', '#FFF263', '#6AF9C4'] WindRoseColors= ;WindRoseColors=['lightgrey', 'green', 'blue', 'yellow', 'orange', 'red', 'deeppink', 'purple', 'black']
Inner working
Algorithmic
The output files are HTML UTF8 format. All javascript is included in <script> tags so these are not pure javascript libraries. For each output file the javascript menu is written. When finished the Highcharts lib include specifications are written IF the modules are not meant to be used in the CumulusUtils Website Generator which has the specifications by itself.
When menu and includes are ready, all required graphs are generated together with their data. Code generation and data selection is a one pass process.
Defaults, Colours and Language
Defaults
Defaults are taken from the Highcharts theme which is current. See the page for the HighCharts theme.
Colours
NOTE: the colours of the lines in the Website Generator Home page have their own specification, see the Website Generator and ChartsCompiler.
A very important thing with the graphs is the Colour selection. For some charts, users can specify colours in multiples ways for other charts no specification is possible. In general for line charts, the user can choose the colour per line, for specific charts like the heatmap no choice is possible. See each chart description for the specification. If any colour specification in reality is not according to this specification, please report as a bug (either in documentation of in software)
Where applicable, use is made of the Highcharts colour specification.
- A set of default colours can be specified in the parameter section. For the WindRose a specific selection can be specified.
- When the selection possibility set to empty a fallback is made to the HighCharts theme in use.
- When no colours are specified in the theme, then the user relies on the implicit Highcharts defaults.
Language
For the Language in the charts the user must make a distinction between the texts CumulusUtils generates for titles, series names and tooltips. Those texts are found in the CUstringsXX.txt file and have to be translated by the user. For Locale specific and ruled translations (like weekdays, months etc...) CumulusUtils generates a file called HighchartsLanguage.js in which names of days, months and abbreviated month names are translated conform the Locale the user specifies. These are set as options to Highcharts and thus will always be in the local language.
This file may also be used for other Locale specific attributes like separators, if so, it will be specified here.
How the parameters work
There is only a limited number of parameters which influence the behaviour and display of the graph. Those parameters are described below:
UseHighchartsBoostModule
For some charts like the scatter (Wind direction) and the heatmap, Highcharts makes use of a boost technique (library: https://code.highcharts.com/modules/boost.js). However this does not work on some browsers on some older graphic cards. If you do not see the chart, please set this parameter to false. It may slow down the drawing of the chart, but you will see it.
UseNormalTempReference
This parameter has effect on the Monthly Temperature chart.
CumulusMX has the possibility to refer to the normal values valid for the location of the weather station. The user has to fill those in the CumulusMX inifile parameter section [NOAA] in the parameters NOAATempNormJan and NOAARainNormJan (for all months). When filled in those values appear in the Monthly Rain and Monthly Temperature graphs. If they are not specified the value -1000 is shown which heavily debalances the chart.
When Normal values are not available, the user may choose to display StationAverage for those charts. StationAverage also displays the unbiased estimator of the variance (standard deviation) around the average of the observations.
When setting the parameter to both the obvious thing happens: both the Normal and the StationAverage are displayed along with the actual observations.
UseNormalRainReference
This parameter has effect on the Daily rain chart and the Monthly Rain chart.
The functional behaviour of this parameter is similar to the above.
In addition, this parameter determines the presence of the reference lines for the Normal Total Rainfall and/or the Station Average Rainfall as shown in the Daily Rain chart.
MaxNrOfSeriesVisibileInGraph
This parameter has effect in both Monthly Temperature, Monthly Rain and the Agri Charts.
A high number of series shown can severely clutter the chart. Therefore the user can limit the number of lines initially made visible. When the chart is on screen, the user can click on the legend to show additional charts.
PeriodMovingAverage
This parameter has effect on the Daily Rain chart and the Daily EVT chart.
The running average as shown in the Daily Rain and Daily EVT charts, shows a Simple Moving Average. The period of that moving average - or the number of days in the current value of the moving average - can be set through this parameter.
WindRoseNrOfWindforceClasses & WindRoseMaxWindSpeed
These parameters have effect on the Wind Rose chart.
Because wind differs highly with location and above all also with unit used it is necessary to make a meaningful division of the legend. The WindRoseMaxWindSpeed gives the highest wind speed class. All higher wind speed will be counted as higher the and will not be subdivided. The WindRoseNrOfWindforceClasses gives the number of classes where the winds lower than WindRoseMaxWindSpeed will be subdivided. So if the max wind speed is 60 km/h and the number of classes is 6 you get a class width of 10 km/h. But if you use the same numbers for m/s or mph you get completely different graphs. So it is the unit and the local conditions which determine the numbers you have to use.
A wind silence (Calm, 0 km/h) is an always present class and thus not counted in the calculation as above.
WindRoseInversed
This parameter has effect on the Wind Rose chart.
This parameter determines the order of the legend and the stacking of the values in the rose from inside to outside or the other way around.
WindrunClassWidth
This parameter has effect on the Windrun chart.
With the same arguments as with the WindRose chart, the Windrun chart requires some configuration because of unit and local situation. To give the chart meaning a class width which shows but not clutters is best. It is also personal taste which counts.
HeatmapNumberOfYearsPerPage
This parameter has effect on the Heatmap.
The heatmap does get a bit compressed when the series get longer. If more than ten years are available the years are split up in pages and buttons appear to switch between pages or display all data. This has to do with taste. There is also the button All which gives the user the possibility to undo the split.
GrowingDegreeDaysReferenceTemp
This parameter contains the reference temperature for the chart Growing Degree Days and represents the heuristic temperature at which plants come out of their winter rest. In principle the chart Temperature Sum has a non modifiable reference temperature of 0.
WinterToSpringTemperatureLimit
With a default of zero degrees Celsius this parameter defines the thermal boundary between winter and spring. If 10 successive days have an average temperature above 0 °C then Spring is declared. The same boundary works the other way around to declare transition from autumn to winter.
SpringToSummerTemperatureLimit
With a default of 10 °C this parameter defines the thermal boundary between spring and summer. If 10 successive days have an average temperature above 10 °C then Summer is declared. The same boundary works the other way around to declare transition from summer to autumn.