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.