Moderate the CF recommendation regarding use of time unit **year**

[larsbarring]

Moderate the CF recommendation regarding use of time unit year

Moderator

@user

Moderator Status Review [last updated: YYYY-MM-DD]

Requirement Summary

For some applications the usual time units (e.g. second, minute, hour, and day) is less convenient because focus is on time periods of many years. In such circumstances the time unit year is often used, despite that the CF Conventions text explicitly recommends not to use it. Despite that there are already a few standard names that make use of yearin their canonical units. These are
age_of_sea_ice (year),
sea_water_age_since_surface_contact (year),
tendency_of_global_average_sea_level_change (m year-1), and
tendency_of_sea_surface_height_above_mean_sea_level (m year-1), as well as the aliased
tendency_of_sea_surface_height_above_sea_level (m year-1).

The UDUNITS2 definition of the unit year is approximately the same length of the average Gregorian year. For applications where the time unit year is relevant to use, this difference is negligible. Hence, there is room for improving the CF convention by moderating the recommendation when to use the unit year.

Technical Proposal Summary

UDUNITS defines unit year as an alias for tropical_year, which has the astronomical definition as is stated within the parentheses. At the same time UDUNITS defines the gregorian_year as 365.2425 days = 31556952 s. The corresponding definition of the tropical_year is 31556925.9747 s, that is a difference of only about 26 seconds.

NOTE: This issue should preferably be considered in connection with PR #604 that also deals with the text in Section 4.4.1

Benefits

Potential users interested in long time periods will find the CF Conventions more appealing.

Status Quo

Associated pull request

tbd

Detailed Proposal

Currently Section 4.4.1 on time units includes this text:

UDUNITS defines a year to be exactly 365.242198781 days (the interval between 2 successive passages of the sun through vernal equinox). It is not a calendar year. UDUNITS defines a month to be exactly year/12, which is not a calendar month. The CF standard follows UDUNITS in the definition of units, but we recommend that year and month should not be used, because of the potential for mistakes and confusion.

The suggestion is to change the wording as follows:

UDUNITS defines a year to be the unit year as an alias for the unit tropical_year defined as exactly 365.242198781 days, which is the interval between 2 successive passages of the sun through vernal equinox. It is not a calendar year , but it closely approximates the average of the Gregorian calendar years, which is 365.2425 days. The difference is approximately 26 seconds. Thus the unit year may be considered for long time perspectives, when there is little or no risk that it is interpreted as calendar year. UDUNITS defines a month to be exactly year/12, which is not a calendar month. The CF standard follows UDUNITS in the definition of units, but we recommend that year and month should not be used, because of the potential for mistakes and confusion.

[davidhassell]

Hi Lars,

Thanks for this!

• Why single out year and, not month. If m year-1 is acceptable for a variable, why wouldn't m month-1 also be OK? Could we not say that either year or month is OK when the data are representative of time periods that are long enough for the inaccuracies in year and month to be negligible?

• I'm wondering what the possible downsides of changing the canonical units of those standard names to s and m s-1 could be. That doesn't stop people using year (or month).

Cheers,
David

[larsbarring]

Hi David,

Regarding you first point, I think there are basically three arguments for keeping the recommendation against using month:

• The month (i.e. the calendar month) is a cultural construct, which since some 2000 years has not been used as a unit of measure in natural sciences:
  • the length of the individual months varies,
  • is there a tangible use case where people actually are using the average length of the Gregorian (or Julian) months? I haven't seen one (happy to be proven wrong!) If not, then the use is likely to mistakenly use it for calendar months. Which I regard as gross error (see next point) that CF should not encourage.
• The sheer difference of the magnitude in error/bias introduced:
  • for year it is ~26 s year-1 or about 0.82 ppm,
  • the error introduced by the varying month lengths is up to about 10% in the extreme.
• There are several question marks regarding the UDUDITS2 unit database when it comes to length of months. I am currently looking into this. What I can say so far is that some units related to months are not correctly defined.

Regarding your second point, I have nothing against changing canonical units to use second instead of year. Refer to #562 (comment) for a wider perspective on what canonical units are actually in use.

