CBDataSet object

File: cbdataset.m
Location: ..\cubatch\@cbdatset
function DataSet = cbdataset(data,['propertyname',value1[,'propertyname',value2,[...]]])

or, alternatively
function DataSet = cbdataset(data,Content)
Inputs
data: n-way array of doubles
Content: Content object relative to data

Outputs
DataSet: cbdataset object

Properties and values

Property | Assignment | Reference
'name' | string of char. If it not inserted the name of the array containing the data is used. | string of chars
'type' | can either be 'data', 'batch' or 'image' (the latter is not implemented) | string of chars
'author' | either matrix of chars or cell of strings (the cell is vectorised) | cell vector of strings
'description' | either matrix of chars or cell of strings (the cell is vectorised | cell vector of strings
'labels' | cell vector. Its length equal to ndims(data). It can contain label objects, cell vectors of strings, char arrays, vectors of doubles or be empty (see the label object for more details). | cell vector of strings Its length equal to ndims(data).
'userdata' | empty box where everything can be saved. May be used for adding features to the object (such as multiple sets support in Cubatch). The display method gives only 'yes' or 'no' to indicates the presence of data in this field. | the class is identical to that of what is saved here.
'labobj' | Not available for the creator funtion cbdataset.m In assignment it must be a cell vector of label objects. Its length must be equal to ndims(data) | cell vector of label objects Its length equal to ndims(data).
'data' | it is not available for the creator function | the same rule of arrays of double apply
'modified' | read only property | date and time of the last modification of the CBDataSet
'dims' | read only property | dimensions of the CBDataSet. Method 'size' uses this function

Description
Creator function for the cbdataset object.
The cbdataset object is extensively used in CuBatch but can also be used separately from it.

This object requires the existence of two other objects in the path: label and content (which is the parent object).

The simplest syntax is the following (X being here a 20 x 30 x 20 array):

> » Data = cbdataset(X);

> > Name : X
> > Type : Data
> > Dimensions : [20 x 30 x 25]
> > Author :
> > Description :
> > Last modified : 30/01/2002, 22:00:10

The labels are generated automatically as 'Sam. #' for the first mode and 'Var. #' for the following. The different modes will also be named as 'Mode #'.
If one wants to use different labels it is possible to provide them at the moment of the creation of the cbdataset object:

> » Labels = {[1:2:40],[1:30],[]};
> » Data = cbdataset(X,'labels',Labels)

> > Name : X
> > Type : Data
> > Dimensions : [20 x 30 x 25]
> > Author :
> > Description :
> > Last modified : 30/01/2002, 22:20:55

The Labels must be a cell vector with as many elements as modes in the array otherwise an error
message will be generated. At the same time the length of each element of this cell array must be
0 (i.e. an empty array) or equal to the corresponding dimension otherwise an error message is
produced.

> » Labels = {[1:2:60],[1:30],[]};
> » Data = cbdataset(X,'labels',Labels)
> ??? Error using ==> d:\matlab\cubatch\@cbdataset\private\checklabels
> Inconsistent labels length for mode 1

When the cell element is empty the default values will be used.
The labels can be provided as a vector of doubles (generating 'Var. value' labels), as a char array holding one label per line, as a cell vector of chars with one label per cell-element or as a label object.
In the latter case the scalars, the mode names and the other feature of the label object will be saved in the cbdataset object without being automatically generated.
e.g. the cell Labs generated as

> » Labs{1}=label(1:30,'Sam.',[],'Samples','Samples');
> » Labs{2}=label([],'Var.',273.15:20:373.15,'T (K)','Temperature','K');
> » Labs{3}=label([],'Var.',100:150:700,'P (mB)','Pressure','mB');
> » Labs{4}=label([],'Var.',2:0.4:5,'pH','pH');

can be used as labels for an X array of dimensions 30 x 6 x 5 x 8.
The labels can be extracted using the subreference '.labels':

> » Data.labels

> > ans =
> > {20x1 cell} {30x1 cell} {25x1 cell}

The '.labels' property is a cell row vector where the nth element holds the labels for the nth mode as cell vectors of chars.
Complex subreference is also allowed, hence to access the labels for the 2nd mode one just has to type:

> » Lab = Data.labels{2};

All the properties (e.g. '.modenames','.axislabels','.measunits') available for the label object can also be directly accessed. For instance, the scalars are extracted by adding '.scalars' to the cbdataset object name:

> » Data.scalars

> > ans =
> > [20x1 double] [30x1 double] [25x1 double]

Unless further reference is provided this construction will yield a cell row vector with as many elements as the number of modes (dimension) of the data set.
The labels of an existing cbdataset object can be modified using an analogous syntax:

> » Data.labels{1} = label(1:3:60,'Sam.');
> » Data.labels{1}
> ans =
> 'Sam. 1'
> 'Sam. 4'
> ... (the actual list is displayed on MatLab® )
> 'Sam. 55'
> 'Sam. 58'

The properties that CBDataset objects inherit from the Content objects ( 'author','description', 'name', 'dims' and 'labobj'), as well as its own ('data','modified', 'userdata') can be modified and referred to using the same syntax used for the labels, i.e. the CBDataSet name followed by a dot and the property name: Data.author, Data.description etc
Data.dims and Data.modified can be used only to read the values and cannot be set.
A very important feature of the cbdataset object is that it can essentially be treated as a standard array
apart from a significant exception that will be explained below.
Hence, defined a cbdataset object Data of dimensions 20 x 30 x 25 as above, one can write:
» Data2 = Data(1:2:end,:,:)
yielding a data set with one every second horizontal slab:
Name : X
Type : Data
Dimensions : [10 x 30 x 25]
Author :
Description :
Last modified : 30/01/2002, 22:45:54
The labels, scalars and all the other features are preserved and modified accordingly with the
advantage of not requiring separate commands.
A significant difference is that if an incomplete reference is given, e.g. if an index is
given only for the first mode, it will be completed so that the whole slabs are included:
the previous line can then be simplified as:
» Data2 = Data(1:2:end);
This means that Data(:) does not vectorise the cbdataset as for normal arrays but simply yields
the whole data set.
This syntax can be used in combination with the previous ones referring labels.
F.i.
» Data(1:2:end).labels{1}
ans =
'Sam. 1'
'Sam. 3'
'Sam. 5'
'Sam. 7'
'Sam. 9'
'Sam. 11'
'Sam. 13'
'Sam. 15'
'Sam. 17'
'Sam. 19'
Author:
Giorgio Tomasi
Royal Agricultural and Veterinary University
MLI, LMT, Chemometrics group
Rolighedsvej 30
DK-1958 Frederiksberg C
Danmark
Last modified: 05 Oct. 2002
Contact: Giorgio Tomasi, gt@kvl.dk
References