octave_packages/nan-2.5.5/std.m

   1 function [o,v]=std(x,opt,DIM,W)
   2 % STD calculates the standard deviation.
   3 %
   4 % [y,v] = std(x [, opt[, DIM [, W]]])
   5 %
   6 % opt   option
   7 %       0:  normalizes with N-1 [default]
   8 %               provides the square root of best unbiased estimator of the variance
   9 %       1:  normalizes with N,
  10 %               this provides the square root of the second moment around the mean
  11 %       otherwise:
  12 %               best unbiased estimator of the standard deviation (see [1])
  13 %
  14 % DIM   dimension
  15 %       N STD of  N-th dimension
  16 %       default or []: first DIMENSION, with more than 1 element
  17 % W     weights to compute weighted s.d. (default: [])
  18 %       if W=[], all weights are 1.
  19 %       number of elements in W must match size(x,DIM)
  20 %
  21 % y     estimated standard deviation
  22 %
  23 % features:
  24 % - provides an unbiased estimation of the S.D.
  25 % - can deal with NaN's (missing values)
  26 % - weighting of data
  27 % - dimension argument also in Octave
  28 % - compatible to Matlab and Octave
  29 %
  30 % see also: RMS, SUMSKIPNAN, MEAN, VAR, MEANSQ,
  31 %
  32 %
  33 % References(s):
  34 % [1] http://mathworld.wolfram.com/StandardDeviationDistribution.html
  35
  36
  37 %    This program is free software; you can redistribute it and/or modify
  38 %    it under the terms of the GNU General Public License as published by
  39 %    the Free Software Foundation; either version 3 of the License, or
  40 %    (at your option) any later version.
  41 %
  42 %    This program is distributed in the hope that it will be useful,
  43 %    but WITHOUT ANY WARRANTY; without even the implied warranty of
  44 %    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  45 %    GNU General Public License for more details.
  46 %
  47 %    You should have received a copy of the GNU General Public License
  48 %    along with this program; If not, see <http://www.gnu.org/licenses/>.
  49
  50 %       $Id: std.m 8223 2011-04-20 09:16:06Z schloegl $
  51 %       Copyright (C) 2000-2003,2006,2009,2010 by Alois Schloegl <alois.schloegl@gmail.com>
  52 %       This is part of the NaN-toolbox for Octave and Matlab
  53 %       http://pub.ist.ac.at/~schloegl/matlab/NaN/
  54
  55 if nargin<4,
  56         W = [];
  57 end;
  58 if nargin<3,
  59         DIM = [];
  60 end;
  61 if isempty(DIM),
  62         DIM = find(size(x)>1,1);
  63         if isempty(DIM), DIM=1; end;
  64 end;
  65
  66
  67 [y,n,ssq] = sumskipnan(x,DIM,W);
  68 if all(ssq(:).*n(:) > 2*(y(:).^2))
  69         %% rounding error is neglectable
  70         y = ssq - y.*y./n;
  71 else
  72         %% rounding error is not neglectable
  73         szx = size(x);
  74         szy = size(y);
  75         if length(szy)<length(szx);
  76                 szy(length(szy)+1:length(szx)) = 1;
  77         end;
  78         [y,n] = sumskipnan((x-repmat(y./n,szx./szy)).^2,DIM,W);
  79 end;
  80
  81
  82 if nargin<2,
  83         opt = 0;
  84 end;
  85 if isempty(opt),
  86         opt = 0;
  87 end;
  88
  89
  90 if opt==0,
  91         % square root if the best unbiased estimator of the variance
  92         ib = inf;
  93         o  = sqrt(y./max(n-1,0));       % normalize
  94
  95 elseif opt==1,
  96         ib = NaN;
  97         o  = sqrt(y./n);
  98
  99 else
 100         % best unbiased estimator of the mean
 101         if exist('unique','file'),
 102                 % usually only a few n's differ
 103                 [N,tmp,tix] = unique(n(:));     % compress n and calculate ib(n)
 104                 ib = sqrt(N/2).*gamma((N-1)./2)./gamma(N./2);   %inverse b(n) [1]
 105                 ib = ib(reshape(tix,size(y)));  % expand ib to correct size
 106
 107         elseif exist('histo3','file'),
 108                 % usually only a few n's differ
 109                 [N,tix] = histo3(n(:)); N = N.X;
 110                 ib = sqrt(N/2).*gamma((N-1)./2)./gamma(N./2);   %inverse b(n) [1]
 111                 ib = ib(reshape(tix,size(y)));  % expand ib to correct size
 112
 113         else    % gamma is called prod(size(n)) times
 114                 ib = sqrt(n/2).*gamma((n-1)./2)./gamma(n./2);   %inverse b(n) [1]
 115         end;
 116         ib = reshape(ib,size(y));
 117         o  = sqrt(y./n).*ib;
 118 end;
 119
 120 if nargout>1,
 121         v = y.*((max(n-1,0)./(n.*n))-1./(n.*ib.*ib)); % variance of the estimated S.D. ??? needs further checks
 122 end;
 123
 124