struct2dataset

(Not Recommended) Convert structure array to dataset array

The dataset data type is not recommended. To work with heterogeneous data, use the MATLAB^® table data type instead. See MATLAB table documentation for more information.

Syntax

ds = struct2dataset(S)

ds = struct2dataset(S,Name,Value)

Description

ds = struct2dataset(S) converts a structure array to a dataset array.

ds = struct2dataset(S,Name,Value) performs the conversion using additional options specified by one or more Name,Value pair arguments.

Examples

Convert Scalar Structure Array to Dataset Array

Convert a scalar structure array to a dataset array using the default options.

Create a structure array to convert.

S.Name = {'CLARK';'BROWN';'MARTIN'};
S.Gender = {'M';'F';'M'};
S.SystolicBP = [124;122;130];
S.DiastolicBP = [93;80;92];
S

S = struct with fields:
           Name: {3x1 cell}
         Gender: {3x1 cell}
     SystolicBP: [3x1 double]
    DiastolicBP: [3x1 double]

The scalar structure array has four fields, each with three rows.

Convert the structure array to a dataset array.

ds = struct2dataset(S)

ds = 
    Name              Gender       SystolicBP    DiastolicBP
    {'CLARK' }        {'M'}        124           93         
    {'BROWN' }        {'F'}        122           80         
    {'MARTIN'}        {'M'}        130           92         

The structure field names in S become the variable names in the output dataset array. The size of ds is 3-by-4.

Convert Nonscalar Structure Array to Dataset Array

Convert a nonscalar structure array to a dataset array, using one of the structure fields for observation names.

Create a nonscalar structure array to convert.

S(1,1).Name = 'CLARK';
S(1,1).Gender = 'M';
S(1,1).SystolicBP = 124;
S(1,1).DiastolicBP = 93;

S(2,1).Name = 'BROWN';
S(2,1).Gender = 'F';
S(2,1).SystolicBP = 122;
S(2,1).DiastolicBP = 80;

S(3,1).Name = 'MARTIN';
S(3,1).Gender = 'M';
S(3,1).SystolicBP = 130;
S(3,1).DiastolicBP = 92;

S

S=3×1 struct array with fields:
    Name
    Gender
    SystolicBP
    DiastolicBP

This is a 3-by-1 structure array with 4 fields.

Convert the structure array to a dataset array, using the Name field for observation names.

ds = struct2dataset(S,'ReadObsNames','Name')

ds = 
              Gender       SystolicBP    DiastolicBP
    CLARK     {'M'}        124           93         
    BROWN     {'F'}        122           80         
    MARTIN    {'M'}        130           92         

The size of ds is 3-by-3 because the structure field Name is used for observation names, and not as a dataset array variable.

ds.Properties.DimNames

ans = 1x2 cell
    {'Name'}    {'Variables'}

ds.Properties.ObsNames

ans = 3x1 cell
    {'CLARK' }
    {'BROWN' }
    {'MARTIN'}

Input Arguments

S — Input structure array

structure array

Input structure array to convert to a dataset array, specified as a scalar structure array with N fields, each with M rows, or a nonscalar M-by-1 structure array with N fields.

Data Types: struct

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: 'ReadObsNames','myField' specifies that the structure field, myField, contains observation names.

'ReadObsNames' — Name of structure field containing observation names for dataset array

false (default) | character vector | string scalar

Name of structure field containing observation names for the output dataset array, specified as the comma-separated pair consisting of 'ReadObsNames' and a character vector or string scalar containing a field name from the input structure array, S. When you specify a field name, struct2dataset uses that field to create observation names, and sets ds.Properties.DimNames equal to {ReadObsNames,'Variables'}.

For example, to specify that observation names are in the structure field, Names, use

Example: 'ReadObsNames','Names'

By default, or if ReadObsNames is equal to false, struct2dataset does not create observation names unless you specify names using the name-value pair argument ObsNames.

'ObsNames' — Observation names for dataset array

string array | cell array of character vectors

Observation names for the output dataset array, specified as the comma-separated pair consisting of 'ObsNames' and a string array or cell array of character vectors containing observation names. The names do not need to be valid MATLAB identifiers, but they must be unique.

'AsScalar' — Indicator for how to treat scalar structure

false | true

Indicator for how to treat a scalar input structure array, specified as the comma-separated pair consisting of 'AsScalar' and either true or false. The default value is true if S is a scalar structure array, and false otherwise.

By default, struct2dataset converts a scalar structure array with N fields, each with M rows, into an M-by-N dataset array.

If instead you set AsScalar equal to false for a scalar input structure array, then struct2dataset converts S to a dataset array with N observations.

Output Arguments

ds — Output dataset array

dataset array

Output dataset array, returned by default with M observations and N variables.

• If S is a scalar structure array with N fields, each with M rows, then ds is an M-by-N dataset array.

• If S is a nonscalar M-by-1 structure array with N fields, then ds is an M-by-N dataset array.

• If S is a scalar structure array with N fields, each with M rows, and AsScalar is set equal to false, then ds is a dataset array with N observations.