This function reads in a time variable from a netCDF file into a datetime array, assuming that the variable conforms to CF standards with a ' time units since reference time' units attribute.
tdt = ncdateread(file, var) [tdt, tnum, unit, refdate] = ncdateread(file, var)
tdt = ncdateread(file, var) reads values from the time variable var in the netCDF file (or files) file into the datetime array tdt, assuming that variable uses a standard (i.e. gregorian) calendar and includes a units attribute in the form of ' time units since reference time'. The supported time units are microseconds, milliseconds, seconds, hours, minutes, and days (or day). file can be either a string/character array holding the path of a single file, or a cell array of strings holding a set of files that share a single unlimited time dimension.
[tdt, tnum, unit, refdate] = ncdateread(file, var) also returns the original file time values tnum in their unconverted form, the unit character array, and a datetime refdate that matches the reference date in the units attribute.
[...] = ncdateread(file, var, tnum) provides an option to convert numeric-time values in a variable using the same unit properties in the indicated by the file and variable name.
NOTE: Options for year or month units are intentionally not included here due to the possibility for incorrect translation related to these units. CF standards define a year to be exactly 365.242198781 days, rather than a calendar year; similarly, a month is 1/12 of this value. This is rarely a useful way of counting time, and therefore we leave it to the user to determine whether a file using these units intends the calendar year interpretation or the strict interpretation and to manually parse the date themselves.
The example ERA Interim file follows typical climate data standards for its time attribute:
Source: /Users/kakearney/Documents/MATLAB/Add-Ons/Toolboxes/Climate Data Toolbox/code/cdt_data/ERA_Interim_2017.nc Format: 64bit Dimensions: time = 12 (UNLIMITED) Variables: time Size: 12x1 Dimensions: time Datatype: int32 Attributes: units = 'hours since 1900-01-01 00:00:00.0' long_name = 'time' calendar = 'gregorian'
Here, we can read that time data directly from the file without needing to know ahead of time what the units or reference date are:
[tdt, tnum, unit, refdate] = ncdateread('ERA_Interim_2017.nc', 'time')
tdt = 12×1 datetime array 2017-01-01 2017-02-01 2017-03-01 2017-04-01 2017-05-01 2017-06-01 2017-07-01 2017-08-01 2017-09-01 2017-10-01 2017-11-01 2017-12-01 tnum = 12×1 int32 column vector 1025628 1026372 1027044 1027788 1028508 1029252 1029972 1030716 1031460 1032180 1032924 1033644 unit = 'hours' refdate = datetime 1900-01-01
If the time variables were already in our workspace (for example, if the data had been read in using some of the more flexible hyperslab subsetting options available in ncreads, we can convert the values after the fact by pointing to a file with the necessary conversion units data:
A = ncreads('ERA_Interim_2017.nc', struct('time', [1 5 2])); A.time
ans = 5×1 int32 column vector 1025628 1027044 1028508 1029972 1031460
A.time = ncdateread('ERA_Interim_2017.nc', 'time', A.time); A.time
ans = 5×1 datetime array 2017-01-01 2017-03-01 2017-05-01 2017-07-01 2017-09-01
This function and supporting documentation was written by Kelly Kearney for the Climate Data Toolbox for Matlab, 2019. It is available as part of this toolbox, and can also be downloaded individually from GitHub.