ncread

读取 netCDF 数据源中的变量数据

语法

vardata = ncread(source,varname)

vardata = ncread(source,varname,start,count)

vardata = ncread(source,varname,start,count,stride)

说明

vardata = ncread(source,varname) 读取 source 所含 netCDF 变量 varname 中的所有数据。返回的变量值 varname 属于与 netCDF 数据类型 vardata 最匹配的 MATLAB^® 数据类型。

vardata = ncread(source,varname,start,count) 从由 start 指定的位置开始读取数据。count 参量指定沿每个维度读取的元素数。

vardata = ncread(source,varname,start,count,stride) 以变量的每个维度的索引之间的 stride 指定的间隔返回数据。

示例

读取 NetCDF 变量

从 netCDF 文件 example.nc 中读取名为 peaks 的变量并对该变量绘图。

peaksData = ncread("example.nc","peaks");
whos peaksData

  Name            Size            Bytes  Class    Attributes

  peaksData      50x50             5000  int16              

绘制 peaksData 并添加标题。

surf(peaksData)
title("Peaks Data")

从变量中读取部分数据

仅读取并绘制 peaks 变量数据的一部分，即从位置 [25 17] 开始直到每个维度的末尾。

start = [25 17];   % Start location along each coordinate
count = [Inf Inf]; % Read until the end of each dimension
peaksData = ncread("example.nc","peaks",start,count);
whos peaksData

  Name            Size            Bytes  Class    Attributes

  peaksData      26x34             1768  int16              

绘制数据图。

surf(peaksData)
title("Peaks Data Starting at [25 17]")

以指定的变量索引间距读取数据

读取并绘制数据，读数据时在每个维度上均按指定的变量索引间距进行采样。从 start 中位置开始，以 stride 中指定的间隔读取变量数据。stride 中的值为 1 表示在对应维度连续访问相邻值，值为 2 表示在对应维度中每隔一个值访问一个值，依此类推。

start  = [1 1]; 
count  = [10 15]; 
stride = [2 3]; 
sampledPeaksData = ncread("example.nc","peaks",start,count,stride);
whos sampledPeaksData

  Name                   Size            Bytes  Class    Attributes

  sampledPeaksData      10x15              300  int16              

绘制数据图。

surf(sampledPeaksData)
title("Peaks Data Subsampled by [2 3]")

输入参数

source — netCDF 数据源的名称

字符串标量 | 字符向量

netCDF 数据源的名称，指定为字符串标量或字符向量。source 参量可以是以下值之一：

• 本地 netCDF 源的路径

• 远程 OPeNDAP netCDF 数据源的 OPeNDAP URL

• 远程 netCDF 源的 HTTP URL，在 URL 的末尾附加 #mode=bytes 以支持字节范围读取

  注意

  字节范围读取比从其他来源读取要慢。有关字节范围读取的更多详细信息，请参阅 netCDF 文档。

示例: "myNetCDFfile.nc"

示例: "http://host_name/netcdf_filename#mode=bytes"

varname — 变量名称

字符串标量 | 字符向量

变量名称，指定为包含 netCDF 数据源中变量名称的字符串标量或字符向量。

如果 source 指定格式为 netcdf4 的文件，您可以通过将 varname 指定为完全限定名称来指定变量在组层次结构中的位置。

示例: "myVar"

示例: "/myGrp/mySubGrp/myNestedVar"

start — 变量中数据的起始位置

由 1 组成的向量 (默认) | 数值向量

变量中数据的起始位置，指定为正整数组成的数值向量。对于 N 维变量，将 start 指定为长度为 N 的向量，其中包含从 1 开始的索引。

如果未指定 start，则 ncread 函数将沿每个维度从第一个索引开始读取变量。

示例: [2 1 3]

数据类型: double

count — 元素数量

由 Inf 组成的向量 (默认) | 数值向量

要读取的元素数，指定为由正整数或 Inf 值组成的数值向量。对于 N 维变量，将 count 指定为长度为 N 的向量，包含要沿每个维度读取的元素数。如果 count 的任一元素是 Inf，则 ncread 将一直读取，直到对应维度的末尾。

