0
# Mathematical & Statistical Operations
1

2
Mathematical utilities, statistical analysis, and data summarization tools. Includes bit manipulation, number clamping, descriptive statistics, histogram formatting, and comprehensive data analysis capabilities.
3

4
## Capabilities
5

6
### Mathematical Utilities
7

8
Basic mathematical operations and number manipulation.
9

10
```python { .api }
11
def clamp(x, lower=float('-inf'), upper=float('inf')):
12
    """
13
    Clamp value between bounds.
14
    
15
    Parameters:
16
    - x (numeric): Value to clamp
17
    - lower (numeric): Lower bound (default: negative infinity)
18
    - upper (numeric): Upper bound (default: positive infinity)
19
    
20
    Returns:
21
    numeric: Clamped value
22
    """
23

24
def ceil(x, options=None):
25
    """
26
    Ceiling function with rounding options.
27
    
28
    Parameters:
29
    - x (numeric): Value to round up
30
    - options: Rounding options
31
    
32
    Returns:
33
    numeric: Ceiling value
34
    """
35

36
def floor(x, options=None):
37
    """
38
    Floor function with rounding options.
39
    
40
    Parameters:
41
    - x (numeric): Value to round down
42
    - options: Rounding options
43
    
44
    Returns:
45
    numeric: Floor value
46
    """
47
```
48

49
### Bit Manipulation
50

51
Utilities for working with bits and binary operations.
52

53
```python { .api }
54
class Bits:
55
    """Bit manipulation and representation utility class."""
56
    def __init__(self, value=0, length=None): ...
57
    def __getitem__(self, index): ...
58
    def __setitem__(self, index, value): ...
59
    def __len__(self): ...
60
    def __int__(self): ...
61
    def __str__(self): ...
62
    def __repr__(self): ...
63
    def flip(self, index): ...
64
    def set(self, index, value=1): ...
65
    def clear(self, index): ...
66
    def count(self): ...
67
    def to_bytes(self, length=None, byteorder='big'): ...
68
    @classmethod
69
    def from_bytes(cls, bytes_obj, byteorder='big'): ...
70
```
71

72
### Statistical Analysis
73

74
Comprehensive statistical analysis and data summarization.
75

76
```python { .api }
77
class Stats:
78
    """Statistical analysis class with descriptive statistics."""
79
    def __init__(self, data=None): ...
80
    def add(self, value): ...
81
    def extend(self, values): ...
82
    
83
    @property
84
    def count(self): ...
85
    @property
86
    def mean(self): ...
87
    @property
88
    def median(self): ...
89
    @property
90
    def mode(self): ...
91
    @property
92
    def std_dev(self): ...
93
    @property
94
    def variance(self): ...
95
    @property
96
    def min(self): ...
97
    @property
98
    def max(self): ...
99
    @property
100
    def range(self): ...
101
    
102
    def quantile(self, q): ...
103
    def percentile(self, p): ...
104
    def histogram(self, bins=10): ...
105
    def describe(self): ...
106

107
def describe(data, quantiles=None, format=None):
108
    """
109
    Generate descriptive statistics summary.
110
    
111
    Parameters:
112
    - data (iterable): Data to analyze
113
    - quantiles (list, optional): Custom quantiles to calculate
114
    - format (str, optional): Output format ('dict', 'text')
115
    
116
    Returns:
117
    dict or str: Statistical summary
118
    """
119
```
120

121
### Histogram Utilities
122

123
Format and display histogram data.
124

125
```python { .api }
126
def format_histogram_counts(bin_counts, width=None, **kwargs):
127
    """
128
    Format histogram data for display.
129
    
130
    Parameters:
131
    - bin_counts (list): List of (bin_edge, count) tuples
132
    - width (int, optional): Display width for formatting
133
    
134
    Returns:
135
    str: Formatted histogram display
136
    """
137
```
138

139
## Usage Examples
140

