0
# Mathematical Functions
1

2
Comprehensive mathematical operations including arithmetic, trigonometric, logarithmic, and statistical functions for data analysis and transformations.
3

4
## Capabilities
5

6
### Basic Mathematical Functions
7

8
```python { .api }
9
def abs(x):
10
    """Absolute value of x"""
11

12
def exp(x):
13
    """Exponential function (e^x)"""
14

15
def exp2(x):
16
    """Base-2 exponential function (2^x)"""
17

18
def expm1(x):
19
    """Exponential minus 1 (e^x - 1), accurate for small x"""
20

21
def log(x):
22
    """Natural logarithm (base e)"""
23

24
def log10(x):
25
    """Base-10 logarithm"""
26

27
def log2(x):
28
    """Base-2 logarithm"""
29

30
def log1p(x):
31
    """Logarithm of (1 + x), accurate for small x"""
32

33
def sqrt(x):
34
    """Square root"""
35

36
def cbrt(x):
37
    """Cube root"""
38

39
def square(x):
40
    """Square (x^2)"""
41

42
def pow(x, y):
43
    """x raised to power y"""
44
```
45

46
### Trigonometric Functions
47

48
```python { .api }
49
def sin(x):
50
    """Sine function"""
51

52
def cos(x):
53
    """Cosine function"""
54

55
def tan(x):
56
    """Tangent function"""
57

58
def arcsin(x):
59
    """Inverse sine (arcsine)"""
60

61
def arccos(x):
62
    """Inverse cosine (arccosine)"""
63

64
def arctan(x):
65
    """Inverse tangent (arctangent)"""
66

67
def atan2(y, x):
68
    """Two-argument arctangent"""
69

70
def sinh(x):
71
    """Hyperbolic sine"""
72

73
def cosh(x):
74
    """Hyperbolic cosine"""
75

76
def tanh(x):
77
    """Hyperbolic tangent"""
78

79
def arsinh(x):
80
    """Inverse hyperbolic sine"""
81

82
def arcosh(x):
83
    """Inverse hyperbolic cosine"""
84

85
def artanh(x):
86
    """Inverse hyperbolic tangent"""
87
```
88

89
### Rounding and Comparison Functions
90

91
```python { .api }
92
def ceil(x):
93
    """Ceiling (smallest integer >= x)"""
94

95
def floor(x):
96
    """Floor (largest integer <= x)"""
97

98
def round(x, ndigits=0):
99
    """Round to ndigits decimal places"""
100

101
def rint(x):
102
    """Round to nearest integer"""
103

104
def trunc(x):
105
    """Truncate to integer"""
106

107
def sign(x):
108
    """Sign of x (-1, 0, or 1)"""
109

110
def signbit(x):
111
    """True if sign bit is set"""
112

113
def copysign(x, y):
114
    """Return x with sign of y"""
115

116
def fabs(x):
117
    """Floating-point absolute value"""
118

119
def fmod(x, y):
120
    """Floating-point remainder of x/y"""
121
```
122

123
### Special Functions
124

125
```python { .api }
126
def gamma(x):
127
    """Gamma function"""
128

129
def lgamma(x):
130
    """Natural logarithm of gamma function"""
131

132
def erf(x):
133
    """Error function"""
134

135
def erfc(x):
136
    """Complementary error function"""
137

138
def hypot(x, y):
139
    """Euclidean distance sqrt(x^2 + y^2)"""
140

141
def ldexp(x, i):
142
    """x * 2^i"""
143

144
def logaddexp(x, y):
145
    """log(exp(x) + exp(y))"""
146

147
def logaddexp2(x, y):
148
    """log2(2^x + 2^y)"""
149
```
150

151
### Testing and Utility Functions
152

153
```python { .api }
154
def isna(x):
155
    """Test for missing values (NaN)"""
156

157
def isfinite(x):
158
    """Test for finite values"""
159

160
def isinf(x):
161
    """Test for infinite values"""
162

163
def isclose(x, y, rtol=1e-5, atol=1e-8):
164
    """Test for approximate equality"""
165
```
166

167
### Conditional Functions
168

