1//
  2//  BCDistribution.h
  3//  Xynk
  4//
  5//  Created by Tom Houpt on 3/21/09.
  6//  Copyright 2009 Behavioral Cybernetics. All rights reserved.
  7//
  8//  Last modified 8/17/2014
  9
 10#import <Cocoa/Cocoa.h>
 11
 12
 13
 14
 15/** Descriptive Statistics Keys
 16 
 17 keys to access descriptive statistics in BCDistribution dictionary
 18*/
 19
 20
 21#define kBCMidmeanKey @"midmean"
 22#define kBCTrimmedMeanKey @"trimmed_mean"
 23#define kBCWinsorizedMeanKey @"winsorized_mean"
 24#define kBCSumKey @"sum"
 25#define kBCMeanKey @"mean"
 26#define kBCMedianKey @"median"
 27#define kBCMidrangeKey @"midrange"
 28#define kBCMidpointKey @"midpoint"
 29#define kBCRootMeanSquareKey @"root_mean_square"
 30#define kBCKurtosisKey @"kurtosis"
 31#define kBCSkewKey @"skew"
 32#define kBCGeometricMeanKey @"geometric_mean"
 33#define kBCHarmonicMeanKey @"harmonic_mean"
 34#define kBCNumberKey @"number"
 35#define kBCCountKey @"count"
 36#define kBCMinKey @"min"
 37#define kBC5thPercentileKey @"percentile_5"
 38#define kBC25thPercentileKey @"percentile_25"
 39#define kBC75thPercentileKey @"percentile_75"
 40#define kBC95thPercentileKey @"percentile_95"
 41#define kBCMaxKey @"max"
 42#define kBCRangeKey @"range"
 43#define kBCSumSqDeviationsKey @"sum_sq_deviations"
 44#define kBCVarianceKey @"variance"
 45#define kBCStdErrorKey @"std_error"
 46#define kBCStdDeviationKey @"std_deviation"
 47#define kBCConfidenceIntervalKey @"confidence_interval"
 48#define kBCCoefficientOfVariationKey @"coefficient_of_variation"
 49
 50
 51
 52/** default value of decscriptive statistics, if distribution or statistic is undefined 
 53    we use a default value of 0.0, so that any calling routine has a valid number to work with 
 54    (but it should really be checking undefined flag)
 55*/
 56
 57#define kBCUndefinedStatisticValue 0.0
 58
 59@interface BCDistribution : NSObject {
 60    
 61    
 62    NSArray *valueArray;
 63    ///< an array of NSNumbers that make up distribution
 64    
 65    NSMutableArray *sortedArray;
 66    ///< the valueArray sorted from min to max
 67        
 68
 69}
 70
 71@property (readonly) BOOL undefined; ///< YES if the statistics have not been updated
 72
 73/** Measures of Location
 74*/
 75@property (readonly) double sum; // sum of all the non-NAN values in the distribution
 76@property (readonly) double mean; // mean of all values = sum divided by n
 77@property (readonly)    double midmean; ///<mean of values between 25th and 75th percentile (ncludes 25th and 75th percentile)
 78@property (readonly)    double trimmed_mean; ///< mean of values between 5th and 95th percentile (includes 5th and 95th percentile)
 79@property (readonly)    double winsorized_mean; ///< mean of values, after values outside 5th and 95th percentile  are set to 5th and 95th percentile value, respectively
 80@property (readonly) double median; ///<if an odd number of values, then median is the central value of the distribution; if an even number of values, then median is the average of the 2 middle values
 81
 82@property (readonly)    double midrange; ///< (max - min)/2
 83@property (readonly)    double midpoint; ///< synonym for midrange
 84@property (readonly) double root_mean_square;
 85@property (readonly) double kurtosis;
 86@property (readonly) double skew;
 87@property (readonly) double geometric_mean;
 88@property (readonly) double harmonic_mean;
 89
 90/** Measures of Dispersion
 91*/
 92@property (readonly) unsigned long number; ///< number of values in the distribution (n)
 93@property (readonly) unsigned long count; ///<synonym for number
 94@property (readonly) double min; ///< lowest number in distribution
 95@property (readonly)    double percentile_5; ///<  estimated percentiles according to formular from http://www.itl.nist.gov/div898/handbook/prc/section2/prc262.htm
 96@property (readonly)    double percentile_25;
 97@property (readonly)    double percentile_75;
 98@property (readonly)    double percentile_95;
 99@property (readonly) double max; ///< highest number in distribution
