Add a recommendation to including a TZ offset in time units.

[ChrisBarker-NOAA]

Title

Add a recommendation to including a TZ offset in time units

Moderator

TBA (if needed)

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

TBA

Requirement Summary

The current doc, for time coordinates says:

"""
The reference datetime string (appearing after the identifier since) is required. It may include date alone, or date and time, or date, time and time zone offset. Its format is y-m-d [H:M:S [Z]], where […​] indicates an optional element,
"""

So the timezone offset (Z) is optional.

and:

"""
The default time zone offset is zero.
"""

So leaving out the offset means that the timestamp is the prime meridian time.

It's far too late to change that default, but it is unfortunate that there is no way to express "naive" datetime, or "localtime", etc.

Granted, it's a bad practice to do so -- presumably data providers should know what offset their data are in, and let us know. But it's also, I think, bad practice to simply leave it off.

Note that according to Wikipedia, ISO 8601 specifies that:

"If no UTC relation information is given with a time representation, the time is assumed to be in local time"

Rather than UTC or meridian zero, or ...

So it's not unrealistic to think someone out there might expect that to be the case for CF. (or frankly, they simply aren't thinking about it).

Technical Proposal Summary

Proposal 1:

I propose that we add language to the effect of:

"""
The default time zone offset is zero, but it is recommended that an offset always be provided -- "+0" can be specified for reference datetime strings at the prime meridian.
"""

Proposal 2:

ISO 8601 allows "Z" to be used to mean 0 offset. In fact, according to wikipedia, it recommends it.

But it seems CF does not currently allow the "Z"

But I'm pretty sure I've seen otherwise conforming files use the "Z", and all the software I've tested accepts it.

So I think we should allow it in CF.

Conformance question:

not specific to this proposal, but is there a standard for flagging non-recommended practices in conformance checkers?

I thought there was a "conformance document" somewhere, but I can't find it -- am I imagining things? -- found it: https://github.com/cf-convention/Conformance/blob/master/conformance.adoc
Nevermind.

Benefits

Hopefully, future datasets will be a tiny bit less ambiguous in the future.

Status Quo

Status Quo is that a number of datasets in the wild don't have a TZ offset explicitly -- not a killer, but hopefully there might be fewer in the future if this is added.

Associated pull request

I'll do a PR, if folks think this is a good idea.

[JonathanGregory]

Dear Chris

These are interesting points. Thanks.

Proposal 1

If you have a gridded field (which is the kind of data CF was invented for and is very commonly used for) it doesn't really make sense to use a non-zero timezone offset anyway, because the same time-coordinate applies everywhere in the spatial field, often the whole world. I don't think a recommendation to include a timezone offset is useful in that case.

Is this a concern more for data in discrete sampling geometries, such as station timeseries? If so, perhaps we could make the recommendation for that kind of data only?

Proposal 2

CF uses UDUNITS for its units syntax, as you know, and I find that UDUNITS supports Z to mean zero timezone offset. In fact, UDUNITS is more accepting than I wrote when drafting the new text in Sect 4.4.1. It allows you to specify the timezone offset or Z even when you omit the time. We could change the text to say

Its format is y-m-d [H:M:S] [Z], where [...] indicates an optional element

as well as allowing Z to be Z, if people think it's useful. You can put seconds since 1972-1-1Z, for instance.

Cheers

Jonathan

[ChrisBarker-NOAA]

If you have a gridded field (which is the kind of data CF was invented for and is very commonly used for) it doesn't really make sense to use a non-zero timezone offset anyway, because the same time-coordinate applies everywhere in the spatial field, often the whole world. I don't think a recommendation to include a timezone offset is useful in that case.

well, there are smaller scale region models that are all in one timezone, and, as you point out, point data is sometimes stored in some version of local time.

but whether you want to include a non-xzero offset or not -- it's still better for us to be consistent, and having "0" or "Z" there is better than leaving it blank and hoping for teh best.

In any case, there's never a reason not to do it, hence why I htink we should suggest that it always be done.

as well as allowing Z to be Z, if people think it's useful. You can put seconds since 1972-1-1Z, for instance.

Lets do that -- I'll draft a PR soon, unless someone beats me to it :-)

[taylor13]

Suggesting, I suppose, is o.k., but I'm pretty sure nearly everyone that's time-stamping 0Z will simply omit it. I know I would.

[JonathanGregory]

I don't think it's worthwhile recommending it for gridded fields. Do you know examples of gridded fields (from models or obs), contained all within one timezone, for there is a risk or actual cases where the data-writer intended local time but has forgotten to record the timezone offset?

I do think it's more likely to be forgotten for discrete sampling geometries containing observed data, but I don't know how likely, because I lack experience of these data. Do you work with such data? Does anyone else have experience of whether people forget to record timezones - Luke @lhmarsden, for instance?

Suggesting is harmless, but recommending has the cost of possibly annoying and useless warnings being produced by the CF checker.

[ChrisBarker-NOAA]

I don't think it's worthwhile recommending it for gridded fields

well, I'm not so sure I agree, but the way CF is is written, a time coordinate is a time coordinate, so we can only make one recommendation.

Does anyone else have experience of whether people forget to record timezones

I certainly have -- though I can't say for sure whether they files in question claimed to be CF compliant.

But anyway, there's nothing we can do about that now -- CF has stated (forever?) that no offset provided means time at prime meridian (what most people call UTC or GMT, but I know why we're not using those terms).

All I'm suggesting is that it's better to put:

2025-01-10T12:12:30Z

than

2025-01-10T12:12:30

Because then there is no chance whatsoever for a misunderstanding.

explicit is better than implicit, and all that.

NOTE: This came up for me because I'm working on some software where we are trying to make it more timezone smart -- and my team was uncomfortable with using UTC when an offset is not specified -- even though it's the CF standard. I think we've been bitten far to often with not-quite compliant files, even if not for this particular reason.

So I thought -- "wouldn't it be better if people simply put the Z (or zero) on there?"

Side note: There was also a painful misfeature in the initial numpy datetime implementation -- following standards, it interpreted no offset as UTC, and then applied the offset that the computer is was running on to make it UTC -- that was a really ugly mess! I know this is not the same thing, but it makes me wary -- again, I really prefer being explicit!

@taylor13 wrote:
" I'm pretty sure nearly everyone that's time-stamping 0Z will simply omit it. I know I would."

Why is that (for you anyway)? It seems simple and clear to me is that much of a burden?

Anyway, off to write a PR -- at least for the "Z" part, still not clear there's any consensus on the recommendation.