Making a time-series AO


Exercise 4

Time-series data are stored in a data object of the class tsdata. As a user, you don't need to care about this, but it's sometimes nice to know how things work. There are various ways (constructors) to build time-series AOs. For example, you can give a set of values and a sample rate like

  a = ao([1 2 3 4 5], 2)

The first argument is the Y data vector; the second, the sample rate.

If you run this command in the MATLAB terminal you should see

>> a = ao([1 2 3 4 5], 2)
M:     constructing from Y values and fs
----------- ao 01: a -----------

       name: ''
       data: (0,1) (0.5,2) (1,3) (1.5,4) (2,5)
             -------- tsdata 01 ------------

                 fs:  2
                  x:  [1 5], double
                  y:  [1 5], double
                 dx:  [0 0], double
                 dy:  [0 0], double
             xunits:  [s]
             yunits:  []
              nsecs:  2.5
                 t0:  1970-01-01 00:00:00.000
             -------------------------------

       hist: ao / ao / SId: fromXYVals.m,v 1.10 2011/05/07 05:15:26 mauro Exp S-->SId: ao.m,v 1.346 2011/05/07 06:56:17 mauro Exp S
description:
       UUID: 2484d029-4616-4b22-8229-7685c8d3e847
--------------------------------

Now you see that the data type is tsdata and the X units are automatically set to seconds ('s'). You can also see that the data series spans 2.5s and that the first sample corresponds to 1970-01-01 00:00:00.000 UTC. You can set further properties of the object, for example

a.setT0('2009-02-03 12:23:44');
a.setDescription('My lovely time-series')


You can do all of this in one block on the workbench. To do that:

  1. Start the workbench and create a new pipeline
  2. Drag an AO constructor block from the library (or use "Quick Block")
  3. Select the block and select the "From XY Values" parameter set
  4. Click the "Set" button to set the parameters to the block
  5. Double-click the value cell for the key "YVALS" and enter some values, e.g., 1:10
  6. Double-click the value cell for the key "FS" and enter a sample frequency, e.g., 2. By setting a set of values for the Y-data and a sample rate, we tell the AO constructor that we want to build a tsdata AO.
  7. To set the name of the block, double click the block and enter a name in the dialog box. Automatic setting of AO names from the block name only happens for constructor blocks. To the set the name of AOs which are outputs of all other block types, use the setName block.
  8. You'll notice that the parameter list doesn't contain a T0 parameter by default, but you can easily add this parameter by clicking on the "plus" button below the parameter list. Enter the key T0 in the dialog box, and an appropriate value in the next dialog box. (Note: parameter key names are case insensitive.)
  9. You can do the same for the description, or any other property of the AO.

The final parameter list in this case might look like:

Time-series parameter set

Digression: Introducing parameter lists


The time has come to go back to that plist command we saw earlier when plotting the AO history via the graphviz renderer.

The following two commands are equivalent:

a = ao([1 2 3 4 5], 2);
a = ao(plist('yvals', [1 2 3 4 5], 'fs', 2))

Here we introduce the idea of parameter lists (plist). A plist is a list of parameters, each parameter being defined by a key/value pair. The key of a plist is always a string and is always case insensitive. The value can be anything: a number, a string, another LTPDA object, a cell-array, a structure, etc. For more information about parameter lists, see the appropriate section of the LTPDA user manual.

Going on with time-series objects: The following is almost equivalent:

  a = ao(plist('xvals', [0 0.5 1 1.5 2], 'yvals', [1 2 3 4 5]))

The difference is, if you run this command, you will see that the resulting AO has data of type xydata. To make this a time-series object, we need to tell the constructor some more information. Either you need to specify the sample-rate, or you can explicitly set the data type:

  a = ao(plist('xvals', [0 0.5 1 1.5 2], 'yvals', [1 2 3 4 5], 'fs', 2))
  a = ao(plist('xvals', [0 0.5 1 1.5 2], 'yvals', [1 2 3 4 5], 'type',...
        'tsdata'))

The ellipsis (...) in MATLAB means join the two lines.

If you specify the samples rate with the key 'fs', then the 'xvals' are just ignored. If you tell the data type with the key 'type', then the sample rate is computed from the 'xvals'.

You can add additional parameters to these constructor lines. For example,

a = ao(plist('xvals', [0 0.5 1 1.5 2], 'yvals', [1 2 3 4 5], ...
                  'type', 'tsdata', ...
                  'name', 'Bob', ...
                  't0', '2008-09-01'))

There are other constructors which make constructing time-series AOs from simulated data more convenient. Two of these are discussed below.


