Main Content

spreadsheetDatastore

用于电子表格文件的数据存储

说明

对于不一定能放入内存的大型电子表格文件集合,可以使用 spreadsheetDatastore 对象来进行管理。您可以使用 spreadsheetDatastore 函数创建 spreadsheetDatastore 对象,指定其属性,然后使用对象函数导入数据。

创建对象

描述

示例

ssds = spreadsheetDatastore(location) 根据 location 指定的数据集合创建一个电子表格数据存储。

ssds = spreadsheetDatastore(location,Name,Value) 使用一个或多个名称-值参数为 ssds 指定其他参数和属性。例如,spreadsheetDatastore(location,"FileExtensions",[".xlsx",".xls"]) 指定根据文件扩展名要在数据存储中包含哪些文件。

输入参数

全部展开

数据存储中包含的文件或文件夹,指定为 FileSet 对象、文件路径或 DsFileSet 对象。

  • FileSet 对象 - 您可以将 location 指定为 FileSet 对象。与指定路径或 DsFileSet 对象相比,将位置指定为 FileSet 对象会加快数据存储的构造时间。有关详细信息,请参阅 matlab.io.datastore.FileSet

  • 文件路径 - 您可以将单个文件路径指定为字符向量或字符串标量。您可以将多个文件路径指定为字符向量元胞数组或字符串数组。

  • DsFileSet 对象 - 您可以指定 DsFileSet 对象。有关详细信息,请参阅 matlab.io.datastore.DsFileSet

文件或文件夹可以是本地的或远程的:

  • 本地文件或文件夹 - 指定文件或文件夹的本地路径。如果文件不在当前文件夹中,则指定完整路径或相对路径。指定文件夹的子文件夹中的文件不会自动包括在数据存储中。在指定本地路径时可以使用通配符 (*)。此字符指定数据存储包含所有匹配的文件或匹配文件夹中的所有文件。

  • 远程文件或文件夹 - 将远程文件或文件夹的完整路径指定为 hdfs:///path_to_file 形式的统一资源定位器 (URL)。有关详细信息,请参阅处理远程数据

当您指定文件夹时,数据存储仅包括具有支持的文件格式的文件,而忽略任何其他格式的文件。要指定要包含在数据存储中的自定义文件扩展名列表,请参阅 FileExtensions 属性。

spreadsheetDatastore 函数支持扩展名为 .xls.xlsx.xlsm.xltx.xltm 的文件。

示例: "file1.xlsx"

示例: "../dir/data/file1.xlsx"

示例: ["C:\dir\data\file1.xlsx","C:\dir\data\file2.xlsx"]

示例: "s3://bucketname/path_to_files/*.xls"

名称-值参数

将可选的参数对组指定为 Name1=Value1,...,NameN=ValueN,其中 Name 是参数名称,Value 是对应的值。名称-值参数必须出现在其他参数之后,但参数对组的顺序无关紧要。

在 R2021a 之前,使用逗号分隔每个名称和值,并用引号将 Name 引起来。

示例: ssds = spreadsheetDatastore("C:\dir\spreadsheetdata","FileExtensions",[".xls",".xlsm"])

电子表格文件扩展名,指定为名称-值参数,其中包含 "FileExtensions" 和一个字符向量、字符向量元胞数组、字符串标量或字符串数组。

  • 如果不指定 "FileExtensions",则 spreadsheetDatastore 会自动包含指定路径中具有 .xls.xlsx.xlsm.xltx.xltm 扩展名的所有文件。

  • 如果要在 SpreadsheetDatastore 中包含具有非标准文件扩展名的电子表格,请显式指定这些扩展名。

  • 如果要为没有任何扩展名的文件创建 SpreadsheetDatastore,请将 "FileExtensions" 指定为空字符向量 ''

示例: "FileExtensions",''

示例: "FileExtensions",".xls"

示例: "FileExtensions",[".xlsx",".xlsm"]

数据类型: char | cell | string

子文件夹包含标记,指定为名称-值参数,其中包含 "IncludeSubfolders" 以及 truefalse、0 或 1。指定 true 可包含每个文件夹中的所有文件和子文件夹,指定 false 则仅包含每个文件夹中的文件。

如果不指定 "IncludeSubfolders",则默认值为 false

