5,838
edits
Dayfile.txt: Difference between revisions
From Cumulus Wiki
Jump to navigationJump to search
m
minor resequencing
m (→Specific issues for MX: Time-stamp issue added) |
m (minor resequencing) |
||
| (3 intermediate revisions by 2 users not shown) | |||
| Line 1: | Line 1: | ||
{{Template:Version badge Mx}}{{Version badge 1}}This Wiki page applies to both Cumulus flavours. | {{Template:Version badge Mx}}{{Version badge 1}}This Wiki page applies to both Cumulus flavours. [[Category:Files_with_Comma_Separated_Values]] | ||
As part of a redevelopment of Wiki, this page has been simplified, by moving some content to new pages. Old links in the support forum, that were to content no longer on this page, will bring you here. | |||
Content previously on this page has been moved as follows: | |||
* Explanations about Cumulus terminology can be accessed from [[:Category:Terminology]] page | |||
* Each line in this file represents one day, but the start time need not be same for all fields, | |||
** so please see [[Meteorological_day|Meteorological day]], and [[today.ini]] for more details about that | |||
* Advice regarding editing this file has been moved to [[Amending dayfile]] page, this also covers date-separator issues and dealing with missing or corrupted lines | |||
* General advice about Cumulus files with a '''.txt''' extension has been consolidated on [[:Category:Files_with_Comma_Separated_Values]] page | |||
* Advice about correcting any rogue extreme figures inadvertently stored in this file has been consolidated in new [[Correcting Extremes]] page | |||
* If some lines in your file have fewer fields than other lines the advice has been consolidated on [[Calculate Missing Values]] page | |||
** For MX there is a [[Calculate_Missing_Values#CreateMissing.exe|Create Missing Utility]], which checks spot readings in the [[Standard_log_files|MMMyylog.txt]] files, adds any missing derivative spots (e.g. heat index) and uses these figures to recalculate daily derivatives and uses those to replace missing fields/lines in dayfile.txt | |||
** For the legacy Cumulus, there was a [[Amending_dayfile#Create_Missing_on_legacy_dayfile_editor|dayfile editor with create missing option]], that performed equivalent function | |||
** If you import historic data from before you started using Cumulus into [[Standard log files]], | |||
** then see [[Calculate Missing Values]] page for how to generate new lines in dayfile.txt | |||
* Cumulus MX is more fussy, than Cumulus 1, about various formattting issues, see below, also see [[Migrating_from_Cumulus_1_to_MX#dayfile.txt]] section for more advice | |||
The content that remains on this page is summarised by the table of contents that follows. | |||
=About this file= | =About this file= | ||
* This Wiki page describes one of the [[:Category:Cumulus Files|files]] not included in any release download. | |||
* This daily summary file (Steve Loft shortened that to "day" plus "file") uses a ".txt" extension, and is essentially a plain text file in CSV format. | |||
* The file is created in [[Data folder|data sub-folder]] of your Cumulus installation when Cumulus needs to store its first line in this file. | |||
* Cumulus MX reads the whole of this file when you restart the software, | |||
** So if you move house, it is probably best to archive the old "dayfile.txt", and avoid any discontinuities in any graphs plotted from active file | |||
([[Speciallog.txt|speciallog.txt]] is another log file that contains all dates in a single file, as do all the [[:Category:Ini_Files|.ini files]]). | |||
==How Cumulus Creates and Updates this file== | |||
==How | |||
For | * Cumulus reads values supplied by your weather station, (either directly while Cumulus running, or for some weather station types can read historic data during catch-up on restarting Cumulus) | ||
* Cumulus converts them to the units you prefer, | |||
* Cumulus applies any calibration (multiplier and offset) you have set, | |||
* For a sub-set of those readings (perhaps those every minute if readings are collected every 10 seconds), the spot values of source items like temperature, humidity, wind speed, can be used in calculations of derived items like "wind chill", "dewpoint" and "feel-like" temperature. | |||
* Cumulus then sees if the resulting soource, or derived, value implies [[:Category:Ini Files|any extreme records file]] needs to be updated | |||
** Daily extremes are held in [[today.ini]] and that is main source used when a new line is added to "dayfile.txt" | |||
= | ==Why this file should be backed up== | ||
* This file contains daily extremes, the accuracy of those daily extremes depends on the interval between the spot readings that are used as explained above. | |||
* If the file is corrupted, and not regenerated from a back-up, the only source of spot readings is the [[Standard_log_files|MMMyylog.txt]] files, and their interval might be only every half an hour (it has to be an exact fraction of an hour). | |||
* As explained [[Monthly_log_files#Enhancement never implemented|here]] minima and maxima between such logging intervals are not recorded by Cumulus software | |||
* Thus it is worth backing up this file, to another device than that running Cumulus, on a regular basis, probably a few times a week, to ensure this precious data is not lost if your device running Cumulus has a malfunction (or is damaged), or an electrical blip (or mistake by you) causes corruption to the original file, | |||
Cumulus does periodically copy this file within the installation, but the copies are only kept for a limited time, and are on the same physical storage device, and so your main file is corrupted you might not be able to access the Cumulus back up or might not be able to go far back enough for an uncorrupted file: | |||
* The file is backed up when MX is restarted into a date/time stamped sub-folder of the [[Backup folder|'''backup''' folder]] | |||
*The file is also backed up (to a date/time stamped sub-folder within '''daily''' sub-folder of that backup sub-folder) during the end of day process, depending on the release you are running the back-up copy may, or may not, include the line that is appended in the same end of day | |||
[[File:Badge | Retention of these back ups: | ||
* [[File:Badge vMx.png]] MX only keeps the last 9 of the date/time stamped subfolders. | |||
[[File:Badge | * [[File:Badge v1.png]] Legacy Cumulus 1 only keeps up to 8 of the date/time stamped subfolders. | ||
== Specific issues for MX == | == Specific issues for MX == | ||
WARNING: It is important to note that MX | WARNING: It is important to note that some releases of MX are very fussy about consistency in all lines of '''dayfile.txt'''. Earlier releases tended to have better compatibility with the legacy software. Subsequent releases expected every line to be expressed exactly as specified in the locale. MX in its latest release is trying to cope better with inconsistent date separators, and at the time of writing this there was a proposal for forcing this file to use decimal points (full stops not commas) regardless of locale. Therefore, information here might be incorrect for the release that you are using. | ||
Date field: Cumulus 1 (C1) did not care what character (or characters) separated the day, month, and year elements of the date field. MX insists that the same character (or characters), as defined in the locale, is used for all lines in file. | Date field: Cumulus 1 (C1) did not care what character (or characters) separated the day, month, and year elements of the date field. MX insists that the same character (or characters), as defined in the locale, is used for all lines in file. | ||
| Line 57: | Line 70: | ||
* MX too has added fields as the software has developed, and it even (as shown in field list) inadvertently added 2 fields later removed. The difference is that MX (for some functionality from release 3.4.5, for all functionality from release 3.9.5) reads the whole file into an array with a fixed number of elements, therefore every line ends up with same number of fields when written back into file. If you have some lines in your file that were created by an earlier release of Cumulus, and so have less than whatever is the current number of fields for the release you are using, you can add the missing derived fields, please see [[Calculate Missing Values]] page. Please ensure you use the right version of the "Create Missing" utility mentioned on that page as it also get upgraded when fields are added. | * MX too has added fields as the software has developed, and it even (as shown in field list) inadvertently added 2 fields later removed. The difference is that MX (for some functionality from release 3.4.5, for all functionality from release 3.9.5) reads the whole file into an array with a fixed number of elements, therefore every line ends up with same number of fields when written back into file. If you have some lines in your file that were created by an earlier release of Cumulus, and so have less than whatever is the current number of fields for the release you are using, you can add the missing derived fields, please see [[Calculate Missing Values]] page. Please ensure you use the right version of the "Create Missing" utility mentioned on that page as it also get upgraded when fields are added. | ||
= | ==How to view or edit this file== | ||
An editor has been included within Cumulus: | |||
* [[File:Badge vMx.png]] From release 3.4.5 (13 Mar 2020) onwards: In [[MX_Administrative_Interface#The_Data_Log_Viewing_and_Editing_interface|the interface]] go to '''Data logs''' menu and select ''Dayfile'' | |||
* [[File:Badge v1.png]] From version 1.9.2 (5th October 2011) to final legacy release: On Main Screen from [[Cumulus_Screenshots#File.2FEdit.2FHelp_Menu|'''Edit''' menu]] select ''Dayfile.txt'' | |||
**'''Note for obsolete version 1.9.0 to 1.9.3:''' There is a bug in these versions in that 'Create missing' inserts 'heating and cooling degree day' values the wrong way round. | |||
**'''Note for obsolete version 1.9.3 only:''' Create missing might in some cases be affected by a bug in 1.9.3 that can cause lines to be stored in incorrect date order (dayfile.txt uses dd.mm.yy, dd/mm/yy or dd-mm-yy, for its date field; and all lines should be in ascending chronological order) | |||
**There are no known bugs for dayfile.txt handling in version 1.9.4 builds 1086 to 1101. Build 1099 is the standard stable final release of Cumulus 1 for most weather station types, 1100 and 1101 are for specific weather station types. | |||
For detailed information, please see [[Amending dayfile|viewing/editing '''dayfile.txt''']]. | |||
==Reading the file== | |||
See [[Daily Summary]] page for a full discussion of ways, external to Cumulus, to read this file. | |||
Cumulus | Apart from the viewing/editing options just described, Cumulus software reads this daily summary file in various other circumstances depending on the release you are running. | ||
* The | * [[File:Badge v1.png]] The legacy Cumulus has a number of [[Cumulus_Screenshots#View_data|screens for viewing data for various periods]], these use several of the [[Category:Cumulus Files|files]] for their source, including "dayfile.txt". The '''Select a graph''' feature also uses several of the [[Category:Cumulus Files|files]] for their source, including "dayfile.txt". Thus the legacy software only reads the file when the Cumulus user makes a specific request, in normal operation the existing content is ignored, and the end of day action uses a simple "append" instruction. | ||
* | * [[File:Badge vMx.png]] From release 3.9.2 - b3097 (7 Dec 2020), MX reads the entire '''dayfile.txt''' file, to drive the [[Highcharts_-_Historic|'''historic charts functionality''']]; both in the [[MX Administrative Interface|interface]], and the example included [[New Default Web Site Information|Historic Charts web page]]. | ||
** Consequently, any error in say the date field (or change of separating character) will stop historic charts working. | |||
= List of fields in dayfile.txt = | = List of fields in dayfile.txt = | ||
'''For your installed build please see ''dayfileheader.txt'' (stored within the folder that contains your Cumulus executable), as that will list which fields your Cumulus installation uses.''' | '''For your installed build please see ''[[dayfileheader.txt]]'' (stored within the folder that contains your Cumulus executable), as that will list which fields your Cumulus installation uses.''' | ||
If you have been using Cumulus for a while, you may wonder which of your log file lines might be shorter, so the table below shows fields grouped by the Cumulus version when those fields were added. | If you have been using Cumulus for a while, you may wonder which of your log file lines might be shorter, so the table below shows fields grouped by the Cumulus version when those fields were added. | ||
==Field numbering== | |||
Please note the list of fields has been rewritten especially for MX. As part of the rewrite, the fields have been renumbered, in some forum posts you might see references to old numbering, in others to new numbering. | |||
* The original table below was for Cumulus 1 and then field number '''was''' starting from zero. | |||
** Cumulus 1 does not actually number lines, however it does count lines as it reads them, so if there is an error when it reads the file, the original Cumulus will report the line number where it first found an error (this uniquely identifies the line even if a date is duplicated or a line feed has been deleted so two lines are merged). | |||
** Please note that the editor in Cumulus 1 allows you to change the date, as well as all the other fields, although the lines must be kept in ascending date order to avoid errors when subsequently reading the file | |||
*The fields are now numbered starting from 1 to fit in with Cumulus MX where when the log file is read, the processing code adds a line number in front of the date field on each line it holds. | |||
** The Cumulus MX user may not be aware of this happening as it is within the internal workings, where data from the file is transferred to an array, or data from the array is written back into the file. | |||
**By using line numbers, MX is able to identify which line has been deleted or edited, MX coding treats the date as a fixed bit of text (MX does not allow you to change a date) | |||
The old numbering from zero had two advantages: | |||
# It stressed that the date field was different to the rest, all other fields were either values or time-stamps | |||
# Numbering starting from zero is consistent with standard indexing used for arrays in programming languages (like JavaScript), so the number shown '''was''' the number to quote in any scripts where a Cumulus 1 line was converted to an array, and you needed to address a single field. | |||
== Information shown in the table == | == Information shown in the table == | ||
* | * The date '''must''' be a unique identifier, the same date should not be repeated in another line, however Cumulus 1's editor allows you to change that date field. | ||
* The remaining fields were all either numerical values, or a time paired with (except for first wind field) preceding numerical value. | |||
** Cumulus 1 actually enforces this pairing (i.e. it validates that a time is present where it is needed). | |||
*The alphabetic column identifiers used by many spreadsheets are shown | |||
** IMPORTANT: Ensure '''all columns are set to "text" format''', | |||
** Note that you will corrupt this file if you let your spreadsheet recognise content as dates or time, change the number of decimal places. | |||
* | * The type of field is shown in the table, | ||
** you must not include a sign for an unsigned field, | |||
*The alphabetic column identifiers used by many spreadsheets are shown | ** you can not specify a decimal point in an integer field, | ||
*The type of field is shown in the table, you must not include a sign for an unsigned field, you can not specify a decimal point in an integer field, all time fields must use HH:mm format | ** all time fields must use 5 character "HH:mm" format | ||
*The field description is shown, together with references to where that terminology is explained | * The field description is shown, together with references to where that terminology is explained | ||
== Table listing Fields == | |||
{| class="wikitable" border="1" | {| class="wikitable" border="1" | ||
|- | |- | ||
| Line 342: | Line 377: | ||
|[[Heat/cold degree days and Chill hours | Cooling degree days]] | |[[Heat/cold degree days and Chill hours | Cooling degree days]] | ||
|- | |- | ||
|colspan="4" style="background:lightgray;"|The next two pairs were added in version 1.9.3 build 1036 (these only show valid values if appropriate sensors exist) | |colspan="4" style="background:lightgray;"|The next two pairs were added in legacy version 1.9.3 build 1036 (these only show valid values if appropriate sensors exist). | ||
Fields listed up to those following here applied to the final legacy Cumulus 1.9.4 and formed the basis for early releases of Cumulus MX. | |||
|- | |- | ||
|43 | |43 | ||
| Line 364: | Line 401: | ||
|Time of high UV Index | |Time of high UV Index | ||
|- | |- | ||
|colspan="4" style="background:lightgray;"|The next two pairs were added in | |colspan="4" style="background:lightgray;"|The next two pairs were added in MX release 3.6.0, 2 more derived values and their times | ||
|- | |- | ||
|47 | |47 | ||
| Line 386: | Line 423: | ||
|Time of low feels like temperature | |Time of low feels like temperature | ||
|- | |- | ||
|colspan="4" style="background:lightgray;"|The next two pairs were added in | |colspan="4" style="background:lightgray;"|The next two pairs were added in release 3.6.12 | ||
*Version 3.6.12 (build 3088) was an emergency release to cure serious problems in previous build 3087. It added the following 4 fields (2 values and their times). | *Version 3.6.12 (build 3088) was an emergency release to cure serious problems in previous build 3087. It added the following 4 fields (2 values and their times). | ||
**The 4 extra fields are left empty in this release, although you can add values and time-stamps using the dayfile editor. | **The 4 extra fields are left empty in this release, although you can add values and time-stamps using the dayfile editor. | ||
*From | *From release 3.7.0 the first 2 of these 4 fields are populated, and the last 2 are removed, so I have labelled them as error. | ||
|- | |- | ||
|51 | |51 | ||
| Line 400: | Line 437: | ||
|AZ | |AZ | ||
|5 characters | |5 characters | ||
|Time of high Humidex | | style="background:pink;"|Time of high Humidex | ||
'''Bug for releases 3.13.0 to 3.14.2 inclusive''': The major code rewrite for release 3.13.0 replaced the previous code for the processing for all Cumulus files, the new code incorrectly stored ''Time of high feels like temperature'' in this field for all these releases! Corrected in minor code rewrite for 3.14.3 - b3163 25 Jan 2022 (not released to public until 3.15.0 - b3169 Released 31 Jan 2022) | |||
|- | |- | ||
|colspan="4" style="background:lightblue;"|Just confirming that the next 2 fields were included by mistake in an emergency release (3.6.12), and are not included in | |colspan="4" style="background:lightblue;"|Just confirming that the next 2 fields were included by mistake in an emergency release (3.6.12), and are not included in any other version, so have labelled them as error. | ||
|- | |- | ||
| 53 ('''error''') | | 53 ('''error''') | ||
| BA | | BA | ||
|signed decimal | |signed decimal | ||
|Labelled as Low Humidex, but not used, (appear in 3.6.12, but no other | |Labelled as Low Humidex, but not used, (appear in 3.6.12, but no other release) | ||
|- | |- | ||
| 54 ('''error''') | | 54 ('''error''') | ||
| BB | | BB | ||
| 5 characters | | 5 characters | ||
| Labelled as Time of low Humidex, but not used, (appear in 3.6.12, but no other | | Labelled as Time of low Humidex, but not used, (appear in 3.6.12, but no other release) | ||
|- | |- | ||
|colspan="4" style="background:lightgray;"|The next value was added in 3.12.0 | |colspan="4" style="background:lightgray;"|The next value was added in release 3.12.0 | ||
|- | |- | ||
| 53 (new) | | 53 (new) | ||
