Skip to content

Statistics

concrete_fhe_toolkit.stats

Encrypted statistics and private-analytics helpers.

These are traceable building blocks over bounded encrypted integers. The order-statistics helpers (median, percentile) reuse the bitonic sorting network, so they require a power-of-two array length. Helpers that build lookup tables take explicit min_value / max_value bounds.

array_mean 

array_mean(array: Union[ndarray, List[Any]]) -> Any

Calculate the floor mean of an encrypted array.

Parameters:

Name Type Description Default
array Union[ndarray, List[Any]]

The encrypted array or list of elements.

 required

Returns:

Name Type Description
Any Any

The integer floor mean of the elements.
Example 
from concrete_fhe_toolkit.stats import array_mean

print(array_mean([2, 4, 6]))  # 4
Source code in src/concrete_fhe_toolkit/stats.py 
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
def array_mean(array: Union[np.ndarray, List[Any]]) -> Any:
    """Calculate the floor mean of an encrypted array.

    Args:
        array (Union[np.ndarray, List[Any]]): The encrypted array or list of elements.

    Returns:
        Any: The integer floor mean of the elements.

    Example:
        ```python
        from concrete_fhe_toolkit.stats import array_mean

        print(array_mean([2, 4, 6]))  # 4
        ```
    """
    return array_sum(array) // len(array)

array_variance 

array_variance(array: Union[ndarray, List[Any]]) -> Any

Calculate the floor variance of an encrypted array.

Parameters:

Name Type Description Default
array Union[ndarray, List[Any]]

The encrypted array or list of elements.

 required

Returns:

Name Type Description
Any Any

The integer floor variance of the elements.
Example 
from concrete_fhe_toolkit.stats import array_variance

print(array_variance([2, 4, 6]))  # 2
Source code in src/concrete_fhe_toolkit/stats.py 
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
def array_variance(array: Union[np.ndarray, List[Any]]) -> Any:
    """Calculate the floor variance of an encrypted array.

    Args:
        array (Union[np.ndarray, List[Any]]): The encrypted array or list of elements.

    Returns:
        Any: The integer floor variance of the elements.

    Example:
        ```python
        from concrete_fhe_toolkit.stats import array_variance

        print(array_variance([2, 4, 6]))  # 2
        ```
    """
    tensor = _ensure_tensor(array)
    mean_value = array_mean(tensor)
    diffs = tensor - mean_value
    diff_sum = np.sum(diffs * diffs)
    return diff_sum // len(array)

array_std 

array_std(array: Union[ndarray, List[Any]], min_value: int, max_value: int) -> Any

Calculate the integer standard deviation (isqrt of the variance).

min_value / max_value bound the array elements; the isqrt lookup is built over the worst-case variance for that range.

Parameters:

Name Type Description Default
array Union[ndarray, List[Any]]

The encrypted array or list of elements.

 required
min_value int

The lower bound for the encrypted inputs, used to dimension the FHE circuit.

 required
max_value int

The upper bound for the encrypted inputs, used to dimension the FHE circuit.

 required

Returns:

Name Type Description
Any Any

The integer standard deviation of the elements.
Example 
from concrete_fhe_toolkit.stats import array_std

# Used inside an FHE program compilation
std_val = array_std([2, 4, 6], min_value=0, max_value=10)
Source code in src/concrete_fhe_toolkit/stats.py 
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
def array_std(array: Union[np.ndarray, List[Any]], min_value: int, max_value: int) -> Any:
    """Calculate the integer standard deviation (isqrt of the variance).

    ``min_value`` / ``max_value`` bound the array elements; the isqrt lookup
    is built over the worst-case variance for that range.

    Args:
        array (Union[np.ndarray, List[Any]]): The encrypted array or list of elements.
        min_value (int): The lower bound for the encrypted inputs, used to dimension the FHE circuit.
        max_value (int): The upper bound for the encrypted inputs, used to dimension the FHE circuit.

    Returns:
        Any: The integer standard deviation of the elements.

    Example:
        ```python
        from concrete_fhe_toolkit.stats import array_std

        # Used inside an FHE program compilation
        std_val = array_std([2, 4, 6], min_value=0, max_value=10)
        ```
    """
    minimum_value, maximum_value = validate_bounds(min_value, max_value)
    span = maximum_value - minimum_value
    variance = array_variance(array)
    if span == 0:
        return variance
    isqrt = make_isqrt(span * span)
    return isqrt(variance)

