ncdateread documentation
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.
Back to Climate Data Tools Contents
Contents
Syntax
tdt = ncdateread(file, var) [tdt, tnum, unit, refdate] = ncdateread(file, var)
Description
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.
Example
The example ERA Interim file follows typical climate data standards for its time attribute:
ncdisp('ERA_Interim_2017.nc', 'time');
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
Author Info
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.