示例: "IncludeSubfolders",true

数据类型: logical | double

输出数据类型,指定为名称-值参数,由 "OutputType" 和以下值之一组成:

  • "auto" - 根据您是否指定 "RowTimes" 名称-值参数,检测数据存储的输出是表还是时间表。如果您指定 "RowTimes",则输出是时间表;否则,输出是表。

  • "table" - 返回 table

  • "timetable" - 返回 timetable

OutputType 的值决定 previewreadreadall 函数返回的数据类型。将此选项与 "RowTimes" 名称-值对组结合使用,可从 spreadsheetDatastore 返回时间表。

示例: "OutputType","timetable"

数据类型: char | string

备用文件系统根路径,以名称-值参数形式指定,其中包含 "AlternateFileSystemRoots" 和一个字符串向量或元胞数组。当您在本地计算机上创建数据存储,但需要访问和处理另一台计算机(可能是不同操作系统)上的数据时,请使用 "AlternateFileSystemRoots"。此外,如果您使用 Parallel Computing Toolbox™ 和 MATLAB® Parallel Server™ 处理数据,而数据存储在本地计算机上并且在不同平台云或集群计算机上存储数据副本,则必须使用 "AlternateFileSystemRoots" 关联根路径。

  • 要关联一组等效的根路径,请将 "AlternateFileSystemRoots" 指定为字符串向量。例如,

    ["Z:\datasets","/mynetwork/datasets"]

  • 要将在数据存储方面等效的多组根路径关联起来,请将 "AlternateFileSystemRoots" 指定为包含多个行的元胞数组,其中每一行代表一组等效的根路径。将元胞数组中的每一行指定为一个字符串向量或字符向量元胞数组。例如:

    • "AlternateFileSystemRoots" 指定为字符串向量元胞数组。

      {["Z:\datasets", "/mynetwork/datasets"];...
       ["Y:\datasets", "/mynetwork2/datasets","S:\datasets"]}

    • 也可以将 "AlternateFileSystemRoots" 指定为字符向量元胞数组。

      {{'Z:\datasets','/mynetwork/datasets'};...
       {'Y:\datasets', '/mynetwork2/datasets','S:\datasets'}}

"AlternateFileSystemRoots" 的值必须满足以下条件:

  • 包含一行或多行,每一行指定一组等效的根路径。

  • 每一行指定多个根路径,每个根路径必须至少包含两个字符。

  • 根路径是唯一的,并且不是彼此的子文件夹。

  • 包含至少一个指向文件位置的根路径条目。

有关详细信息,请参阅Set Up Datastore for Processing on Different Machines or Clusters

示例: ["Z:\datasets","/mynetwork/datasets"]

数据类型: string | cell

文本变量的输出数据类型,指定为名称-值参数,其中包含 "TextType""char""string" 之一。

  • 如果 readreadallpreview 函数的输出表包含文本变量,则 "TextType" 指定这些变量的数据类型。

  • 如果 "TextType""char",则输出为字符向量元胞数组。

  • 如果 "TextType""string",则输出的类型为 string

数据类型: char | string

除了这些名称-值对组外,还可以指定本页上除 Files 属性之外的任何属性作为名称-值对组。

属性

全部展开

SpreadsheetDatastore 属性描述数据存储对象中文件的格式,并控制如何从数据存储中读取数据。除了 Files 属性之外,您可以在创建数据存储对象时使用名称-值对组参数指定 SpreadsheetDatastore 属性的值。要在创建对象后查看或修改属性,请使用圆点表示法:

ds = spreadsheetDatastore("airlinesmall_subset.xlsx");
ds.Sheets = [1 2];
ds.Range = "A1:C6";

文件属性

包含在数据存储中的文件,解析为字符向量元胞数组或字符串数组,其中每个字符向量或字符串表示文件的一个完整路径。spreadsheetDatastoredatastore 函数中的 location 参数定义这些文件。

在元胞数组中指定的第一个文件确定数据存储中的所有文件的变量名称和格式信息。

示例: ["C:\dir\data\file1.xls";"C:\dir\data\file2.xls"]

数据类型: cell | string