array_covariance 

array_covariance(array1: Union[ndarray, List[Any]], array2: Union[ndarray, List[Any]]) -> Any

Calculate the floor covariance of two encrypted arrays.

Parameters:

Name Type Description Default
array1 Union[ndarray, List[Any]]

The first encrypted array.

 required
array2 Union[ndarray, List[Any]]

The second encrypted array.

 required

Returns:

Name Type Description
Any Any

The integer floor covariance of the two arrays.
Example 
from concrete_fhe_toolkit.stats import array_covariance

print(array_covariance([1, 2, 3], [1, 2, 3]))  # 0
Source code in src/concrete_fhe_toolkit/stats.py 
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
def array_covariance(array1: Union[np.ndarray, List[Any]], array2: Union[np.ndarray, List[Any]]) -> Any:
    """Calculate the floor covariance of two encrypted arrays.

    Args:
        array1 (Union[np.ndarray, List[Any]]): The first encrypted array.
        array2 (Union[np.ndarray, List[Any]]): The second encrypted array.

    Returns:
        Any: The integer floor covariance of the two arrays.

    Example:
        ```python
        from concrete_fhe_toolkit.stats import array_covariance

        print(array_covariance([1, 2, 3], [1, 2, 3]))  # 0
        ```
    """
    if len(array1) != len(array2):
        raise ValueError("The array sizes must be equal")
    tensor1 = _ensure_tensor(array1)
    tensor2 = _ensure_tensor(array2)
    mean1 = array_mean(tensor1)
    mean2 = array_mean(tensor2)
    product_sum: Any = np.sum((tensor1 - mean1) * (tensor2 - mean2))
    return product_sum // len(array1)

array_max 

array_max(elements: Union[ndarray, List[Any]]) -> Any

Find the maximum value in an encrypted array using a tournament reduction.

Parameters:

Name Type Description Default
elements Union[ndarray, List[Any]]

The encrypted array or list of elements.

 required

Returns:

Name Type Description
Any Any

The maximum value found in the array.
Example 
from concrete_fhe_toolkit.stats import array_max

print(array_max([1, 5, 3]))  # 5
Source code in src/concrete_fhe_toolkit/stats.py 
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
def array_max(elements: Union[np.ndarray, List[Any]]) -> Any:
    """Find the maximum value in an encrypted array using a tournament reduction.

    Args:
        elements (Union[np.ndarray, List[Any]]): The encrypted array or list of elements.

    Returns:
        Any: The maximum value found in the array.

    Example:
        ```python
        from concrete_fhe_toolkit.stats import array_max

        print(array_max([1, 5, 3]))  # 5
        ```
    """
    max_item = np.max(_ensure_tensor(elements))
    return max_item

array_min 

array_min(elements: Union[ndarray, List[Any]]) -> Any

Find the minimum value in an encrypted array using a tournament reduction.

Parameters:

Name Type Description Default
elements Union[ndarray, List[Any]]

The encrypted array or list of elements.

 required

Returns:

Name Type Description
Any Any

The minimum value found in the array.
Example 
from concrete_fhe_toolkit.stats import array_min

print(array_min([1, 5, 3]))  # 1
Source code in src/concrete_fhe_toolkit/stats.py 
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
def array_min(elements: Union[np.ndarray, List[Any]]) -> Any:
    """Find the minimum value in an encrypted array using a tournament reduction.

    Args:
        elements (Union[np.ndarray, List[Any]]): The encrypted array or list of elements.

    Returns:
        Any: The minimum value found in the array.

    Example:
        ```python
        from concrete_fhe_toolkit.stats import array_min

        print(array_min([1, 5, 3]))  # 1
        ```
    """
    min_item = np.min(_ensure_tensor(elements))
    return min_item

array_range 

