nccreate

Create variable in netCDF file

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 Variables in NetCDF File

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

Specify Dimensions and File Format

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` — Filename
string scalar | character vector

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"

`varname` — Name of new variable
string scalar | character vector

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

collapse all

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` — Dimensions of variable
cell array

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

`Datatype` — MATLAB^® data type
`"double"` (default) | `"single"` | `"int32"` | ...

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 `Datatype`	NetCDF 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

`Format` — NetCDF file format
`"netcdf4_classic"` (default) | `"netcdf4"` | `"classic"` | `"64bit"`

NetCDF file format, specified as one of these values.

Value of `Format`	Description
`"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

`FillValue` — Replacement value for missing values
scalar | `"disable"`

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

`ChunkSize` — Chunk size along each dimension
numeric vector

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

`DeflateLevel` — Level of compression
`0` (default) | integer scalar value between `0` and `9`

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

`Shuffle` — Status of shuffle filter
`false` or `0` (default) | `true` or `1`

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

R2023b: Setting `DeflateLevel` to `0` disables the deflate filter

Setting the compression level to zero disables the deflate filter. Previously, the deflate filter could be enabled with a compression level of zero.

R2023b: Use compression and shuffle filter only with fixed-length data types

Compression and the shuffle filter can be used only with fixed-length data types and generate an error if applied to variables of type NC_STRING. Previously, if you specified compression or the shuffle filter for NC_STRING variables, the specification had no effect.

R2021b: Define `NC_STRING` data

You can define NC_STRING data in netCDF-4 files.

nccreate

Syntax

Description

Examples

Create Variables in NetCDF File

Specify Dimensions and File Format

Input Arguments

`filename` — Filename
string scalar | character vector

`varname` — Name of new variable
string scalar | character vector

Name-Value Arguments

`Dimensions` — Dimensions of variable
cell array

`Datatype` — MATLAB^® data type
`"double"` (default) | `"single"` | `"int32"` | ...

`Format` — NetCDF file format
`"netcdf4_classic"` (default) | `"netcdf4"` | `"classic"` | `"64bit"`

`FillValue` — Replacement value for missing values
scalar | `"disable"`

`ChunkSize` — Chunk size along each dimension
numeric vector

`DeflateLevel` — Level of compression
`0` (default) | integer scalar value between `0` and `9`

`Shuffle` — Status of shuffle filter
`false` or `0` (default) | `true` or `1`

Tips

Version History

R2023b: Setting `DeflateLevel` to `0` disables the deflate filter

R2023b: Use compression and shuffle filter only with fixed-length data types

R2021b: Define `NC_STRING` data

See Also

Topics

nccreate

Syntax

Description

Examples

Create Variables in NetCDF File

Specify Dimensions and File Format

Input Arguments

filename — Filename string scalar | character vector

varname — Name of new variable string scalar | character vector

Name-Value Arguments

Dimensions — Dimensions of variable cell array

Datatype — MATLAB® data type "double" (default) | "single" | "int32" | ...

Format — NetCDF file format "netcdf4_classic" (default) | "netcdf4" | "classic" | "64bit"

FillValue — Replacement value for missing values scalar | "disable"

ChunkSize — Chunk size along each dimension numeric vector

DeflateLevel — Level of compression 0 (default) | integer scalar value between 0 and 9

Shuffle — Status of shuffle filter false or 0 (default) | true or 1

Tips

Version History

R2023b: Setting DeflateLevel to 0 disables the deflate filter

R2023b: Use compression and shuffle filter only with fixed-length data types

R2021b: Define NC_STRING data

See Also

Topics

`filename` — Filename
string scalar | character vector

`varname` — Name of new variable
string scalar | character vector

`Dimensions` — Dimensions of variable
cell array

`Datatype` — MATLAB^® data type
`"double"` (default) | `"single"` | `"int32"` | ...

`Format` — NetCDF file format
`"netcdf4_classic"` (default) | `"netcdf4"` | `"classic"` | `"64bit"`

`FillValue` — Replacement value for missing values
scalar | `"disable"`

`ChunkSize` — Chunk size along each dimension
numeric vector

`DeflateLevel` — Level of compression
`0` (default) | integer scalar value between `0` and `9`

`Shuffle` — Status of shuffle filter
`false` or `0` (default) | `true` or `1`

R2023b: Setting `DeflateLevel` to `0` disables the deflate filter

R2021b: Define `NC_STRING` data