Simulink.SimulationData.Dataset

访问记录的仿真数据或对仿真输入数据分组

全页展开

说明

Simulink.SimulationData.Dataset 对象可对相关数据进行分组。记录的仿真结果通常分组到 Dataset 对象中。当您加载初始状态时以及使用 Inport 模块或 Signal Editor 模块加载外部输入数据时，您还可以使用 Dataset 对象对仿真输入数据进行分组。

通过记录仿真数据创建的 Dataset 对象包含一个或多个元素。每个元素都包含记录信号、输出、数据存储或状态的数据。每个元素都是一个对象，该对象的类型取决于它包含的数据。

当您创建一个 Dataset 对象以对仿真输入数据进行分组时，每个元素都包含信号、总线或总线数组的数据。您可以添加您使用的加载方法支持的任何格式的数据。

输入类型数据格式

标量、向量或多维信号

总线

  • 与总线层次结构相匹配的 timeseries、timetable 或 matlab.io.datastore.SimulationDatastore 对象的结构体

  • Simulink.SimulationData.Signal

总线数组

  • 结构体数组

  • Simulink.SimulationData.Signal

函数调用信号

  • N×1 向量

  • Simulink.SimulationData.Signal

创建对象

记录仿真数据通常会创建一个 Simulink.SimulationData.Dataset 对象，包括以下记录情况：

  • 使用信号记录来记录数据。

  • 使用数据集格式记录输出、状态或最终状态。

  • 日志数据存储。

  • 使用 Record 模块将数据记录到工作区或 MAT 文件。

  • 使用 Scope 模块以数据集格式记录数据。

  • 使用 Floating Scope 或 Scope Viewer 记录数据。

要将模型的外部输入数据分组到 Dataset 对象中，您可以：

  • 创建一个空的 Dataset 对象并使用 addElement 函数添加输入数据。

  • 使用 createInputDataset 创建一个 Dataset 对象，该对象包含模型中每个根级 Inport 模块或 In Bus Element 模块的元素。然后，指定每个元素的数据。

  • 使用信号编辑器以交互方式创建和编辑包含仿真输入数据的 Dataset 对象。有关详细信息，请参阅创建和编辑信号数据。

您还可以通过将使用其他格式的数据转换为使用数据集格式来创建 Dataset 对象。所有数据都采用通用格式可以方便后处理。有关详细信息，请参阅Convert timeseries Object to Dataset Object。

语法

ds = Simulink.SimulationData.Dataset
ds = Simulink.SimulationData.Dataset(dataToConvert)
ds = Simulink.SimulationData.Dataset(dataToConvert,"DatasetName",dsName)

描述

ds = Simulink.SimulationData.Dataset 创建一个未命名的空 Dataset 对象，您可以向其中添加元素。使用此语法可手动创建一个包含外部输入数据的 Dataset 对象，以便使用 Inport 或 In Bus Element 模块加载。

示例

ds = Simulink.SimulationData.Dataset(dataToConvert) 创建一个未命名的 Dataset 对象，该对象包含一个或多个包含数据 dataToConvert 的元素。使用此语法可将使用其他格式的数据转换为使用数据集格式。有关详细信息，请参阅Convert timeseries Object to Dataset Object。

转换过程每次仅转换一个输入的数据。要转换多个变量的数据，请一次转换一个变量，然后使用 concat 函数组合生成的 Dataset 对象。

ds = Simulink.SimulationData.Dataset(dataToConvert,"DatasetName",dsName) 创建一个名称由 dsName 指定的 Dataset 对象，该对象包含一个或多个包含数据 dataToConvert 的元素。使用此语法可将使用其他格式的数据转换为使用数据集格式。有关详细信息，请参阅Convert timeseries Object to Dataset Object。

输入参量

全部展开

要转换为数据集格式的数据，指定为 timeseries 对象、结构体或数组。转换的结果取决于输入数据的格式。

输入数据转换结果
timeseries 对象

包含一个 Simulink.SimulationData.Signal 对象的 Dataset 对象，该对象的 Values 属性中包含 timeseries 数据。

与带时间的结构体记录格式匹配的结构体。