在读取时在每个工作表开头跳过的行数,指定为正整数。如果您还指定了 Range 属性,则 NumHeaderLines 是在指定的数据区域开头跳过的行数。

数据类型: double

文件中的工作表,指定为包含工作表名称的字符向量、字符向量元胞数组、字符串标量或字符串数组,或者指定为工作表索引的数值向量。空字符向量 '' 表示包含文件中的所有工作表。

示例: ["sheet1","sheet7"]

示例: [3 5 7]

数据类型: char | cell | string | double

行和列的边界,指定为字符向量或字符串标量,用于在工作表中定义一个矩形数据区域。空字符向量 '' 表示边界就是文件的开头和数据的末尾。

示例: "B1:T7"

示例: "A:C"

数据类型: char | string

将数据存储中的第一个文件的第一行读作变量名称的指示符,指定为 true (1) 或 false (0)。

  • 如果为 true,则第一个文件的第一个非标头行确定了数据的变量名称。

  • 如果为 false,则第一个文件的第一个非标头行包含第一行数据。默认的变量名称指定为 Var1Var2 等。

数据类型: logical | double

保留变量名称的标志,指定为 "modify""preserve"

  • "modify" - 将无效变量名称(由 isvarname 函数确定)转换为有效的 MATLAB 标识符。

  • "preserve" - 保留作为无效 MATLAB 标识符的变量名称,如包含空白和非 ASCII 字符的变量名称。

从 R2019b 开始,变量名称和行名称可以包含任何字符,包括空格和非 ASCII 字符。此外,它们可以由任何字符(而不仅仅是字母)开头。变量名称和行名称可以不是有效的 MATLAB 标识符(由 isvarname 函数决定)。要保留这些变量名称和行名称,请将 VariableNamingRule 的值设置为 "preserve"。当 VariableNamingRule 的值从 "modify" 更改为 "preserve" 时,变量名称不会刷新。

数据类型: char | string

数据存储中变量的名称,指定为字符向量、字符向量元胞数组、字符串标量或字符串数组。按变量显示在文件中的顺序指定变量名称。如果不指定变量名称,数据存储会从第一个文件的第一个非标头行中检测它们。您可以用字符向量或字符串标量指定 VariableNames,但是,数据存储会转换属性值并将其存储为字符向量元胞数组。修改 VariableNames 属性时,新变量名称的数量必须与原始变量名称的数量匹配。

要支持无效的 MATLAB 标识符作为变量名称,例如包含空白和非 ASCII 字符的变量名称,请将 VariableNamingRule 参数的值设置为 "preserve"

如果 ReadVariableNamesfalse,则 VariableNames 默认为 ["Var1","Var2", ...]

示例: ["Time","Date","Quantity"]

数据类型: char | cell | string

变量类型,指定为 "double""char""string""categorical""datetime",表示读取数据时每个变量的类型。

以下变量类型列表对应于 VariableNames 中的变量。类型 doublechardatetime 可以自动从数据中检测。您可以将 VariableTypes 指定为字符向量或字符串标量,但 spreadsheetDatastore 会自动将它转换为字符向量元胞数组或字符串数组。

示例: ["char","categorical"]

数据类型: char | cell | string

previewreadreadall 表的属性

要从文件中读取的变量,指定为字符向量、字符向量元胞数组、字符串标量或字符串数组。每个字符向量或字符串包含一个变量的名称。可按任何顺序指定变量名称。您可以使用字符向量或字符串标量指定 SelectedVariableNames,但 spreadsheetDatastore 会自动将它转换为字符向量元胞数组或字符串数组。

要支持无效的 MATLAB 标识符作为变量名称,例如包含空白和非 ASCII 字符的变量名称,请将 VariableNamingRule 参数的值设置为 "preserve"

示例: ["Var3","Var7","Var4"]

数据类型: char | cell | string

选定变量的类型,指定为 "double""char""string""categorical""datetime",表示读取数据时每个选定变量的类型。以下变量类型列表对应于 SelectedVariableNames 中的变量。类型 doublechardatetime 可以自动从数据中检测。您可以将 SelectedVariableTypes 指定为字符向量或字符串标量,但它会自动转换为字符向量元胞数组或字符串数组。

示例: ["double","datetime"]

数据类型: char | cell | string

