Today.ini

Revision as of 15:13, 8 June 2021 by Sfws (talk | contribs) (Update category)

Introduction

The files today.ini and yesterday.ini are used by Cumulus to store some counts, plus the Highs and Lows (and their timestamps) for key parameters as reached on each of the two days, for Cumulus 1 these are source for figures that appear on the main screen, for Cumulus 2 and 3(MX) they appear on the dashboard you can view. These files are normally located in the "Data" sub-folder of the path where your Cumulus.exe is installed. See FAQ on location of data log files for where else to look.


Format of the file

This is as described at Category:Ini_Files, where some differences between the legacy Cumulus and MX are noted. For today.ini, it is important to be aware that MX can read a file created by Cumulus 1 (MX can read the time format in the value for Timestamp= parameter whether it is in Cumulus 1 or MX format), but Cumulus 1 cannot read a file that has been updated by MX. MX adds sections [FeelsLike] and [Records] that Cumulus 1 does not recognise, and MX changes the time format in the value for Timestamp= parameter so that Cumulus 1 cannot understand it.

The today.ini contains a number of sections, also headed with something in square brackets [], then a number of parameters in format "attribute=value".

The sections (after the first [General]) can be in any order, Cumulus will maintain whatever order the sections are currently in. For readability you can insert blank lines into this file, Cumulus will not mind. Do not however introduce any punctuation nor change the format of any parameter line. Remember Cumulus needs to read and update this log file throughout the day, so do not attempt to edit it while Cumulus is running, as that could conflict with an edit by Cumulus.

  • The [General] section stores current date and time.
  • The [Wind} section stores the highest wind speed and highest gust, it holds the sum of wind speeds as wind run, and details for the dominant wind.
  • The [Temp], or temperature, section stores the highest and lowest temperature, the sum of all temperatures from every minute (Total), and the number of Samples in that total, the Cumulative Chill Hours in the season, and the cumulative Heating and Cooling Degree Days for the current day.
  • The [Pressure], [Humidity], [AppTemp], or apparent temperature, and [Dewpoint] sections just hold Highs and Lows.
  • The [WindChill] section only holds lowest, the [HeatIndex] section only has highest.
  • The [Rain] section holds a lot of different parameters, including the Start count that derives most rain outputs, and the LastTip date-time.

Other sections always present are [ET], [Solar], and [FineOffset] whether these are updated depends on whether your weather station supplies the necessary information.

All today.ini also have [NOAA] which will only be populated if you have set up NOAA reports, once you have enabled NOAA reporting, this section shows the file names of the latest monthly and yearly reports.


Differences between Cumulus 1 and Cumulus MX

