Home > atmlab > randomize > randmvar.m

randmvar

PURPOSE ^

RANDMVAR Realisation of random multivariate data

SYNOPSIS ^

function X = randmvar(P,C,n)

DESCRIPTION ^

 RANDMVAR   Realisation of random multivariate data

    The function returns *n* vectors fulfilling the given statistical
    properties. The statistics are described by cumulative distribution 
    function (CDF) for each vector element and the correlation matrix. 
    The cumulative distribution function is the cumulative integral of 
    the probability density function.

    The statistics for each individual vector element will be fulfilled
    completely, while the correlation structure will be somewhat distorted.
    The correlation distortion depends on the deviation from normal 
    statistics.

    The cumulative distribution function is described by the cell array *P*, 
    where each element must/can have the fields listed below. The only 
    mandatory field is 'cdf'.

    cdf        : The distribution function as a 2 column matrix. Column 1 is 
                 the data abscissa. Column 2 is the distribution function. 
                 The distribution function must start with 0 and end with 1.
    interpmeth : Method for interpolating data in 'cdf'. See *interp1*
                 for options. Default is 'linear'.
    datalims   : Min and max allowed values for obtained data. The purpose of
                 this field is to make it possible to create PDF peaks at
                 the end points of the data range. See example below.

    To create 1e6 vectors of length 2 with uniformly distributed data:
       C = covmat1d_from_cfun(1:2,[], ... );
       P{1}.cdf = [0 0;1 1]; 
       P{2} = P{1};
       X = randmvar(P,C,1e6);

    To obtain PDF peaks at 0 and 1, each holding 10% of the data
       P{1}.cdf = [-0.01 0;0 0.1;1 0.9;1.01 1];
       P{1}.datalims = [0 1];

 FORMAT   X = randmvar( P, C, n )
        
 OUT   X    Random data [length(x) x n].
 IN    P    Description of CDF. Format given above.
       C    Correlation matrix. 
       n    Number of vector realisations to generate.

CROSS-REFERENCE INFORMATION ^

This function calls: This function is called by:

DOWNLOAD ^

randmvar.m

SOURCE CODE ^

0001 % RANDMVAR   Realisation of random multivariate data
0002 %
0003 %    The function returns *n* vectors fulfilling the given statistical
0004 %    properties. The statistics are described by cumulative distribution
0005 %    function (CDF) for each vector element and the correlation matrix.
0006 %    The cumulative distribution function is the cumulative integral of
0007 %    the probability density function.
0008 %
0009 %    The statistics for each individual vector element will be fulfilled
0010 %    completely, while the correlation structure will be somewhat distorted.
0011 %    The correlation distortion depends on the deviation from normal
0012 %    statistics.
0013 %
0014 %    The cumulative distribution function is described by the cell array *P*,
0015 %    where each element must/can have the fields listed below. The only
0016 %    mandatory field is 'cdf'.
0017 %
0018 %    cdf        : The distribution function as a 2 column matrix. Column 1 is
0019 %                 the data abscissa. Column 2 is the distribution function.
0020 %                 The distribution function must start with 0 and end with 1.
0021 %    interpmeth : Method for interpolating data in 'cdf'. See *interp1*
0022 %                 for options. Default is 'linear'.
0023 %    datalims   : Min and max allowed values for obtained data. The purpose of
0024 %                 this field is to make it possible to create PDF peaks at
0025 %                 the end points of the data range. See example below.
0026 %
0027 %    To create 1e6 vectors of length 2 with uniformly distributed data:
0028 %       C = covmat1d_from_cfun(1:2,[], ... );
0029 %       P{1}.cdf = [0 0;1 1];
0030 %       P{2} = P{1};
0031 %       X = randmvar(P,C,1e6);
0032 %
0033 %    To obtain PDF peaks at 0 and 1, each holding 10% of the data
0034 %       P{1}.cdf = [-0.01 0;0 0.1;1 0.9;1.01 1];
0035 %       P{1}.datalims = [0 1];
0036 %
0037 % FORMAT   X = randmvar( P, C, n )
0038 %
0039 % OUT   X    Random data [length(x) x n].
0040 % IN    P    Description of CDF. Format given above.
0041 %       C    Correlation matrix.
0042 %       n    Number of vector realisations to generate.
0043 
0044 % 2005-05-21   Created by Patrick Eriksson.
0045 
0046 
0047 function X = randmvar(P,C,n)
0048 
0049 
0050 %= Check input
0051 %
0052 rqre_nargin( 3, nargin );
0053 %
0054 if ~iscell(P)
0055   error('Input argument *P* must be a cell array.');
0056 end
0057 %
0058 if ndims(C) > 2  |  size(C,1) ~= size(C,1) 
0059   error('Input argument *C* must be a square matrix.');
0060 end
0061 %
0062 if length(P) ~= size(C,1) 
0063   error('Mismatch in size between *P* and *C*.');
0064 end
0065 %
0066 if ~isscalar(n)  |  ~iswhole(n)  |  n<1
0067   error('Input argument *n* must be a positive integer.');
0068 end
0069 %
0070 if nargin < 4
0071   interpmeth = 'linear';
0072 end
0073 
0074 
0075 lxm = length(P);
0076 
0077 
0078 %= Generate cases with normal distribution and unit std dev
0079 %
0080 X = randmvar_normal( zeros(lxm,1), 1, C, n );
0081 
0082 
0083 %= Transform to cumulative values
0084 %
0085 Xc = cdf_normal( X );
0086 
0087 
0088 %= Map to given distribution
0089 %
0090 for i = 1:lxm
0091   %
0092   if isvector( P{i}.cdf )
0093     %
0094     X(i,:) = P{i}.cdf(1,1) + X(i,:) * P{i}.cdf(1,2);
0095 
0096   else
0097     %
0098     if P{i}.cdf(1,2) ~= 0
0099       error( sprintf('CDF %d does not start with 0',i) );
0100     end
0101     if P{i}.cdf(end,2) ~= 1
0102       error( sprintf('CDF %d does not end with 1',i) );
0103     end
0104     %
0105     if isfield( P{i}, 'interpmeth' )
0106       imethod = P{i}.interpmeth
0107     else
0108       imethod = 'linear';
0109     end
0110     %
0111     X(i,:) = interp1( P{i}.cdf(:,2), P{i}.cdf(:,1), Xc(i,:), imethod );
0112     %
0113   end
0114 end
0115 
0116 
0117 %= Datalims
0118 %
0119 if isfield( P{i}, 'datalims' )
0120   X(i,find(X(i,:)<P{i}.datalims(1))) = P{i}.datalims(1);
0121   if length(P{i}.datalims) > 1
0122     X(i,find(X(i,:)>P{i}.datalims(2))) = P{i}.datalims(2);
0123   end
0124 end

Generated on Mon 15-Sep-2014 13:31:28 by m2html © 2005