要读取到 read 函数调用中的数据量,指定为 "file""sheet",或指定为正整数标量。

  • 如果 ReadSize"file",则每次调用 read 都会按照一次读取一个文件的方式读取所有数据。

  • 如果 ReadSize"sheet",则每次调用 read 都会按照一次读取一个工作表的方式读取所有数据。

  • 如果 ReadSize 是正整数,则每次调用 read 都会读取 ReadSize 指定的行数(如果已到数据末尾,则可能小于此值)。

如果您将 ReadSize 从整数标量更改为 "file""sheet",或者进行相反的更改,数据存储将使用 reset 函数重置。

数据类型: char | string | double

行时间变量的名称,以名称-值参数形式指定,其中包含 "RowTimes" 和变量名称(如 "Date")或变量索引(如 3)。

RowTimes 是与时间表相关的参数。时间表的每行都与一个时间相关联,该时间是在时间表的时间向量中捕获的。RowTimes 中指定的变量必须包含 datetimeduration 向量。

如果 "OutputType" 的值是 "timetable",但您没有指定 "RowTimes",则 spreadsheetDatastore 使用第一个 datetimeduration 变量作为时间表的行时间。

writeall 使用的属性

此 属性 为只读。

用于构造数据存储的文件夹,以字符向量元胞数组形式返回。该元胞数组定向为一个列向量。每个字符向量均为指向一个包含数据文件的文件夹的路径。创建数据存储时,spreadsheetDatastoredatastore 函数中的 location 参数用来定义 Folders

当您修改 SpreadsheetDatastore 对象的 Files 属性时,将重置 Folders 属性。

数据类型: cell

此 属性 为只读。

支持写入的格式,以字符串组成的行向量形式返回。此属性指定使用 writeall 从数据存储写入输出文件时可能的输出格式。

此 属性 为只读。

默认输出格式,以字符串标量形式返回。此属性指定使用 writeall 从数据存储写入输出文件时的默认格式。

数据类型: string

对象函数

hasdata确定是否有数据可读取
numpartitions数据存储分区数
partition划分数据存储
preview预览数据存储中的数据子集
read读取数据存储中的数据
readall读取数据存储中的所有数据
writeall将数据存储写入文件
reset将数据存储重置为初始状态
sheetnames从数据存储中查询工作表名称
transform变换数据存储
combine合并来自多个数据存储的数据
isPartitionable确定数据存储是否可分区
isSubsettableDetermine whether datastore is subsettable
isShuffleable确定数据存储是否可乱序

示例

全部折叠

使用 FileSet 对象或文件路径创建一个 spreadsheetDatastore 对象。

创建一个 FileSet 对象。创建一个 spreadsheetDatastore 对象。

fs = matlab.io.datastore.FileSet("airlinesmall_subset.xlsx");
ssds = spreadsheetDatastore(fs)
ssds = 
  SpreadsheetDatastore with properties:

                      Files: {
                             ' ...\Documents\MATLAB\Examples\airlinesmall_subset.xlsx'
                             }
                    Folders: {
                             ' ...\Documents\MATLAB\Examples'
                             }
   AlternateFileSystemRoots: {}
                     Sheets: ''
                      Range: ''

  Sheet Format Properties:
             NumHeaderLines: 0
         VariableNamingRule: 'modify'
          ReadVariableNames: true
              VariableNames: {'Year', 'Month', 'DayofMonth' ... and 26 more}
              VariableTypes: {'double', 'double', 'double' ... and 26 more}

  Properties that control the table returned by preview, read, readall:
      SelectedVariableNames: {'Year', 'Month', 'DayofMonth' ... and 26 more}
      SelectedVariableTypes: {'double', 'double', 'double' ... and 26 more}
                   ReadSize: 'file'
                 OutputType: 'table'
                   RowTimes: []

  Write-specific Properties:
     SupportedOutputFormats: ["txt"    "csv"    "xlsx"    "xls"    "parquet"    "parq"]
        DefaultOutputFormat: "xlsx"

您也可以使用文件路径指定数据。

ssds = spreadsheetDatastore("airlinesmall_subset.xlsx");

创建包含文件 airlinesmall_subset.xlsxSpreadsheetDatastore 对象。

