Numerical Module

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

Basic Math Operations

add

def add(a: Union[int, float], b: Union[int, float]) -> Union[int, float]

Adds two numbers.

Parameters:

• a (Union[int, float]): First number.
• b (Union[int, float]): Second number.

Returns:

• Union[int, float]: Sum of a and b.

Example:

from pydash import add

add(6, 4)
# 10

add(1.5, 2.3)
# 3.8

subtract

def subtract(a: Union[int, float], b: Union[int, float]) -> Union[int, float]

Subtracts the second number from the first.

Parameters:

• a (Union[int, float]): Number to subtract from.
• b (Union[int, float]): Number to subtract.

Returns:

• Union[int, float]: Difference of a and b.

Example:

from pydash import subtract

subtract(6, 4)
# 2

subtract(10.5, 3.2)
# 7.3

multiply

def multiply(a: Union[int, float], b: Union[int, float]) -> Union[int, float]

Multiplies two numbers.

Parameters:

• a (Union[int, float]): First number.
• b (Union[int, float]): Second number.

Returns:

• Union[int, float]: Product of a and b.

Example:

from pydash import multiply

multiply(6, 4)
# 24

multiply(2.5, 4)
# 10.0

divide

def divide(a: Union[int, float], b: Union[int, float]) -> float

Divides the first number by the second.

Parameters:

• a (Union[int, float]): Dividend.
• b (Union[int, float]): Divisor.

Returns:

• float: Quotient of a and b.

Example:

from pydash import divide

divide(6, 4)
# 1.5

divide(10, 2)
# 5.0

power

def power(a: Union[int, float], b: Union[int, float]) -> Union[int, float]

Returns a raised to the power of b.

Parameters:

• a (Union[int, float]): Base number.
• b (Union[int, float]): Exponent.

Returns:

• Union[int, float]: a raised to power of b.

Example:

from pydash import power

power(2, 3)
# 8

power(4, 0.5)
# 2.0

Rounding and Precision Functions

ceil

def ceil(number: Union[int, float], precision: int = 0) -> Union[int, float]

Computes number rounded up to precision.

Parameters:

• number (Union[int, float]): Number to round up.
• precision (int): Precision to round up to. Defaults to 0.

Returns:

• Union[int, float]: Rounded up number.

Example:

from pydash import ceil

ceil(4.006)
# 5

ceil(6.004, 2)
# 6.01

ceil(6040, -2)
# 6100

floor

def floor(number: Union[int, float], precision: int = 0) -> Union[int, float]

Computes number rounded down to precision.

Parameters:

• number (Union[int, float]): Number to round down.
• precision (int): Precision to round down to. Defaults to 0.

Returns:

• Union[int, float]: Rounded down number.

Example:

from pydash import floor

floor(4.006)
# 4

floor(0.046, 2)
# 0.04

floor(4060, -2)
# 4000

round_

def round_(number: Union[int, float], precision: int = 0) -> Union[int, float]

Computes number rounded to precision.

Parameters:

• number (Union[int, float]): Number to round.
• precision (int): Precision to round to. Defaults to 0.

Returns:

• Union[int, float]: Rounded number.

Example:

from pydash import round_

round_(4.006)
# 4

round_(4.006, 2)
# 4.01

round_(4060, -2)
# 4100

Comparison and Boundary Functions

clamp

def clamp(number: Union[int, float], lower: Union[int, float, None] = None, upper: Union[int, float, None] = None) -> Union[int, float]

Clamps number within the inclusive lower and upper bounds.

Parameters:

• number (Union[int, float]): Number to clamp.
• lower (Union[int, float, None]): Lower bound.
• upper (Union[int, float, None]): Upper bound.

Returns:

• Union[int, float]: Clamped number.

Example:

from pydash import clamp

clamp(-10, -5, 5)
# -5

clamp(10, -5, 5)
# 5

clamp(3, -5, 5)
# 3

max_

def max_(array: Iterable[Union[int, float]], default: Any = None) -> Union[int, float, Any]

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

Parameters:

• array (Iterable[Union[int, float]]): Array to iterate over.
• default (Any): Default value to return for empty arrays.

Returns:

• Union[int, float, Any]: Maximum value.

Example:

from pydash import max_

max_([4, 2, 8, 6])
# 8

max_([], 0)
# 0

max_by

def max_by(array: Iterable[Any], iteratee: Callable = None) -> Any

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

Parameters:

• array (Iterable[Any]): Array to iterate over.
• iteratee (Callable, optional): Function invoked per iteration.

Returns:

• Any: Maximum element.

Example:

from pydash import max_by

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

max_by(objects, 'n')
# {'n': 2}

min_

def min_(array: Iterable[Union[int, float]], default: Any = None) -> Union[int, float, Any]

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

Parameters:

• array (Iterable[Union[int, float]]): Array to iterate over.
• default (Any): Default value to return for empty arrays.

Returns:

• Union[int, float, Any]: Minimum value.

Example:

from pydash import min_

min_([4, 2, 8, 6])
# 2

min_([], 0)
# 0

min_by

def min_by(array: Iterable[Any], iteratee: Callable = None) -> Any

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

Parameters:

• array (Iterable[Any]): Array to iterate over.
• iteratee (Callable, optional): Function invoked per iteration.

Returns:

• Any: Minimum element.

Example:

from pydash import min_by

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

min_by(objects, 'n')
# {'n': 1}

Statistical Functions

mean

def mean(array: Iterable[Union[int, float]]) -> float

Computes the arithmetic mean of the values in array.

Parameters:

• array (Iterable[Union[int, float]]): Array of numbers.

Returns:

• float: Arithmetic mean.

