Dataset Arrays

On this page…
Overview Test Results Data Looking at Data

Overview

When you run a test, you can view your test results data as a dataset array in MATLAB. This appendix contains general information on the dataset array that is the format used for test results that can be accessed in MATLAB. See Accessing Test Results from the MATLAB Command Line for information on using the command-line test results.

Dataset arrays are used to collect heterogeneous data and metadata including into a single container variable. Dataset arrays can be viewed as tables of values, with rows representing different observations and columns representing different measured variables. Dataset arrays can accommodate variables of different types, sizes, units, etc.

Note   In the SystemTest software, each observation (i.e., row) is used to represent a test iteration, while each measured variable (i.e., column) represents a test vector or test result value.

Dataset arrays combine the organizational advantages of basic MATLAB data types while addressing their shortcomings with respect to storing complex heterogeneous data.

Dataset arrays have a family of functions for assembling, accessing, manipulating, and processing the collected data. Basic array operations parallel those for numerical, cell, and structure arrays.

Back to Top

Test Results Data

MATLAB data containers (variables) are suitable for completely homogeneous data (numeric, character, and logical arrays) and for completely heterogeneous data (cell and structure arrays). Test results data, however, are often a mixture of homogeneous variables of heterogeneous types and sizes. Dataset arrays are suitable containers for this kind of data.

Dataset arrays can be viewed as tables of values, with rows representing different test iterations or cases and columns representing different test vector and test result values. Basic methods for creating and manipulating dataset arrays parallel the syntax of corresponding methods for numerical arrays. Because of the potentially heterogeneous nature of the data, dataset arrays have indexing methods with syntax that parallels corresponding methods for cell and structure arrays.

Back to Top

Looking at Data

Dataset arrays in MATLAB are variables created with the dataset function, and then manipulated with associated functions. In the case of the SystemTest software, when a test is run, a dataset array is created and stored as part of a test results object. The test results object is assigned to a variable named stresults in the MATLAB workspace when the test stops running. See Accessing Test Results from the MATLAB Command Line for information on using stresults.

The following table lists the accessible properties of dataset arrays. Properties can be configured using the set function, or accessed using the get function.

Dataset Property	Value
Description	A string describing the data set. The default is an empty string.
Units	A cell array of strings giving the units of the variables in the data set. The number of strings must equal the number of variables. Strings may be empty. The default is an empty cell array.
DimNames	A cell array of two strings giving the names of the rows and columns, respectively, of the data set. The default is {'Observations' 'Variables'}.
UserData	Any variable containing additional information to be associated with the data set. The default is an empty array.
ObsNames	A cell array of nonempty, distinct strings giving the names of the observations in the data set. The number of strings must equal the number of observations. The default is an empty cell array.
VarNames	A cell array of nonempty, distinct strings giving the names of the variables in the data set. The number of strings must equal the number of variables. The default is the cell array of string names for the variables used to create the data set.

Functions associated with dataset arrays are used to display, summarize, convert, concatenate, and access the collected data. Examples include disp, summary, double, horzcat, and get, respectively. Many of these functions are invoked using operations analogous to those for numerical arrays, and do not need to be called directly. (For example, horzcat is invoked by [].) Other functions access the collected data and must be called directly (for example, replacedata).

Dataset arrays are implemented as MATLAB objects; the associated functions are their methods. It isn't necessary to understand objects and methods to make use of dataset arrays—in fact, dataset arrays are designed to behave as much as possible like other, familiar MATLAB arrays.

Back to Top

The dataset Array

Dataset Array Operations

© 1984-2012- The MathWorks, Inc.    -   Site Help   -   Patents   -   Trademarks   -   Privacy Policy   -   Preventing Piracy   -   RSS