Main Content

struct2dataset

(Not Recommended) Convert structure array to dataset array

collapse all in page

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.

example

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

example

Examples

collapse all

Open Live Script

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.

Open Live Script

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

collapse all

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 Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

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

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.

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.

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

collapse all

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.

Version History

Introduced in R2012b

See Also

| |