Home > classes > @tsdata > tsdata.m

tsdata

PURPOSE ^

TSDATA time-series object class constructor.

SYNOPSIS ^

This is a script file.

DESCRIPTION ^

 TSDATA time-series object class constructor.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

 DESCRIPTION: TSDATA time-series object class constructor.
              Create a time-series data object. If the time-series object
              is determined to be evenly sampled, no x vector is stored.

 SUPER CLASSES: data2D < ltpda_data < ltpda_nuo < ltpda_obj

 PROPERTIES:

     Inherit Properties (read only)
       version - cvs-version string
       xunits  - units of the y-axis
       yunits  - units of the y-axis
       x       - data values of the x-axis
       y       - data values of the y-axis

     Properties (read only)
       fs      - sample rate of data
       nsecs   - the length of this time-series in seconds
       t0      - time-stamp of the first data sample in UTC format yyyy-mm-dd HH:MM:SS

 CONSTRUCTORS:

       ts = tsdata()        - creates a blank time-series object
       ts = tsdata(y)       - creates a time-series object with the given
                              y-data.
       ts = tsdata(x,y)     - creates a time-series object with the given
                              (x,y)-data. The sample rate is then set using
                              the private method fitfs(). This computes the
                              best sample rate that fits the data. If the
                              data is evenly sampled, the sample rate is set
                              as 1/median(diff(x)) and the x data is then
                              not stored (empty vector).
       ts = tsdata(y,fs)    - creates a time-series object with the given
                              y-data. The data is assumed to be evenly sampled
                              at the given sample rate with the first sample
                              assigned time 0. No x vector is created.
       ts = tsdata(y,t0)    - creates a time-series object with the given
                              y-data. The data are assumed to be evenly
                              sampled at 1Hz. The first sample is assumed to
                              be at 0s offset from t0 and t0 is set to the
                              user specified value.
       ts = tsdata(x,y,fs)  - creates a time-series object with the given
                              x/y data vectors. The sample rate is set to
                              fs.
       ts = tsdata(x,y,t0)  - creates a time-series object with the given
                              x/y data vectors. The t0 property is set to
                              the supplied t0 and the sample rate is
                              computed from the x vector using fitfs(). If
                              the data is found to be evenly sampled, the
                              x vector is discarded.
       ts = tsdata(y,fs,t0) - creates a time-series object with the given
                              y-data. The data are assumed to be evenly
                              sampled at fs and the first sample is
                              assumed to be taken at time t0. No x vector
                              is generated.
       ts = tsdata(x,y,fs,t0)-creates a time-series object with the given
                              x-data, y-data, fs and t0.

 TSDATA METHODS:

     Defined Abstract methods:
       char          - returns one character string which represents the object
       copy          - copies an object
       display       - displays an object
       update_struct - updates a object structure to the current tbx-version

     Public methods:
       setT0         - set the property 't0'
       setFs         - set the property 'fs'
       setNsecs      - set the property 'nsecs'
       getX          - overload the method in data2D
       growT         - grows the time (x) vector if it is empty
       fixNsecs      - fixes the numer of seconds
       collapseX     - checks whether the x vector is evenly sampled and
                       then remove it

     Static methods:
       fitfs         - computes the sample rate of the input data.


 M-FILE INFO:  The following call returns an minfo object that contains
               information about the tsdata constructor:
                    >> info = tsdata.getInfo
               or   >> info = tsdata.getInfo('tsdata')

               You can get information about class methods by calling:
                    >> info = tsdata.getInfo(method)
               e.g. >> info = tsdata.getInfo('eq')

               You can also restrict the sets of parameters contained in
               the minfo object by calling:
                    >> info = tsdata.getInfo(method, set)
               e.g. >> info = tsdata.getInfo('tsdata', 'Default')

 VERSION:  $Id: tsdata.m,v 1.56 2008/08/22 14:05:46 ingo Exp $

 HISTORY:  30-01-2007 Hewitson
              Creation

 SEE ALSO: tsdata, fsdata, xydata, cdata, data2D, data3D, xyzdata

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

