Accelerating the pace of engineering and science

# struct2dataset

Convert structure array to dataset array

The dataset data type might be removed in a future release. To work with heterogeneous data, use the MATLAB® table data type instead. See MATLAB table documentation for more information.

## Syntax

• ds = struct2dataset(S) example
• ds = struct2dataset(S,Name,Value) example

## Description

example

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.

## Examples

expand all

### 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 =

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 =

3x1 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 =

'Name'    'Variables'```
`ds.Properties.ObsNames`
```ans =

'CLARK'
'BROWN'
'MARTIN'```

## Input Arguments

expand all

### S — Input structure arraystructure 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 single 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 arrayfalse (default) | string

Name of structure field containing observation names for the output dataset array, specified as the comma-separated pair consisting of 'ReadObsNames' and a string 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

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 arraycell array of strings

Observation names for the output dataset array, specified as the comma-separated pair consisting of 'ObsNames' and a cell array of strings 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 structurefalse | 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

expand all

### ds — Output dataset arraydataset 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.