ssds = spreadsheetDatastore("airlinesmall_subset.xlsx")
ssds = 
  SpreadsheetDatastore with properties:

                      Files: {
                             ' ...\Documents\MATLAB\Examples\airlinesmall_subset.xlsx'
                             }
                    Folders: {
                             ' ...\Documents\MATLAB\Examples'
                             }
   AlternateFileSystemRoots: {}
                     Sheets: ''
                      Range: ''

  Sheet Format Properties:
             NumHeaderLines: 0
         VariableNamingRule: 'modify'
          ReadVariableNames: true
              VariableNames: {'Year', 'Month', 'DayofMonth' ... and 26 more}
              VariableTypes: {'double', 'double', 'double' ... and 26 more}

  Properties that control the table returned by preview, read, readall:
      SelectedVariableNames: {'Year', 'Month', 'DayofMonth' ... and 26 more}
      SelectedVariableTypes: {'double', 'double', 'double' ... and 26 more}
                   ReadSize: 'file'
                 OutputType: 'table'
                   RowTimes: []

  Write-specific Properties:
     SupportedOutputFormats: ["txt"    "csv"    "xlsx"    "xls"    "parquet"    "parq"]
        DefaultOutputFormat: "xlsx"

显示文件的工作表名称。文件中针对每一年包含一个工作表。

sheetnames(ssds,1)
ans = 13x1 string
    "1996"
    "1997"
    "1998"
    "1999"
    "2000"
    "2001"
    "2002"
    "2003"
    "2004"
    "2005"
    "2006"
    "2007"
    "2008"

在第二个工作表中指定变量 FlightNum 作为感兴趣的数据,并预览前八行。

ssds.Sheets = 2; 
ssds.SelectedVariableNames = "FlightNum";
preview(ssds)
ans=8×1 table
    FlightNum
    _________

      1014   
      1201   
       702   
      1184   
      1310   
      1759   
      1242   
      1558   

只读取第一个工作表中变量 DepTimeArrTime 的前三行。

ssds.ReadSize = 3;
ssds.Sheets = 1;
ssds.SelectedVariableNames = ["DepTime","ArrTime"];
read(ssds)
ans=3×2 table
    DepTime    ArrTime
    _______    _______

     2117       2305  
     1252       1511  
     1441       1708  

读取所有工作表,包括四、五、六。

ssds.Sheets = 4:6;
readall(ssds);

使用 OutputTypeRowTimes 名称-值对组来使 SpreadsheetDatastore 返回时间表,而不是表。

tsunamis_dated.xlsx 创建一个数据存储。指定 "OutputType""timetable",以使 SpreadsheetDatastore 返回时间表而不是表。

ssds = spreadsheetDatastore("tsunamis_dated.xlsx","OutputType","timetable");
preview(ssds)
ans=8×15 timetable
       Date        Latitude    Longitude    ValidityCode          Validity          CauseCode               Cause                EarthquakeMagnitude       Country                 Location              MaxHeight    IidaMagnitude    Intensity    NumDeaths    DescDeaths              Time          
    ___________    ________    _________    ____________    ____________________    _________    ____________________________    ___________________    _____________    ____________________________    _________    _____________    _________    _________    __________    ________________________

    04-Mar-1952     42.15        143.85          4          {'definite tsunami'}        1        {'Earthquake'              }            8.1            {'JAPAN'    }    {'SE. HOKKAIDO ISLAND'     }        6.5           2.7              2           33           1         04-Mar-1952 01:22:41.000
    10-Jul-1958     58.34       -136.52          4          {'definite tsunami'}        3        {'Earthquake and Landslide'}            8.3            {'USA'      }    {'SE. ALASKA, AK'          }     524.26           4.6              5            5           1         10-Jul-1958 06:15:53.600
    22-May-1960     -39.5         -74.5          4          {'definite tsunami'}        1        {'Earthquake'              }            9.5            {'CHILE'    }    {'CENTRAL CHILE'           }         25           4.6              4         1260           3         22-May-1960 19:11:17.000
    20-Nov-1960      -6.8         -80.7          4          {'definite tsunami'}        1        {'Earthquake'              }            6.8            {'PERU'     }    {'PERU'                    }          9           3.2            2.5           66           2         20-Nov-1960 22:01:56.400
    28-Mar-1964      61.1        -147.5          4          {'definite tsunami'}        3        {'Earthquake and Landslide'}            9.2            {'USA'      }    {'PRINCE WILLIAM SOUND, AK'}         67           6.1              5          221           3         28-Mar-1964 03:36:14.000
    16-Jun-1964     38.65         139.2          4          {'definite tsunami'}        1        {'Earthquake'              }            7.5            {'JAPAN'    }    {'NW. HONSHU ISLAND'       }        5.8           2.7              2           26           1         16-Jun-1964 04:01:44.300
    14-Aug-1968       0.2         119.8          4          {'definite tsunami'}        1        {'Earthquake'              }            7.8            {'INDONESIA'}    {'BANDA SEA'               }         10           3.3              3          200           3         14-Aug-1968 22:14:19.400
    23-Feb-1969      -3.1         118.9          4          {'definite tsunami'}        1        {'Earthquake'              }            6.9            {'INDONESIA'}    {'MAKASSAR STRAIT'         }          4             2              2          600           3         23-Feb-1969 00:36:56.600