包含一个或多个 Simulink.SimulationData.Signal 对象的 Dataset 对象，这些对象包含输入结构体中每个信号的数据。

与结构体记录格式匹配的结构体

包含一个或多个 Simulink.SimulationData.Signal 对象的 Dataset 对象，这些对象包含输入结构体中每个信号的数据。

由于输入不包含时间数据，因此，转换会为每个信号创建一个时间向量，该向量从 0 开始并使用 1 作为采样间隔。

数组

包含一个 Simulink.SimulationData.Signal 对象的 Dataset 对象。Signal 对象的 Values 属性包含 timeseries 对象，timeseries 对象的 Data 属性包含整个数组。

由于输入不包含时间数据，因此，转换会为信号创建一个时间向量，该向量从 0 开始并使用 1 作为采样间隔。

有关详细信息，请参阅Convert timeseries Object to Dataset Object和Convert Data to Dataset Format。

Dataset 对象名称，指定为字符串或字符向量。

输出参量

全部展开

Dataset 对象，返回为 Simulink.SimulationData.Dataset 对象。当您不指定输入参量时，Dataset 对象为空。当您要将仿真输入数据分组到单个变量中时，请创建一个空的 Dataset 对象。

当您指定输入参量时，Dataset 对象包含一个或多个包含输入数据的元素。转换的结果取决于输入数据的格式。

输入数据转换结果
timeseries 对象

包含一个 Simulink.SimulationData.Signal 对象的 Dataset 对象，该对象的 Values 属性中包含 timeseries 数据。

与带时间的结构体记录格式相匹配的结构体

包含一个或多个 Simulink.SimulationData.Signal 对象的 Dataset 对象，这些对象包含输入结构体中每个信号的数据。

与结构体记录格式匹配的结构体

包含一个或多个 Simulink.SimulationData.Signal 对象的 Dataset 对象，这些对象包含输入结构体中每个信号的数据。

由于输入不包含时间数据，因此，转换会为每个信号创建一个时间向量，该向量从 0 开始并使用 1 作为采样间隔。

数组

包含一个 Simulink.SimulationData.Signal 对象的 Dataset 对象。Signal 对象的 Values 属性包含 timeseries 对象，timeseries 对象的 Data 属性包含整个数组。

由于输入不包含时间数据，因此，转换会为信号创建一个时间向量，该向量从 0 开始并使用 1 作为采样间隔。

有关详细信息，请参阅Convert timeseries Object to Dataset Object和Convert Data to Dataset Format。

属性

全部展开

Dataset 对象名称，指定为字符串或字符向量。当您创建一个 Dataset 对象来对仿真输入数据进行分组时，您需要指定 Dataset 对象的名称。您指定的名称不需要与包含 Dataset 对象的变量的名称匹配。

通过记录仿真数据创建的 Dataset 对象的 Name 属性设置为与模型配置参数中指定的记录变量名称匹配。

对象函数

addElementAdd element to end of Simulink.SimulationData.Dataset object
concat将 Simulink.SimulationData.Dataset 对象串联到另一个 Dataset 对象
exportToPreviousReleaseSave a Dataset object to a MAT file you can open in any release
extractTimetableExtract data from Simulink.SimulationData.Dataset or Simulink.SimulationData.Signal objects into timetables
find从 Simulink.SimulationData.Dataset 对象获取元素或元素集合
get从 Simulink.SimulationData.Dataset 对象获取元素或元素集合
getElementNames返回 Simulink.SimulationData.Dataset 对象中所有元素的名称
numElements获取 Simulink.SimulationData.Dataset 对象中的元素数
plot在仿真数据检查器中绘制数据
removeElementRemove element from Simulink.SimulationData.Dataset object
setElementChange Simulink.SimulationData.Dataset object element stored at specified index

示例

全部折叠

打开实时脚本

打开模型 vdp。该模型生成两个输出：x1 和 x2。 

mdl = "vdp";
open_system(mdl);

The model vdp.

仿真模型，同时记录模块状态以及输出数据。

out = sim(mdl,"SaveState","on");

所有记录的数据都作为 Simulink.SimulationOutput 对象在单个变量 out 中返回。SimulationOutput 对象包含一个 Simulink.SimulationData.Dataset 对象，以对每种记录的数据进行分组。

