0
# Descriptive Statistics
1

2
Functions for calculating measures of central tendency, variability, and distribution shape.
3

4
## Core Imports
5

6
```typescript
7
import { 
8
  mean, median, mode, 
9
  standardDeviation, variance, 
10
  sampleVariance, sampleStandardDeviation,
11
  sampleSkewness, sampleKurtosis,
12
  rootMeanSquare,
13
  geometricMean, harmonicMean
14
} from "simple-statistics";
15
```
16

17
## Measures of Central Tendency
18

19
### mean (alias: average) { .api }
20

21
```typescript { .api }
22
function mean(values: number[]): number;
23
```
24

25
Calculates the arithmetic mean (average) of an array of numbers.
26

27
**Parameters:**
28
- `values: number[]` - Array of numeric values
29

30
**Returns:** `number` - The arithmetic mean
31

32
**Throws:** Error if array is empty
33

34
```typescript
35
import { mean, average } from "simple-statistics";
36

37
const data = [1, 2, 3, 4, 5];
38
const result = mean(data); // 3
39

40
// Alternative using alias
41
const result2 = average(data); // 3 - same function
42
```
43

44
### median { .api }
45

46
```typescript { .api }
47
function median(values: number[]): number;
48
```
49

50
Finds the middle value in a dataset. Automatically sorts the data.
51

52
**Parameters:**
53
- `values: number[]` - Array of numeric values
54

55
**Returns:** `number` - The median value
56

57
```typescript
58
import { median } from "simple-statistics";
59

60
const data = [1, 3, 2, 5, 4];
61
const result = median(data); // 3
62
```
63

64
### medianSorted { .api }
65

66
```typescript { .api }
67
function medianSorted(values: number[]): number;
68
```
69

70
Optimized median calculation for pre-sorted arrays.
71

72
**Parameters:**
73
- `values: number[]` - Pre-sorted array of numeric values
74

75
**Returns:** `number` - The median value
76

77
```typescript
78
import { medianSorted } from "simple-statistics";
79

80
const sortedData = [1, 2, 3, 4, 5];
81
const result = medianSorted(sortedData); // 3
82
```
83

84
### mode { .api }
85

86
```typescript { .api }
87
function mode(values: number[]): number;
88
```
89

90
Finds the most frequently occurring value in a dataset.
91

92
**Parameters:**
93
- `values: number[]` - Array of numeric values
94

95
**Returns:** `number` - The mode (most frequent value)
96

97
```typescript
98
import { mode } from "simple-statistics";
99

100
const data = [1, 2, 2, 3, 4, 2];
101
const result = mode(data); // 2
102
```
103

104
### modeFast { .api }
105

106
```typescript { .api }
107
function modeFast(values: number[]): number;
108
```
109

110
Fast mode calculation using optimized algorithm.
111

112
### modeSorted { .api }
113

114
```typescript { .api }
115
function modeSorted(values: number[]): number;
116
```
117

118
Mode calculation for pre-sorted arrays.
119

120
### geometricMean { .api }
121

122
```typescript { .api }
123
function geometricMean(values: number[]): number;
124
```
125

126
Calculates the geometric mean - the nth root of the product of n numbers.
127

128
**Parameters:**
129
- `values: number[]` - Array of positive numeric values
130

131
**Returns:** `number` - The geometric mean
132

133
```typescript
134
import { geometricMean } from "simple-statistics";
135

136
const data = [1, 2, 4, 8];
137
const result = geometricMean(data); // 2.828...
138
```
139

140
### harmonicMean { .api }
141

142
```typescript { .api }
143
function harmonicMean(values: number[]): number;
144
```
145

146
Calculates the harmonic mean - useful for rates and ratios.
147

148
**Parameters:**
149
- `values: number[]` - Array of positive numeric values
150

151
**Returns:** `number` - The harmonic mean
152

153
```typescript
154
import { harmonicMean } from "simple-statistics";
155

156
const rates = [10, 20, 30];
157
const result = harmonicMean(rates); // 16.36...
158
```
159

160
## Measures of Variability
161

162
### variance { .api }
163

164
```typescript { .api }
165
function variance(values: number[]): number;
166
```
167

168
Calculates the population variance - average of squared deviations from the mean.
169

170
**Parameters:**
171
- `values: number[]` - Array of numeric values
172

173
**Returns:** `number` - The population variance
174

