Main Content

nccreate

Create variable in netCDF file

collapse all in page

    Syntax

    nccreate(filename,varname)
    nccreate(filename,varname,Name,Value)

    Description

    nccreate(filename,varname) creates a scalar double variable named varname in the netCDF file specified by filename. For files of format netcdf4, you can specify group hierarchy in varname. If filename does not exist, then nccreate creates the file using the netCDF-4 classic model.

    example

    nccreate(filename,varname,Name,Value) creates a variable with additional options specified by one or more name-value arguments. For example, to create a nonscalar variable, use the Dimensions name-value argument.

    example

    Examples

    collapse all

    Create a netCDF file named myexample.nc that contains a variable named Var1.

    nccreate("myexample.nc","Var1")

    Create a second variable in the same file.

    nccreate("myexample.nc","Var2")

    Display the contents of the netCDF file.

    ncdisp("myexample.nc")
    Source:
           pwd\myexample.nc
Format:
           netcdf4_classic
Variables:
    Var1
           Size:       1x1
           Dimensions: 
           Datatype:   double
    Var2
           Size:       1x1
           Dimensions: 
           Datatype:   double

    Create a two-dimensional variable named peaks in a netCDF-3 classic format file named myncclassic.nc. Specify the name and length of each dimension by using the Dimensions name-value argument. Specify the file format by using the Format name-value argument.

    nccreate("myncclassic.nc","peaks", ...
         "Dimensions",{"r",300,"c",400},"Format","classic")

    Write data to the variable.

    ncwrite("myncclassic.nc","peaks",peaks(100))

    Display the contents of the netCDF file.

    ncdisp("myncclassic.nc")
    Source:
           pwd\myncclassic.nc
Format:
           classic
Dimensions:
           r = 300
           c = 400
Variables:
    peaks
           Size:       300x400
           Dimensions: r,c
           Datatype:   double

    Input Arguments

    collapse all

    Filename, specified as a string scalar or character vector. Specify the name of an existing netCDF file or the name you want to assign to a new netCDF file.

    Example: "myFile.nc"

    Name of the new variable, specified as a string scalar or character vector.

    If filename specifies a file with format netcdf4, you can specify the location of the new variable within the group hierarchy by specifying varname as a fully qualified name. In this case, nccreate creates new groups as needed to place the new variable at the specified location in the hierarchy.

    Example: "myVar"

    Example: "/myGrp/mySubGrp/myNestedVar"

    Name-Value Arguments

    Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

    Example: nccreate("myFile.nc","Var1",Datatype="double",Format="classic") creates a variable named Var1 of type NC_DOUBLE in a netCDF-3 classic file named myFile.nc.

    Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

    Example: nccreate("myFile.nc","Var1","Datatype","double","Format","classic")

    Dimensions of the new variable, specified as a cell array. The cell array lists the dimension name as a string scalar or character vector followed by its numerical length, in this form: {dname1,dlength1,dname2,dlength2,...,dnameN,dlengthN}. The dname1 entry is the name of the first dimension, and dlength1 is the length of the first dimension, specified as a nonnegative integer or Inf. Then dname2 is the name of the second dimension, dlength2 the length of the second dimension, and so on. A variable with a single dimension is treated as a column vector.

    For dimensions that already exist, specifying the length is optional. If you do specify the length of an existing dimension, it must match the current length.

    Use a dimension length of Inf or 0 to specify an unlimited dimension. A file with format netcdf4 can have any number of unlimited dimensions in any order; all other formats can have only one unlimited dimension per file, and it must be specified last in the cell array.

    nccreate creates the dimension at the same location as the variable. For files with format netcdf4, you can specify a different location for the dimension using a fully qualified dimension name.

    Example: "Dimensions",{"dim1",100,"/mygroup/dim2",150,"dim3",Inf}

    Data Types: cell

    MATLAB data type, specified as one of the values in this table. When nccreate creates the variable in the netCDF file, it uses the corresponding netCDF data type.

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

    (*) These values of Datatype are available only for files with format netcdf4.

    Example: "Datatype","int16"

    Data Types: string | char

    NetCDF file format, specified as one of these values.

    Value of FormatDescription
    "classic"netCDF-3
    "64bit"netCDF-3, with 64-bit offsets
    "netcdf4_classic"netCDF-4 classic model
    "netcdf4"netCDF-4 (Use this format to enable group hierarchy)

    If varname specifies a group (for example, "/grid3/temperature"), then nccreate sets the value of Format to "netcdf4".

    Example: "Format","64bit"

    Data Types: string | char

    Replacement value for missing values, specified as a scalar or "disable". The default value is supplied by the netCDF library. To disable replacement values, specify a value of "disable". You cannot disable FillValue when writing string data to files with format netcdf4.

    Note

    The nccreate function assigns the value of FillValue to the _FillValue attribute of the new netCDF variable varname. You cannot change the value of this attribute after you have created the variable.

    This argument is available only for files with format netcdf4 or netcdf4_classic.

    Example: "FillValue",0

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

    Chunk size along each dimension, specified as a numeric vector. The first element specifies the number of rows, the second element specifies the number of columns, the third element specifies the length of the third dimension, and so on. The default value is supplied by the netCDF library.

    This argument is available only for files with format netcdf4 or netcdf4_classic.

    Example: "ChunkSize",[5 6 9]

    Data Types: double

    Level of compression, specified as an integer scalar value between 0 and 9. A value of 0 indicates no compression. A value of 1 indicates the least compression, and a value of 9 indicates the most. You cannot set DeflateLevel if Datatype is "string".

    This argument is available only for files with format netcdf4 or netcdf4_classic.

    Example: "DeflateLevel",5

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

    Status of the shuffle filter, specified as a numeric or logical 0 (false) or 1 (true). A value of false disables the shuffle filter, and true enables it. The shuffle filter assists with the compression of integer data by changing the byte order in the data stream. You cannot enable the shuffle filter if Datatype is "string".

    This argument is available only for files with format netcdf4 or netcdf4_classic.

    Example: "Shuffle",true

    Data Types: logical

    Tips

    • MATLAB interprets data as column major, but the netCDF C API interprets data as row major. Multidimensional data in the netCDF C API shows dimensions in the reverse of the order shown by MATLAB and consequently appears transposed.

    Version History

    Introduced in R2011a

    expand all

    See Also

    | | |

    Topics