[JonathanGregory]

Dear Lars

I think we should keep the recommendation against using year as a unit, for two reasons.

(1) This recommendation has always been part of CF. The fact of its being retained for so long suggests to me that it has not caused problems, and that the CF community in general has thought it appropriate. Of course, we can always change the convention, but there must be a strong reason for removing a recommendation against something, just as there would have to be for introducing one.

The recommendation was included in the COARDS convention in these words:

It is recommended that the unit "year" not be used as a unit of time. Year is an ambiguous unit as years are of varying length. Udunits defines a year as exactly 365 days.

The last sentence is incorrect about the UDUNITS definition of year. CF 1.0 (2003) upheld the COARDS convention, with the words:

We recommend that the unit year be used with caution. The Udunits package defines a year to be exactly 365.242198781 days (the interval between 2 successive passages of the sun through vernal equinox). It is not a calendar year.

Again, that's not exactly correct about UDUNITS, which defines year (https://docs.unidata.ucar.edu/udunits/current/udunits2-common.xml) as 3.15569259747e7 seconds. Dividing by 86400 gives the number of days stated, but it's debatable how many decimal places should be quoted!

In CF 1.9 (2021) the text was changed to the present wording, which you quote:

UDUNITS defines a year to be exactly 365.242198781 days (the interval between 2 successive passages of the sun through vernal equinox). ... The CF standard follows UDUNITS in the definition of units, but we recommend that year and month should not be used, because of the potential for mistakes and confusion.

I can't find a reason in the history for why it was reworded, but I think the present wording is better because it's more direct. "Used with caution" is rather vague, I feel.

(2) The potential for mistakes and confusion is no less than it ever was. In fact the quotations above show that confusion. Either COARDS is wrong about the UDUNITS year, or UDUNITS has changed its definition of year since COARDS was written in 1995. Even if it hasn't before, UDUNITS could change in future, which would make the meaning unclear for existing CF data that used year as a unit. That's a clear hazard with using a non-standard unit. In any case (as we have recently discussed) it's not clear that upholds the UDUNITS definition of units. The convention only says it follows the UDUNITS syntax. It might be that year has no precise definition in CF.

I guess you might argue that the imprecision is too small to matter in practice. I don't agree. Someone might assume that year meant 365.25 days (since it's not instantly obvious what the accurate Gregorian answer is), or 365 days (like COARDS did). If they were using model data, they might assume it meant a model year, which could be exactly 366 or 360 days. The latter would be an error of more than 1%.

Even 1% is not a lot, but any error which is more than numerical precision can cause concern and confusion when doing calculations from model data. A typical situation where it might come up is if you're comparing a given time-mean rate of change or flux between instants separated by a model year with the instantaneous values or content at those instants, as a check that the model is conserving properly. If the flux or rate was given per year and you used the wrong year length, your budget wouldn't close, and I can imagine the analyst wasting hours or days trying to find the problem.

For historical observational data, the error is not large, but it could still be perplexing. Suppose a long historical dataset used the unit of years since 1600-01-01 for its time coordinate. With those units, and the UDUNITS definition of year, midnight on 2025-10-21 is 425.80514 years. If you assumed that year meant 365 days, you'd convert the time coordinate to 2025-07-09 21:00. While this is not a large error, I think it could cause confusion.

Since the purpose of CF is to provide conventions which enable data writers to record metadata giving "a definitive description of what the data in each variable represents", I think we should continue to recommend against year as a unit, because of its ill-defined status.

Best wishes

Jonathan

[pvanlaake]

Dear Jonathan,

I cannot find fault with anything that you wrote but I have to note that it is all premised on one condition: CF time calculus is based on UDUNITS. While that is in general not problematic, there are some specific issues where the choices underlying UDUNITS are problematic. The definition of "year" would be one. It is, for instance, in direct conflict with ISO 34000 which defines "year" as the "duration of a calendar year", pretty much identical to the italicized admonition in the conventions text immediately following the description of the year as used in UDUNITS. In practical terms, the problem of using a "year" as a time coordinate unit is the UDUNITS definition and how it deviates from the common understanding of what a year is.