CROSS-REFERENCE INFORMATION ^

This function calls: This function is called by:

SUBFUNCTIONS ^

SOURCE CODE ^

0001 % TSDATA time-series object class constructor.
0002 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0003 %
0004 % DESCRIPTION: TSDATA time-series object class constructor.
0005 %              Create a time-series data object. If the time-series object
0006 %              is determined to be evenly sampled, no x vector is stored.
0007 %
0008 % SUPER CLASSES: data2D < ltpda_data < ltpda_nuo < ltpda_obj
0009 %
0010 % PROPERTIES:
0011 %
0012 %     Inherit Properties (read only)
0013 %       version - cvs-version string
0014 %       xunits  - units of the y-axis
0015 %       yunits  - units of the y-axis
0016 %       x       - data values of the x-axis
0017 %       y       - data values of the y-axis
0018 %
0019 %     Properties (read only)
0020 %       fs      - sample rate of data
0021 %       nsecs   - the length of this time-series in seconds
0022 %       t0      - time-stamp of the first data sample in UTC format yyyy-mm-dd HH:MM:SS
0023 %
0024 % CONSTRUCTORS:
0025 %
0026 %       ts = tsdata()        - creates a blank time-series object
0027 %       ts = tsdata(y)       - creates a time-series object with the given
0028 %                              y-data.
0029 %       ts = tsdata(x,y)     - creates a time-series object with the given
0030 %                              (x,y)-data. The sample rate is then set using
0031 %                              the private method fitfs(). This computes the
0032 %                              best sample rate that fits the data. If the
0033 %                              data is evenly sampled, the sample rate is set
0034 %                              as 1/median(diff(x)) and the x data is then
0035 %                              not stored (empty vector).
0036 %       ts = tsdata(y,fs)    - creates a time-series object with the given
0037 %                              y-data. The data is assumed to be evenly sampled
0038 %                              at the given sample rate with the first sample
0039 %                              assigned time 0. No x vector is created.
0040 %       ts = tsdata(y,t0)    - creates a time-series object with the given
0041 %                              y-data. The data are assumed to be evenly
0042 %                              sampled at 1Hz. The first sample is assumed to
0043 %                              be at 0s offset from t0 and t0 is set to the
0044 %                              user specified value.
0045 %       ts = tsdata(x,y,fs)  - creates a time-series object with the given
0046 %                              x/y data vectors. The sample rate is set to
0047 %                              fs.
0048 %       ts = tsdata(x,y,t0)  - creates a time-series object with the given
0049 %                              x/y data vectors. The t0 property is set to
0050 %                              the supplied t0 and the sample rate is
0051 %                              computed from the x vector using fitfs(). If
0052 %                              the data is found to be evenly sampled, the
0053 %                              x vector is discarded.
0054 %       ts = tsdata(y,fs,t0) - creates a time-series object with the given
0055 %                              y-data. The data are assumed to be evenly
0056 %                              sampled at fs and the first sample is
0057 %                              assumed to be taken at time t0. No x vector
0058 %                              is generated.
0059 %       ts = tsdata(x,y,fs,t0)-creates a time-series object with the given
0060 %                              x-data, y-data, fs and t0.
0061 %
0062 % TSDATA METHODS:
0063 %
0064 %     Defined Abstract methods:
0065 %       char          - returns one character string which represents the object
0066 %       copy          - copies an object
0067 %       display       - displays an object
0068 %       update_struct - updates a object structure to the current tbx-version
0069 %
0070 %     Public methods:
0071 %       setT0         - set the property 't0'
0072 %       setFs         - set the property 'fs'
0073 %       setNsecs      - set the property 'nsecs'
0074 %       getX          - overload the method in data2D
0075 %       growT         - grows the time (x) vector if it is empty
0076 %       fixNsecs      - fixes the numer of seconds
0077 %       collapseX     - checks whether the x vector is evenly sampled and
0078 %                       then remove it
0079 %
0080 %     Static methods:
0081 %       fitfs         - computes the sample rate of the input data.
0082 %
0083 %
0084 % M-FILE INFO:  The following call returns an minfo object that contains
0085 %               information about the tsdata constructor:
0086 %                    >> info = tsdata.getInfo
0087 %               or   >> info = tsdata.getInfo('tsdata')
0088 %
0089 %               You can get information about class methods by calling:
0090 %                    >> info = tsdata.getInfo(method)
0091 %               e.g. >> info = tsdata.getInfo('eq')
0092 %
0093 %               You can also restrict the sets of parameters contained in
0094 %               the minfo object by calling:
0095 %                    >> info = tsdata.getInfo(method, set)
0096 %               e.g. >> info = tsdata.getInfo('tsdata', 'Default')
0097 %
0098 % VERSION:  $Id: tsdata.m,v 1.56 2008/08/22 14:05:46 ingo Exp $
0099 %
0100 % HISTORY:  30-01-2007 Hewitson
0101 %              Creation
0102 %
0103 % SEE ALSO: tsdata, fsdata, xydata, cdata, data2D, data3D, xyzdata
0104 %
0105 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0106 
0107 classdef tsdata < data2D
0108 
0109   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0110   %                            Property definition                            %
0111   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0112 
0113   %---------- Public (read/write) Properties  ----------
0114   properties
0115   end
0116 
0117   %---------- Protected read-only Properties ----------
0118   properties (SetAccess = protected)
0119     t0    = time(0);
0120     fs    = NaN;
0121     nsecs = 0;
0122   end
0123 
0124   %---------- Private Properties ----------
0125   properties (GetAccess = protected, SetAccess = protected)
0126   end
0127 
0128   %---------- Abstract Properties ----------
0129   properties (Abstract = true, SetAccess = protected)
0130   end
0131 
0132   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0133   %                          Check property setting                           %
0134   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0135 
0136   methods
0137     function obj = set.t0(obj, val)
0138       if (~isa(val, 'time') && ~ischar(val) && ~isnumeric(val))|| isempty(val)
0139         error('### The value for the property ''t0'' must be a string, a number or a time object');
0140       end
0141       if ischar(val) || isnumeric(val)
0142         obj.t0 = time(val);
0143       else
0144         obj.t0 = val;
0145       end
0146     end
0147     function obj = set.fs(obj, val)
0148       if ~isnumeric(val) || isempty(val) || ~isreal(val) || val < 0
0149         error('### The value for the property ''fs'' must be a real positive number');
0150       end
0151       obj.fs = val;
0152     end
0153     function obj = set.nsecs(obj, val)
0154       if ~isnumeric(val) || isempty(val) || ~isreal(val) || val < 0
0155         error('### The value for the property ''nsecs'' must be a real positive number');
0156       end
0157       obj.nsecs = val;
0158     end
0159   end
0160 
0161   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0162   %                                Constructor                                %
0163   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0164 
0165   methods
0166     function obj = tsdata(varargin)
0167 
0168       % Call data2D constructor since we add no special features here.
0169       obj = obj@data2D(varargin{:});
0170 
0171       %%% Exept for a struct as an input
0172       if ~(nargin == 1 && isstruct(varargin{1}))
0173         % set version
0174         obj.setVersion('$Id: tsdata.m,v 1.56 2008/08/22 14:05:46 ingo Exp $');
0175       end
0176 
0177       if nargin == 0
0178         %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0179         %%%%%%%%%%%%%%%%%%%%%%%%%%%%   no inputs   %%%%%%%%%%%%%%%%%%%%%%%%%%%%
0180         %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0181 
0182       elseif nargin == 1
0183         %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0184         %%%%%%%%%%%%%%%%%%%%%%%%%%%%   one input   %%%%%%%%%%%%%%%%%%%%%%%%%%%%
0185         %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0186 
0187         if isa(varargin{1}, 'tsdata')
0188           %%%%%%%%%%   data = tsdata(tsdata-object)   %%%%%%%%%%
0189           %----------- Copy tsdata Object   %%%%%%%%%%
0190           obj = copy(varargin{1}, 1);
0191 
0192         elseif isstruct(varargin{1})
0193           %%%%%%%%%%   data = tsdata(struct)   %%%%%%%%%%
0194           %----------- struct
0195 
0196           obj.t0      = utils.helper.struct2obj(varargin{1}.t0, 'time');
0197           obj.fs      = varargin{1}.fs;
0198           obj.nsecs   = varargin{1}.nsecs;
0199 
0200         elseif isnumeric(varargin{1})
0201           %%%%%%%%%%   data = tsdata(y-vector)   %%%%%%%%%%
0202           %----------- y vector
0203           obj.setY(varargin{1});
0204           obj.fs = 1;
0205 
0206         else
0207           error('### Unknown single argument constructor.');
0208         end
0209 
0210       elseif nargin == 2
0211         %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0212         %%%%%%%%%%%%%%%%%%%%%%%%%%%%   two input   %%%%%%%%%%%%%%%%%%%%%%%%%%%%
0213         %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0214 
0215         if numel(varargin{1}) > numel(varargin{2}) && numel(varargin{2}) == 1 && ~isa(varargin{2}, 'time')
0216           %%%%%%%%%%   data = tsdata(y-vector, fs)   %%%%%%%%%%
0217           % tsdata(y,fs)
0218           obj.y  = varargin{1};
0219           obj.fs = varargin{2};
0220 
0221         elseif numel(varargin{1}) == numel(varargin{2})
0222           %%%%%%%%%%   data = tsdata(x-vector, y-vector)   %%%%%%%%%%
0223           % tsdata(x,y)
0224           if numel(varargin{1}) > 1
0225             [fs,t0,fitted] = tsdata.fitfs(varargin{1});
0226             obj.fs = fs;
0227             if fitted
0228               obj.setXY(varargin{1}, varargin{2});
0229             else
0230               obj.setY(varargin{2});
0231             end
0232           else
0233             obj.setXY(varargin{1}, varargin{2});
0234             obj.fs = 1;
0235             t0     = 0;
0236           end
0237           obj.t0 = time(t0*1000);
0238 
0239         elseif isa(varargin{2}, 'time')
0240           %%%%%%%%%%   data = tsdata(y-vector, t0)   %%%%%%%%%%
0241           % tsdata(y,t0)
0242           obj.setY(varargin{1});
0243           obj.fs = 1;
0244           obj.t0 = varargin{2};
0245         else
0246           error('### Unknown two argument constructor.');
0247         end
0248       elseif nargin == 3
0249         %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0250         %%%%%%%%%%%%%%%%%%%%%%%%%%%   three input   %%%%%%%%%%%%%%%%%%%%%%%%%%%
0251         %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0252 
0253         if numel(varargin{1}) == numel(varargin{2}) && numel(varargin{3}) == 1 && ~isa(varargin{3}, 'time')
0254           %%%%%%%%%%   data = tsdata(x-vector, y-vector, fs)   %%%%%%%%%%
0255           % tsdata(x,y,fs)
0256           obj.setXY(varargin{1}, varargin{2});
0257           obj.fs = varargin{3};
0258 
0259         elseif numel(varargin{1}) == numel(varargin{2}) && isa(varargin{3}, 'time')
0260           %%%%%%%%%%   data = tsdata(x-vector, y-vector, t0)   %%%%%%%%%%
0261           % tsdata(x,y,t0)
0262           [fs,t0,fitted] = tsdata.fitfs(varargin{1});
0263           obj.fs = fs;
0264           obj.t0 = varargin{3}+t0;
0265           if fitted
0266             obj.setXY(varargin{1}, varargin{2});
0267           else
0268             obj.setY(varargin{2});
0269           end
0270 
0271         elseif numel(varargin{1}) > numel(varargin{2}) && isa(varargin{3}, 'time')
0272           %%%%%%%%%%   data = tsdata(y-vector, fs, t0)   %%%%%%%%%%
0273           % tsdata(y,fs,t0)
0274           obj.setY(varargin{1});
0275           obj.fs = varargin{2};
0276           obj.t0 = varargin{3};
0277         else
0278           error('### Unknown three argument constructor.');
0279         end
0280       elseif nargin == 4
0281         %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0282         %%%%%%%%%%%%%%%%%%%%%%%%%%%   four input   %%%%%%%%%%%%%%%%%%%%%%%%%%%%
0283         %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0284 
0285         if numel(varargin{1}) == numel(varargin{2}) && numel(varargin{3}) == 1 && isa(varargin{4}, 'time')
0286           %%%%%%%%%%   data = tsdata(x-vector, y-vector, fs, t0)   %%%%%%%%%%
0287           [fs,t0,fitted] = tsdata.fitfs(varargin{1});
0288           if ~fitted
0289             obj.setY(varargin{2});
0290           end
0291           obj.fs = fs;
0292           obj.t0 = varargin{4}+t0;
0293         else
0294           error('### Unknown four argument constructor.');
0295         end
0296       else
0297         error('### Unknown number of constructor arguments.');
0298       end
0299 
0300       % Now we can set nsecs
0301       if ~isempty(obj.x)
0302         % Then we have unevenly sampled data and the data duration
0303         % is taken as x(end) - x(1);
0304         obj.setNsecs(obj.x(end)-obj.x(1) + 1/obj.fs);
0305       else
0306         if ~isempty(obj.y)
0307           % Then the data is evenly sampled and the
0308           % duration of the data is easily computed.
0309           Ndata = length(obj.y);
0310           nsecs = Ndata / obj.fs;
0311           obj.setNsecs(nsecs);
0312         end
0313       end
0314 
0315     end % End constructor
0316   end % End public methods
0317 
0318   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0319   %                              Methods  (Public)                            %
0320   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0321 
0322   methods
0323     % Setters
0324     varargout = setT0(varargin)
0325     varargout = setFs(varargin)
0326     varargout = setNsecs(varargin)
0327 
0328     % Getters
0329     varargout = getX(varargin)
0330 
0331     varargout = growT(varargin)
0332     varargout = fixNsecs(varargin)
0333     varargout = collapseX(varargin)
0334 
0335     % Other public methods
0336     varargout = display(varargin);
0337     varargout = copy(varargin)
0338     % varargout = string(varargin);
0339   end
0340 
0341   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0342   %                              Methods (protected)                          %
0343   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0344 
0345   methods (Access = protected)
0346   end
0347 
0348   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0349   %                               Methods (private)                           %
0350   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0351 
0352   methods (Access = private)
0353   end
0354   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0355   %                            Methods (static)                               %
0356   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0357   methods (Static)
0358     varargout = fitfs(varargin)
0359     varargout = update_struct(varargin);
0360 
0361     function out = VEROUT()
0362       out = '$Id: tsdata.m,v 1.56 2008/08/22 14:05:46 ingo Exp $';
0363     end
0364 
0365     function ii = getInfo(varargin)
0366       ii = utils.helper.generic_getInfo(varargin{:}, 'tsdata');
0367     end
0368 
0369     function out = SETS()
0370       out = {'Default'};
0371     end
0372 
0373     function out = getDefaultPlist(set)
0374       switch set
0375         case 'Default'
0376           out = plist();
0377         otherwise
0378           error('### Unknown set [%s]', set');
0379       end
0380     end
0381 
0382   end % End static methods
0383 
0384   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0385   %                         Methods (static, private)                         %
0386   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0387 
0388   methods (Static, Access=private)
0389   end % End static, private methods
0390 
0391 end % End classdef
0392

Generated on Mon 25-Aug-2008 22:39:29 by m2html © 2003