如果您没有指定 "RowTimes"spreadsheetDatastore 将使用第一个日期时间或持续时间变量作为行时间。在本例中,将 Date 变量用于行时间。此数据有两个日期时间变量:DateTimeDate 变量不包括小时、分钟或秒的信息,而 Time 变量有每个事件的具体时间。

指定 "RowTimes" 选项以使用事件时间(Time 变量)作为行时间。

ssds = spreadsheetDatastore("tsunamis_dated.xlsx","OutputType","timetable","RowTimes","Time");
preview(ssds)
ans=8×15 timetable
              Time              Latitude    Longitude    ValidityCode          Validity          CauseCode               Cause                EarthquakeMagnitude       Country                 Location              MaxHeight    IidaMagnitude    Intensity    NumDeaths    DescDeaths       Date    
    ________________________    ________    _________    ____________    ____________________    _________    ____________________________    ___________________    _____________    ____________________________    _________    _____________    _________    _________    __________    ___________

    04-Mar-1952 01:22:41.000     42.15        143.85          4          {'definite tsunami'}        1        {'Earthquake'              }            8.1            {'JAPAN'    }    {'SE. HOKKAIDO ISLAND'     }        6.5           2.7              2           33           1         04-Mar-1952
    10-Jul-1958 06:15:53.600     58.34       -136.52          4          {'definite tsunami'}        3        {'Earthquake and Landslide'}            8.3            {'USA'      }    {'SE. ALASKA, AK'          }     524.26           4.6              5            5           1         10-Jul-1958
    22-May-1960 19:11:17.000     -39.5         -74.5          4          {'definite tsunami'}        1        {'Earthquake'              }            9.5            {'CHILE'    }    {'CENTRAL CHILE'           }         25           4.6              4         1260           3         22-May-1960
    20-Nov-1960 22:01:56.400      -6.8         -80.7          4          {'definite tsunami'}        1        {'Earthquake'              }            6.8            {'PERU'     }    {'PERU'                    }          9           3.2            2.5           66           2         20-Nov-1960
    28-Mar-1964 03:36:14.000      61.1        -147.5          4          {'definite tsunami'}        3        {'Earthquake and Landslide'}            9.2            {'USA'      }    {'PRINCE WILLIAM SOUND, AK'}         67           6.1              5          221           3         28-Mar-1964
    16-Jun-1964 04:01:44.300     38.65         139.2          4          {'definite tsunami'}        1        {'Earthquake'              }            7.5            {'JAPAN'    }    {'NW. HONSHU ISLAND'       }        5.8           2.7              2           26           1         16-Jun-1964
    14-Aug-1968 22:14:19.400       0.2         119.8          4          {'definite tsunami'}        1        {'Earthquake'              }            7.8            {'INDONESIA'}    {'BANDA SEA'               }         10           3.3              3          200           3         14-Aug-1968
    23-Feb-1969 00:36:56.600      -3.1         118.9          4          {'definite tsunami'}        1        {'Earthquake'              }            6.9            {'INDONESIA'}    {'MAKASSAR STRAIT'         }          4             2              2          600           3         23-Feb-1969

版本历史记录

在 R2016a 中推出