175
```typescript
176
import { variance } from "simple-statistics";
177

178
const data = [1, 2, 3, 4, 5];
179
const result = variance(data); // 2
180
```
181

182
### standardDeviation { .api }
183

184
```typescript { .api }
185
function standardDeviation(values: number[]): number;
186
```
187

188
Calculates the population standard deviation - square root of variance.
189

190
**Parameters:**
191
- `values: number[]` - Array of numeric values
192

193
**Returns:** `number` - The population standard deviation
194

195
```typescript
196
import { standardDeviation } from "simple-statistics";
197

198
const data = [1, 2, 3, 4, 5];
199
const result = standardDeviation(data); // 1.414...
200
```
201

202
### sampleVariance { .api }
203

204
```typescript { .api }
205
function sampleVariance(values: number[]): number;
206
```
207

208
Calculates the sample variance using n-1 denominator (Bessel's correction).
209

210
**Parameters:**
211
- `values: number[]` - Array of numeric values
212

213
**Returns:** `number` - The sample variance
214

215
```typescript
216
import { sampleVariance } from "simple-statistics";
217

218
const sample = [1, 2, 3, 4, 5];
219
const result = sampleVariance(sample); // 2.5
220
```
221

222
### sampleStandardDeviation { .api }
223

224
```typescript { .api }
225
function sampleStandardDeviation(values: number[]): number;
226
```
227

228
Calculates the sample standard deviation using n-1 denominator.
229

230
**Parameters:**
231
- `values: number[]` - Array of numeric values
232

233
**Returns:** `number` - The sample standard deviation
234

235
```typescript
236
import { sampleStandardDeviation } from "simple-statistics";
237

238
const sample = [1, 2, 3, 4, 5];
239
const result = sampleStandardDeviation(sample); // 1.58...
240
```
241

242
### rootMeanSquare (alias: rms) { .api }
243

244
```typescript { .api }
245
function rootMeanSquare(values: number[]): number;
246
```
247

248
Calculates the root mean square (quadratic mean).
249

250
**Parameters:**
251
- `values: number[]` - Array of numeric values
252

253
**Returns:** `number` - The root mean square
254

255
```typescript
256
import { rootMeanSquare } from "simple-statistics";
257

258
const data = [1, 2, 3, 4, 5];
259
const result = rootMeanSquare(data); // 3.31...
260
```
261

262
## Distribution Shape Measures
263

264
### sampleSkewness { .api }
265

266
```typescript { .api }
267
function sampleSkewness(values: number[]): number;
268
```
269

270
Measures the asymmetry of the probability distribution. Positive skew indicates a tail extending toward more positive values.
271

272
**Parameters:**
273
- `values: number[]` - Array of numeric values
274

275
**Returns:** `number` - The sample skewness
276

277
```typescript
278
import { sampleSkewness } from "simple-statistics";
279

280
const data = [1, 2, 2, 3, 4, 7, 9];
281
const result = sampleSkewness(data); // positive value (right-skewed)
282
```
283

284
### sampleKurtosis { .api }
285

286
```typescript { .api }
287
function sampleKurtosis(values: number[]): number;
288
```
289

290
Measures the "tailedness" of the probability distribution relative to a normal distribution.
291

292
**Parameters:**
293
- `values: number[]` - Array of numeric values
294

295
**Returns:** `number` - The sample kurtosis
296

297
```typescript
298
import { sampleKurtosis } from "simple-statistics";
299

300
const data = [1, 2, 3, 4, 5];
301
const result = sampleKurtosis(data); // measure of tail weight
302
```
303

304
## Helper Functions
305

306
### addToMean { .api }
307

308
```typescript { .api }
309
function addToMean(currentMean: number, n: number, newValue: number): number;
310
```
311

312
Updates the mean when adding a new value to the dataset.
313

314
### subtractFromMean { .api }
315

316
```typescript { .api }
317
function subtractFromMean(currentMean: number, n: number, value: number): number;
318
```
319

320
Updates the mean when removing a value from the dataset.
321

322
### combineMeans { .api }
323

324
```typescript { .api }
325
function combineMeans(mean1: number, n1: number, mean2: number, n2: number): number;
326
```
327

328
Combines means from two separate samples.
329

330
### combineVariances { .api }
331

332
```typescript { .api }
333
function combineVariances(variance1: number, mean1: number, n1: number, variance2: number, mean2: number, n2: number): number;
334
```
335

336
Combines variances from two separate samples.