Coming back to Lars' use case of data sets covering large time intervals (years between successive time coordinates), it would make perfect sense to use a time coordinate unit of "year" because it is more natural to use years than to express time in the only reasonable alternative (day), and using years as a unit does not suggest a higher temporal resolution (and the values will not suffer from numerical instability for very long time series).

Furthermore, there are datasets out there using a time coordinate unit of "year" so it would be good if the conventions can support those in a considered way: use the unit of year only when the difference between a calendar year and a tropical year is insignificant due to the resolution of the data (i.e. do not use the unit of "year" to separate between successive time coordinates at smaller scales).

Obviously, CF software depending on UDUNITS to perform time conversions would suffer some inaccuracy, as Lars noted to the tune of 26 seconds per year, which may add up over long multi-annual periods, but that is an issue that should not be guiding the CF conventions. Maybe UDUNITS should update its definition of a "yaer" instead?

[JonathanGregory]

Dear Patrick

It's true that the explanations previously given for deprecating the unit of year refer to UDUNITS, because CF (like COARDS) adopted UDUNITS for the syntax of units strings. However, we'd be in a similar difficulty even without the link to UDUNITS. If we didn't have UDUNITS, I expect we would refer to some other standard for the definition of units, because it's essential to CF, as a metadata standard for numerical scientific data, that there should be some reference for the legal units strings and their meanings. If CF adhered directly to SI, year might not be allowed at all, because it is not one of the non-SI units permitted for use with SI (though minute, hour and day are). Even if it were allowed, CF would have to define it with some constant value, and I think that's the critical difficulty.

When data-writers want to use year as a time unit, they probably mean a calendar year, which has various possible lengths in UTC up to now (365, 366 days, and each of these plus a number of leap seconds), and three possible lengths in CF model calendars (360, 365 and 366 days). All of these are exact, but they differ. A difference of 5 or 6 days is more serious than the difference of 26 s which Lars mentions between tropical_year and gregorian_year.

Therefore I think we should continue to recommend against year as a unit, for two reasons: (1) If it's some precise but average length such as 365.2425 days, it is almost certainly not what the data-writer thought it meant; (2) If it's an integral number of days, it's quite likely to be wrong by a number of days.

If there is a strong use-case for providing "year" as a time unit by some means, I think it should be a new unit of calendar_year, which would not be convertible to time units i.e. a new base unit. Special software would be needed to convert time coordinates that were stated using this unit (e.g. units="calendar_years since 2025-12-02") into units of time, by referring to the calendar attribute, and dealing with the problem of birthdays falling on 29th February in the standard, julian and proleptic_gregorian calendars.

Best wishes

Jonathan

[taylor13]

I would vote to retain recommendations that neither "month" nor "year" be specified as a unit for data under the CF conventions. There is no standard length of either that is independent of time. And when allowed to vary over time, these units depend on the calendar.

[ChrisBarker-NOAA]

I agree with @taylor13.

But a note: I think people want to use "year" or "month" and others, because they want to capture a concept that CF currently does not (easily) support, which is data associated with named timespan, e.g. an annual average, rather than a value by associated with a particular point in time.

Logically, "years since 2000" seems to make sense -- except that isn't what a time coordinate means in CF.

Maybe we need a way to easily express this concept.

And maybe a note in the doc that that is why "year" and "month" are not supported.

[ChrisBarker-NOAA]

Looking back at the OP on this issue.

There's two kinds of "time": timestamps (time coordinates) and "delta time".

The encoding of time coordinates in CF is, of course, using delta time, but the use case is different than, e.g.

age_of_sea_ice (year)

For which year does make sense, and to some extent it's inherently imprecise enough that exactly which definition is used doesn't much matter.

Though strictly speaking, age of sea ice really is a calendar (or astronomical) year. Not a duration of time per se.

[taylor13]

The age_of_sea_ice is described as: "Age of sea ice" means the length of time elapsed since the ice formed. So it's the answer to the question "how old are you?" Not "when were you formed?". So I think this is "delta time" (elaspsed time since formation). So maybe "year" is not recommended for this variable.

[larsbarring]

My proposal was not taken out of thin air.