All the sections listed above are found in both flavours of the software, and ap[art from time-stamps the contents are identically formatted.

Please see the examples later on this page for more information about time-stamp formats, as it varies depending on weather station type as well as Cumulus flavour.

MX adds an additional section [Records] that contains entries denoting when extreme records were last revised. For example "Alltime=2020-03-06T06:42:13", indicates when the all-time extreme records was last updated. In the example file, there were various extreme records broken at that time on 6 March (lowest temperature, lowest apparent temperature, and greatest wind chill), but none have been broken since.

MX adds another new section [Feels like] which stores highest and lowest feel like temperatures (and time-stamps) for the day.

Changes to this file at particular releases

This section may not be a complete history, and may not be kept up to date; so don't take it as authoritative

  • 3.11.0 build 3129 (released on 7 May 2021)
    • Fix: End of day backup now always runs at rollover, so like most releases of the legacy software, the stored file represents the true end of day position.
      • For example in the [General]' section, the Date (calendar date) and Timestamp attributes will relate to when it was last updated, but the three Current attributes will relate to the meteorological date just ended.
      • For the today.ini in the backup/daily folder, last update time-stamp will indicate time as at one update cycle before end of day, but file last modified will show that was at end-of-day
    • New: Added (to [Temp]) GrowingDegreeDaysThisYear1=, and GrowingDegreeDaysThisYear2=.
  • 3.7.0 - build 3089 (released on 28 July 2020)
    • Canadian Humidity Index (Humidex) added for highest extreme monitoring in today.ini (and other longer period extreme log files)
  • Release 3.6.6 build 3082 (released on 1 June 2020)
    • Values in the file had been stored (in all previous builds) using 15 decimal places (because of difficulty in representing decimal parts of numbers in binary), from this release revised so all values stored using 17 significant figures
  • Release 3.6.3 - build 3079 (released on 21 May 2020)
    • Fix long standing problem with today.ini becoming corrupted when Microsoft Windows is shutdown
  • Release 3.6.0 build 3076 (released on 4 May 2020)
    • added Feels Like to daily high and low extremes monitored in today.ini (and other longer period extreme log files)
  • From version 1.9.4 build 1089 to release 3.10.5 build 3122
    • The today.ini stored in the daily backup contains the position as at start of day (or in specified older MX releases, up to one UPDATE interval later), so it does not contain any information (except Cumulative Chill Hours) that relates to day that has just ended.
  • Up to version 1.9.4 build 1088 (released 28 Jan 2014)
    • The today.ini stored in the cumulus\backup\daily\FOLDER_NAME ((where FOLDER_NAME is based on date and time of creation) represented the end of day (including on last day of month) extremes
  • version 1.8.9 (released on 31st March 2010)
    • Fix problem with month names (timestamp in today.ini) using short date format
  • version 1.8.6 (released on 14th April 2009)
    • Don't write today.ini unless station contacted
  • version 1.8.5 (released on 12th February 2009)
    • Fix wrong times for some of today's extremes
  • Not documented
    • It is believed that today.ini may have been introduced at version 1.4
  • Version 1.0 27th January 2004 First release
    • Only dealt with current conditions handling, there was no tracking of daily extremes

General information

Important Note

  This page was written for the (legacy) Cumulus 1 software. It has been partially updated to cover MX, but that was for a MX release that is no longer latest!

Please can a contributor update content, so it is more friendly for those using latest release, while still helping those using older MX releases and the legacy Cumulus software.


When Cumulus is running

The highs and lows, as held in memory while Cumulus is running, are constantly re-written to today.ini.

At the end of a day [either midnight, or 9am (or 10am) depending on your configuration and season], the final values and timestamps written to today.ini file are rolled-over. Many are written as a new line appended onto dayfile.txt and most become values and timestamps in yesterday.ini; then a new today.ini is created. The three files have a few differences in content, so rolling-over does involve a little editing work, for example the 'Total' and 'Samples' values in today.ini become the single 'AvgTemp' in yesterday.ini and dayfile.txt; another example is the multiple lines in the [General] section of today.ini shrink to just one item in yesterday.ini (Date) and one item in dayfile.txt (abbreviated date). When Cumulus is left running, a daily backup of all the files is created as part of this rollover in a subfolder 'daily' of the backup folder. Equally, if you close Cumulus during the day it will write the final values for highs and lows and their timestamps to today.ini as part of the close down process.

Restart and Catch-up

If you restart Cumulus during the day it will read the today.ini file at startup, so it can resume tracking extremes of the key parameters starting from latest stored values in today.ini. On restart it also writes a backup of today.ini (and some of the other Cumulus files) into the sub folder 'backup' below the folder with the cumulus.exe. Because Cumulus software does it changes first in an internally stored area before writing out to today.ini, if you try to edit today.ini while Cumulus is running, you may find your edit is lost next time Cumulus itself outputs an updated file, even if your edit is not lost, you may lose a Cumulus edit by saving your own edited version to overwrite the Cumulus edit. So never edit without stopping Cumulus first. (yesterday.ini is created at rollover and then not updated, so that file can be edited while Cumulus is running provided you are several minutes away from rollover time).

If your weather station type supports it, while Cumulus is doing a catch-up, after being restarted, today.ini will be updated with revised highs and lows as it processes the station's memory; and if necessary it will do a roll-over as it processes the readings for the relevant time (this roll-over process takes a bit longer to create the daily backup than that when Cumulus is left running). As explained on support forum, there can be problems if Cumulus is started/stopped just before or just after (i.e. close to) its roll-over time, the problems were worse for earlier versions of Cumulus 1, but have been reduced in newer builds of C1 and therefore for MX. You should not start or stop it within whatever time you have set as interval between logs.

Dealing with rogue values

The today file is written to throughout the current day as any new High or Low for the day at reached. If your weather station reports a rogue value, an incorrect update to the High or Low may result, but details of that update should be in the Diags_folder, so look there to see what correction will be required to eliminate the rogue value. Normally you would not need to edit today.ini, as if you wait until the next day, Cumulus provides (with its Edit menu) an easy way to amend the stored extremes for this month, this year, monthly records, and all-time. The wrong figures may be displayed on the yesterday screen for this next day, but yesterday.ini can be edited more easily!

Notes:

  • If you do decide to edit 'today.ini' outside Cumulus, you must close Cumulus down first!

Editing rainfall in today.ini within Cumulus

This applied to Cumulus 1 and Cumulus MX. Both contain an editor for 'today's rain'.

  • You may wish to edit the rain data if there has been a quirk in your weather station sensor for rain (or in figure reporting) during the day and the figure is abnormally inflated (or indeed under-reported).
  • The stored rainfall today start count value in today.ini may be edited via Today's rain screen on the Edit menu.
    • This edit purely changes the Start= line within the '[rain]' section, i.e. changes the Total rainfall counter (content depends on weather station type, might be rainfall total so far this year; it is not intended to be useful in itself, it may vary for no apparent reason) value that is stored within today.ini.
    • Consequently, using this feature creates a sudden increase or decrease in the 'Total rainfall counter (content depends on weather station type, might be rainfall total so far this year)' figure stored the next time Cumulus updates its log file for the current month.
    • You still need to manually edit (using an external text editor) the other parameters within that [Rain] section to correct the other rain statistics held in 'today.ini':
      • last tip time-stamp ("LastTip=")
      • highest rainfall rate so far today and time-stamp ("High=" and "HTime=")
      • hourly high amount and time-stamp ("HourlyHigh=" and "HHourlyTime=")
      • consecutive wet/dry days ("ConsecutiveRainDays=" and "ConsecutiveDryDays=") - remember these counts are to last roll-over, they exclude today
    • If you do edit any parameter values remember to ensure the replacement is in exactly same format as before (whether integers, real numbers or a particular format for time-stamps)
  • This edit does not affect any derived rainfall values (such as totals for the month or year that are displayed (and output via web-tags)), unless you subsequently close and restart Cumulus the same day to force recalculation of the longer period totals.
  • You don't need to restart Cumulus after a change to today's rain to ensure that dayfile.txt has correct new line added at next roll-over.
  • This edit does not change any lines already in the log file for the current month, so any process you have that reads those will read some wrong values and this can distort for example graphs attempting to portray rainfall within a day. Although rainfall since midnight is stored in the last field of the Cumulus log file for the current month, manually editing there will not help as Cumulus does not read it from there. Cumulus works out rainfall since midnight by looking at the entry at (or first just after) midnight, and that past line has not been updated. If you want to correct rainfall since midnight there because you have processes that read this file, then remember you can only safely edit (using a specialist CSV editor, a good text editor, or a programmer's editor like 'Notepad++) that file with Cumulus stopped, as Cumulus demands full locked access to this file for periodic updating. Editing this file is difficult, because you have to work backwards through time working out what needs to be subtracted from the rain counter value from what increment the old value had from the one immediately earlier.

Editing today.ini or yesterday.ini outside Cumulus

If the rogue value is not rainfall, then you might need to edit today.ini or yesterday.ini using an external editor. Note: If you do edit either of these files, you must close Cumulus down first!

The files are text files, so edit using any plain text editor. The format consists of a number of sections (section title is delimited by [ ]), and a number of properties (consisting of attribute name, an equals sign and a value). Blank lines can be included for readability, they are ignored in these .ini type log files. All values have to be specified in the correct format, see example below.

Composite Example of 'today.ini' file

The minimum content for this file is the "[General]" section. See FAQ here for the single reason why you might want to remove all other sections from your file when you are first starting use of Cumulus with a weather station. This is an example made up of composites that may not all be present in an actual file; and an actual file may have the sections in a different order. Because this example is made up of composites, the times shown are not all consistent, in a real file no time anywhere will be later than the time at the top!

  • This composite contains time-stamp formats used by Cumulus 1.x.y and Cumulus MX in the few places where they differ. Notes in round brackets () are not part of the file, they simply explain elements of the composite.
  • The sections can be in any order; I'm not sure what order Cumulus 1 and Cumulus MX use when they first create this file, but when they recreate this file, the order remains unchanged. So if you do edit this file and that edit leaves the sections in a different order, both versions of Cumulus will from then onwards use that new order. I discovered this as I have a PHP script that reads today.ini from the backup directory and it failed when it found sections in a different order. I had copied part of my today.ini from a nearby site (the Chill Hours figure shown represents a season, but I had just started at a new location so I decided to use his section for that and copied it in at end, deleting my original section that had been higher). Morale of this story is don't make assumptions when writing a script, make it cope with all possibilities when working with a file where the sequence is not fixed!
[General]
Date=29/09/2019
Timestamp= (the format here is different for Cumulus 1 e.g. "29/09/2019 09:50:00" and Cumulus MX e.g. "2019-09-29T09:50:00")
CurrentYear=2019
CurrentMonth=9
CurrentDay=13

[Wind]
Speed=10.7008972167969
SpTime=10:09
Gust=22.0114517211914
Time=08:42
Bearing=90
Direction=E
Windrun=63.1526298522949
DominantWindBearing=317
DominantWindBearingMinutes=1041
DominantWindBearingX=-3914.11743164063
DominantWindBearingY=4215.82763671875

[Pressure]
Low=1014.89996337891
LTime=11:13
High=1018.79998779297
HTime=00:06

[Rain]
High=0
HTime=00:00
Start=1923.59997558594         
Yesterday=0                    
LastTip=2012-09-14 10:48
HourlyHigh=0
HHourlyTime=00:00
ConsecutiveRainDays=2
ConsecutiveDryDays=0
RG11Today=20

[ET]
Annual=1148.2578125
Startofday=1147.24182128906

[Temp]
Low=8.30000019073486
LTime=01:16
High=16.8999996185303
HTime=11:41
Total=7500.697265625
Samples=714
ChillHours=3147.15673828125
HeatingDegreeDays=5.34738397598267
CoolingDegreeDays=0.502222061157227

[HeatIndex]
High=16.8999996185303
HTime=11:41

[AppTemp]
Low=5.0417857170105
LTime=01:30
High=15.0359125137329
HTime=11:52

[WindChill]
Low=6.39816427230835
LTime=01:30

(this next section only appears if you are using Cumulus MX)
[FeelsLike]
Low=13.6250566304131
LTime=10:00
High=18.2396897206409
HTime=14:21

[Dewpoint]
Low=5.30104923248291
LTime=00:52
High=10.7219848632813
HTime=11:38

[Humidity]
Low=65
High=88
LTime=11:45
HTime=06:06

[Solar]
SunshineHours=1.08333301544189
SunshineHoursToMidnight=5.80002069473267
HighSolarRad=1048
HighSolarRadTime=09:41
HighUV=7.40000009536743
HighUVTime=09:41
SunStart=0

[NOAA]
LatestMonthlyReport=NOAAMOSep2012.txt
LatestYearlyReport=NOAAYR2012.txt

(The above section will look like the one below if NOAA reporting has not been set up)

[NOAA]
LatestMonthlyReport=
LatestYearlyReport=

[FineOffset] (this is MX format when not a Fine Offset station)
FOSensorClockTime=0001-01-01T00:00:00
FOStationClockTime=0001-01-01T00:00:00

[FineOffset] (this is when using a Fine Offset station)
FOSensorClockTime=(the format here is different for Cumulus 1 e.g. "29/09/2019 09:50:00" and Cumulus MX e.g. "2019-09-29T09:50:00")
FOStationClockTime=(the format here is different for Cumulus 1 e.g. "29/09/2019 09:50:00" and Cumulus MX e.g. "2019-09-29T09:50:00")

(this last section only appears if you are using Cumulus MX)
[Records]
Alltime=2020-03-06T06:42:13

Cross-references for explanations of key parameters

Bearing and Direction, Windrun;

Temp, Total and Samples, Humidity, Heating degree days, Cooling degree days, AppTemp, Heat index, wind chill, Chill hours, Dewpoint;

Rain, ConsecutiveRainDays, ConsecutiveDryDays;

NOAA.