array_range(array: Union[ndarray, List[Any]]) -> Any

Calculate the range (max - min) of an encrypted array.

Parameters:

Name Type Description Default
array Union[ndarray, List[Any]]

The encrypted array or list of elements.

 required

Returns:

Name Type Description
Any Any

The difference between the maximum and minimum values in the array.
Example 
from concrete_fhe_toolkit.stats import array_range

print(array_range([1, 5, 3]))  # 4
Source code in src/concrete_fhe_toolkit/stats.py 
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
def array_range(array: Union[np.ndarray, List[Any]]) -> Any:
    """Calculate the range (max - min) of an encrypted array.

    Args:
        array (Union[np.ndarray, List[Any]]): The encrypted array or list of elements.

    Returns:
        Any: The difference between the maximum and minimum values in the array.

    Example:
        ```python
        from concrete_fhe_toolkit.stats import array_range

        print(array_range([1, 5, 3]))  # 4
        ```
    """
    return array_max(array) - array_min(array)

array_count_greater 

array_count_greater(array: Union[ndarray, List[Any]], threshold: Any) -> Any

Count how many elements are strictly greater than a threshold.

Parameters:

Name Type Description Default
array Union[ndarray, List[Any]]

The encrypted array or list of elements.

 required
threshold Any

The value to compare each element against.

 required

Returns:

Name Type Description
Any Any

The count of elements that are strictly greater than the threshold.
Example 
from concrete_fhe_toolkit.stats import array_count_greater

print(array_count_greater([1, 5, 3], threshold=2))  # 2
Source code in src/concrete_fhe_toolkit/stats.py 
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
def array_count_greater(array: Union[np.ndarray, List[Any]], threshold: Any) -> Any:
    """Count how many elements are strictly greater than a threshold.

    Args:
        array (Union[np.ndarray, List[Any]]): The encrypted array or list of elements.
        threshold (Any): The value to compare each element against.

    Returns:
        Any: The count of elements that are strictly greater than the threshold.

    Example:
        ```python
        from concrete_fhe_toolkit.stats import array_count_greater

        print(array_count_greater([1, 5, 3], threshold=2))  # 2
        ```
    """
    return np.sum(_ensure_tensor(array) > threshold)

array_median 

array_median(array: Union[ndarray, List[Any]], min_value: int, max_value: int) -> Any

Return the median of an encrypted array (floor average of the middle pair).

Uses the bitonic sorting network, so the array length must be a power of two.

Parameters:

Name Type Description Default
array Union[ndarray, List[Any]]

The encrypted array or list of elements.

 required
min_value int

The lower bound for the encrypted inputs, used to dimension the FHE circuit.

 required
max_value int

The upper bound for the encrypted inputs, used to dimension the FHE circuit.

 required

Returns:

Name Type Description
Any Any

The median value of the array.
Example 
from concrete_fhe_toolkit.stats import array_median

# Used inside an FHE program compilation
median_val = array_median([1, 5, 3, 4], min_value=0, max_value=10)
Source code in src/concrete_fhe_toolkit/stats.py 
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
def array_median(array: Union[np.ndarray, List[Any]], min_value: int, max_value: int) -> Any:
    """Return the median of an encrypted array (floor average of the middle pair).

    Uses the bitonic sorting network, so the array length must be a power
    of two.

    Args:
        array (Union[np.ndarray, List[Any]]): The encrypted array or list of elements.
        min_value (int): The lower bound for the encrypted inputs, used to dimension the FHE circuit.
        max_value (int): The upper bound for the encrypted inputs, used to dimension the FHE circuit.

    Returns:
        Any: The median value of the array.

    Example:
        ```python
        from concrete_fhe_toolkit.stats import array_median

        # Used inside an FHE program compilation
        median_val = array_median([1, 5, 3, 4], min_value=0, max_value=10)
        ```
    """
    items = list(array)
    size = validate_size(len(items), power_of_two=True)
    minimum_value, maximum_value = validate_bounds(min_value, max_value)
    sort_values = make_sort(size, minimum_value, maximum_value)
    ordered = sort_values(items)
    middle = size // 2
    if size % 2 == 1:
        return ordered[middle]
    return (ordered[middle - 1] + ordered[middle]) // 2

