netcdf.putAtt

Write data to netCDF attribute

Syntax

netcdf.putAtt(ncid,varid,attname,attvalue)

netcdf.putAtt(ncid,varid,attname,attvalue,xtype)

Description

netcdf.putAtt(ncid,varid,attname,attvalue) writes the attribute named attname with value attvalue to the netCDF variable identified by varid in the netCDF file or group specified by ncid. The written attribute value is of the netCDF data type that best matches the MATLAB^® data type of attvalue. For more information about how MATLAB determines the best match, see MATLAB to NetCDF Data Type Conversion.

netcdf.putAtt(ncid,varid,attname,attvalue,xtype) writes attvalue as the data type specified by xtype.

Examples

Write Attribute to Variable

Make a copy of the example netCDF file and open the copy for writing. Write an attribute to the avogadros_number variable.

copyfile("example.nc","myfile.nc")
ncid = netcdf.open("myfile.nc","NC_WRITE");
varid = netcdf.inqVarID(ncid,"avogadros_number");

attname = "significant_figures";
attvalue = 9;
netcdf.putAtt(ncid,varid,attname,attvalue)

Check that the value was written as expected, using the netcdf.getAtt function.

netcdf.getAtt(ncid,varid,attname)

ans = 
9

Close the netCDF file.

netcdf.close(ncid)

Write Global Attribute

Create and open a netCDF file.

ncid = netcdf.create("myfile.nc","NOCLOBBER");

Write a global attribute. Use netcdf.getConstant("NC_GLOBAL") for varid.

varid = netcdf.getConstant("NC_GLOBAL");

attname = "creation_time";
attvalue = string(datetime("now"));
netcdf.putAtt(ncid,varid,attname,attvalue)

Check that the value was written as expected, using the netcdf.getAtt function.

netcdf.getAtt(ncid,varid,attname)

ans = 
'05-Sep-2024 15:14:38'

Close the netCDF file.

netcdf.close(ncid)

Write MATLAB String Array

Create and open a netCDF-4 file.

ncid = netcdf.create("myfile.nc","NETCDF4");

Write a global attribute using MATLAB string array. Use netcdf.getConstant("NC_GLOBAL") for varid.

varid = netcdf.getConstant("NC_GLOBAL");

attname = "temperature_units";
attvalue = ["°F" "°C"];
netcdf.putAtt(ncid,varid,attname,attvalue)

Check that the value was written as expected, using the netcdf.getAtt function.

netcdf.getAtt(ncid,varid,attname)

ans = 1x2 string
    "°F"    "°C"

Close the netCDF file.

netcdf.close(ncid)

Specify NetCDF String Data

Make a copy of the example netCDF file and open the copy for writing. Write an attribute to the temperature variable. Specify xtype as "NC_STRING".

copyfile("example.nc","myfile.nc")
ncid = netcdf.open("myfile.nc","NC_WRITE");
varid = netcdf.inqVarID(ncid,"temperature");

attname = "Month";
attvalue = "March";
xtype = "NC_STRING";
netcdf.putAtt(ncid,varid,attname,attvalue,xtype)

Check that the value was written as expected, using the netcdf.getAtt function.

netcdf.getAtt(ncid,varid,attname)

ans = 
"March"

Close the netCDF file.

netcdf.close(ncid)

Input Arguments

ncid — Identifier of netCDF source

nonnegative integer scalar

Identifier of a netCDF source, specified as a nonnegative integer scalar. The netCDF source can be a netCDF file or a netCDF group.

Data Types: double | single | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

varid — Identifier of netCDF variable

nonnegative integer scalar

Identifier of a netCDF variable, specified as a nonnegative integer scalar.

To write a global attribute, specify varid as netcdf.getConstant("NC_GLOBAL").

Data Types: double | single | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

attname — Attribute name to write

string scalar | character vector

Attribute name to write, specified as a string scalar or character vector.

Example: "myAtt"

attvalue — Attribute value

numeric array | text | cell array

Attribute value, specified as a numeric array, text, or a cell array.

Note

If attvalue has more than one dimension, then the netcdf.putAtt function flattens attvalue in column-major order before writing the attribute value. For example, specifying attvalue as [1 2 3; 4 5 6] and specifying attvalue as [1 4 2 5 3 6] have the same effect.

Additionally, for attributes of type NC_VLEN, if attvalue contains any entries that have more than one dimension, then the netcdf.putAtt function flattens those entries in column-major order before writing the values. For example, for an attribute of type NC_VLEN, specifying attvalue as

{[0.5 0.3]; [0 -0.7 5.2; 4.6 2.5 1.8]}

and specifying attvalue as

{[0.5; 0.3] [0; 4.6; -0.7; 2.5; 5.2; 1.8]}

have the same effect.

Data Types: double | single | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | char | string | cell

xtype — NetCDF data type

string scalar | character vector | nonnegative integer scalar

NetCDF data type, specified as a string scalar, character vector, or nonnegative integer scalar.

• You can specify xtype as one of these string scalars or character vectors.

  Value of xtype	MATLAB Class
  "NC_DOUBLE"	double
  "NC_FLOAT"	single
  "NC_INT"	int32
  "NC_SHORT"	int16
  "NC_BYTE"	int8
  "NC_CHAR"	char
  "NC_INT64" (*)	int64
  "NC_UINT64" (*)	uint64
  "NC_UINT" (*)	uint32
  "NC_USHORT" (*)	uint16
  "NC_UBYTE" (*)	uint8
  "NC_STRING" (*)	string

  (*) These values of xtype are valid only for sources with format netcdf4.

• You can specify xtype as a numeric value returned by the netcdf.getConstant function.

• For attributes of the user-defined NC_VLEN types that correspond to MATLAB cell arrays, you can specify xtype as a numeric value returned by the netcdf.defVlen function.

Data Types: double | single | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | char | string

More About

MATLAB to NetCDF Data Type Conversion

The netCDF-related MATLAB functions automatically choose the netCDF data type that best matches the MATLAB data type according to this table.

MATLAB Data Type	NetCDF Data Type
double	NC_DOUBLE
single	NC_FLOAT
int32	NC_INT
int16	NC_SHORT
int8	NC_BYTE
char	NC_CHAR
string scalar	NC_CHAR
int64 (*)	NC_INT64
uint64 (*)	NC_UINT64
uint32 (*)	NC_UINT
uint16 (*)	NC_USHORT
uint8 (*)	NC_UBYTE
string vector (*)	NC_STRING

(*) These MATLAB data types are available only for sources with format netcdf4.

Tips

• You cannot use netcdf.putAtt to set the _FillValue attribute of variables in netCDF-4 files. Use the netcdf.defVarFill function to set the fill value for a variable.

• This function corresponds to several (nc_put_att_*) functions in the netCDF library C API.

  To use this function, you must be familiar with the netCDF C interface. You can access the netCDF documentation at the netCDF website.

Version History

Introduced in R2008b

R2022a: Write variable length array data types (NC_VLEN)

You can write variable length array data types (NC_VLEN) to netCDF-4 files.

R2021b: Write NC_STRING data

You can write NC_STRING data to netCDF-4 files.