169
```python { .api }
170
def ifelse(condition, x, y):
171
    """Return x where condition is True, y otherwise"""
172
```
173

174
### Mathematical Constants
175

176
```python { .api }
177
e: float        # Euler's number (2.718281828...)
178
pi: float       # Pi (3.141592653...)
179
tau: float      # Tau (2*pi, 6.283185307...)
180
golden: float   # Golden ratio (1.618033988...)
181
nan: float      # Not-a-Number
182
inf: float      # Positive infinity
183
```
184

185
### Conversion Functions
186

187
```python { .api }
188
def deg2rad(x):
189
    """Convert degrees to radians"""
190

191
def rad2deg(x):
192
    """Convert radians to degrees"""
193
```
194

195
## Usage Examples
196

197
### Basic Arithmetic Operations
198

199
```python
200
import datatable as dt
201
from datatable import f
202

203
DT = dt.Frame({
204
    'x': [-2, -1, 0, 1, 2],
205
    'y': [0.5, 1.0, 1.5, 2.0, 2.5],
206
    'z': [4, 9, 16, 25, 36]
207
})
208

209
# Basic functions
210
result = DT[:, dt.update(
211
    abs_x=dt.math.abs(f.x),
212
    sqrt_z=dt.math.sqrt(f.z),
213
    square_y=dt.math.square(f.y),
214
    exp_x=dt.math.exp(f.x)
215
)]
216

217
# Logarithmic functions
218
result = DT[:, dt.update(
219
    log_y=dt.math.log(f.y),
220
    log10_z=dt.math.log10(f.z),
221
    log2_z=dt.math.log2(f.z)
222
)]
223
```
224

225
### Trigonometric Calculations
226

227
```python
228
import datatable as dt
229

230
# Create angles in radians
231
angles = dt.Frame({'radians': [0, dt.math.pi/6, dt.math.pi/4, dt.math.pi/3, dt.math.pi/2]})
232

233
# Trigonometric functions
234
trig_results = angles[:, dt.update(
235
    sin_val=dt.math.sin(f.radians),
236
    cos_val=dt.math.cos(f.radians),
237
    tan_val=dt.math.tan(f.radians)
238
)]
239

240
# Convert degrees to radians
241
degrees = dt.Frame({'degrees': [0, 30, 45, 60, 90]})
242
result = degrees[:, dt.update(
243
    radians=dt.math.deg2rad(f.degrees),
244
    sin_deg=dt.math.sin(dt.math.deg2rad(f.degrees))
245
)]
246
```
247

248
### Rounding and Precision
249

250
```python
251
DT = dt.Frame({
252
    'values': [1.234, 2.567, 3.891, 4.125, 5.999]
253
})
254

255
# Different rounding methods
256
result = DT[:, dt.update(
257
    rounded=dt.math.round(f.values, 2),
258
    ceiling=dt.math.ceil(f.values),
259
    floor=dt.math.floor(f.values),
260
    truncated=dt.math.trunc(f.values)
261
)]
262

263
# Sign operations
264
mixed_values = dt.Frame({'x': [-3.2, -0.1, 0, 0.1, 3.2]})
265
result = mixed_values[:, dt.update(
266
    sign=dt.math.sign(f.x),
267
    abs_val=dt.math.abs(f.x),
268
    signbit=dt.math.signbit(f.x)
269
)]
270
```
271

272
### Statistical and Special Functions
273

274
```python
275
# Probability distributions
276
x_vals = dt.Frame({'x': [-2, -1, 0, 1, 2]})
277
result = x_vals[:, dt.update(
278
    erf_x=dt.math.erf(f.x),
279
    erfc_x=dt.math.erfc(f.x),
280
    gamma_x=dt.math.gamma(f.x + 1)  # Avoid negative values for gamma
281
)]
282

283
# Distance calculations
284
points = dt.Frame({
285
    'x1': [0, 1, 3],
286
    'y1': [0, 2, 4],
287
    'x2': [3, 4, 0],
288
    'y2': [4, 6, 0]
289
})
290

291
distances = points[:, dt.update(
292
    euclidean=dt.math.hypot(f.x2 - f.x1, f.y2 - f.y1)
293
)]
294
```
295