Let's straight out a few things before the discussion gets too entrenched:

• @JonathanGregory writes "This recommendation has always been part of CF " and notes at the same time that the text has been changed. The current text (since CF-1.9) reads

  ...we recommend that year and month should not be used, because of the potential for mistakes and confusion" (since CF-1.9)

  In CF-1.8 the text corresponding text reads

  We recommend that the unit year be used with caution."

  There is an obvious difference in strength between recommend not to use and recommend to use with caution. The latter may seem vague if one is is inclined to not "like" year as a time unit. However, if one feels that it is the appropriate time unit in some specific albeit less mainstream use case this change of wording may make all the difference in that is leaves more room for acceptance.

• This change of wording was not properly discussed in an specific issue, but was added after general agreement had been reached on a much wider and more complex issue on calendars, and in particular this comment.

• @JonathanGregory continues "... that the CF community in general has thought it appropriate". Well, I beg to differ:

  • The canonical units associated with the five standard names I refer to in my initial post suggest something else. It is worth noting that these standard names refers to slow (multi-year) processes in the ocean.
  • In the in-person presentation by Heiko Goelzer (ping @hgoelzer), representing the ice-sheet modelling community (ISMIP) at the 2024 CF Workshop, it was specifically noted (viewgraph 6)

    Ice sheets tend to have long memory and integration times (kyr)
    ’years’ is a meaningful unit for us, calendars were/are not

  • After this presentation there was some discussion, and the in the published notes (p. 34) the following comment was recorded:

    we could define a special unit of year (different from UDUNITS) for this sort of application so could link to a date for a paleo calendar.

• year (yr) is a valid UDUNITS2 time unit. It is defined as exactly 3.15569259747e7 s which is exactly same as 31556925.9747 s, which in turn is exactly the same as 365.24219878125 d. As I did these calculation using float64 and arbitrary size integers any floating point errors should be negligible.

• Making the assumption that the real world year is 365 days (i.e. 365.00) days can at best be described as a mistake or a typo. And this kind of mistake on the user side is typically not something that CF is concerned with. On the other hand, assuming a year equals 365.25 days is already catered for in UDUNITS2 by the unit julian_year.

• I will not any further debate arguments where the real world year is mistakenly mixed up with or replaced by various model calendar years.

• As @JonathanGregory notes, for historic reasons CF refers to UDUNITS (I usually thinks of it as "outsourcing") for units syntax and formatting, etc. But behind this there is the more fundamental concept of unit of measure(ment), UoM, where a fundamental requirement is that the unit correspond to a specific, fixed amount of a physical quantity. This quantity can not be ambiguous or context-dependent, which is not the case for a calendar year as both @pvanlaake and @taylor13 notes.

---

Instead I would like to focus on what we have:

• We have the UDUNITS definition of the time unit named tropical_yearand its alias nameyear, with symbol yr. This is not a calendar year that changes over time. It is a unit precisely defined as a multiple of seconds, and hence of days, too.

• As I noted already in my initial post this unit is already (and has been for a long time) associated with five standard names.

• As I further showed in this comment there is indeed a community that has expressed the need for using this unit.

• The current text does not forbid using the unit year, only recommends not to use it. That is, a data file containing the unit year is still fully CF compliant (however see comment below).

• In my initial comment I suggested a change to the current text to more precisely express what the UDUNITS unit year in fact is and how it related to the average Gregorian calendar year. My aim was to better explain for those communities (both those using the existing standard names, and new ones like ISMIP) what it means to make use if this unit.

• Of course, I welcome suggestions how to improve the changes I suggested.

