How to convert the number of seconds from an epoch into UTC using the datetime function.

I am struggling to convert the number of seconds from an epoch (1980-01-06 GPS epoch) into UTC using the datetime function. The following commands give me a time of 18-Mar-2021 20:37:31, however in UTC this should be 18-Mar-2021 20:37:13 since I would need to subtract out the number of leap seconds from the total (currently there are 18 leap seconds since the 1980-01-06 GPS epoch).

NoOfSeconds=1300135051;
datetime(NoOfSeconds,'convertfrom','epochtime','Epoch','1980-01-06')

Can the datetime function automatically account for leapseconds in this conversion? I tried using the 'TimeZone','UTCLeapSeconds' name/value pair, but this adds 18 seconds since it assumes the time is already in UTC.

Answer 1

[Peter Perkins]

Matthew, this is easier than you think. In MATLAB, 'TimeZone','UTC' is sort of a ficticious timeline that pretends that leaps seconds don't exist (because hardly anyone wants to actually account for leap seconds). 'UTCLeapSeconds' is the timeline that knows all about leap seconds. The GPS timeline (in the real world) ticks off the same leap seconds as 'UTCLeapSeconds' in MATLAB does, it just doesn't treat them specially. So for the purposes of arithmetic, i.e. elapsed time, 'UTCLeapSeconds' is what you want. Then all you have to do is change to 'UTC' (or not, it's up to you).

>> epoch = datetime(1980,1,6,'TimeZone','UTCLeapSeconds')
epoch = 
  datetime
   1980-01-06T00:00:00.000Z
>> dtUTC = epoch + seconds(1300135051)
dtUTC = 
  datetime
   2021-03-18T20:37:13.000Z
>> dtUTC.TimeZone = 'UTC'
dtUTC = 
  datetime
   18-Mar-2021 20:37:13

Also, this Answer might be helpful:

https://www.mathworks.com/matlabcentral/answers/660293-get-gps-time-to-calulate-time-since-referencje-epoch#answer_554718

If I may ask, I would be interested in hearing more about how you work with GPS timestamps. Do you always get "seconds since 1980" as your input? Do you need to work with "week number, seconds within week"? Do you need to work with "human readable timestamps" (e.g. 18-Mar-2021 20:37:31) that refer to the GPS timeline (as opposed to UTC)? Do you need to convert back to one of those GPS time formats? Thanks in advance for anything you are able to share.

[Matthew Casiano]

That's great, thanks for the help.

I may get data in 'seconds since the 1980 epoch' or I may get it in 'UTC'. Being able to go back and forth is helpful, but generally I keep everything in 'UTC'. I do not work with week number or seconds within the week, but might need the day of the year. So I do use the 'datevec' and the 'day' functions. For example if I need it in this form yyyy:ddd:hh:mm:ss.sssssssss, I would use the 'datevec' and 'day' functions to operate on the 'datetime' object and then concatenate the appropriate information into a string.

[Peter Perkins]

You don't need to build those strings yourself:

>> d = datetime
d = 
  datetime
   03-Aug-2021 09:27:24
>> s = string(d,'yyyy:ddd:hh:mm:ss.SSSSSSSSS')
s = 
    "2021:003:09:27:24.941045000"

But you may not need to convert to string at all:

>> d.Format = 'yyyy:ddd:hh:mm:ss.SSSSSSSSS'
d = 
  datetime
   2021:003:09:27:24.941045000

[Matthew Casiano]

Great advice. Next revision I'll definitely streamline my scripts with this. Not sure how I missed this means of outputing the timestamp. Thank you for the help,

[Abhishek Ballaney]

How to convert week, seconds to UTC?

[Peter Perkins]

I imagine what you mean is convert GPS week/second to UTC. It would be good for you to be clear.

The GPS timeline has no leap seconds or DST, so each week is equal length. Convert to seconds, and then do what's described earlier in this thread.

[James Tursa]

One needs to be careful with this approach, since a direct conversion of UTCLeapSeconds into UTC during a leap second creates a jump at a location that doesn't match posixtime. E.g.,

format longg
% Create a GPS seconds in the middle of a leap second.
GPS_epoch = datetime(1980,1,6,'TimeZone','UTCLeapSeconds')

GPS_epoch = datetime
   1980-01-06T00:00:00.000Z

dtleap = datetime(2016,12,31,23,59,60.5,'TimeZone','UTCLeapSeconds')

dtleap = datetime
   2016-12-31T23:59:60.500Z

gps = seconds(dtleap - GPS_epoch)

gps = 
              1167264017.5

% Now reconstruct the datetime associated with this GPS time
dtutc1 = GPS_epoch + seconds(gps)

dtutc1 = datetime
   2016-12-31T23:59:60.500Z

% Direct conversion to UTC
dtutc1.TimeZone = 'UTC';
dtutc1.Format = 'dd-MMM-uuuu HH:mm:ss.S z'

dtutc1 = datetime
   31-Dec-2016 23:59:59.5 UTC

Well, it jumped backwards instead of counting into the next day. This conflicts with the posixtime result:

dtgps2 = GPS_epoch + seconds(gps)

dtgps2 = datetime
   2016-12-31T23:59:60.500Z

dtutc2 = datetime(1970,1,1,'TimeZone','UTC') + seconds(posixtime(dtgps2));
dtutc2.Format = 'dd-MMM-uuuu HH:mm:ss.S z'

dtutc2 = datetime
   01-Jan-2017 00:00:00.5 UTC

Here we get the leap second itself counting into the next day. Bottom line is to use posixtime on the UTCLeapSeconds version of the datetime BEFORE converting to UTC if you want this consistency.

Side Note: MATLAB may be changing the behavior of the direct UTCLeapSeconds to UTC conversion in a future release to be consistent with posixtime, so the direct conversion of UTCLeapSeconds to UTC may not behave the same as the above in future MATLAB releases.

[Peter Perkins]

James, you are mixing apples and oranges. "UTCLeapSeconds" represents the real-world timeline that official UTC clocks follow, including counting leap seconds. "UTC" is a ficticious timeline that makes life less painful for the overwhelming majority of people who do not want to complicate their life with leap seconds.

2016-12-31T23:59:60.500Z does not exist on the ficticious "UTC" timeline. If I want to convert that to "UTC", should it map to 23:59:59.5 on that timeline, or to 00:00:0.5 on the next day? I would argue that the former creates fewer problems because it does not change the date, and I guess you would argue that since POSIX defines the POSIX time during a leap second as the 0th second of the next day, that's how the conversion should work. But the real answer is that there is no answer. It can't possibly be a lossless conversion.

This

dtutc2 = datetime(1970,1,1,'TimeZone','UTC') + seconds(posixtime(dtgps2))

adds an elapsed time that was calculated under "UTCLeapSeconds" to a "UTC" datetime. They should not be mixed, and it's going to lead to inconsistencies.

It seems like maybe the underlying issue is that UTCLeapSeconds only supports the ISO display format, and you'd like more flexibility, so you are partially using "UTC", and partially "UTCLeapSeconds".

[James Tursa]

@Peter Perkins I am not trying to get into an argument here about what MATLAB should do in this lossy conversion. I prefer consistency among other MATLAB functions such as posixtime, and you prefer to keep the date the same. OK, fine. But that's not my point. My point is the user should be aware of what datetime does during this conversion and offer a different formulation so they can choose the behavior they want if needed. That's all.

Answer 2

[Matthew Casiano]

Since there is a leapseconds table included in Matlab, there is a workaround to obtain the cumalative number of leap seconds. This can then be subtracted off of the total number of seconds from an epoch.

% Determine the number of leap seconds since the 06-Jan-1980 GPS epoch by using a Matlab-defined timetable array called 'leapseconds'. 
TimeTableLeapSeconds=leapseconds;                                       % Matlab-defined timetable array of leap seconds information
CurrentDateTime=char(datetime('now'));                                  % converts the current time to a character array
DateTimeRange = timerange('06-Jan-1980 00:00:00',CurrentDateTime);      % creates a timerange object with the desired time range
[tf, whichrows]=containsrange(TimeTableLeapSeconds,DateTimeRange);      % determines which rows of the leap seconds timetable are within the time range
AllRowsRange=TimeTableLeapSeconds(whichrows,1);                         % selects the first column of all rows in the range which is a timetable containing the leap second sign
AllLeapSecondSignsRange=char(AllRowsRange.Type);                        % convert timetable array to character array containing all the leap second signs within the time range
AllLeapSecondsRange=str2double(AllLeapSecondSignsRange+"1");            % append '1' to the sign and create a numeric array with all the leap seconds within the time range
CumLeapSecondAdj=sum(AllLeapSecondsRange);                              % sum contents of the numeric array producting the cumulative leap second adjustment

Answer 3

[Sarthak]

function date = gps2utc(g0, g1)

date = datevec(datetime(g0*604800+g1,'convertfrom','epochtime','Epoch','1980-01-06'));