0
# Numerical Module
1

2
The Numerical module provides 28 functions for mathematical operations and statistical calculations. These functions cover basic arithmetic, rounding, comparisons, statistics, and mathematical transformations.
3

4
## Basic Math Operations
5

6
### add
7

8
```python { .api }
9
def add(a: Union[int, float], b: Union[int, float]) -> Union[int, float]
10
```
11

12
Adds two numbers.
13

14
**Parameters:**
15
- `a` (`Union[int, float]`): First number.
16
- `b` (`Union[int, float]`): Second number.
17

18
**Returns:**
19
- `Union[int, float]`: Sum of `a` and `b`.
20

21
**Example:**
22
```python { .api }
23
from pydash import add
24

25
add(6, 4)
26
# 10
27

28
add(1.5, 2.3)
29
# 3.8
30
```
31

32
### subtract
33

34
```python { .api }
35
def subtract(a: Union[int, float], b: Union[int, float]) -> Union[int, float]
36
```
37

38
Subtracts the second number from the first.
39

40
**Parameters:**
41
- `a` (`Union[int, float]`): Number to subtract from.
42
- `b` (`Union[int, float]`): Number to subtract.
43

44
**Returns:**
45
- `Union[int, float]`: Difference of `a` and `b`.
46

47
**Example:**
48
```python { .api }
49
from pydash import subtract
50

51
subtract(6, 4)
52
# 2
53

54
subtract(10.5, 3.2)
55
# 7.3
56
```
57

58
### multiply
59

60
```python { .api }
61
def multiply(a: Union[int, float], b: Union[int, float]) -> Union[int, float]
62
```
63

64
Multiplies two numbers.
65

66
**Parameters:**
67
- `a` (`Union[int, float]`): First number.
68
- `b` (`Union[int, float]`): Second number.
69

70
**Returns:**
71
- `Union[int, float]`: Product of `a` and `b`.
72

73
**Example:**
74
```python { .api }
75
from pydash import multiply
76

77
multiply(6, 4)
78
# 24
79

80
multiply(2.5, 4)
81
# 10.0
82
```
83

84
### divide
85

86
```python { .api }
87
def divide(a: Union[int, float], b: Union[int, float]) -> float
88
```
89

90
Divides the first number by the second.
91

92
**Parameters:**
93
- `a` (`Union[int, float]`): Dividend.
94
- `b` (`Union[int, float]`): Divisor.
95

96
**Returns:**
97
- `float`: Quotient of `a` and `b`.
98

99
**Example:**
100
```python { .api }
101
from pydash import divide
102

103
divide(6, 4)
104
# 1.5
105

106
divide(10, 2)
107
# 5.0
108
```
109

110
### power
111

112
```python { .api }
113
def power(a: Union[int, float], b: Union[int, float]) -> Union[int, float]
114
```
115

116
Returns `a` raised to the power of `b`.
117

118
**Parameters:**
119
- `a` (`Union[int, float]`): Base number.
120
- `b` (`Union[int, float]`): Exponent.
121

122
**Returns:**
123
- `Union[int, float]`: `a` raised to power of `b`.
124

125
**Example:**
126
```python { .api }
127
from pydash import power
128

129
power(2, 3)
130
# 8
131

132
power(4, 0.5)
133
# 2.0
134
```
135

136
## Rounding and Precision Functions
137

138
### ceil
139

140
```python { .api }
141
def ceil(number: Union[int, float], precision: int = 0) -> Union[int, float]
142
```
143

144
Computes `number` rounded up to `precision`.
145

146
**Parameters:**
147
- `number` (`Union[int, float]`): Number to round up.
148
- `precision` (`int`): Precision to round up to. Defaults to `0`.
149

150
**Returns:**
151
- `Union[int, float]`: Rounded up number.
152

153
**Example:**
154
```python { .api }
155
from pydash import ceil
156

157
ceil(4.006)
158
# 5
159

160
ceil(6.004, 2)
161
# 6.01
162

163
ceil(6040, -2)
164
# 6100
165
```
166

167
### floor
168

169
```python { .api }
170
def floor(number: Union[int, float], precision: int = 0) -> Union[int, float]
171
```
172