Times-series AO as a function of t


If you want to specify your time-series as a function of the variable t, then you can use the following constructor:

  a = ao(plist('tsfcn', 't.^2 + t', ...
  'fs', 10, 'nsecs', 1000))

You specify the function of t with the key 'tsfcn', then give the sample rate and the number of seconds. If you run this command you should see the output:

>> a = ao(plist('tsfcn', 't.^2 + t', 'fs', 10, 'nsecs', 1000))
M:     constructing from plist
----------- ao 01: a -----------

       name: ''
       data: (0,0) (0.1,0.11) (0.2,0.24) (0.3,0.39) (0.4,0.56) ...
             -------- tsdata 01 ------------

                 fs:  10
                  x:  [10000 1], double
                  y:  [10000 1], double
                 dx:  [0 0], double
                 dy:  [0 0], double
             xunits:  [s]
             yunits:  []
              nsecs:  1000
                 t0:  1970-01-01 00:00:00.000
             -------------------------------

       hist: ao / ao / SId: fromTSfcn.m,v 1.22 2010/07/28 16:31:01 ingo Exp S-->SId: ao.m,v 1.346 2011/05/07 06:56:17 mauro Exp S
description:
       UUID: d01615d6-82ad-4736-8a0e-4096dc023149
--------------------------------

You can write any valid MATLAB expression as a function of t.

Plists can be reused, of course. Suppose we define a recipe for an AO as

  pl = plist('tsfcn', 'randn(size(t))', 'fs', 10, 'nsecs', 1000)

then we can make repeated AOs from this recipe:

a1 = ao(pl)
a2 = ao(pl)
% Or use the random factory:
% a = ao.randn(nsecs, fs)
a3 = ao.randn(1000, 10)

Here we have made three AOs with different random white-noise data vectors.


Digression: plotting the data


To plot the data in the AO, you can use the intelligent plotting method, iplot. For example, type in the MATLAB terminal:

  a1.iplot

and you should see a plot like the one below.

iplot example 1

We can make a more interesting plot if we first specify some of the properties of the AOs. For example, type the following commands to set the names and Y units of the two AOs we made earlier:

a1.setName
a2.setName
setYunits(a1,a2,'N')

Now plot both time-series together with:

iplot(a1,a2)

and you shoud see a plot like the following:

iplot example 2

Calling the setName method with no input argument causes the AO to be named with the variable name.

iplot has many configurable parameters which are (mostly) documented in the help.


Times-series AO from built in waveforms


MATLAB has various functions for creating standard waveforms, for example, sine waves, square waves, and saw-tooth signals. These are available as convenient AO constructors. For example suppose we want to create a square-wave pulse train with a 30% duty cycle at 2Hz sampled at 100Hz lasting for 5s, then we can do

sw = ao(plist('waveform', 'square wave', 'f', 2, 'duty', 30, ...
    'fs', 100, 'nsecs', 5))

If you run that command and plot the result, you should see the square wave you were expecting:

iplot squarewave

You can construct various different waveforms, but each has different parameters to set. The help of the AO method details the possibilities (help ao -> click on "Parameters Description" -> select "From Window"); here is the relevant extract:

    'waveform' - a waveform description (see options below).

                 You can also specify additional parameters:
                 'fs'      - sampling frequency [default: 10 Hz]
                 'nsecs'   - length in seconds [default: 10 s]
                 't0'      - time-stamp of the first data sample [default time(0)]

                 and, for the following waveform types:
                 'sine wave'      - 'A', 'f', 'phi', 'nsecs', 'toff'
                                    (can be vectors for sum of sine waves)
                        'A'       - Amplitude of the wave
                        'f'       - Frequency of the wave
                        'phi'     - Phase of the eave
                        'nsecs'   - Number of seconds  (in seconds)
                        'toff'    - Offset of the wave (in seconds)
                        'gaps'    - Instead of defining an offset it is possible to
                                    define a gap (in seconds) before the sine wave.
                 'noise'          - 'type' (can be 'Normal' or 'Uniform')
                                    'sigma' specify the standard deviation
                 'chirp'          - 'f0', 'f1', 't1'      (help chirp)
                 'gaussian pulse' - 'f0', 'bw'            (help gauspuls)
                 'square wave'    - 'f', 'duty'           (help square)
                 'sawtooth'       - 'f', 'width'          (help sawtooth)

                 You can also specify the initial time (t0) associated with
                 the time-series by passing a parameter 't0' with a value
                 that is a time object.



©LTP Team