Example:

from pydash import mean

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

mean([1, 2, 3, 4, 5])
# 3.0

mean_by

def mean_by(array: Iterable[Any], iteratee: Callable = None) -> float

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

Parameters:

• array (Iterable[Any]): Array to iterate over.
• iteratee (Callable, optional): Function invoked per iteration.

Returns:

• float: Arithmetic mean.

Example:

from pydash import mean_by

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

mean_by(objects, 'n')
# 5.0

median

def median(array: Iterable[Union[int, float]]) -> Union[int, float]

Computes the median of the values in array.

Parameters:

• array (Iterable[Union[int, float]]): Array of numbers.

Returns:

• Union[int, float]: Median value.

Example:

from pydash import median

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

median([4, 2, 8, 6, 1])
# 4

sum_

def sum_(array: Iterable[Union[int, float]]) -> Union[int, float]

Computes the sum of the values in array.

Parameters:

• array (Iterable[Union[int, float]]): Array of numbers to sum.

Returns:

• Union[int, float]: Sum of array values.

Example:

from pydash import sum_

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

sum_([1.5, 2.5, 3.0])
# 7.0

sum_by

def sum_by(array: Iterable[Any], iteratee: Callable = None) -> Union[int, float]

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

Parameters:

• array (Iterable[Any]): Array to iterate over.
• iteratee (Callable, optional): Function invoked per iteration.

Returns:

• Union[int, float]: Sum of processed values.

Example:

from pydash import sum_by

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

sum_by(objects, 'n')
# 20

moving_mean

def moving_mean(array: Iterable[Union[int, float]], window: int) -> List[float]

Computes the moving mean of array with a window size of window.

Parameters:

• array (Iterable[Union[int, float]]): Array of numbers.
• window (int): Moving window size.

Returns:

• List[float]: Array of moving means.

Example:

from pydash import moving_mean

moving_mean([1, 2, 3, 4, 5], 3)
# [2.0, 3.0, 4.0]

std_deviation

def std_deviation(array: Iterable[Union[int, float]]) -> float

Computes the standard deviation of the values in array.

Parameters:

• array (Iterable[Union[int, float]]): Array of numbers.

Returns:

• float: Standard deviation.

Example:

from pydash import std_deviation

std_deviation([1, 2, 3, 4, 5])
# 1.5811388300841898

variance

def variance(array: Iterable[Union[int, float]]) -> float

Computes the variance of the values in array.

Parameters:

• array (Iterable[Union[int, float]]): Array of numbers.

Returns:

• float: Variance.

Example:

from pydash import variance

variance([1, 2, 3, 4, 5])
# 2.5

zscore

def zscore(collection: Iterable[Union[int, float]], value: Union[int, float]) -> float

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

Parameters:

• collection (Iterable[Union[int, float]]): Collection of numbers.
• value (Union[int, float]): Value to compute z-score for.

Returns:

• float: Z-score of value.

Example:

from pydash import zscore

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

zscore([1, 2, 3, 4, 5], 5)
# 1.2649110640673518

Scaling and Transformation Functions

scale

def scale(array: Iterable[Union[int, float]], maximum: Union[int, float] = 1) -> List[float]

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

Parameters:

• array (Iterable[Union[int, float]]): Array of numbers to scale.
• maximum (Union[int, float]): Maximum value to scale to. Defaults to 1.

Returns:

• List[float]: Scaled array.

Example:

from pydash import scale

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

scale([1, 2, 3, 4, 5], 10)
# [2.0, 4.0, 6.0, 8.0, 10.0]

slope

def slope(point1: Tuple[Union[int, float], Union[int, float]], point2: Tuple[Union[int, float], Union[int, float]]) -> float

Calculate the slope between two points.

Parameters:

• point1 (Tuple[Union[int, float], Union[int, float]]): First point as (x, y).
• point2 (Tuple[Union[int, float], Union[int, float]]): Second point as (x, y).

Returns:

• float: Slope between the two points.

Example:

from pydash import slope

slope((1, 2), (3, 6))
# 2.0

slope((0, 0), (1, 1))
# 1.0

transpose

def transpose(array: Iterable[Iterable[Any]]) -> List[List[Any]]

Transpose a 2D array (matrix transpose).

Parameters:

• array (Iterable[Iterable[Any]]): 2D array to transpose.

Returns:

• List[List[Any]]: Transposed array.

Example:

from pydash import transpose

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

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

Usage Examples

Basic Arithmetic Operations

from pydash import add, subtract, multiply, divide, power

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

# Power operations
square = power(5, 2)  # 25
square_root = power(16, 0.5)  # 4.0

Statistical Analysis

from pydash import mean, median, std_deviation, variance

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

# Central tendency
avg = mean(data)        # 5.5
mid = median(data)      # 5.5

# Spread measures
std = std_deviation(data)  # 3.0276503540974917
var = variance(data)       # 9.166666666666666

Working with Objects

from pydash import max_by, min_by, sum_by, mean_by

students = [
    {'name': 'Alice', 'score': 85},
    {'name': 'Bob', 'score': 92},
    {'name': 'Charlie', 'score': 78}
]

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

# Calculate totals and averages
total_score = sum_by(students, 'score')    # 255
avg_score = mean_by(students, 'score')     # 85.0

Data Scaling and Normalization

from pydash import scale, clamp, zscore

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

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

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

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

# Calculate z-scores for outlier detection
z_scores = [zscore(raw_data, x) for x in raw_data]

Moving Statistics

from pydash import moving_mean

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

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

# 5-day moving average  
ma_5 = moving_mean(prices, 5)
# [103.0, 104.6, 106.6, 110.0]

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