array_percentile 

array_percentile(array: Union[ndarray, List[Any]], q: int, min_value: int, max_value: int) -> Any

Return the nearest-rank q-th percentile (0..100) of an encrypted array.

Uses the bitonic sorting network, so the array length must be a power of two.

Parameters:

Name Type Description Default
array Union[ndarray, List[Any]]

The encrypted array or list of elements.

 required
q int

The percentile to compute, between 0 and 100 inclusive.

 required
min_value int

The lower bound for the encrypted inputs, used to dimension the FHE circuit.

 required
max_value int

The upper bound for the encrypted inputs, used to dimension the FHE circuit.

 required

Returns:

Name Type Description
Any Any

The value at the q-th percentile.
Example 
from concrete_fhe_toolkit.stats import array_percentile

# 50th percentile (median)
perc = array_percentile([1, 5, 3, 4], q=50, min_value=0, max_value=10)
Source code in src/concrete_fhe_toolkit/stats.py 
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
def array_percentile(array: Union[np.ndarray, List[Any]], q: int, min_value: int, max_value: int) -> Any:
    """Return the nearest-rank q-th percentile (0..100) of an encrypted array.

    Uses the bitonic sorting network, so the array length must be a power
    of two.

    Args:
        array (Union[np.ndarray, List[Any]]): The encrypted array or list of elements.
        q (int): The percentile to compute, between 0 and 100 inclusive.
        min_value (int): The lower bound for the encrypted inputs, used to dimension the FHE circuit.
        max_value (int): The upper bound for the encrypted inputs, used to dimension the FHE circuit.

    Returns:
        Any: The value at the q-th percentile.

    Example:
        ```python
        from concrete_fhe_toolkit.stats import array_percentile

        # 50th percentile (median)
        perc = array_percentile([1, 5, 3, 4], q=50, min_value=0, max_value=10)
        ```
    """
    items = list(array)
    size = validate_size(len(items), power_of_two=True)
    percent = validate_integer("q", q, minimum=0)
    if percent > 100:
        raise ValueError("q must be between 0 and 100")
    minimum_value, maximum_value = validate_bounds(min_value, max_value)
    sort_values = make_sort(size, minimum_value, maximum_value)
    ordered = sort_values(items)
    rank = round(percent / 100 * (size - 1))
    return ordered[rank]

array_histogram 

array_histogram(array: Union[ndarray, List[Any]], min_value: int, max_value: int) -> Union[np.ndarray, List[Any]]

Count occurrences of every value in [min_value, max_value] (bincount).

Parameters:

Name Type Description Default
array Union[ndarray, List[Any]]

The encrypted array or list of elements.

 required
min_value int

The lower bound for the encrypted inputs, used to dimension the FHE circuit.

 required
max_value int

The upper bound for the encrypted inputs, used to dimension the FHE circuit.

 required

Returns:

Type Description
Union[ndarray, List[Any]]

Union[np.ndarray, List[Any]]: An array containing the count of occurrences for each value from min_value to max_value.
Example 
from concrete_fhe_toolkit.stats import array_histogram

print(array_histogram([1, 2, 1], min_value=1, max_value=3))  # [2, 1, 0]
Source code in src/concrete_fhe_toolkit/stats.py 
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
def array_histogram(array: Union[np.ndarray, List[Any]], min_value: int, max_value: int) -> Union[np.ndarray, List[Any]]:
    """Count occurrences of every value in [min_value, max_value] (bincount).

    Args:
        array (Union[np.ndarray, List[Any]]): The encrypted array or list of elements.
        min_value (int): The lower bound for the encrypted inputs, used to dimension the FHE circuit.
        max_value (int): The upper bound for the encrypted inputs, used to dimension the FHE circuit.

    Returns:
        Union[np.ndarray, List[Any]]: An array containing the count of occurrences for each value from min_value to max_value.

    Example:
        ```python
        from concrete_fhe_toolkit.stats import array_histogram

        print(array_histogram([1, 2, 1], min_value=1, max_value=3))  # [2, 1, 0]
        ```
    """
    minimum_value, maximum_value = validate_bounds(min_value, max_value)
    items = list(array)
    arr = fhe.array(items)
    counts = []
    for value in range(minimum_value, maximum_value + 1):
        # Tensor broadcast equality, avoiding scalar boolean fallback issues
        mask = (arr == value) * 1
        # Use existing efficient tournament reduction over the mask
        counts.append(array_sum(list(mask)))
    return fhe.array(counts)