296
### Missing Value Handling
297

298
```python
299
DT = dt.Frame({
300
    'a': [1, None, 3, 4, 5],
301
    'b': [2.5, 3.0, None, 4.5, 5.0]
302
})
303

304
# Mathematical functions with missing values
305
result = DT[:, dt.update(
306
    sqrt_a=dt.math.sqrt(f.a),        # sqrt(None) = None
307
    log_b=dt.math.log(f.b),          # log(None) = None
308
    is_missing_a=dt.math.isna(f.a),  # Check for missing values
309
    is_finite_b=dt.math.isfinite(f.b)  # Check for finite values
310
)]
311

312
# Conditional mathematical operations
313
result = DT[:, dt.update(
314
    safe_log=dt.ifelse(dt.math.isna(f.b) | (f.b <= 0), 
315
                      None, 
316
                      dt.math.log(f.b))
317
)]
318
```
319

320
### Complex Mathematical Expressions
321

322
```python
323
# Financial calculations
324
principal = dt.Frame({
325
    'P': [1000, 2000, 5000],      # Principal
326
    'r': [0.05, 0.03, 0.07],      # Interest rate
327
    't': [1, 2, 3]                # Time in years
328
})
329

330
# Compound interest: A = P(1 + r)^t
331
result = principal[:, dt.update(
332
    amount=f.P * dt.math.pow(1 + f.r, f.t),
333
    interest=f.P * dt.math.pow(1 + f.r, f.t) - f.P
334
)]
335

336
# Continuous compounding: A = Pe^(rt)
337
result = principal[:, dt.update(
338
    continuous_amount=f.P * dt.math.exp(f.r * f.t)
339
)]
340
```
341

342
### Numerical Stability
343

344
```python
345
# Stable calculations for small numbers
346
small_vals = dt.Frame({'x': [1e-10, 1e-15, 1e-20]})
347

348
# Use log1p for log(1 + x) when x is small
349
result = small_vals[:, dt.update(
350
    log1p_stable=dt.math.log1p(f.x),
351
    log_unstable=dt.math.log(1 + f.x)
352
)]
353

354
# Use expm1 for exp(x) - 1 when x is small  
355
result = small_vals[:, dt.update(
356
    expm1_stable=dt.math.exp(f.x) - 1,  # Note: expm1 not in API, using exp(x) - 1
357
    exp_minus_one=dt.math.exp(f.x) - 1
358
)]
359
```
360

361
### Mathematical Constants Usage
362

363
```python
364
# Using mathematical constants
365
circle = dt.Frame({'radius': [1, 2, 3, 4, 5]})
366

367
result = circle[:, dt.update(
368
    circumference=2 * dt.math.pi * f.radius,
369
    area=dt.math.pi * dt.math.square(f.radius),
370
    tau_circumference=dt.math.tau * f.radius  # Alternative using tau
371
)]
372

373
# Golden ratio applications
374
fibonacci = dt.Frame({'n': [1, 2, 3, 4, 5, 6, 7, 8]})
375
result = fibonacci[:, dt.update(
376
    approx_fib=dt.math.round(
377
        dt.math.pow(dt.math.golden, f.n) / dt.math.sqrt(5)
378
    )
379
)]
380
```
381

382
### Comparison and Testing
383

384
```python
385
# Approximate equality testing
386
values1 = dt.Frame({'a': [1.0, 2.0, 3.0]})
387
values2 = dt.Frame({'b': [1.0000001, 1.9999999, 3.0000001]})
388

389
comparison = dt.cbind(values1, values2)
390
result = comparison[:, dt.update(
391
    exactly_equal=(f.a == f.b),
392
    approximately_equal=dt.math.isclose(f.a, f.b, rtol=1e-6)
393
)]
394

395
# Testing for special values
396
test_vals = dt.Frame({'x': [1.0, dt.math.inf, -dt.math.inf, dt.math.nan, 0.0]})
397
result = test_vals[:, dt.update(
398
    is_finite=dt.math.isfinite(f.x),
399
    is_infinite=dt.math.isinf(f.x),
400
    is_nan=dt.math.isna(f.x)
401
)]
402
```