173
Computes `number` rounded down to `precision`.
174

175
**Parameters:**
176
- `number` (`Union[int, float]`): Number to round down.
177
- `precision` (`int`): Precision to round down to. Defaults to `0`.
178

179
**Returns:**
180
- `Union[int, float]`: Rounded down number.
181

182
**Example:**
183
```python { .api }
184
from pydash import floor
185

186
floor(4.006)
187
# 4
188

189
floor(0.046, 2)
190
# 0.04
191

192
floor(4060, -2)
193
# 4000
194
```
195

196
### round_
197

198
```python { .api }
199
def round_(number: Union[int, float], precision: int = 0) -> Union[int, float]
200
```
201

202
Computes `number` rounded to `precision`.
203

204
**Parameters:**
205
- `number` (`Union[int, float]`): Number to round.
206
- `precision` (`int`): Precision to round to. Defaults to `0`.
207

208
**Returns:**
209
- `Union[int, float]`: Rounded number.
210

211
**Example:**
212
```python { .api }
213
from pydash import round_
214

215
round_(4.006)
216
# 4
217

218
round_(4.006, 2)
219
# 4.01
220

221
round_(4060, -2)
222
# 4100
223
```
224

225
## Comparison and Boundary Functions
226

227
### clamp
228

229
```python { .api }
230
def clamp(number: Union[int, float], lower: Union[int, float, None] = None, upper: Union[int, float, None] = None) -> Union[int, float]
231
```
232

233
Clamps `number` within the inclusive `lower` and `upper` bounds.
234

235
**Parameters:**
236
- `number` (`Union[int, float]`): Number to clamp.
237
- `lower` (`Union[int, float, None]`): Lower bound.
238
- `upper` (`Union[int, float, None]`): Upper bound.
239

240
**Returns:**
241
- `Union[int, float]`: Clamped number.
242

243
**Example:**
244
```python { .api }
245
from pydash import clamp
246

247
clamp(-10, -5, 5)
248
# -5
249

250
clamp(10, -5, 5)
251
# 5
252

253
clamp(3, -5, 5)
254
# 3
255
```
256

257
### max_
258

259
```python { .api }
260
def max_(array: Iterable[Union[int, float]], default: Any = None) -> Union[int, float, Any]
261
```
262

263
Computes the maximum value of `array`. If `array` is empty or falsey, `default` is returned.
264

265
**Parameters:**
266
- `array` (`Iterable[Union[int, float]]`): Array to iterate over.
267
- `default` (`Any`): Default value to return for empty arrays.
268

269
**Returns:**
270
- `Union[int, float, Any]`: Maximum value.
271

272
**Example:**
273
```python { .api }
274
from pydash import max_
275

276
max_([4, 2, 8, 6])
277
# 8
278

279
max_([], 0)
280
# 0
281
```
282

283
### max_by
284

285
```python { .api }
286
def max_by(array: Iterable[Any], iteratee: Callable = None) -> Any
287
```
288

289
Like `max_` except that it accepts `iteratee` which is invoked for each element in `array` to generate the criterion by which they're compared.
290

291
**Parameters:**
292
- `array` (`Iterable[Any]`): Array to iterate over.
293
- `iteratee` (`Callable`, optional): Function invoked per iteration.
294

295
**Returns:**
296
- `Any`: Maximum element.
297

298
**Example:**
299
```python { .api }
300
from pydash import max_by
301

302
objects = [{'n': 1}, {'n': 2}]
303
max_by(objects, lambda x: x['n'])
304
# {'n': 2}
305

306
max_by(objects, 'n')
307
# {'n': 2}
308
```
309

310
### min_
311

312
```python { .api }
313
def min_(array: Iterable[Union[int, float]], default: Any = None) -> Union[int, float, Any]
314
```
315

316
Computes the minimum value of `array`. If `array` is empty or falsey, `default` is returned.
317

318
**Parameters:**
319
- `array` (`Iterable[Union[int, float]]`): Array to iterate over.
320
- `default` (`Any`): Default value to return for empty arrays.
321

