# spreadsheetImportOptions
电子表格的导入选项对象
函数库: TyBase
# 说明
spreadsheetImportOptions 对象允许您指定 Syslab 如何从电子表格文件中导入表格数据。此对象包含的属性可以控制数据导入过程，包括如何处理错误和缺失的数据。
# 创建对象
您可以使用 detectImportOptions 函数或 spreadsheetImportOptions 函数（下文介绍）创建 spreadsheetImportOptions 对象：
- 使用 detectImportOptions 根据 filename 中指定的电子表格内容检测并填充导入属性。
opts = detectImportOptions(filename);
- 使用 spreadsheetImportOptions 根据导入要求定义导入属性。
# 语法
opts = spreadsheetImportOptions()
opts = spreadsheetImportOptions(numVars)
opts = spreadsheetImportOptions(___,key=value)
# 说明
opts = spreadsheetImportOptions() 使用一个变量创建 spreadsheetImportOptions 对象。示例
opts = spreadsheetImportOptions(numVars) 使用 numVars 中指定的变量数目创建该对象。示例
opts = spreadsheetImportOptions(___,key=value) 使用一个或多个名称-值对组参数指定 spreadsheetImportOptions 对象的其他属性。示例
# 输入参数
numVars - 变量的数目正整数标量
变量的数目，指定为正整数标量。
# 属性
# 变量属性
variablenames - 变量名称字符串数组
变量名称，指定为字符串数组。variablenames 属性包含导入变量时要使用的名称。
如果数据中包含 N 个变量，但未检测到变量名称，variablenames 属性中将包含 ["Var1","Var2",...,"VarN"]。
要支持无效的 Syslab 标识符作为变量名称，例如包含空格和非 ASCII 字符的变量名称，请将 PreserveVariableNames 参数设置为 true。
示例： opts.variablenames 返回当前（检测到的）变量名称。
示例： opts.variablenames(3) = ["Height"] 将第三个变量的名称更改为 Height。
数据类型： String
variabletypes - 变量的数据类型字符串数组
变量的数据类型，指定为字符串数组。variabletypes 属性指定导入变量时要使用的数据类型。分配新值时，将 variabletypes 指定为有效数据类型名称的数组。
要更新 variabletypes 属性，请使用 setvartype 函数。
示例： opts.variabletypes 返回当前（检测到的）变量数据类型。
示例： opts = setvartype(opts,"Height",Float64) 将变量 Height 的数据类型更改为 Float64。
数据类型： Float32 | Float64 | Int8 | Int16 | Int32 | Int64 | UInt8 | UInt16 | UInt32 | UInt64 | Bool | Char | String | DateTime
selectedvariablenames - 要导入的变量子集字符串数组
要导入的变量子集，指定为字符串数组。
selectedvariablenames 必须是 VariableNames 属性中包含的名称的子集。默认情况下，selectedvariablenames 包含 VariableNames 属性中的所有变量名称，也就是说将导入所有变量。
可以使用 selectedvariablenames 属性只导入相关变量。使用 selectedvariablenames 属性指定变量子集，然后使用 readtable 只导入该子集。
示例： opts.selectedvariablenames = ["Height","LastName"] 只为导入操作选择两个变量，即 Height 和 LastName。
示例： T = readtable(filename,opts) 返回一个表，其中只包含在 opts 对象的 selectedvariablenames 属性中指定的变量。
数据类型： String
variableoptions - 类型特定的变量导入选项变量导入选项对象的数组
类型特定的变量导入选项，以变量导入选项对象数组形式返回。此数组为 variablenames 属性中指定的每个变量包含一个对应的对象。数组中的每个对象均包含一些属性，支持导入特定数据类型的数据。
变量选项支持以下数据类型：数值、文本、Bool、DateTime 或 categorical。
要查询变量的当前（或检测到的）选项，请使用 getvaropts 函数。
要为变量设置和自定义选项，请使用 setvaropts 函数。
示例： opts.variableoptions 返回 VariableImportOptions 对象的集合，每个对象对应于数据中的一个变量。
示例： getvaropts(opts,"Height") 返回 Height 变量的 VariableImportOptions 对象。
示例： opts = setvaropts(opts,"Height","FillValue",0) 将变量 Height 的 FillValue 属性设置为 0。
# 位置属性
sheet - 要从中读取数据的工作表"" 空字符串 （默认） | 字符串标量 | 正整数标量
要从中读取数据的工作表，指定为空字符数组、包含工作表名称的字符向量或字符串标量，或表示工作表索引的正整数标量。根据为 sheet 属性指定的值，导入函数的行为如下表中所述。
| 指定的值 | 行为 |
|---|---|
| ""（默认值） | 从第一个工作表导入数据。 |
| 名称 | 从具有匹配名称的工作表中导入数据，不考虑电子表格文件中工作表的顺序。 |
| 整数 | 从由整数指定的位置的工作表导入数据，不考虑电子表格文件中的工作表名称。 |
数据类型： String | Float32 | Float64
datarange - 数据的位置字符串标量
要导入的数据的位置，指定为字符串标量组成的 N×2 数组。使用以下形式之一指定 datarange。
| 值 | 行为 |
|---|---|
| n 起始单元格 | 使用 Excel A1 表示法指定数据的起始单元。例如，A5 是第 A 列与第 5 行相交处的单元格的标识符。 根据起始单元格，导入函数通过从起始单元格开始导入，并在到达最后一个空行或页脚范围时结束，从而自动检测数据范围。 例如："A5" 或 5 |
| "Corner1:Corner2" 矩形范围 | 使用矩形范围格式指定确切范围，其中 Corner1 和 Corner2 是定义要读取的区域的两个对角。 导入函数只读取指定范围内包含的数据。指定范围内的任何空字段都作为缺失单元导入。 列数必须与 NumVariables 属性中的指定的数字匹配。 示例："A5:K50" |
数据类型： String | Float32 | Float64
variablenamesrange - 变量名称的位置字符串标量
变量名称的位置，指定为字符串标量。将 variablenamesrange 指定为下表中的值之一。
| 值 | 行为 |
|---|---|
| "Cell" | 使用 Excel A1 表示法指定数据的起始单元。例如，A5 是第 A 列与第 5 行相交处的单元格的标识符。 导入函数为数据中的每个变量读取一个名称。 示例："A5" |
| "Corner1:Corner2" 矩形范围 | 使用矩形范围格式指定确切范围，其中 Corner1 和 Corner2 是定义要读取的区域的两个对角。 RowNamesRange 中包含的行数必须与数据行的数量匹配，而且 RowNamesRange 指示的范围只能跨一列。 示例："A5:K5" |
数据类型： String
# 对象函数
| getvaropts | 获取变量导入选项 |
| setvaropts | 设置变量导入选项 |
| setvartype | 设置变量数据类型 |
| preview | 使用导入选项预览文件中的八行数据 |
# 示例
在电子表格文件中定义变量的导入选项
创建一个导入选项对象，以从 patients.xls 文件中读取一个变量。
初始化 spreadsheetImportOptions 对象，指定变量名称、变量类型和数据起始单元格。然后，将 preview 函数与导入选项对象结合使用以预览数据。
using TyBase
res_dir = joinpath(pkgdir(TyBase), "examples", "resources", "readtable")
filename = joinpath(res_dir, "patients.xlsx")
opts = spreadsheetImportOptions();
opts.VariableNames = "LastName";
opts.DataRange = "A2";
preview(filename, opts)
8×1 DataFrame
Row │ LastName
│ String
─────┼──────────
1 │ Smith
2 │ Johnson
3 │ Williams
4 │ Jones
5 │ Brown
6 │ Davis
7 │ Miller
8 │ Wilson
从文件中导入变量。
oneVar = readtable(filename, opts);
varinfo(r"^oneVar$")
name size summary
–––––– ––––––––– –––––––––––––––
oneVar 2.797 KiB 100×1 DataFrame
在电子表格文件中定义多个变量的导入选项
创建一个导入选项对象，以从 patients.xls 读取多个变量。
根据文件的内容，定义变量的数目、变量名称、变量类型和数据起始位置。
using TyBase
numVars = 7;
varNames = ["LastName", "Gender", "Age", "Location", "Height", "Weight", "Smoker"];
varTypes = [String, String, Int, String, Float64, Float64, Bool];
dataStartLoc = "A2";
使用 spreadsheetImportOptions 函数和变量信息初始化导入选项对象 opts。
opts = spreadsheetImportOptions(
numVars; variablenames=varNames, datarange=dataStartLoc, variabletypes=varTypes
);
结合使用 preview 函数和导入选项来预览数据。
res_dir = joinpath(pkgdir(TyBase), "examples", "resources", "readtable")
filename = joinpath(res_dir, "patients.xlsx")
preview(filename, opts)
8×7 DataFrame
Row │ LastName Gender Age Location Height Weight Smoker
│ String String Int64 String Float64 Float64 Bool
─────┼──────────────────────────────────────────────────────────────────────────────
1 │ Smith Male 38 County General Hospital 71.0 176.0 true
2 │ Johnson Male 43 VA Hospital 69.0 163.0 false
3 │ Williams Female 38 St. Mary's Medical Center 64.0 131.0 false
4 │ Jones Female 40 VA Hospital 67.0 133.0 false
5 │ Brown Female 49 County General Hospital 64.0 119.0 false
6 │ Davis Female 46 St. Mary's Medical Center 68.0 142.0 false
7 │ Miller Female 33 VA Hospital 64.0 142.0 true
8 │ Wilson Male 40 VA Hospital 68.0 180.0 false
使用 readtable 导入数据。
T = readtable(filename, opts);
varinfo(r"^T$")
name size summary
–––– ––––––––– –––––––––––––––
T 7.235 KiB 100×7 DataFrame