@Dataseries

From COSSAN Wiki
Jump to: navigation, search
Outdated.png This article's factual accuracy may be compromised because of out-of-date information. Please help improve the article by updating it.
The dataseries object has been rewritten and the documentation need to be updated as well

Description

The class Dataseries allows to define an object containing vector/matrix quantities. A Dataseries object is defined by a matrix of coordinate (property Mcoord) and a vector of data (property Vdata), such that there is a one to one correspondence between a value of the data vector and a coordinate. It also possible to create vectors or matrices of Dataseries objects. In this case, entries belonging to the same column must have the same coordinate matrix, and they are interpreted as samples of a same quantity.

Dataseries object are constructed automatically by the method Sample@StochasticProcess and the method Sample@Input to store samples of a stochastic process. They are also used to save the history of the values of Design Variables, Objective Functions and Constraints during an optimization into the optimization output. Finally, they are used to store values of vector or matrix output from a Mio or Connector.

The object can be constructed manually providing a vector/matrix with the coordinates (e.g. time, step number, indices, etc.) and the corresponding realizations. A vector or matrix of Dataseries can be constructed either by setting manually each entry of the matrix, using the methods addSamples, using horizontal or vertical concatenation, or by passing the cell array properties CVdata and CMcoord to the constructor (see paragraph "technical details").

Technical Details

In order to understand better the functionalities of the Dataseries object, some additional technical details are given. A Dataseries matrix is not a real matrix of objects, but is actually a single object accessed via the parenthesis - () - notation. The coordinates and data vectors are not saved into real properties, but are actually stored in the cell arrays CMcoord and CVdata. CVdata has dimension [Nrows×Ncols], where Nrows and Ncols are the number of rows and columns of the Dataseries matrix, while CMcoord has a dimension equal to [1×Ncols], so that the identical coordinates are not repeated for every sample.

As an example, accessing Xds(3,2).Vdata will return Xds.CVdata{3,2}, and Xds(3,2).MCoord will return Xds.CMcoord{1,2}.

Input Arguments

Name

Type
Required
Default value
Description
Sdescription
String
no
description of the object
Mcoord matrix no Matrices with the coordinates/time instances to which the data points in Vdata are associated. The number of rows is equal to the dimension of the coordinate, the number of columns corresponds to the number of points. Automatically populated when left empty.
Vdata horizontal array yes - Array containing the data corresponding to the matrix Mcoord. The length of Vdata must be equal to the number of columns of Mcoord
Mdata matrix no - This input can be used only if Mcoord and Vdata are not specified. It is used to fast create a Dataseries that stores a matrix quantity. As an example, passing Mdata of [1 2 3;4 5 6] will create a Dataseries with Vdata and Mcoord equal to [1 2 3 4 5 6] and [1 2 3 1 2 3;1 1 1 2 2 2] respectively.
SindexName string no - Name of the indeces. Multiple names must be separated with a comma. Must have as many index names as the number of rows of Mcoord.
SindexUnit cell array of string no - Unit of the indeces. Multiple units must be separated with a comma. Must have as many units as the number of rows of Mcoord.


To directly construct a [Nrows×Ncols] Dataseries matrix:


Name

Type
Required
Default value
Description
Sdescription
String
no
description of the object
CMcoord cell array of matrix no [1×Ncols] cell array, containing the matrices with the coordinates/time instances of each column of the Dataseries matrix.
CVdata cell array of horizontal array yes - [Nrows×Ncols] cell array. The data contained in each element must be an horizontal array, and the length of the data of each column must be equal to the number of columns of the corresponding entry in CMcoord.
CSindexName cell array of cell array of string no - [1×Ncols] cell array, containing the names of the indeces
CSindexUnit cell array of cell array of string no - [1×Ncols] cell array, containing the unit of the indeces


Output Arguments

The constructor returns an object of type @Dataseries.

Methods

The following methods are available for the object Dataseries:

  • addData - method for adding data to the dataseries (i.e. more data points and corresponding indices)
  • addSamples - method for adding samples to the dataseries (i.e. Mcoord or Vindex, respectively, remains unchanged, additional rows are added to Mdata)
  • chopData - method for removing data to the dataseries (i.e. data points and corresponding indices are removed)
  • chopSamples - method for removing samples from the dataseries (i.e. Mcoord or Vindex, respectively, remains unchanged, the specified rows are removed from Mdata)


Warning.png Calling Dataseries methods
Because of the overloaded subsref function, it is NOT possible to access the methods via dot notation. The methods can be called only through function notation.
Example: use addData(Xobj,...) instead of Xobj.addData(...)


Overloaded MATLAB functions:

  • cat - method for concatenating arrays of Dataseries
  • horzcat - horizontal concatenation of arrays of Dataseries
  • vertcat - vertical concatenation of arrays of Dataseries
  • numel - returns the number of elements of a Dataseries matrix
  • size - returns the size of a Dataseries matrix
  • isempty - determine whether a Dataseries matrix is empty
  • plot - plot data from a Dataseries object
  • subsasgn - subscripted reference for Dataseries object
  • subsref - subscripted assignment for Dataseries object
  • display

Usage

Xds  = Dataseries('Mcoord',1:10,'Mdata',randn(2,10));

Tutorial

echodemo TutorialDataseries


See Also