322
**Returns:**
323
- `Union[int, float, Any]`: Minimum value.
324

325
**Example:**
326
```python { .api }
327
from pydash import min_
328

329
min_([4, 2, 8, 6])
330
# 2
331

332
min_([], 0)
333
# 0
334
```
335

336
### min_by
337

338
```python { .api }
339
def min_by(array: Iterable[Any], iteratee: Callable = None) -> Any
340
```
341

342
Like `min_` except that it accepts `iteratee` which is invoked for each element in `array` to generate the criterion by which they're compared.
343

344
**Parameters:**
345
- `array` (`Iterable[Any]`): Array to iterate over.
346
- `iteratee` (`Callable`, optional): Function invoked per iteration.
347

348
**Returns:**
349
- `Any`: Minimum element.
350

351
**Example:**
352
```python { .api }
353
from pydash import min_by
354

355
objects = [{'n': 1}, {'n': 2}]
356
min_by(objects, lambda x: x['n'])
357
# {'n': 1}
358

359
min_by(objects, 'n')
360
# {'n': 1}
361
```
362

363
## Statistical Functions
364

365
### mean
366

367
```python { .api }
368
def mean(array: Iterable[Union[int, float]]) -> float
369
```
370

371
Computes the arithmetic mean of the values in `array`.
372

373
**Parameters:**
374
- `array` (`Iterable[Union[int, float]]`): Array of numbers.
375

376
**Returns:**
377
- `float`: Arithmetic mean.
378

379
**Example:**
380
```python { .api }
381
from pydash import mean
382

383
mean([4, 2, 8, 6])
384
# 5.0
385

386
mean([1, 2, 3, 4, 5])
387
# 3.0
388
```
389

390
### mean_by
391

392
```python { .api }
393
def mean_by(array: Iterable[Any], iteratee: Callable = None) -> float
394
```
395

396
Like `mean` except that it accepts `iteratee` which is invoked for each element in `array` to generate the value to be averaged.
397

398
**Parameters:**
399
- `array` (`Iterable[Any]`): Array to iterate over.
400
- `iteratee` (`Callable`, optional): Function invoked per iteration.
401

402
**Returns:**
403
- `float`: Arithmetic mean.
404

405
**Example:**
406
```python { .api }
407
from pydash import mean_by
408

409
objects = [{'n': 4}, {'n': 2}, {'n': 8}, {'n': 6}]
410
mean_by(objects, lambda x: x['n'])
411
# 5.0
412

413
mean_by(objects, 'n')
414
# 5.0
415
```
416

417
### median
418

419
```python { .api }
420
def median(array: Iterable[Union[int, float]]) -> Union[int, float]
421
```
422

423
Computes the median of the values in `array`.
424

425
**Parameters:**
426
- `array` (`Iterable[Union[int, float]]`): Array of numbers.
427

428
**Returns:**
429
- `Union[int, float]`: Median value.
430

431
**Example:**
432
```python { .api }
433
from pydash import median
434

435
median([4, 2, 8, 6])
436
# 5.0
437

438
median([4, 2, 8, 6, 1])
439
# 4
440
```
441

442
### sum_
443

444
```python { .api }
445
def sum_(array: Iterable[Union[int, float]]) -> Union[int, float]
446
```
447

448
Computes the sum of the values in `array`.
449

450
**Parameters:**
451
- `array` (`Iterable[Union[int, float]]`): Array of numbers to sum.
452

453
**Returns:**
454
- `Union[int, float]`: Sum of array values.
455

456
**Example:**
457
```python { .api }
458
from pydash import sum_
459

460
sum_([4, 2, 8, 6])
461
# 20
462

463
sum_([1.5, 2.5, 3.0])
464
# 7.0
465
```
466

467
### sum_by
468

469
```python { .api }
470
def sum_by(array: Iterable[Any], iteratee: Callable = None) -> Union[int, float]
471
```
472

473
Like `sum_` except that it accepts `iteratee` which is invoked for each element in `array` to generate the value to be summed.
474

475
**Parameters:**
476
- `array` (`Iterable[Any]`): Array to iterate over.
477
- `iteratee` (`Callable`, optional): Function invoked per iteration.
478

