Reports folder

This page is 'Work In Progress' so any contributor can add further content.

Introduction

All flavours of Cumulus software include in their release distribution, a sub-folder called Reports. Please note that it starts with a capital letter, whilst (for Cumulus 1 and 2, all; for MX, most) other folders have totally lower case names.

In enhancement request 44 (for Cumulus 1, the enhancement register is no longer available), someone asked Steve Loft to consider producing some monthly, and yearly Climate reports using the weather data that Cumulus software processed, and making comparisons against 20 year normals for that sort of area. These reports are generated and stored in the Reports folder if you choose to turn on the NOAA report option in the configuration settings (in Cumulus 1 see Configuration_Menu_Screens, see NOAA_report_settings in MX).

A brief history of these reports

Cumulus 1, 2, and MX, generate climatological reports for both Monthly and Yearly periods.

The reports were first added to Cumulus 2 after someone asked, in enhancement request 44, if Cumulus software could copy what a rival weather software package (Weatherlink) did and output some climatological reports.

Steve Loft did some investigation, and found that Ken True had implemented the Weatherlink reports in his Saratoga suite, so Steve Loft took that as his starting point (see Steve's post on the Cumulus Support Forum for more details).

These Saratoga reports were based on climatological reports (annnual report and monthly report), issued by The US National Oceanic and Atmospheric Administration's National Weather Service (the reason why Steve Loft decided to use NOAA in the naming of the reports).

Steve Loft had abandoned work on Cumulus 1 at the time he worked on this enhancement request, so the first implementation was in Cumulus 2 as Steve was developing that at the time.

Subsequently, Steve Loft abandoned Cumulus 2, so his NOAA report design was added to Cumulus 1, this was in version 1.9.2 (build 1004) released in July 2011.

When Steve Loft first started work on Cumulus 3 (MX) beta, he initially did NOT include this climate report functionality, but it was added subsequently to Cumulus MX, attempting to copy the legacy Cumulus look.

Additional Information for NOAA reports

Steve Loft: Be aware that a regenerated report for a past period might not be quite as accurate as the report that Cumulus can generate as part of end of day processing. The original report will use figures processed during the preceding day, while a regenerated report has to recalculate them (unless accurate figures are in dayfile.txt). Such differences may be seen for average temperature, average wind speed, dominant direction, and the heating and cooling degree days, because Cumulus has to calculate those as it goes along, it can't do it retrospectively.

Monthly Reports

For each day, a monthly report includes (in references to dayfile.txt, field numbering is based on the date as field 1, although for day just ended these figures are also in yesterday.ini):

1. Average temperature (taken from what Cumulus has just calculated to put into field 16 of daily summary log file
2. Highest daily temperature and time (taken from fields 7 and 8 of the daily summary log)
3. Lowest daily temperature and time (taken from fields 5 and 6 of the daily summary log)
4. Heating degree days (taken from field 41 of the daily summary log)
5. Cooling degree days (taken from field 42 of the daily summary log)
6. Daily Rainfall (taken from field 15 of the daily summary log)
7. Average Wind Speed (calculated from field 17 of daily summary log, by dividing by 24 - the number of hours in a day)
8. Highest daily average wind speed and time (taken from fields 18 and 19 of the daily summary log)
9. Dominant Direction (taken from field 40 of the daily summary log)

In the summary line below the daily rows (note information is not taken from parameters in month.ini:

• the arithmetic average is calculated, and shown, for Mean Temp column and Wind Speed column
• the total is calculated, and shown, for the Rain column
• the highest figure in column above is found, and shown, for all columns headed High or Low
  • the number in time columns represents the day number where the High/Low figure shown was reported

In the climate summary:

1. There are 4 thresholds for temperature, and the number of days blow or above is indicated
2. the wettest day is indicated, and counts of days with rain above certain thresholds is shown

Note that the Heat Base and Cool Base shown are those in force the day the report was generated, and may not have been the setting when the individual Heating Degree Days and Cooling Degree Days were stored in dayfile.txt.

Annual Report

The annual report has a number of tables. Within each table a line appears for each month available for the year.

For the current month, the information is available in parameters in month.ini. Although MX retains old copies of that log file, it does not access them, instead all the parameters are recalculated for older lines.

Temperature table

Each line repeats some of the information appearing in the summary line of the respective monthly report.

In the settings, you can enter a month by month normal for temperature, and this report calculates, and shows, the divergence from that normal.

In the summary line:

• for the the Mean Max, Mean Min, and Dep. From Norm columns, the figure shown is the arithmetic average of figures above
• for the mean column,
  • in recent MX releases, the figure shown is the mean of all entries for this year in field 16 of daily summary log file
  • in early MX releases and the legacy Cumulus, the figure shown is the arithmetic average of figures above
• totals of figures above are shown for the Heat Deg Days, Cool Deg Days, and Max/Min comparisons with thresholds

Precipitation table

Similar to previous table, information shown represents monthly figures and divergences from normal. All should be self-explanatory. The month with most rain is shown in the summary line.

Wind Speed table

The simplest table, it shows average and highest for each month, together with dominant direction for each month. The summary line is based on the information in each column.

Development notes

Cumulus 1

Information taken from support forum posts by Steve Loft:

• The NOAA report takes the figures from dayfile.txt. If you did a 'create missing' in the dayfile.txt editor with a version before 1.9.4 build 1083, that "Create Missing" action would have stored the figures the wrong way round in dayfile.txt, and hence any NOAA report including those days created by "Create Missing" would have the wrong figures for those days.
• for obsolete versions up to 1.9.4 build 1085 only: The average wind speed used for NOAA reports and 'This period' type screens was, by a bug, based on midnight to midnight days regardless of rollover time in use. (It is calculated on generation of report or screen from standard log file entries).
• From build 1086, the calculation is based on the rollover time being used.
• For all Cumulus 1 versions, and the MX versions below 3.4.4: the yearly average temperature is calculated from summing monthly maximum and monthly minimum values and dividing by number of values in calculation.

MX

Information taken from support forum posts by Mark Crossley:

• For release versions 3.0.0 to 3.4.3, on yearly reports, the annual, average temperature was calculated as the mean of the averages for each month above, and so not identical to the average of daily means, because months vary in length
  • The divergence was particularly significant in say March, when the reported average was based on 31 days in January, 28 days in February and a few days in March.
• From version 3.4.4 the annual average temperature is calculated using the integrated method based on every temperature reading processed (it is actually the average calculated from all daily means stored in daily summary log for this year).

NOAA style Report Naming

The format used for naming reports

The monthly reports have a name in this format "NOAAMO"...".txt". The yearly reports have a name in this format "NOAAYR"...".txt". This format with 4 double quotes in all cases is used both in the NOAA settings screen and in the [NOAA] section of Cumulus.ini_(Cumulus_1).

It is between the double quotes where I have placed '...' that Cumulus expects us to use the date output modifiers described. Note that the double quotes must be used at each of the places where they are shown when you define your report naming in the NOAA Settings screen of either Cumulus 1 or MX. The default selected by Steve Loft is MMyyyy and yyyy respectively (expressed in a way that suits both Cumulus 1 and MX) so the inserted part is all numerical. Here is a table showing the main alternative options, for more details about these selectors see the table below as there are obviously a lot more options.

Delphi Specifier for Cumulus 1.9.x	Mono Specifier for Cumulus MX	Explanation	Setting to use that suits both flavours	Example of produced name
Yearly report
YYYY or yyyy	yyyy	Note that Cumulus 1 accepts lower or upper case, this is the default mentioned above	"NOAAYR"yyyy".txt"	NOAAYR2010.txt
YY or yy	yy	Note that Cumulus 1 accepts lower or upper case, this represents a 2 digit year number alternative format	"NOAAYR"yy".txt"	NOAAYR10.txt
Monthly report
mmyyyy (or MMYYYY)	MMyyyy	Note that Cumulus 1 accepts lower or upper case, these are equivalent to default mentioned above, so this is most common for users who first encounter with Cumulus is with MX flavour	"NOAAMO"MMyyyy".txt"	NOAAMO032010.txt
mmyy (or MMyy or mmYY or MMYY)	MMyy	Note that Cumulus 1 accepts lower or upper case, this represents a 2 digit year number alternative format, this was the format frequently selected by Cumulus 1 users as it keeps file names as short as possible	"NOAAMO"MMyy".txt"	NOAAMO0310.txt
yyyy-mm (or YYYY-MM)	yyyy-MM	Note that Cumulus 1 accepts lower or upper case, this naming format is popular as it results in files being in chronological sequence when listed by file name	"NOAAMO"yyyy-MM".txt"	NOAAM2010-03.txt
MMMyyyy	MMMyyyy	Note that Cumulus 1 accepts lower or upper case, this represents an informative naming format using 3 letter month name as defined for your locale on your device, in .NET or in MONO so it is used by those who want to quickly spot which report they want to look at.	"NOAAMO"MMMyyyy".txt"	NOAAMOMar2010.txt (for English locales)

If you migrate from Cumulus 1 (where case does not matter) to Cumulus MX (where case does matter), from version 3.3.0 onwards the NOAA default monthly name if it reads "NOAAMO'mmyy'.txt" (MX believes "mm" means minutes, not month) is changed into "NOAAMO'MMyy'.txt" (which works on both Cumulus 1 and MX).

Encoding

Why does encoding matter?

If you have problems with a web page not displaying the ° symbol correctly, it will be because the character set encoding is either not declared or not consistent.

What encoding does my web page use?

Put simply, most modern web pages start with this:

<!DOCTYPE html>
<!-- the above must be on the first line by itself and tells the browser that HTML 5 applies -->
<html lang="en"><!-- modify this to indicate your language -->
<head>
	<meta charset="UTF-8"><!-- assigns the recommended standard encoding that copes with all international characters -->
...

The last line shown there is critical, it indicates that the web page uses "utf-8" encoding.

You will find that all standard web templates included with MX start as shown above. For Cumulus 1, from build 1094 up the various builds defined for final release, the above code is used. However for earlier builds of Cumulus 1, the standard web pages start as follows:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">

<head>
<meta content="text/html; charset=iso-8859-1" http-equiv="Content-Type" />

The last line there shows how the original web templates (designed by Beth Loft) used the ISO 8859-1 character set. Consequently, the original NOAA reports used ISO-8859-1 encoding and for compatibility with this original setting, the default encoding for NOAA reports is unchanged despite the mismatch with web pages, because Cumulus 1 does not contain any web page to display NOAA reports.

How does MX complicate encodings?

MX complicates the issue, the admin interface does include a web page for displaying reports, (/CumulusMX/interface/noaayearreport.html). This web page includes <meta charset="utf-8">, but the defaults prior to using the web page for editing NOAA settings (/CumulusMX/interface/noaasettings.html) include not using "utf-8" building in an inconsistency because there is nothing in the hints on that page to help you select reasonable settings!

Consistency for encoding

To add just a little more detail here, if you choose to implement a web page to display these Cumulus reports, then the HTML of the web page to display the report, the JavaScript that selects which report to show, and inserts the report into the HTML, and the report itself must all use the same encoding, otherwise you will not get characters like ° displaying correctly.

When did Cumulus 1 change?

In April 2014, Steve introduced the choice in Cumulus 1 of either ISO-8859-1 encoding (as he used originally) or UTF-8 encoding (what he migrated his web page templates to) for these reports. For backwards compliance, the default selected by Steve Loft is his original ISO-8859-1 encoding, but his recommendation strongly expressed was that users should switch to UTF-8. This choice with the former as default, but the latter as recommended, remains unchanged in MX. The encoding for NOAA reports can be selected on the NOAA Settings screen of either Cumulus 1 or MX, and you are as Steve says strongly advised to reverse the setting.

Relevance to Extra Web Files

Before I go into any more technical detail, this same advice of selecting "UTF-8" applies to any choices on the Extra web files in MX (or Files tab of internet settings in Cumulus 1).

TECHNICAL BIT

With that introduction, you can now choose whether to read the rest of this section which uses more technical terminology.

Let me explain that technical term, essentially encoding refers to the character set used by any file.

A computer uses binary, binary can only be in state 0 or state 1, so a combination of 0 and 1 states needs to be defined for every character you want to represent. What you can include in that character set depends to some extent on how many binary bits are used to be mapped to individual characters; and if more than one byte worth of bits is used the order in which the bits within the multiple bytes are used must be defined for each particular encoding.

With any fixed number of bits available, there will be a limit to how many characters can be defined, and different organisations might select different characters to include. This is what leads to multiple encoding standards. One might use a particular arrangement of bits to represent the degree symbol, while another encoding uses that particular arrangement of bits for a different purpose. The general problem is that unless you match the encoding used initially, any retrieval cannot know what character to display for certain combinations of bits.

This means that when you read a file you probably find the letters A to Z where you expect them, but whether you see correct case cannot be guaranteed. Some encodings put capital letters at lower binary values than lower case letters, and some put capitals at higher binary values.

If you use 7 bits, you have 127 combinations, enough for standard 26 letters in both capitals, and lower case, plus 10 digits (0 to 9), some punctuation, and some control characters (like new line, end of file, and so on). If you use 8 bits, a whole byte, you have 254 combinations, and you can start coping with accented letters, with alphabets that don't have 26 letters, and even add some symbols. Obviously, once you start using more than one byte, you can have 16, 32, 64, or even more bits to use and can include lots more characters and the bigger character sets start including lots of symbols and the biggest add smilies or emotion icons.

Remember, most modern web pages (including the standard web templates provided with both flavours of Cumulus) use UTF-8 encoding. The only problem is MX not defaulting to this for NOAA reports.