cftime documentation
The cftime function converts between Climate Forecast (CF) convention times and Matlab datetimes.
Back to Climate Data Tools Contents
Contents
Syntax
[dt, unit, refdate] = cftime(t, tunit) [dt, unit, refdate] = cftime(t, tunit, fmt) [dt, unit, refdate] = cftime(t, tunit, fmt, mode)
Description
[dt, unit, refdate] = cftime(t, tunit) converts a matrix of numeric CF times t with units described by the reference string or character array tunit to a matrix of datetimes, dt, with the same dimensions as t. tunit should be specified as "time-unit since timestamp"; see the CF Conventions time coordinate documentation for more information. The unit and refdate output variables are optional, and will parse the tunit string into a character array with the time unit and a scalar datetime holding the reference date, respectively.
[dt, unit, refdate] = cftime(t, tunit, fmt) allows the user to specify the format of the reference date portion of the tunit string. This string should follow the same format as the 'InputFormat' option for datetime. If not included, cftime will attempt to parse the string automatically using the same rules as datetime.
t = cftime(dt, tunit, fmt, 'reverse') converts a matrix of datetimes to numeric CF times t. The optional fmt specifier can be an empty array to allow for default reference date parsing within the tunit string.
Example 1: Converting from CF time to datetime
Most data files used in climate science try to abide by the Climate Forecast standards for metadata; for time variables, these standards specify dates as a time duration since a reference date. We can see this in the example ERA Interim data:
ncdisp('ERA_Interim_2017.nc', 'time'); t = ncread('ERA_Interim_2017.nc', 'time')
Source:
/Users/kakearney/Documents/MatlabCodeKAK/External/CDT/cdt/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'
t =
12×1 int32 column vector
1025628
1026372
1027044
1027788
1028508
1029252
1029972
1030716
1031460
1032180
1032924
1033644
We can convert this data to a more user-friendly datetime via cftime:
tunit = 'hours since 1900-01-01 00:00:00.0';
dt = cftime(t, tunit)
dt = 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
(In this case, we could also simply read directly from the file with the ncdateread function, which also reads the time data and time unit string directly from the file and then calls cftime internally.)
Example 2: Converting from datetime to CF time
The reverse calculation will often be useful if you want to write new data to your own netCDF file and follow the recommended CF standards. First, we calculate the conversion:
tnew = datetime(2018,1:12,1)';
tcf = cftime(tnew, tunit, [], 'reverse')
tcf =
1034376
1035120
1035792
1036536
1037256
1038000
1038720
1039464
1040208
1040928
1041672
1042392
Next, write to a file (see ncbuild for details of this process):
ncbuild('testcffile.nc', tcf, ... 'name', 'time', ... 'dimname', {'time'}, ... 'varatts', {'units', tunit});
We can now check and see that these units are properly interpreted by standard netCDF utilities like the command-line ncdump function:
system('ncdump -v time -t testcffile.nc')
netcdf testcffile {
dimensions:
time = 12 ;
variables:
double time(time) ;
time:units = "hours since 1900-01-01 00:00:00.0" ;
data:
time = "2018-01-01", "2018-02-01", "2018-03-01", "2018-04-01", "2018-05-01",
"2018-06-01", "2018-07-01", "2018-08-01", "2018-09-01", "2018-10-01",
"2018-11-01", "2018-12-01" ;
}
ans =
0
Author Info
This function and supporting documentation was written by Kelly Kearney for the Climate Data Toolbox for Matlab.