479
**Returns:**
480
- `Union[int, float]`: Sum of processed values.
481

482
**Example:**
483
```python { .api }
484
from pydash import sum_by
485

486
objects = [{'n': 4}, {'n': 2}, {'n': 8}, {'n': 6}]
487
sum_by(objects, lambda x: x['n'])
488
# 20
489

490
sum_by(objects, 'n')
491
# 20
492
```
493

494
### moving_mean
495

496
```python { .api }
497
def moving_mean(array: Iterable[Union[int, float]], window: int) -> List[float]
498
```
499

500
Computes the moving mean of `array` with a window size of `window`.
501

502
**Parameters:**
503
- `array` (`Iterable[Union[int, float]]`): Array of numbers.
504
- `window` (`int`): Moving window size.
505

506
**Returns:**
507
- `List[float]`: Array of moving means.
508

509
**Example:**
510
```python { .api }
511
from pydash import moving_mean
512

513
moving_mean([1, 2, 3, 4, 5], 3)
514
# [2.0, 3.0, 4.0]
515
```
516

517
### std_deviation
518

519
```python { .api }
520
def std_deviation(array: Iterable[Union[int, float]]) -> float
521
```
522

523
Computes the standard deviation of the values in `array`.
524

525
**Parameters:**
526
- `array` (`Iterable[Union[int, float]]`): Array of numbers.
527

528
**Returns:**
529
- `float`: Standard deviation.
530

531
**Example:**
532
```python { .api }
533
from pydash import std_deviation
534

535
std_deviation([1, 2, 3, 4, 5])
536
# 1.5811388300841898
537
```
538

539
### variance
540

541
```python { .api }
542
def variance(array: Iterable[Union[int, float]]) -> float
543
```
544

545
Computes the variance of the values in `array`.
546

547
**Parameters:**
548
- `array` (`Iterable[Union[int, float]]`): Array of numbers.
549

550
**Returns:**
551
- `float`: Variance.
552

553
**Example:**
554
```python { .api }
555
from pydash import variance
556

557
variance([1, 2, 3, 4, 5])
558
# 2.5
559
```
560

561
### zscore
562

563
```python { .api }
564
def zscore(collection: Iterable[Union[int, float]], value: Union[int, float]) -> float
565
```
566

567
Computes the z-score of `value` relative to the `collection` of values.
568

569
**Parameters:**
570
- `collection` (`Iterable[Union[int, float]]`): Collection of numbers.
571
- `value` (`Union[int, float]`): Value to compute z-score for.
572

573
**Returns:**
574
- `float`: Z-score of `value`.
575

576
**Example:**
577
```python { .api }
578
from pydash import zscore
579

580
zscore([1, 2, 3, 4, 5], 3)
581
# 0.0
582

583
zscore([1, 2, 3, 4, 5], 5)
584
# 1.2649110640673518
585
```
586

587
## Scaling and Transformation Functions
588

589
### scale
590

591
```python { .api }
592
def scale(array: Iterable[Union[int, float]], maximum: Union[int, float] = 1) -> List[float]
593
```
594

595
Scales all values in `array` up to `maximum` while maintaining proportions.
596

597
**Parameters:**
598
- `array` (`Iterable[Union[int, float]]`): Array of numbers to scale.
599
- `maximum` (`Union[int, float]`): Maximum value to scale to. Defaults to `1`.
600

601
**Returns:**
602
- `List[float]`: Scaled array.
603

604
**Example:**
605
```python { .api }
606
from pydash import scale
607

608
scale([1, 2, 3, 4, 5])
609
# [0.2, 0.4, 0.6, 0.8, 1.0]
610

611
scale([1, 2, 3, 4, 5], 10)
612
# [2.0, 4.0, 6.0, 8.0, 10.0]
613
```
614

615
### slope
616

617
```python { .api }
618
def slope(point1: Tuple[Union[int, float], Union[int, float]], point2: Tuple[Union[int, float], Union[int, float]]) -> float
619
```
620

621
Calculate the slope between two points.
622