out
out = 
  Simulink.SimulationOutput:

                logsout: [1x1 Simulink.SimulationData.Dataset] 
                   tout: [87x1 double] 
                   xout: [1x1 Simulink.SimulationData.Dataset] 
                   yout: [1x1 Simulink.SimulationData.Dataset] 

     SimulationMetadata: [1x1 Simulink.SimulationMetadata] 
           ErrorMessage: [0x0 char]

使用圆点表示法访问包含记录的输出数据的 Dataset 对象 yout。Dataset 对象包含每个输出的 Simulink.SimulationData.Signal 对象。

outputs = out.yout
outputs = 
Simulink.SimulationData.Dataset 'yout' with 2 elements

                         Name  BlockPath 
                         ____  _________ 
    1  [1x1 Signal]      x1    vdp/Out1 
    2  [1x1 Signal]      x2    vdp/Out2 

  - Use braces { } to access, modify, or add elements using index.

Signal 对象包含有关信号的元数据，包括产生信号的模块的路径和端口的索引。使用 getElement 函数可按名称访问包含信号 x1 数据的 Signal 对象。您还可以使用花括号 ({}) 按索引访问 Dataset 对象中的元素。

outputX1 = getElement(outputs,'x1')
outputX1 = 
  Simulink.SimulationData.Signal
  Package: Simulink.SimulationData

  Properties:
              Name: 'x1'
    PropagatedName: ''
         BlockPath: [1×1 Simulink.SimulationData.BlockPath]
          PortType: 'inport'
         PortIndex: 1
            Values: [1×1 timeseries]


  Methods, Superclasses

信号数据作为 timeseries 对象存储在 Signal 对象的 Values 属性中。 

outputValsX1 = outputX1.Values
  timeseries

  Common Properties:
            Name: 'x1'
            Time: [87x1 double]
        TimeInfo: [1x1 tsdata.timemetadata]
            Data: [87x1 double]
        DataInfo: [1x1 tsdata.datametadata]

  More properties, Methods

时间值在 timeseries 对象的 Time 属性中。信号值在 Data 属性中。

outputTimesX1 = outputValsX1.Time
outputTimesX1 = 87×1

         0
    0.0001
    0.0006
    0.0031
    0.0157
    0.0785
    0.1922
    0.3283
    0.4956
    0.7068
    0.9891
    1.3891
    1.7891
    2.1891
    2.5891
      ⋮


outputDataX1 = outputValsX1.Data
outputDataX1 = 87×1

    2.0000
    2.0000
    2.0000
    2.0000
    1.9998
    1.9947
    1.9739
    1.9380
    1.8854
    1.8115
    1.7025
    1.5253
    1.3083
    1.0177
    0.5596
      ⋮

您还可以通过将步骤组合成一行代码来访问时间值或数据值。

outputDataX1 = getElement(out.yout,'x1').Values.Data
outputDataX1 = 87×1

    2.0000
    2.0000
    2.0000
    2.0000
    1.9998
    1.9947
    1.9739
    1.9380
    1.8854
    1.8115
    1.7025
    1.5253
    1.3083
    1.0177
    0.5596
      ⋮
打开实时脚本

为三个仿真输入信号创建数据并将它们分组到 Dataset 对象中。一个简单的模型使用三个根级 Inport 模块加载 Dataset 对象的内容。模型中的 Dashboard Scope 模块显示使用加载的输入数据创建的每个信号。

首先，创建要加载到模型中的信号数据。使用此示例中的表达式为输入信号创建等间距时间向量，尤其是在对离散输入信号进行建模时。MATLAB® 还支持其他几种创建等间距向量的方法，但其他方法可能会在时间数据中引入双精度舍入误差，从而导致意外的仿真结果。

sampleTime = 0.01;
numSteps = 1001;
time = sampleTime*(0:numSteps-1);
time = time';

为正弦信号、余弦信号和线性信号创建信号数据。 

sineVals = sin(2*pi/3*time);
cosVals = cos(2*pi/3*time);
lineVals = time;

