View source for Recent history

[[Category:Terminology]] [[Category:Cumulus Files]]

= Recent History - Introduction =

Recent history functionality in Cumulus is the ability to store weather values, for the last 7 days.  

Only some spot readings are stored in Recent History, the stored values will miss any extremes that occur between the times when the recent history values are stored. The weather value that tends to vary the most is wind speed, so that is where peaks are most often missed. 

When Cumulus is running normally, entries are stored once a minute, regardless of how often Cumulus interrogates the weather station (might be every 10 seconds, or more or less frequently) and regardless of how often the weather station gets updated readings from sensors (might be every few seconds, every 40 seconds, every minute or less frequently). This can mean that the readings stored on a 1-minute basis may actually be duplicates if the station has not supplied a new value since the previous minute, or may not capture every reading from sensors if they are read more than once in a minute.

When Cumulus is restarted, if the weather station provides historical catch-up data, then the interval between entries for that period when Cumulus was not running, is stored at whatever interval the historical catch-up data uses.  Entries less than a week old, from when MX was previously running will be retained, and those will be at one minute interval.

The data are held in [[cumulusmx.db|RecentData table in cumulusmx.db]] (uses SQLite). There are many software tools available that can read/edit SQLite3, this is not the place to get too technical, but take a look at '''sqlitebrowser''' in a Windows and Linux environment, and '''phpLiteAdmin''' in Microsoft Windows.  Also, you could use any application that can read ODBC files (e.g. Libre Office's Base functionality) can read the MX databases.

While Cumulus is left running, every minute:
#The oldest set of records, in database table row number 0
#Cumulus then works through subsequent table rows (or array elements), as it reads each one, it moves it to the previous (now empty) row (or array element)
#The number of table rows, or array elements, is actually variable, this is because of two reasons:
#*Table rows, or array elements, will be less frequent (or even missing) for the period before Cumulus is started
#*Cumulus uses current time, read from the computer, in its decision as to where to store each new recent history value set, so it can overwrite existing table rows, or array elements, if date-time matches one that already exists, such as in the hour after when clocks go back.

= Using Recent History =

By a request through a Webtag to Cumulus specifying 1 to 10 079 minutes (equals 7 days) ago. Then Cumulus will retrieve the value for the nearest available time. 

The normal way to retrieve a specific value is by using [[Full list of Webtags#Table of Recent History tag names available|Recent History Webtag names]] and specifying how much time you want before the now using the [[Webtags/Parameters|parameters]].

You'll get the nearest value if you ask for a time for which there is currently no exact match, and the [[Full list of Webtags#Timestamp tag|Timestamp tag]] tells you that nearest time.

There are a number of internal calculations, such as calculating [[Average temperature]], [[Heat/cold degree days and Chill hours]], which use the recent history data stored in the Recent History Database for CumulusMX. These data are also used for the standard [[MX_Administrative_Interface#Charts|charts]] and the JSON data for the charts on the standard website and many other websites. See: [[:Category:JSON_Files#Uploading_data_to_a_web_server_outside_MX:|Uploading data to a webserver outside CumulusMX ]] .

== Which weather values are stored ==

For '''Current Conditions''', Cumulus can display values from the basic set of weather sensors it expects, from some derived values, and from various extra sensors, as per table below.

As Cumulus has been developed, more and more of these have been stored for Recent History. Those available in current version of CumulusMX release are listed at [[cumulusmx.db|RecentData table in cumulusmx.db]].

== Warning when Daylight Saving Time starts or ends ==

Please note that parameters specify time-stamped array element to retrieve based on counting back from current local time so the result for ''any period including when clocks change'' may not be quite what you anticipated.

=== Changing from Summer to Winter time ===

Remember, ''when clocks go back'', that for a whole hour following the clock change, clock times (now in winter time) repeat the previous clock times (that were in summer time).  The way that Cumulus has coded this functionality, instead of the new sets of spot values being added after the old rows/elements, they overwrite the old table rows, or array elements, for the same times.  Consequently, you cannot retrieve any values for the times that have been overwritten, and you must be careful when you specify to Cumulus which values you wish to retrieve.

=== Changing from Winter to Summer time ===

As for ''when the clocks go forward'', the new values do get added after the old rows/elements, but of course there will be one hour's worth of times that simply do not exist.  Consequently, any attempt to retrieve values around the time of the clock change has to be careful not to specify any time in that non-existent period, as Cumulus will just return the value before, or the value after, depending on which is nearest.

=== Technical note ===

As explained earlier, you request an entry from Recent History by specifying 1 to 10 079 minutes ago. Cumulus looks at current clock time, calculates what time would be that long ago, and seeks the nearest datetime entry.

Since SQLite database tables use the row number as the primary key (see [[cumulusmx.db]]), the datetime column does not have to contain a unique value, so technically it would be possible for MX to create rows in the database that have same time as other rows when the clocks go back; equally technically when clocks go forward, it would technically be possible to calculate a revised timestamp so you don't have 60 minute specifiers for which the time never existed.

However, to do this would involve more complicated code, because MX would need to keep track of which row was last updated, keep track of when the clocks changed, and modify its search routine to find the correct row. Life is much easier if the Cumulus user makes allowance for any clock change when making their request.