Statistics Toolbox™

dataset - Construct dataset array

Class

@dataset

Syntax

A = dataset(VAR1,VAR2,...) A = dataset(...,{VAR,name},...) A = dataset(...,{VAR,name_1,...,name_m},...) A = dataset(...,'VarNames',{name_1,...,name_m},...) A = dataset(...,'ObsNames',{name_1,...,name_n},...) A = dataset('file',filename,param1,val1,param2,val2,...) A = dataset('xlsfile',filename,param1,val1,param2,val2,...)

Description

A = dataset(VAR1,VAR2,...) creates dataset array A from workspace variables VAR1, VAR2, ... using the workspace variable names for the names of the variables in A. Variables can be arrays of any size, but all variables must be the same size along dimension 1 (rows).

A = dataset(...,{VAR,name},...) creates a variable in dataset A from the workspace variable VAR and assigns it the name name in A. Names must be valid, unique MATLAB^® identifier strings.

A = dataset(...,{VAR,name_1,...,name_m},...), where VAR is an array with size m along dimension 2 (columns), creates m variables in dataset A from the columns of the workspace variable VAR and assigns them the names name_1, ..., name_m in A.

A = dataset(...,'VarNames',{name_1,...,name_m},...) names the m variables in A with the specified variable names. Names must be valid, unique MATLAB identifier strings. The number of names must equal the number of variables in A. You cannot use the 'VarNames' parameter if you provide names for individual variables using {VAR,name} pairs.

A = dataset(...,'ObsNames',{name_1,...,name_n},...) names the n observations in A with the specified observation names. The names need not be valid MATLAB identifier strings, but must be unique. The number of names must equal the number of observations (rows) in A.

Note Dataset arrays may contain built-in types or array objects as variables. Array objects must implement each of the following:

Standard MATLAB parenthesis indexing of the form var(i,...), where i is a numeric or logical vector corresponding to rows of the variable
A size method with a dim argument
A vertcat method

A = dataset('file',filename,param1,val1,param2,val2,...) creates dataset array A from column-oriented data in the text file specified by the string filename. Variables in A are of type double if data in the corresponding column of the file, following the column header, are entirely numeric; otherwise the variables in A are cell arrays of strings. Optional parameter name/value pairs are those listed in the following table and, when the 'format' parameter is used, all those allowed by textscan.

Name	Value
`'delimiter'`	A string indicating the character separating columns in the file. Values are `'\t'` (tab—the default), `' '` (space), `','` (comma), `';'` (semicolon), and `'\|'` (bar).
`'format'`	A string indicating how data is read from the file into the variables in `A`. Values are conversion specifiers for `textscan`. Additional `textscan` parameter/value pairs may be used when this parameter is used.
`'ReadVarNames'`	A logical value indicating whether (`true`) or not (`false`) to read variable names from the first row of the file. The default is `true`. If `'ReadVarNames'` is `true`, variable names in the column headers of the file cannot be empty.
`'ReadObsNames'`	A logical value indicating whether (`true`) or not (`false`) to read observation names from the first column of the file. The default is `false`. If `'ReadObsNames'` and `'ReadVarNames'` are both `true`, the header of the first column in the file is saved as the name of the first dimension in `A.Properties.DimNames`.

A = dataset('xlsfile',filename,param1,val1,param2,val2,...) creates dataset array A from column-oriented data in the Excel^® spreadsheet specified by the string filename. Variables in A are of type double if data in the corresponding column of the spreadsheet, following the column header, are entirely numeric; otherwise the variables in A are cell arrays of strings. Optional parameter name/value pairs are listed in the following table.

Name	Value
`'sheet'`	A positive scalar value of type `double` indicating the sheet number, or a quoted string indicating the sheet name.
`'range'`	A string of the form `'C1:C2'` where `C1` and `C2` are the names of cells at opposing corners of a rectangular region to be read, as for `xlsread`. By default, the rectangular region extends to the right-most column containing data. If the spreadsheet contains empty columns between columns of data, or if the spreadsheet contains figures or other non-tabular information, specify a range that contains only data.
`'ReadVarNames'`	A logical value indicating whether (`true`) or not (`false`) to read variable names from the first row of the range. The default is `true`. If `'ReadVarNames'` is `true`, variable names in the column headers of the range cannot be empty.
`'ReadObsNames'`	A logical value indicating whether (`true`) or not (`false`) to read observation names from the first column of the range. The default is `false`. If `'ReadObsNames'` and `'ReadVarNames'` are both `true`, the header of the first column in the range is saved as the name of the first dimension in `A.Properties.DimNames`.

Examples

Example 1

Create a dataset array to contain Fisher's iris data:

load fisheriris
NumObs = size(meas,1);
NameObs = strcat({'Obs'},num2str((1:NumObs)','%d'));
iris = dataset({nominal(species),'species'},...
               {meas,'SL','SW','PL','PW'},...
               'ObsNames',NameObs);
iris(1:5,:)
ans = 
            species    SL     SW     PL     PW 
    Obs1    setosa     5.1    3.5    1.4    0.2
    Obs2    setosa     4.9      3    1.4    0.2
    Obs3    setosa     4.7    3.2    1.3    0.2
    Obs4    setosa     4.6    3.1    1.5    0.2
    Obs5    setosa       5    3.6    1.4    0.2

Example 2

Load patient data from the CSV file hospital.dat and store the information in a dataset array with observation names given by the first column in the data (patient identification):
```
patients = dataset('file','hospital.dat',...
                   'delimiter',',',...
                   'ReadObsNames',true);
```
Make the {0,1}-valued variable smoke nominal, and change the labels to 'No' and 'Yes':
```
patients.smoke = nominal(patients.smoke,{'No','Yes'});
```

Add new levels to smoke as placeholders for more detailed histories of smokers:

patients.smoke = addlevels(patients.smoke,...
                 {'0-5 Years','5-10 Years','LongTerm'});

Assuming the nonsmokers have never smoked, relabel the 'No' level:
```
patients.smoke = setlabels(patients.smoke,'Never','No');
```

Drop the undifferentiated 'Yes' level from smoke:

patients.smoke = droplevels(patients.smoke,'Yes');

Warning: OLDLEVELS contains categorical levels that 
were present in A, caused some array elements to have 
undefined levels.

Note that smokers now have an undefined level.

Set each smoker to one of the new levels, by observation name:
```
patients.smoke('YPL-320') = '5-10 Years';
```