100@property (readonly) double range; ///< max - min
101@property (readonly) double sum_sq_deviations; // sum of squared deviations from the mean sum (xi - mean x)^2
102@property (readonly) double variance; // sum of squared deviations divided by n-1 (for sample variance)
103@property (readonly) double std_error; // standard error of all the values; variance divided by sqrt of n
104@property (readonly) double std_deviation; // sample SD = sqrt of variance
105@property (readonly)    double confidence_interval; ///< 95% CI = 1.96 * std_error
106@property (readonly)    double coefficient_of_variation; ///< standard deviation / mean
107    
108
109
110/** initialize distribution with an array of NSNumbers
111 
112    NSNumbers in the array are accessed as doubles for calculations
113    note: NANs are stripped from the array (and do not contribute to number of values in the distribution)
114    if array is nil or has zero members, then:
115    - undefined is YES
116    - all the statistical values remain at kBCUndefinedStatisticValue
117    - [BCDistribution dictionary] returns nil
118    otherwise, the initialization calls update and the descriptive stats are calculated
119 
120    @param anArray an NSArray of NSNumbers. can be nil, or have zero members. Member values can be NaN (which will be stripped for calculations).
121*/
122
123-(id)initWithArray:(NSArray *)anArray;
124
125/** check if stats were calculated
126 
127 if stats are not defined, then values == kBCUndefinedStatisticValue
128 and [BCDistribution dictionary] returns nil
129 
130 @return YES if stats were NOT calculated (because value array was nil);
131 otherwise NO if stats were calculated
132 
133 */
134-(BOOL) undefined;
135
136//**************************************************************************
137
138/** Access to Values
139 */
140/** the values that make up the distribution
141 
142 Note that NAN are stripped from the array on initializations; otherwise the values are in the same order as the initializing array.
143 
144 @return an NSArray of NSNumbers of the values that make up distribution.
145 */
146
147-(NSArray *)values;
148/** access to specific value within the distribution
149 
150 note that the passed index does NOT include any NAN values which would have been stripped from the initializing array
151 
152 @param index an unsigned long indexing into the distribution
153 @return value a double of specificed value within the distribution
154 
155 */
156-(double) value_at_i:(unsigned long)index;
157
158/** given a percentile between 0 and 1.0, return the  value at that percentile estimated according to 
159 
160 http://www.itl.nist.gov/div898/handbook/prc/section2/prc262.htm
161 @param percentile a double between 0 and 1.0
162 @return a double estimated value at the given percentile
163 
164 */
165-(double)value_at_percentile:(double)percentile;
166
167/** mean deviation of specific value within the distribution
168 
169 this can be helpful for later statistical calculations
170 note that the passed index does NOT include any NAN values which would have been stripped from the initializing array
171 
172 @param index an unsigned long indexing into the distribution
173 @return a double =  (indexed value - mean)
174 
175 */
176-(double) mean_deviation_at_i:(unsigned long)index;
177
178//**************************************************************************
179
180/** returns a dictionary containing the descriptive stats, accessed by kBCNumberKey etc.
181 
182 @returns an NSdictionary containing descriptive stats, accessed by kBCNumberKey etc.
183    if distribution is undefined, then returns nil
184 
185*/
186-(NSDictionary *)dictionary;
187
188
189@end