• Leaving the text as is would leave this part of the CF Conventions text in the difficult-to-interpret state where a recommendation to not use is really a must not (or is it????) Is this what @taylor13 and @ChrisBarker-NOAA would prefer, or is the suggestion to actually strengthen the text to actually forbid unit ỳear`?

• Using the CEDA CF checker on netCDF file containing the following

   netcdf test.nc {
   dimensions:
       time = 5 ;
   variables:
       double time(time) ;
           time:axis = "T";
           time:standard_name = "time" ;
           time:units = "day since 1990-1-1 0:0:0" ;
           time:calendar = "standard";
   // global attributes
       :Conventions = "CF-1.8" ;
  
   data:
  
    time = 1., 2., 3., 10., 20. ;
    }
  

  results in no errors, no warnings and no information messages.

• However, changing the unit from day to year result in the following error:

  ERROR: (3.1): Invalid units: year since 1990-1-1 0:0:0
  

  which is not correct for two reasons mentioned earlier:

  • year is a valid UDUNITS year
  • CF only recommended not to use unit year; hence this should be a warning not an error.

[ChrisBarker-NOAA]

where a recommendation to not use is really a must not (or is it????) Is this what @taylor13 and @ChrisBarker-NOAA would prefer, or is the suggestion to actually strengthen the text to actually forbid unit ỳear`?

For my part, I think year and month should be forbidden (or very highly discouraged -- is that a thing?) for time coordinates, but not for variables, e.g. age_of_sea_ice. Time coordinates are already "encoded" [*}, and if a year is clearly defined as a certain number of seconds (as it is by udunits) then there is nothing gained by using year, rather than seconds, or hour, or day.

But for a variable, "year" can be interpreted a bit differently, to mean what it is intended to mean -- a low precision definition time-delta, aligned with the astronomical year. Sure -- if anyone converts it to another time unit, that will be lost, but if not, the intended meaning is preserved.

[*] a lot of software (e.g. xarray) auto-converts time coordinates to datetimes (timestamps) for instance. So the original unit is never seen by the end user anyway.

[pvanlaake]

UDUNITS has a definition for year in terms of a precise number of seconds. But in what context? We all know that the exact duration of the interval between 2 successive passages of the sun through vernal equinox is variable, slowing down by about 0.5 seconds per century. The UDUNITS year is just another definition out there, and faulty too: the vernal-equinox year at J2000 is 365.242374 d, whereas the mean tropical year at J2000 is 365.2421896698 d, so there is a difference of 0.0001843302 d or 15.92612928 s. On the surface, this would all point to disallowing the use of year as a time coordinate unit.

In terms of CF, however, there is not a single calendar that is exactly conforming with the UDUNITS definition. Which brings us back to what @taylor13 said:

when allowed to vary over time, these units depend on the calendar

So the UDUNITS definition depends on a given "calendar" which is based on a celestial phenomenon. But in CF there are specific calendars and for each of these calendars there is a specific definition of the length of a year. And yes, the length of a year may differ, but there are exact rules that determine the length of each year in each calendar. So if year is used as a unit for a time coordinate, then the rules of the specific calendar of the time coordinate can be applied to perform any necessary calculations in a correct way. Within the definition of the CF calendar, that is all correct.

[larsbarring]

@patrick: Of course you are right regarding variations in the length of the tropical year, as well as the long-term changes.

This reminded me of what I did when developing UDUSI. back then , for the very reason you point at I actually considered updating the definition of the tropical year to follow the commonly accepted value for the J2000 mean tropical year. However, as the aim was (and still is) to have a drop-in replacement, I did not change the value. But I did not explore any further the origin of the UDUNITS value (the cited web pages does not exist any more). However, by some further digging, partly assisted by a popular LLM, I have now found out that it is the value used for the previous epochs (B1900/B1950) that were replaced by the J2000 value in1984. Hence I plan to update the UDUSI text to read something like

"
Fixed value derived from the Besselian tropical year (365.242198781 days) used in historical astronomical practice, including the B-epoch system (B1900.0/B1950.0) and the original definition of the ephemeris second. This is a legacy constant retained for compatibility; it is not the true interval between successive vernal equinoxes (which varies) nor the modern tropical year at J2000 (~365.24218XX days).
"
The final value ( the "XX") is still open, but now we are down at micro-second precision, and CF is not for those pointing telescopes at distant objects or involved in high-frequency financial transactions.

Anyway, after this detour, I would like to bring us back to the context of my initial post. The aim is to better support those in need of a unit practical to use over time periods of many years, the unit kiloyear was mentioned, where certainly seconds, and even days, do not matter. And, of course also provide an explanation to those using standard names where unit year appear in the canonical unit.