5,838
edits
m (Sfws moved page Correcting Missing Values to Calculate Missing Values without leaving a redirect: More descriptive title) |
m (Minor rewrite and typo correction) |
||
=Introduction=
If you started using Cumulus software before June 2020, you will be aware that the list of fields in both [[Standard_log_files#List_of_fields_in_the_file|data logs]] and [[Dayfile.txt#List_of_fields_in_dayfile.txt|daily summary log]] will be different depending on when an individual line was first created (or last edited).
If you are using the [[Highcharts_-_Historic|'''Historic Charts''']] feature introduced from release 3.9.2 - b3097 (7 December 2020), you may notice that these new charts have gaps in available data, and the dates with/without data vary depending on what is being plotted.
For these, and other reasons, this page explains various ways in which you can edit log files, (and for MX users, database tables) so all lines contain all the fields that can be calulated for the weather station you are using.
[[Category:Log Files]]
{{TOCright}}
To make sense of explanations on this page, you need to understand the terminology used here.
=Some definitions=
==
A weather station sends values based on its sensors to Cumulus. If Cumulus reports that value without changing it (an offset and/or multiplier might be applied to convert it to the unit wanted by the Cumulus User), the value is described as a '''source value''' because Cumulus is reporting something that has its source elsewhere.
There is not a single list of what weather values are called "source values", because this varies depending on the weather station, and in some cases, a Cumulus User can ask Cumulus to recalulate a value instead of using what is sent by their weather station.
However, Cumulus does include code that expects a weather station to provide ''a defined minimum set of source values'':
# Current air temperature
# Relative Humidity
# At least one wind speed
# Current air pressure (absolute or sea-level)
By default [[Cumulus.ini#Read-only_parameters_in_the_Station_section|see here]], Cumulus will stop processing any readings from a weather station unless the above 4 source values are being supplied and reveal they are being updated (failure is set is after a total of 6 unsuccessful consecutive attempts to read each of these).
Cumulus also expects that your weather station can provide:
* A rainfall counter (this could be annual rainfall, or count of rocker bucket gauge tips)
Although the lack of that source value will affect functionality, Cumulus will continue to process other source values that are available.
Some weather stations may also provide one, or more, of these other source values (not a complete definitive list):
* Dew-point Temperature
* Wind Chill Temperature
* Evaporation
* Sunshine hours
* Solar radiation
* UV index
* Air pollution measurement
There are some configuration settings [[Cumulus.ini#Read-Write_parameters_in_the_Station_section|here]] where you can decide whether to use a weather station supplied dewpoint temperature and whether to use a weather station supplied wind chill temperature.
===How Cumulus might transform a Source Value===
*For some weather data processed by Cumulus the value sent by the weather station and that used by Cumulus will be different:
** This can be because the units used by the weather station, and the units required by the Cumulus user are different (and Cumulus allows the user to select the units in which values will be stored)
** This can be because the user has entered some calibration settings. The exact settings available vary for different weather data, but in some cases a second order multiplier is available (the square of the input value is multiplied by the
**A weather station might use a rainfall counter, Cumulus converts it to a rainfall rate (based on difference between two counter readings scaled up to represent amount per hour)
==Derived value==
A dictionary will define '''derived''' as "obtained from a source", and that is the meaning adopted on this page. Cumulus software will use the source values it obtains from your weather station to output not just those source values (as described above), but also values that are "obtained from the source" in two ways:
#By using a combination of two (or three) source values, and in some cases adding a time element, Cumulus software is able to calculate the various derived values that this Cumulus Wiki page will be explaining later.
#*As Cumulus has developed more and more of these derived spot values are being reported, and that explains why an old [[Standard_log_files#List_of_fields_in_the_file|data log line]] might have fewer fields than newer lines.
#*If you have some of these derived value fields where the value is missing because it was not calculated by the Cumulus software release you were running at the time the line was created, you will find out below how to calculate those missing values and have them added to the data logs.
#Cumulus software will track, both the source values, and the values derived from them, and compare against existing extreme records, to report the highest and/or lowest, in various periods.
#*Although, Steve Loft (in the Cumulus Support Forum) used the terminology "derived" for this process in his description of what his software does, this Wiki page is not about those derived values.
#*You can find out about how a rogue source value can affect extreme records derived from it, and how to correct such issues on the [[Correcting_Extremes]] page.
===Derived spot values===
Now we have established what we mean by a derived spot value, we can understand that Cumulus software code as it reads source spot values, will detect if that source value is required for the calculation of an instant derived spot value.
Here are all the derived spot values that Cumulus can calculate (depending on Cumulus configuration settings, and what your weather station can output):
* '''Dew point''', a weather station might output dew point temperatures, but Cumulus can calculate it from source values for outdoor temperature and outdoor humidity
** The original Cumulus and MX use different formulae to calculate dew point, so there is a continuity break if some of your data logs were created by the original Cumulus software and some by MX.
*'''Wind Chill''', again this might be output by your weather station, but Cumulus can calculate it from outdoor temperature and average wind speed.
*[[Humidex|'''Canadian Humidity Index (Humidex)''']], [[Heat_index|'''USA Heat Index''']], and [[Apparent_temperature|'''Apparent Temperature''']] are not output by your weather station, but both the original Cumulus 1 and the newer Cumulus MX will derive these spot values for you (except if you are running a very old release)
**(The implementation of these by Cumulus software is briefly mentioned [[Feels_Like#Rest_of_this_article|here]]).
** The calculation formulae used for these may not be consistent for all releases, so again there is a possibility a data log might have continuity breaks.
*[[Feels_Like|'''Feels Like Temperature''']] is calculated by the Cumulus MX flavour only, the actual calculation formula [[Feels_Like#The_various_ways_to_express_Feels_Like|has varied]] in different releases, but use a variation on
*'''Heating Degree Days''' and '''Cooling Degree Days'''; these are further examples of derived values that most versions of Cumulus will calculate for you (from all processed outdoor temperatures in a day)
**A bug in some versions of the original Cumulus software could result in these derived values being swapped and therefore tracked wrongly when reporting extremes.
The links about will take you to where the derived values are explained in the [[:Category:Terminology]] pages of this Wiki, however at the time of writing this page, many of those links have very little information, so you may wish to search online to find more information in for example Wikipedia.
=Calculating Missing Derived Spot Values for fields in Standard Data Logs=
==Using a PHP script on your web server==
If you have access to a web server that can run PHP Hypertext Pre-processor (PHP) scripts, then [https://cumulus.hosiene.co.uk/viewtopic.php?f=18&t=18096 this post in support forum] includes a script that produces a HTML form where you specify [[Standard_log_files#Introduction|the log file name]] you wish to edit. The script will read that file, and output a replacement file with all possible spot derived fields populated.
That might sound a bit technical, so here are some step by step instructions:
#Download the '''processStandardLog.php''' script from [https://cumulus.hosiene.co.uk/viewtopic.php?f=18&t=18096 here].
#File transfer (or copy for local web server) that script to your web server
#File transfer (or copy for local web server) all the standard log files from the data sub-folder in your Cumulus installation to a suitable holding folder (you may need to create it) on your web server
#Open in a browser '''PATH/processStandardLog.php''' by preceding the file name with the path as defined from the root on your web server
#This loads a web page where you have a field asking you to enter a path and file name for the data log you want to process
#Continue to follow the instructions on the web page
#When it has created a replacement file, you can enter details for another data log, and continue until all your data logs have been processed
#Take a backup of your existing Cumulus installation (you should be doing that on a regular basis anyway, so I will not give instructions here)
#Carefully delete any non-current data log in your data sub-folder that you have a replacement for, and file transfer (or copy back) the replacement data logs from your web server into the local data sub-folder, noting that the file extension will need to be renamed from '''.csv''' to '''.txt'''.
==Using the '''data log''' editor provided in MX==
In the [[MX_Administrative_Interface#The_Data_Log_Viewing_and_Editing_interface|MX admin interface]] go to the '''Data Logs''' menu tab, and select the ''Data Logs'' page.
There is a box for selecting the data log you want to edit. Once you have loaded that, the first (up to) 10 lines are shown. Navigation links let you select 'First', 'Previous', 'Next', and 'Last' pages, also a small number of pages can be selected directly.
Once you select a line, an '''Edit''' button is enabled, click that and you can manually input the missing values for that line. '''Save''' that edit, and you can select another line. Once you have edited all the lines on that page, you can select another page, and repeat the process. Then you can select another log, and repeat the process.
It is a long-winded way to edit, and the MX editor does not even validate what you have entered. An alternative is to edit each log file externally, and you can read how to do that in the "Work around for standard log files" section below.
Some readers of the Cumulus support log will know that a third-party replacement for the MX editor was worked on, but never got incorporated into MX. The idea was to replace the alt_editor software used by Mark Crossley, with a standard HTML form script. This allowed in-line editing, it allowed the derived values to be calculated and displayed (so you simply decided whether to accept the replacements as suggested for the various fields), and finally it applied some validation to each field to ensure any manual edit inserted a value that was within the allowed range. The main reason for its rejection from the public MX was the complex way in which different files included in the admin interface interact, and the consequent issue that changes made for this replacement had a knock on effect on other pages in the admin interface. The author could not afford the time to redesign the whole admin interface so the proposed replacement could be integrated.
==Lack of editor in Cumulus 1==
Cumulus 1 provides a [[Cumulus_Screenshots#View_Menu|viewer]] for the data logs. On the '''View''' menu, select ''''Data Logs''', then enter the file name you want to view and load it. You can scroll left to right through the fields, and you can scroll up and down through the lines. The viewer shows a header row so you know which field is which. You cannot do any editing.
If you find that this viewer cannot load a data log, it is probably because you ignored the '''read me''' that is part of the Cumulus 1 installation procedure, see [[FAQ#I_can.E2.80.99t_find_my_data_files.21|FAQ: I can't find my data files]]. If the displayed headings do not match the data shown, you have not read the caution on the screen, which says the viewer is only for standard data logs, not extra sensor data logs , nor the daily summary log.
Cumulus 1 does not provide any functionality to edit the standard data logs, whether to correct a rogue value, or to add a missing derivative.
===Work around for standard log files===
As Cumulus 1 does not provide an editor, the only option is to edit the file outside Cumulus using a '''Comma Separated File''' editor, a plain text editor, or a spreadsheet program (like the free open source '''Libre Office Calc''' or the commercially charged for ''Microsoft Excel'').
As the log file for the current month will be updated frequently by the original Cumulus software (when it is running), Cumulus 1 applies an exclusive lock, and conflicts can happen if another process seeks to access this file. Consequently don't let your antivirus scans access this file, nor try to edit it outside Cumulus while the original Cumulus software is running. A full discussion of the problems with conflicts of access to the standard log file can be found [https://cumulus.hosiene.co.uk/viewtopic.php?f=4&t=12721 in this support forum topic].
If you decide to edit the current log outside Cumulus, then remember that, if you leave Cumulus running it will continue to append new lines. Therefore, you either need to close Cumulus while you are doing the edit; or (if you are able to merge two files) close Cumulus while you replace its file with a merge of what you have edited and the extra lines added since you took away a copy to edit.
It is best practice, to take a back-up copy of all your Cumulus installation before starting any editing. It is also best practice to take a further copy of any file you want to amend, and to do your edit on that copy, so you do not edit any Cumulus file directly. The original full backup will preserve the existing file, so you can regress to it, should Cumulus find an error in your edit.
Also note these log files do not include a header line, and should not be edited to include it. All flavours of Cumulus provide, in the data sub-folder, a file called '''monthlyfileheader.txt''' which contains the headers appropriate to the release you are running, and you can add that temporarily to your spreadsheet if it helps you with editing, but don't forget to delete it before saving the file ready to make it available to Cumulus.
Here are some other rules to follow when editing the standard log files:
* You can't edit any log file with a word processor, as they add control characters, and other information, that Cumulus cannot understand.
* Editing is straight forward if you use a specialised comma separated value file editor, such editors will split the content by field so it is easy to ensure you only amend field content and do not accidentally change a field divider, plus these editors will not add additional content to any line as they can cope with the number of fields varying in different lines and don't change encoding.
* If you want to use a text editor, it is best if you choose one designed for computer programmers or developers. Such an editor will allow you to select the encoding (Cumulus will be confused by any Byte Order Mark, so select the encoding type without BOM).
* If you choose to use a spreadsheet, ensure that all columns are treated as normal text, do not let (don't accept Excel default) the spreadsheet recognise the first field contains a date as it will convert that column into a number (e.g. days since 1900 or days since 1970). For example in Libre Office make sure that "Detect special numbers" is not selected. Many spreadsheets will offer a CSV option for saving the file (in Libre Office tick "Edit Filter Settings" on "save as ...").
* If you amend a field, ensure that replacement is same format as original (same decimal separator if not integer).
* Ensure no blank lines are introduced by your editing.
*Ensure that all lines continue to have date and time information at the start of the line, and that the format of that identifier is not changed (same sequence, same character(s) separating each element of date, and a colon separating hours and minutes, and that the time does not have a seconds element added.
===Other logs===
Since the derived values this page is discussing are spot values, they have to be calculated from source values measured at the same time. This means that if your [[dayfile.txt|daily summary log]] is missing some fields, they cannot be calculated from other fields in the same log line. The same applies to any missing extreme records for this month, this year, monthly-all-time, or all-time.
However, the techniques for correcting rogue values described on the [[Correcting_Extremes]] page, can be used for inserting missing values in the daily and longer period extreme records.
=Missing fields in dayfile.txt=
For daily extremes to be correct in our daily summary file, we can use a work-around, if you have the correct spot derived values in your standard data logs, whether they were there originally, or you have done some editing of those files (perhaps to edit out rogue values, or to add derived values that were previously missing).
==Daily summary Log in Cumulus 1==
For the daily summary log, the original Cumulus software includes functionality to '''Create Missing''' in its daily summary log editor, which will be described next. This functionality creates an entire missing log line and will insert highs and lows whether they are extremes of source values, or extremes of derived values. This functionality is not designed to work out individual missing extreme figures, only to insert complete missing lines. However, we can workaround that constraint:
'''WORKAROUND FOR DAYFILE.TXT if required dates are present in both the standard log and dayfile.txt, but not all fields for that date exist in dayfile.txt'''
There are two common reasons for needing to use this, Cumulus 1 only, workaround:
# To add extra fields to records created by an earlier version of Cumulus
# If you are importing into Cumulus records from other software, and that other software does not provide derived extremes (apparent temperature, heat index, rain rate, wind run) to insert in the daily summary log file.
The steps you need to take, to implement this Cumulus 1 only workaround:
#Select a time to do this work that is at least 10 minutes, preferably a whole hour, after Cumulus has performed a daily rollover, and ensure you finish this work long before the next rollover time. This will ensure your work cannot conflict with when Cumulus 1 is updating dayfile.txt.
# Take a copy of dayfile.txt original as backup,
# Use the Cumulus 1 editor (in '''Edit''' menu, select '''Dayfile.txt''' screen), and let it edit the original file
# Delete any days with partial information (e.g. from Cumulus versions that created fewer fields)
# Click the ''Create Missing'' button
# Wait while Cumulus scans all the standard log files, and for each source or derived field in those files, tracks the highest and lowest for each meteorological day that is now missing in dayfile.txt.
#* As an aside, be aware that when the contents of [[today.ini]] was used to create a new line in dayfile.txt originally, the high and low that were copied across were derived from all source values that Cumulus obtained from your weather station (depending on your weather station type this might be around every minute; some weather stations provide new readings less frequently, some provide them more frequently).
#*Continuing this aside, the high and low that Cumulus is now deriving are based purely on those values stored in the standard data log, by default that is just every 10 minutes.
#The new lines that Cumulus 1 adds to your dayfile.txt are also added to another log file '''dayfileeditlog.txt''', so we can access that to find the new values.
#For simplicity, click '''OK''' to save the edited '''dayfile.txt''' file, and exit the editor.
#Rename the amended dayfile.txt as "dayfile(generated).txt".
#Create an empty text file in a suitable temporary directory, and name it "dayfile.txt",
#Use an external editor to open your empty file.
#*You can use a Comma Separated Value file editor, although you will find this difficult starting with an empty file
#*You can use an editor designed for computer programmers or developers that can edit text file
#*You can use a spreadsheet application, such as "Libre Office Calc" or "Microsoft Excel", providing you obey the editing rules defined later
#Now merge in (as read-only text) the previous contents of the original dayfile.txt from the copy taken in step 2
#Now merge in (where there are fields missing) just those fields from the respective lines in "dayfile(generated).txt".
#Finally, copy your temporary "dayfile.txt" into the "Cumulus\data" folder, so from now on Cumulus accesses the file with the maximum number of fields present.
One note of caution:
*If a required source or derived value is not present in the standard data log lines, Cumulus will write into related dayfile.txt fields zero for values, and "00:00" for time stamps, because it does not understand the concept of "Null".
*Cumulus 1 does not have the functionality to retrospectively calculate derived values when it is reading source values in the standard data log line.
==Daily Summary Log in Cumulus MX==
Although there exists a tentative plan for an executable, to be added to the MX package, that can read the standard data logs and calculate all the fields needed for a line in dayfile.txt, this is only a gleam in the developer's eye! At the moment, the 'Create Missing' functionality and workaround described above is not available to MX users.
The only method, available at the time of writing, involves using database functionality and multiple steps:
#The first step depends on whether you use the option in MX to create and update database tables...
#*...If you don't use that option yet, use '''ExportMySQL.exe monthly''' to create a database table called "monthly" (you can call it another name, but you must have set name in MX, before you run ExportMySQL.exe), and read all the standard logs into that database table,
#*...Or '''if you already have the table''' and have MX updating the standard logs into that database table
#Once you have the table available, you can fairly easily update the table to add any missing values into existing columns in this 'monthly' table, and from it update columns in a daily summary table.
See [https://cumulus.hosiene.co.uk/viewtopic.php?f=18&t=18096 this post in support forum] where there are two PHP scripts designed for this type of task.
==Rules when editing daily summary log==
===General External Editing Rules===
* Take a copy of the file that can be reverted to if there is a subsequent problem, and you have messed up the file that Cumulus (1 or MX) is now trying to use.
* Take another copy and use that for your editing, don't edit the actual file being used by the software.
** This prevents any conflicts between access by the software and access by your script or tool being used to modify the file.
** It also means that you can go back to the last working copy, you can't upset your "revert" copy.
* The file must never be edited with a word processor, as they store many control and identification characters that prevent Cumulus correctly reading the values.
* Generally, it is easiest if you use either a specialised "Comma Separated Value" file editor or a text editor.
** These tools have the advantage that they can cope with different lines having a different number of fields depending on which version number of Cumulus created each line.
* You can use a spreadsheet application, but if you do, there may be a number of settings to change from their defaults to ensure the file remains in a readable format for Cumulus.
** You need to ensure that your spreadsheet treats every column as plain text, don't let it recognise dates or times and convert them into another format, don't let it convert any numeric field into another format
** If you do use a spreadsheet, extra field separators may be added at end of shorter lines as these make all lines end up with same number of fields.
* Don't remove any figures from fields where figures currently exist, simply overtype one entry with another entry in same format.
* If your file has previously been edited by the relevant editor in MX, a field that looks empty may actually contain one or two space characters.
* If you are editing a field which was empty previously, remember that Cumulus does not accept the concept of nulls (entering -999 or "Null"), there is nothing that can be placed as a place-holder when the correct figure is not known, and empty fields are not permitted in one field if any subsequent field in same line is not empty.
**Beware - if you do insert zero or an obviously wrong extreme value, Cumulus will display those in any editing screen where you wish to update the all-time, monthly-all-time, this month, or this year, extremes. This can make editing by picking values in logs harder.
** Cumulus itself will use zero for any parameters (e.g. solar) not provided by your station, and for up to 6 times it will repeat the last valid value if the station fails to send a value it should provide (normally six successive readings will happen between entries in the standard data log, so repeated values are less likely to affect log files).
* The character (or in a few locales, two characters) used for separating both the day of the month from the month, and for separating the month from the year, must be consistent throughout the whole file (and must not be a single space). Normally, the separator will be either "-" or "/". Whether Cumulus expects a hyphen or a slash is determined by the locale, you must keep to the same locale for the whole file, you cannot change the locale when you do an edit, nor when you update the device running Cumulus. Although, use of comma or point for separating parts of the date is in some locales, and therefore allowed by Cumulus, those locale settings are not recommended as these date separators can cause issues for subsequent edits.
* USA date format with month before day of month, and finally year, is not permitted for log files.
* All figures must be within the range of sensible figures for that field (no hour 24 or higher, no signed numbers when accepted values must be positive, don't put in 200 for a relative humidity)
* Make sure that any editing does not create any blank lines in the file. Cumulus assumes an empty line means end of processing.
* Don't add a header line to the file, Cumulus expects all lines to be data lines.
*Be aware that different devices use different line terminators, so ensure that after editing a file, the line terminator is correct for the device that is running Cumulus:
**The single character representing line feed (in most encodings, LF is binary equivalent of a decimal 10) is used for both UNIX and Linux devices (including Raspberry Pi Operating System)
**The single character representing carriage return (in most encodings, CR is binary equivalent of a decimal 13) is used for Apple operating systems (like Mac)
**The two character sequence first CR then LF is used to terminate lines in all Windows operating systems (part of Microsoft's determination to be different)
**Problems with terminating characters are normally intercepted by operating system, before the contents of a line reaches any software like Cumulus, but if partial editing or merging has produced a file with mixed line terminators, there is a high possibility this will stop any software understanding the resulting file, so be careful if you edit the file on a different device to that running Cumulus.
**Finally, if you are going to use a script (such as JavaScript or PHP) to attempt to read a Cumulus file, that script might only recognise a different line terminator to that your device operating system recognises (most likely with processing on a windows device, the script will treat one of the terminating characters (CR) as part of the adjacent field's text, and only treat the LF as a line terminator).
====Specific rules for dayfile.txt edits====
* The file should be saved without "Byte Order Mark", specialised text editors will include a menu where you select the encoding and can select not to include BOM.
* All rows must start with date and include at least 14 further fields in correct sequence.
* The (meteorological) date format uses two digits for the year.
*In each line, the individual fields must be separated from each other by whatever is the list separator in your locale. Although Cumulus uses "Comma Separated Value" format, the separator does not have to a comma (,), in many locales it is a semicolon (;).
*For fields where a decimal value is permitted (see [[Dayfile.txt#List_of_fields_in_dayfile.txt|daily summary log page]], the separator between integer and decimal parts must consistently be either a decimal point or (only if the field separator is not a comma) a decimal comma. Trailing zeroes are not required, so you can put an integer in a real number field, you don't have to have a decimal comma or decimal point.
*Rows can vary in length but only by missing off fields at the end. The minimum number of fields after the date is 14, the maximum varies between different versions.
*Each field has a pre-defined format, and the same format must always be used in that field position.
*No fields will accept letters.
* Some fields (e.g. bearings, solar, humidity) are integers. Decimals are not allowed in an integer field, so no comma or full-stop can be within these fields.
* Cumulus will only accept highest/lowest figures if each value has a related time-stamp.
** Except for wind gust (start of line) where an extra field is fitted in between value and time-stamp, each time-stamp field will immediately follow the value field for that parameter.
* Time stamp fields must always be in format HH:mm i.e. 2 digit hour in 24-hour format, followed by a colon, then 2 digit minutes
** Be aware you will have problems if you, or your editing software, add seconds.
** If when editing, you don't know what time to quote, the convention is to use a time-stamp of your roll over time i.e. 00:00, 09:00, or 10:00, if you have not looked up the precise time.
* Shorter lines can have multiple field separators added at end of row added either when editing within Cumulus or when editing using a spreadsheet tool.
** Nulls (2 field separators without something between them, e.g.';;') are thus allowed at end of line, but are not allowed within the part of the line with values and time-stamps.
[[File:Open office (editing cumulus log files).png]]
These reasons are why you need to edit this file using an editor that treats all fields as text (a text editor, a CSV editor, or a spreadsheet program that can be instructed not to recognise special field types).
For spreadsheet applications (e.g. Calc in Libre Office, or on Microsoft Windows Excel) avoid using default of recognising formats, ensure that such recognition is turned off, as it is likely to change the dates to either a number representing days since e.g. 31 Dec 1899, or to change it to four figure years, and then Cumulus will no longer be able to use the log file. If you wish to use Excel, or to use "Calc" in 'Apache Open Office', "Libre Office", or similar, you may on opening the file need to pre-select the field separator that is being used now (in this illustration comma is selected, but your file might use semi-colons between fields, don't select commas if your real numbers use comma between integer and decimal parts) and leave "Detect Special Numbers" (or whatever similar feature name your application uses) unselected. Again third party packages processing dayfile.txt will need to recognise your field separator, and some may need to specify it. Don't forget to also select it when you save the edited file (you probably need to select "save as" or the equivalent in your tool to see the option).
|
edits