如果未指定 count，则 ncread 函数将读取变量数据，直到每个维度的末尾。

示例: [Inf 10 50]

数据类型: double

stride — 变量索引之间的间距

由 1 组成的向量 (默认) | 数值向量

沿每个维度读取变量数据时的变量索引间距，指定为由整数组成的数值向量。对于一个 N 维变量，将 stride 指定为长度为 N 的向量。stride 向量的元素按顺序对应于变量的维度。值为 1 表示在对应维度中连续访问 netCDF 变量的相邻值，值为 2 表示在对应维度中每隔一个值访问一个值，依此类推。

如果未指定 stride，则 ncread 函数将沿每个维度以默认间距 1 读取数据。

示例: [2 10 1]

数据类型: double

输出参量

vardata — 变量数据

数值数组 | 文本 | 元胞数组

变量数据，以与 varname 的 netCDF 数据类型最匹配的 MATLAB 数据类型的数值数组、文本或元胞数组形式返回。有关 MATLAB 如何确定最佳匹配的详细信息，请参阅NetCDF 到 MATLAB 数据类型的转换。

对于数值变量，当属性 _FillValue、scale_factor 或 add_offset 中有至少一个存在时，vardata 的类型为 double。此外，ncread 在返回 vardata 之前按顺序应用以下属性约定：

1. 如果 _FillValue 属性存在：

   • 如果 vardata 的类型是 double 或 single，则 ncread 用 NaN 值替换与 _FillValue 属性的值相等的 vardata 值。

   • 如果 vardata 属于任何其他数值类型，则 ncread 用 0 值替换 NaN vardata 值以及与 _FillValue 属性的值相等的 vardata 值。

2. 如果 scale_factor 属性存在，则 ncread 将 vardata 中的值乘以 scale_factor 属性的值。

3. 如果 add_offset 属性存在，则 ncread 会将 vardata 中的值加上 add_offset 属性的值。

注意

如果 varname 的类型是 NC_STRING，则它可以包含 UTF-8 编码的字符；如果 varname 的类型是 NC_CHAR，则它只能包含 ASCII 编码的字符。

数据类型: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | cell | char | string

详细信息

NetCDF 到 MATLAB 数据类型的转换

netCDF 相关的 MATLAB 函数根据此表自动选择与 netCDF 数据类型最匹配的 MATLAB 数据类型。

NetCDF 数据类型	MATLAB 数据类型
NC_DOUBLE	double
NC_FLOAT	single
NC_INT	int32
NC_SHORT	int16
NC_BYTE	int8
NC_CHAR	char
NC_STRING (*)	string
NC_INT64 (*)	int64
NC_UINT64 (*)	uint64
NC_UINT (*)	uint32
NC_USHORT (*)	uint16
NC_UBYTE (*)	uint8
用户定义的 NC_VLEN 类型 (*)	cell

(*) 这些 netCDF 数据类型仅适用于格式为 netcdf4 的文件。

提示

• MATLAB 将多维数据解释为列优先数据，但 netCDF C API 将多维数据解释为行优先数据。netCDF C API 中的多维数据以与 MATLAB 所示顺序相反的顺序显示维度，因此显示为转置。

版本历史记录

在 R2011a 中推出

R2022a: 远程数据集的字节范围读取

只要远程服务器支持字节范围访问，您就可以使用 ncread 通过 HTTP 字节范围功能对远程数据集进行只读访问。

R2022a: 读取可变长度数组数据类型 (NC_VLEN)

您可以从 netCDF-4 文件中读取可变长度的数组数据类型 (NC_VLEN)。

R2021b: 读取 NC_STRING 数据

您可以从 netCDF-4 文件中读取 NC_STRING 数据。

另请参阅

ncdisp | ncinfo | ncreadatt | ncwrite

主题

• 导入 NetCDF 文件和 OPeNDAP 数据