ncaddhis documentation

This function prepends a dated string to a netCDF file's history attribute.

NetCDF best practices recommend that all netCDF files contain a history attribute that is updated whenever the file contents are modified. Some netCDF software packages perform this task automatically, but Matlab's netCDF-writing and modifying utilities do not. This function simplifies the task of adding a new history attribute if one does not yet exist in a file, or preprending a new line to it (rather than overwriting existing content) if the attribute already exists.

Back to Climate Data Tools Contents

Contents

Syntax

ncaddhis(file, hisstr)

Description

ncaddhis(file, hisstr) prepends the character array or scalar string hisstr to the global history attribute within the existing netCDF file file. The string will be preceded by the date and time at which this function is called.

Example

For this example, we'll start with the ERA_Interim_2017.nc sample dataset that comes with CDT. Like many climate datasets, this file already includes a history attribute that gives us some information about where the data came from:

ncreadatt('ERA_Interim_2017.nc', '/', 'history')
ans =

    '2018-12-06 18:53:30 GMT by grib_to_netcdf-2.9.2: grib_to_netcdf /data/data01/scratch/78/bb/_mars-atls17-98f536083ae965b31b0d04811be6f4c6-L3jQQq.grib -o /data/data03/scratch/77/57/_grib2netcdf-atls19-98f536083ae965b31b0d04811be6f4c6-5zbphu.nc -utime'

In this case, we can see that the file was created using the grib_to_netcdf-2.9.2 software, and was retrieved in December 2018.

Some tools, such as the netCDF operator utilities (NCO), automatically add to the history attribute whenever they are used. For example, let's extract a single grid cell (at 0N,0E) of data from the ERA file (you will need NCO installed on your system to run this command; if not, don't worry about it, because this is just for demonstration purposes).

system('ncks -d latitude,0.0 -d longitude,0.0 ../cdt_data/ERA_Interim_2017.nc ERA_Interim_2017_00.nc');

The newly-created file includes an updated line in the history attribute that reflects the command we just use used to extract it:

ncreadatt('ERA_Interim_2017_00.nc', '/', 'history')
ans =

    'Tue Sep  7 10:35:12 2021: ncks -d latitude,0.0 -d longitude,0.0 ../cdt_data/ERA_Interim_2017.nc ERA_Interim_2017_00.nc
     2018-12-06 18:53:30 GMT by grib_to_netcdf-2.9.2: grib_to_netcdf /data/data01/scratch/78/bb/_mars-atls17-98f536083ae965b31b0d04811be6f4c6-L3jQQq.grib -o /data/data03/scratch/77/57/_grib2netcdf-atls19-98f536083ae965b31b0d04811be6f4c6-5zbphu.nc -utime'

However, if we make changes using Matlab's utilities, those are not automatically documented.

oldtemp = ncread('ERA_Interim_2017_00.nc', 't2m');
newtemp = oldtemp + 1;
ncwrite('ERA_Interim_2017_00.nc', 't2m', newtemp);

We can use ncaddhis to quickly document this change.

ncaddhis('ERA_Interim_2017_00.nc', 'Added 1 degK to all t2m values (ncaddhis_documentation.m script)');
ncreadatt('ERA_Interim_2017_00.nc', '/', 'history')
ans =

    'Tue Sep 07 10:35:13 2021: Added 1 degK to all t2m values (ncaddhis_documentation.m script)
     Tue Sep  7 10:35:12 2021: ncks -d latitude,0.0 -d longitude,0.0 ../cdt_data/ERA_Interim_2017.nc ERA_Interim_2017_00.nc
     2018-12-06 18:53:30 GMT by grib_to_netcdf-2.9.2: grib_to_netcdf /data/data01/scratch/78/bb/_mars-atls17-98f536083ae965b31b0d04811be6f4c6-L3jQQq.grib -o /data/data03/scratch/77/57/_grib2netcdf-atls19-98f536083ae965b31b0d04811be6f4c6-5zbphu.nc -utime'

There are no strict rules about what information to include in a history statement. The Climate and Forecast (CF) standards suggest that "Well-behaved generic netCDF filters will automatically append their name and the parameters with which they were invoked to the global history attribute of an input netCDF file"; given that Matlab-based manipulations may be a little more involved than a simple filter, I like to add a quick description and point end users to the script where my calculations were performed.

Author Info

This function and supporting documentation were written by Kelly Kearney for the Climate Data Toolbox for Matlab.