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.57 2008/09/03 16:39:37 hewitson 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.57 2008/09/03 16:39:37 hewitson 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     version = '$Id: tsdata.m,v 1.57 2008/09/03 16:39:37 hewitson Exp $';
0123   end
0124 
0125   %---------- Private Properties ----------
0126   properties (GetAccess = protected, SetAccess = protected)
0127   end
0128 
0129   %---------- Abstract Properties ----------
0130   properties (Abstract = true, SetAccess = protected)
0131   end
0132 
0133   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0134   %                          Check property setting                           %
0135   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0136 
0137   methods
0138     function obj = set.t0(obj, val)
0139       if (~isa(val, 'time') && ~ischar(val) && ~isnumeric(val))|| isempty(val)
0140         error('### The value for the property ''t0'' must be a string, a number or a time object');
0141       end
0142       if ischar(val) || isnumeric(val)
0143         obj.t0 = time(val);
0144       else
0145         obj.t0 = val;
0146       end
0147     end
0148     function obj = set.fs(obj, val)
0149       if ~isnumeric(val) || isempty(val) || ~isreal(val) || val < 0
0150         error('### The value for the property ''fs'' must be a real positive number');
0151       end
0152       obj.fs = val;
0153     end
0154     function obj = set.nsecs(obj, val)
0155       if ~isnumeric(val) || isempty(val) || ~isreal(val) || val < 0
0156         error('### The value for the property ''nsecs'' must be a real positive number');
0157       end
0158       obj.nsecs = val;
0159     end
0160   end
0161 
0162   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0163   %                                Constructor                                %
0164   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0165 
0166   methods
0167     function obj = tsdata(varargin)
0168 
0169       % Call data2D constructor since we add no special features here.
0170       obj = obj@data2D(varargin{:});
0171 
0172       if nargin == 0
0173         %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0174         %%%%%%%%%%%%%%%%%%%%%%%%%%%%   no inputs   %%%%%%%%%%%%%%%%%%%%%%%%%%%%
0175         %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0176 
0177       elseif nargin == 1
0178         %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0179         %%%%%%%%%%%%%%%%%%%%%%%%%%%%   one input   %%%%%%%%%%%%%%%%%%%%%%%%%%%%
0180         %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0181 
0182         if isa(varargin{1}, 'tsdata')
0183           %%%%%%%%%%   data = tsdata(tsdata-object)   %%%%%%%%%%
0184           %----------- Copy tsdata Object   %%%%%%%%%%
0185           obj = copy(varargin{1}, 1);
0186 
0187         elseif isstruct(varargin{1})
0188           %%%%%%%%%%   data = tsdata(struct)   %%%%%%%%%%
0189           %----------- struct
0190 
0191           obj.t0      = utils.helper.struct2obj(varargin{1}.t0, 'time');
0192           obj.fs      = varargin{1}.fs;
0193           obj.nsecs   = varargin{1}.nsecs;
0194           obj.version = varargin{1}.version;
0195 
0196         elseif isnumeric(varargin{1})
0197           %%%%%%%%%%   data = tsdata(y-vector)   %%%%%%%%%%
0198           %----------- y vector
0199           obj.setY(varargin{1});
0200           obj.fs = 1;
0201 
0202         else
0203           error('### Unknown single argument constructor.');
0204         end
0205 
0206       elseif nargin == 2
0207         %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0208         %%%%%%%%%%%%%%%%%%%%%%%%%%%%   two input   %%%%%%%%%%%%%%%%%%%%%%%%%%%%
0209         %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0210 
0211         if numel(varargin{1}) > numel(varargin{2}) && numel(varargin{2}) == 1 && ~isa(varargin{2}, 'time')
0212           %%%%%%%%%%   data = tsdata(y-vector, fs)   %%%%%%%%%%
0213           % tsdata(y,fs)
0214           obj.y  = varargin{1};
0215           obj.fs = varargin{2};
0216 
0217         elseif numel(varargin{1}) == numel(varargin{2})
0218           %%%%%%%%%%   data = tsdata(x-vector, y-vector)   %%%%%%%%%%
0219           % tsdata(x,y)
0220           if numel(varargin{1}) > 1
0221             [fs,t0,fitted] = tsdata.fitfs(varargin{1});
0222             obj.fs = fs;
0223             if fitted
0224               obj.setXY(varargin{1}, varargin{2});
0225             else
0226               obj.setY(varargin{2});
0227             end
0228           else
0229             obj.setXY(varargin{1}, varargin{2});
0230             obj.fs = 1;
0231             t0     = 0;
0232           end
0233           obj.t0 = time(t0*1000);
0234 
0235         elseif isa(varargin{2}, 'time')
0236           %%%%%%%%%%   data = tsdata(y-vector, t0)   %%%%%%%%%%
0237           % tsdata(y,t0)
0238           obj.setY(varargin{1});
0239           obj.fs = 1;
0240           obj.t0 = varargin{2};
0241         else
0242           error('### Unknown two argument constructor.');
0243         end
0244       elseif nargin == 3
0245         %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0246         %%%%%%%%%%%%%%%%%%%%%%%%%%%   three input   %%%%%%%%%%%%%%%%%%%%%%%%%%%
0247         %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0248 
0249         if numel(varargin{1}) == numel(varargin{2}) && numel(varargin{3}) == 1 && ~isa(varargin{3}, 'time')
0250           %%%%%%%%%%   data = tsdata(x-vector, y-vector, fs)   %%%%%%%%%%
0251           % tsdata(x,y,fs)
0252           obj.setXY(varargin{1}, varargin{2});
0253           obj.fs = varargin{3};
0254 
0255         elseif numel(varargin{1}) == numel(varargin{2}) && isa(varargin{3}, 'time')
0256           %%%%%%%%%%   data = tsdata(x-vector, y-vector, t0)   %%%%%%%%%%
0257           % tsdata(x,y,t0)
0258           [fs,t0,fitted] = tsdata.fitfs(varargin{1});
0259           obj.fs = fs;
0260           obj.t0 = varargin{3}+t0;
0261           if fitted
0262             obj.setXY(varargin{1}, varargin{2});
0263           else
0264             obj.setY(varargin{2});
0265           end
0266 
0267         elseif numel(varargin{1}) > numel(varargin{2}) && isa(varargin{3}, 'time')
0268           %%%%%%%%%%   data = tsdata(y-vector, fs, t0)   %%%%%%%%%%
0269           % tsdata(y,fs,t0)
0270           obj.setY(varargin{1});
0271           obj.fs = varargin{2};
0272           obj.t0 = varargin{3};
0273         else
0274           error('### Unknown three argument constructor.');
0275         end
0276       elseif nargin == 4
0277         %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0278         %%%%%%%%%%%%%%%%%%%%%%%%%%%   four input   %%%%%%%%%%%%%%%%%%%%%%%%%%%%
0279         %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0280 
0281         if numel(varargin{1}) == numel(varargin{2}) && numel(varargin{3}) == 1 && isa(varargin{4}, 'time')
0282           %%%%%%%%%%   data = tsdata(x-vector, y-vector, fs, t0)   %%%%%%%%%%
0283           [fs,t0,fitted] = tsdata.fitfs(varargin{1});
0284           if ~fitted
0285             obj.setY(varargin{2});
0286           end
0287           obj.fs = fs;
0288           obj.t0 = varargin{4}+t0;
0289         else
0290           error('### Unknown four argument constructor.');
0291         end
0292       else
0293         error('### Unknown number of constructor arguments.');
0294       end
0295 
0296       % Now we can set nsecs
0297       if ~isempty(obj.x)
0298         % Then we have unevenly sampled data and the data duration
0299         % is taken as x(end) - x(1);
0300         obj.setNsecs(obj.x(end)-obj.x(1) + 1/obj.fs);
0301       else
0302         if ~isempty(obj.y)
0303           % Then the data is evenly sampled and the
0304           % duration of the data is easily computed.
0305           Ndata = length(obj.y);
0306           nsecs = Ndata / obj.fs;
0307           obj.setNsecs(nsecs);
0308         end
0309       end
0310 
0311     end % End constructor
0312   end % End public methods
0313 
0314   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0315   %                              Methods  (Public)                            %
0316   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0317 
0318   methods
0319     % Setters
0320     varargout = setT0(varargin)
0321     varargout = setFs(varargin)
0322     varargout = setNsecs(varargin)
0323 
0324     % Getters
0325     varargout = getX(varargin)
0326 
0327     varargout = growT(varargin)
0328     varargout = fixNsecs(varargin)
0329     varargout = collapseX(varargin)
0330 
0331     % Other public methods
0332     varargout = display(varargin);
0333     varargout = copy(varargin)
0334     % varargout = string(varargin);
0335   end
0336 
0337   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0338   %                              Methods (protected)                          %
0339   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0340 
0341   methods (Access = protected)
0342   end
0343 
0344   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0345   %                               Methods (private)                           %
0346   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0347 
0348   methods (Access = private)
0349   end
0350   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0351   %                            Methods (static)                               %
0352   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0353   methods (Static)
0354     varargout = fitfs(varargin)
0355     varargout = update_struct(varargin);
0356 
0357     function out = VEROUT()
0358       out = '$Id: tsdata.m,v 1.57 2008/09/03 16:39:37 hewitson Exp $';
0359     end
0360 
0361     function ii = getInfo(varargin)
0362       ii = utils.helper.generic_getInfo(varargin{:}, 'tsdata');
0363     end
0364 
0365     function out = SETS()
0366       out = {'Default'};
0367     end
0368 
0369     function out = getDefaultPlist(set)
0370       switch set
0371         case 'Default'
0372           out = plist();
0373         otherwise
0374           error('### Unknown set [%s]', set');
0375       end
0376     end
0377 
0378   end % End static methods
0379 
0380   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0381   %                         Methods (static, private)                         %
0382   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0383 
0384   methods (Static, Access=private)
0385   end % End static, private methods
0386 
0387 end % End classdef
0388

Generated on Mon 08-Sep-2008 13:18:47 by m2html © 2003