623
**Parameters:**
624
- `point1` (`Tuple[Union[int, float], Union[int, float]]`): First point as (x, y).
625
- `point2` (`Tuple[Union[int, float], Union[int, float]]`): Second point as (x, y).
626

627
**Returns:**
628
- `float`: Slope between the two points.
629

630
**Example:**
631
```python { .api }
632
from pydash import slope
633

634
slope((1, 2), (3, 6))
635
# 2.0
636

637
slope((0, 0), (1, 1))
638
# 1.0
639
```
640

641
### transpose
642

643
```python { .api }
644
def transpose(array: Iterable[Iterable[Any]]) -> List[List[Any]]
645
```
646

647
Transpose a 2D array (matrix transpose).
648

649
**Parameters:**
650
- `array` (`Iterable[Iterable[Any]]`): 2D array to transpose.
651

652
**Returns:**
653
- `List[List[Any]]`: Transposed array.
654

655
**Example:**
656
```python { .api }
657
from pydash import transpose
658

659
transpose([[1, 2, 3], [4, 5, 6]])
660
# [[1, 4], [2, 5], [3, 6]]
661

662
transpose([[1, 2], [3, 4], [5, 6]])
663
# [[1, 3, 5], [2, 4, 6]]
664
```
665

666
## Usage Examples
667

668
### Basic Arithmetic Operations
669
```python { .api }
670
from pydash import add, subtract, multiply, divide, power
671

672
# Basic operations
673
result = add(multiply(3, 4), divide(10, 2))  # (3 * 4) + (10 / 2) = 17
674

675
# Power operations
676
square = power(5, 2)  # 25
677
square_root = power(16, 0.5)  # 4.0
678
```
679

680
### Statistical Analysis
681
```python { .api }
682
from pydash import mean, median, std_deviation, variance
683

684
data = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
685

686
# Central tendency
687
avg = mean(data)        # 5.5
688
mid = median(data)      # 5.5
689

690
# Spread measures
691
std = std_deviation(data)  # 3.0276503540974917
692
var = variance(data)       # 9.166666666666666
693
```
694

695
### Working with Objects
696
```python { .api }
697
from pydash import max_by, min_by, sum_by, mean_by
698

699
students = [
700
    {'name': 'Alice', 'score': 85},
701
    {'name': 'Bob', 'score': 92},
702
    {'name': 'Charlie', 'score': 78}
703
]
704

705
# Find extremes
706
top_student = max_by(students, 'score')    # {'name': 'Bob', 'score': 92}
707
lowest_student = min_by(students, 'score') # {'name': 'Charlie', 'score': 78}
708

709
# Calculate totals and averages
710
total_score = sum_by(students, 'score')    # 255
711
avg_score = mean_by(students, 'score')     # 85.0
712
```
713

714
### Data Scaling and Normalization
715
```python { .api }
716
from pydash import scale, clamp, zscore
717

718
raw_data = [10, 20, 30, 40, 50]
719

720
# Scale to 0-1 range
721
normalized = scale(raw_data)  # [0.2, 0.4, 0.6, 0.8, 1.0]
722

723
# Scale to 0-100 range
724
percentage = scale(raw_data, 100)  # [20.0, 40.0, 60.0, 80.0, 100.0]
725

726
# Clamp values to specific bounds
727
bounded = [clamp(x, 0, 100) for x in [-10, 50, 150]]  # [0, 50, 100]
728

729
# Calculate z-scores for outlier detection
730
z_scores = [zscore(raw_data, x) for x in raw_data]
731
```
732

733
### Moving Statistics
734
```python { .api }
735
from pydash import moving_mean
736

737
# Stock prices over time
738
prices = [100, 102, 98, 105, 110, 108, 112, 115]
739

740
# 3-day moving average
741
ma_3 = moving_mean(prices, 3)
742
# [100.0, 101.67, 105.0, 107.67, 110.0, 111.67]
743

744
# 5-day moving average  
745
ma_5 = moving_mean(prices, 5)
746
# [103.0, 104.6, 106.6, 110.0]
747
```
748

749
This Numerical module provides comprehensive mathematical functionality with 25 functions covering basic arithmetic, statistical analysis, data scaling, and mathematical transformations for numerical data processing.