NaN-Tb: A statistics toolbox 
------------------------------------------------------------
Copyright (C) 2000-2005,2009,2010 Alois Schloegl <a.schloegl@ieee.org>
2011 Holger Nahrstaedt

FEATURES of the NaN-tb:
-----------------------
 - statistical toolbox
 - machine learning and classification toolbox
 - NaN's are treated as missing values 
 - supports weightening of data

 - supports DIM argument
 - less round-off errors using extended double
 - less but more powerful functions (no nan-FUN needed)
 - supports unbiased estimation
 - fixes known bugs
 - easy to use
 - The toolbox is tested with scilab 5.3

There are some functions already implemented in scilab. These functions have the nan_ before then name. E.g. mean() is renamed to nan_mean().

REFERENCE(S):
----------------------------------
[1] http://www.itl.nist.gov/
[2] http://mathworld.wolfram.com/


What is the difference to previous implementations?
-------------------------------------------------------------
-

Q: WHY SKIPPING NaN's?:
------------------------
A: Usually, NaN means that the value is not available. This meaning is most 
common, even many different reasons might cause NaN's. In statistics, NaN's 
represent missing values, in biosignal processing such missing values might 
have been caused by some recording error. Other reasons for NaN's are, 
undetermined expressions like e.g. 0/0, inf-inf, data not available, unknown value, 
not a numeric value, etc. 

If NaN has the meaning of a missing value, it is only consequent to say, the 
sum of NaN's should be zero. Similar arguments hold for the other functions. 
The mean of X is undefined if and only if X contains no numbers. The 
implementation sum(X)/sum(~isnan(X)) gives 0/0=NaN, which is the desired 
result. The variance of X is undefined if and only if X contains less than 
2 numbers.  

In most numerical applications, NaN's should be simply skipped. Therefore, 
it is efficient to skip NaN's in the default case. In the other cases, the 
NaN's can still be checked explicitly. This could eventually result in a 
more readable code and in improved performance, too.  


Q: What if I need to check for NaN's:
-------------------------------------
A: You can always check whether there were some skipped NaN's in your 
data with the command flag_nans_occured().

m = nan_mean(x);
if flag_nans_occured()
	// do your error handling, e.g. 
	error('there were NaN's in x, ignore m'); 
end; 

Its also easy to control the granularity of the checks

flag_nans_occured(); 	// reset flag
 // do any statistical analysis you want 
if flag_nans_occured()
	// check, whether some NaN's occured. 
end; 


Installing the NaN-tb for scilab
--------------------------------------------
a) Extract files and save them in /your/directory/structure/to/NaN/

b) execude builder.sce
	exec('/your/directory/structure/to/NaN/builder.sce')


LICENSE:
    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 3 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, see <http://www.gnu.org/licenses/>.