array_mode 

array_mode(array: Union[ndarray, List[Any]], min_value: int, max_value: int) -> Any

Return the most frequent value (smallest value wins ties).

Parameters:

Name Type Description Default
array Union[ndarray, List[Any]]

The encrypted array or list of elements.

 required
min_value int

The lower bound for the encrypted inputs, used to dimension the FHE circuit.

 required
max_value int

The upper bound for the encrypted inputs, used to dimension the FHE circuit.

 required

Returns:

Name Type Description
Any Any

The most frequent value in the array.
Example 
from concrete_fhe_toolkit.stats import array_mode

# Used inside an FHE program compilation
mode_val = array_mode([1, 2, 2, 3], min_value=1, max_value=5)
Source code in src/concrete_fhe_toolkit/stats.py 
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
def array_mode(array: Union[np.ndarray, List[Any]], min_value: int, max_value: int) -> Any:
    """Return the most frequent value (smallest value wins ties).

    Args:
        array (Union[np.ndarray, List[Any]]): The encrypted array or list of elements.
        min_value (int): The lower bound for the encrypted inputs, used to dimension the FHE circuit.
        max_value (int): The upper bound for the encrypted inputs, used to dimension the FHE circuit.

    Returns:
        Any: The most frequent value in the array.

    Example:
        ```python
        from concrete_fhe_toolkit.stats import array_mode

        # Used inside an FHE program compilation
        mode_val = array_mode([1, 2, 2, 3], min_value=1, max_value=5)
        ```
    """
    minimum_value, maximum_value = validate_bounds(min_value, max_value)
    counts = array_histogram(array, minimum_value, maximum_value)
    if len(counts) == 1:
        return minimum_value + counts[0] - counts[0]
    arg_max = make_argmax(len(counts), 0, len(list(array)))
    return minimum_value + arg_max(counts)

array_normalize 

array_normalize(array: Union[ndarray, List[Any]], mean: Any, scale: int) -> Union[np.ndarray, List[Any]]

Return (x - mean) * scale for every element (z-score style affine transform).

Parameters:

Name Type Description Default
array Union[ndarray, List[Any]]

The encrypted array or list of elements.

 required
mean Any

The mean value to subtract from each element.

 required
scale int

The scaling factor applied to the fixed-point representation.

 required

Returns:

Type Description
Union[ndarray, List[Any]]

Union[np.ndarray, List[Any]]: A new array containing the normalized elements.
Example 
from concrete_fhe_toolkit.stats import array_normalize

print(array_normalize([2, 4, 6], mean=4, scale=10))  # [-20, 0, 20]
Source code in src/concrete_fhe_toolkit/stats.py 
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
def array_normalize(array: Union[np.ndarray, List[Any]], mean: Any, scale: int) -> Union[np.ndarray, List[Any]]:
    """Return (x - mean) * scale for every element (z-score style affine transform).

    Args:
        array (Union[np.ndarray, List[Any]]): The encrypted array or list of elements.
        mean (Any): The mean value to subtract from each element.
        scale (int): The scaling factor applied to the fixed-point representation.

    Returns:
        Union[np.ndarray, List[Any]]: A new array containing the normalized elements.

    Example:
        ```python
        from concrete_fhe_toolkit.stats import array_normalize

        print(array_normalize([2, 4, 6], mean=4, scale=10))  # [-20, 0, 20]
        ```
    """
    normalized_scale = validate_integer("scale", scale, minimum=1)
    arr = fhe.array(array)
    # Native tensor arithmetic bypasses boolean / node graph explosion
    return (arr - mean) * normalized_scale