141
```python
142
from boltons.mathutils import clamp, Bits
143
from boltons.statsutils import Stats, describe
144

145
# Mathematical operations
146
value = clamp(150, lower=0, upper=100)
147
print(value)  # 100 (clamped to upper bound)
148

149
negative = clamp(-10, lower=0, upper=100)
150
print(negative)  # 0 (clamped to lower bound)
151

152
# Bit manipulation
153
bits = Bits(0b10110010, length=8)
154
print(bits)        # "10110010"
155
print(bits[0])     # 0 (rightmost bit)
156
print(bits[7])     # 1 (leftmost bit)
157

158
bits.set(0)        # Set rightmost bit
159
print(bits)        # "10110011"
160

161
bits.flip(1)       # Flip second bit
162
print(bits)        # "10110001"
163

164
print(f"Set bits: {bits.count()}")  # Count of 1-bits
165

166
# Convert to/from bytes
167
byte_data = bits.to_bytes(1, 'big')
168
new_bits = Bits.from_bytes(byte_data, 'big')
169

170
# Statistical analysis
171
data = [1, 2, 2, 3, 4, 4, 4, 5, 6, 7, 8, 9, 10]
172
stats = Stats(data)
173

174
print(f"Mean: {stats.mean}")           # 5.0
175
print(f"Median: {stats.median}")       # 4.0
176
print(f"Mode: {stats.mode}")           # 4 (most frequent)
177
print(f"Std Dev: {stats.std_dev}")     # Standard deviation
178
print(f"Range: {stats.range}")         # 9 (max - min)
179

180
# Quick statistical summary
181
summary = describe(data)
182
print(summary)  # Dictionary with comprehensive statistics
183

184
# Add more data
185
stats.extend([11, 12, 13, 14, 15])
186
print(f"Updated mean: {stats.mean}")
187

188
# Quantiles and percentiles
189
q1 = stats.quantile(0.25)  # First quartile
190
q3 = stats.quantile(0.75)  # Third quartile
191
p90 = stats.percentile(90) # 90th percentile
192

193
print(f"Q1: {q1}, Q3: {q3}, P90: {p90}")
194
```
195

196
### Advanced Statistical Analysis
197

198
```python
199
from boltons.statsutils import Stats, format_histogram_counts
200
import random
201

202
# Generate sample data
203
random.seed(42)
204
sample_data = [random.gauss(50, 15) for _ in range(1000)]
205

206
# Comprehensive analysis
207
stats = Stats(sample_data)
208
print(f"Dataset size: {stats.count}")
209
print(f"Mean: {stats.mean:.2f}")
210
print(f"Median: {stats.median:.2f}")
211
print(f"Standard deviation: {stats.std_dev:.2f}")
212
print(f"Variance: {stats.variance:.2f}")
213

214
# Histogram analysis
215
histogram_data = stats.histogram(bins=20)
216
formatted_hist = format_histogram_counts(histogram_data, width=60)
217
print("Distribution:")
218
print(formatted_hist)
219

220
# Custom quantile analysis
221
quantiles = [0.1, 0.25, 0.5, 0.75, 0.9, 0.95, 0.99]
222
print("Quantile analysis:")
223
for q in quantiles:
224
    value = stats.quantile(q)
225
    print(f"  {q*100:2.0f}th percentile: {value:.2f}")
226

227
# Detailed description
228
full_description = stats.describe()
229
print("Full statistical description:")
230
for key, value in full_description.items():
231
    print(f"  {key}: {value}")
232
```
233

234
### Bit Operations for Data Processing
235

236
```python
237
from boltons.mathutils import Bits
238

239
# Process flags and permissions
240
permissions = Bits(0b00000000, length=8)
241
READ_BIT = 0
242
WRITE_BIT = 1
243
EXECUTE_BIT = 2
244
ADMIN_BIT = 7
245

246
# Set permissions
247
permissions.set(READ_BIT)
248
permissions.set(WRITE_BIT)
249
permissions.set(ADMIN_BIT)
250

251
print(f"Permissions: {permissions}")  # Binary representation
252
print(f"Can read: {bool(permissions[READ_BIT])}")
253
print(f"Can write: {bool(permissions[WRITE_BIT])}")
254
print(f"Can execute: {bool(permissions[EXECUTE_BIT])}")
255
print(f"Is admin: {bool(permissions[ADMIN_BIT])}")
256

257
# Serialize permissions
258
perm_bytes = permissions.to_bytes(1, 'big')
259
print(f"Serialized: {perm_bytes.hex()}")
260

261
# Deserialize and verify
262
restored_perms = Bits.from_bytes(perm_bytes, 'big')
263
print(f"Restored: {restored_perms}")
264
assert permissions.to_bytes(1, 'big') == restored_perms.to_bytes(1, 'big')
265
```
266

267
## Types
268

269
```python { .api }
270
# Statistical description return type (from Stats.describe())
271
StatisticalSummary = dict  # Contains keys: count, mean, std, min, 25%, 50%, 75%, max
272

273
# Histogram data format
274
HistogramBin = tuple  # (bin_edge, count) pairs
275
```