创建一个 timeseries 对象来包含每个信号的数据。为每个 timeseries 对象提供一个描述性名称，使信号在分组到 Dataset 对象中后易于识别。

sineTS = timeseries(sineVals,time,'Name','Sine Wave');
cosTS = timeseries(cosVals,time,'Name','Cosine Wave');
lineTS = timeseries(lineVals,time,'Name','Line');

创建一个 Dataset 对象，并使用 addElement 函数将每个 timeseries 对象添加到 Dataset 对象中。

inputData = Simulink.SimulationData.Dataset;
inputData.Name = 'inputData';
inputData = addElement(inputData,sineTS);
inputData = addElement(inputData,cosTS);
inputData = addElement(inputData,lineTS)
inputData = 
Simulink.SimulationData.Dataset 'inputData' with 3 elements

                             Name         BlockPath 
                             ___________  _________ 
    1  [1x1 timeseries]      Sine Wave    ''       
    2  [1x1 timeseries]      Cosine Wave  ''       
    3  [1x1 timeseries]      Line         ''       

  - Use braces { } to access, modify, or add elements using index.

当您使用根级 Inport 模块加载外部输入数据时，您可以使用“数据导入/导出”窗格上“模型配置参数”中的 Input 参数指定要加载的数据。打开模型 LoadInputDataset，查看 Input 参数是否指定为 inputData。

open_system('LoadInputDataset.slx');

对模型进行仿真。连接到第一个 Inport 模块的 Dashboard Scope 模块显示正弦信号，连接到第二个 Inport 模块的 Dashboard Scope 模块显示余弦信号，连接到第三个 Inport 模块的 Dashboard Scope 模块显示线性信号。 

out = sim('LoadInputDataset.slx');

您可以交换 Dataset 对象中元素的顺序，看看元素映射到 Inport 模块的方式所反映的变化。

inputData{1} = lineTS;
inputData{3} = sineTS
inputData = 
Simulink.SimulationData.Dataset 'inputData' with 3 elements

                             Name         BlockPath 
                             ___________  _________ 
    1  [1x1 timeseries]      Line         ''       
    2  [1x1 timeseries]      Cosine Wave  ''       
    3  [1x1 timeseries]      Sine Wave    ''       

  - Use braces { } to access, modify, or add elements using index.

再次对模型进行仿真。显示第一个元素的 Dashboard Scope 模块现在显示直线，显示第三个元素的 Dashboard Scope 模块显示正弦波，反映了 Dataset 对象中元素的新顺序。

out = sim('LoadInputDataset.slx');

提示

  • 您可以使用花括号 ({}) 按索引访问、添加或修改 Dataset 对象中的元素。

  • 要按名称访问、添加或修改 Dataset 对象的元素，请使用 getElement、addElement 和 setElement 函数。

  • 当您使用 Dataset 对象对仿真输入进行分组时，您可以使用信号编辑器或 Signal Editor 模块轻松更改哪个 Dataset 对象为仿真提供输入。

  • 当您使用根级 Inport 模块从 Dataset 对象加载外部输入数据时，您可以使用根输入端口映射器按模块名称、模块路径、信号名称或端口顺序将 Dataset 对象中的每个元素都映射到 Inport 模块。您还可以编写自己的函数来映射数据。有关详细信息，请参阅映射根输入信号数据。

  • 将 Dataset 对象中的数据保存到 MAT 文件时，如果 Dataset 对象的内容太大而无法放入内存，请考虑保存到 7.3 版 MAT 文件。您可以创建 Simulink.SimulationData.DatasetRef 以引用 MAT 文件中的 Dataset 对象，而无需将数据加载到内存中进行数据处理或加载大数据。有关详细信息，请参阅Load Big Data for Simulations。

  • 要将 Dataset 对象保存到可以在早期版本中打开的 MAT 文件，请使用 exportToPreviousRelease 函数而不是 save 函数。

  • 您可以编写自己的读取器，以使用 Simulink.io.FileType 类将文件中的数据导入基础工作区、模型工作区或信号编辑器中的 Dataset 对象。有关详细信息，请参阅Create Custom File Type for Import。

版本历史记录

在 R2011a 中推出

全部展开

另请参阅

对象

函数

模型设置

主题