Analytics statistics and inference

This page describes five files of the analytics module in src/cluster_erp/modules/analytics/: statistics.py (robust descriptives and outlier screens), inference.py (hypothesis tests and models), inference_service.py (the fetch layer that turns declared facts into samples), distributions.py (the distribution functions behind p-values), and stratification.py (stratified ratios). Every method turns its precondition into a gate and refuses to answer when the precondition fails (src/cluster_erp/modules/analytics/statistics.py:1-14).

Scope and source¶

• Defined in: StatisticsEngine (src/cluster_erp/modules/analytics/statistics.py:97), the pure test functions in inference.py, InferenceEngine (src/cluster_erp/modules/analytics/inference_service.py:153), distributions.py, and stratified_ratio (src/cluster_erp/modules/analytics/stratification.py:54).
• Routes: GET /analysis/statistics/{fact_key}/{column}, GET /analysis/outliers/{fact_key}/{column}, GET /analysis/stratified/{fact_key}, GET /analysis/levels/{fact_key}, and the routes under /analysis/tests/, /analysis/pca/, and /analysis/cluster/ (src/cluster_erp/modules/analytics/routes.py:117-940).

Descriptive statistics and outliers¶

The engine supports the quantile types 1 and 7, the two that the database computes natively (src/cluster_erp/modules/analytics/statistics.py:64-68). The parameters come from settings: analytics_quantile_type (default 1), analytics_trimmed_mean_pct (10), analytics_mad_sigma_constant (1.4826), analytics_min_n_for_zscore (11), and analytics_min_iqr_for_fence (0) (src/cluster_erp/config/settings.py:437-452, src/cluster_erp/modules/analytics/service.py:242-253). The docstring states that an outlier screen is a human review queue, never an automatic deletion or correction (src/cluster_erp/modules/analytics/statistics.py:21-25).

Hypothesis tests and models¶

Each test is a pure function on lists. InferenceEngine fetches the samples and calls it.

Rules stated by the module (src/cluster_erp/modules/analytics/inference.py:1-34):

• Each test returns an effect size with its p-value.
• Two constant groups make t undefined; the test is refused.
• Chi-square follows Cochran's rule; a larger table that violates it is refused with the offending counts.
• Mann-Whitney uses the exact distribution for small tie-free groups and otherwise a corrected normal approximation, and says which.
• Every measurement is returned as a string; counts stay integers.

Sample fetching¶

InferenceEngine is the only place samples come from (src/cluster_erp/modules/analytics/inference_service.py:1-17):

• Columns resolve through profile_targets, the same allow-list as every other reader.
• The fact's live filter always applies.
• A monetary value column spanning several currencies is refused with the currency dimension named.
• Rows are capped by analytics_inference_max_rows (default 100000), and the cap refuses instead of truncating (src/cluster_erp/config/settings.py:524, src/cluster_erp/modules/analytics/inference_service.py:156-158).
• Null values are excluded and counted in the answer.

GET /analysis/levels/{fact_key} lists the levels of a dimension so that the interface can offer groups (src/cluster_erp/modules/analytics/routes.py:385-407, src/cluster_erp/modules/analytics/inference_service.py:571).

Distribution functions¶

distributions.py implements the normal, gamma, beta, t, F, and chi-square functions behind p-values from standard numerical algorithms on the standard library, without extra dependencies, in double precision (src/cluster_erp/modules/analytics/distributions.py:1-17, src/cluster_erp/modules/analytics/distributions.py:31-185).

Stratified ratios¶

stratified_ratio returns three rates per group, each labelled with the question it answers: the stratified rate, the crude rate, and the directly standardised rate. It flags a reversal between the crude and standardised rankings and reports coverage when a group has no observations in a stratum (src/cluster_erp/modules/analytics/stratification.py:1-35, src/cluster_erp/modules/analytics/stratification.py:54, src/cluster_erp/modules/analytics/stratification.py:195). The route is GET /analysis/stratified/{fact_key} (src/cluster_erp/modules/analytics/routes.py:310-383).

Constraints and validation¶

• Statistical figures are computed in IEEE double; monetary inputs are converted to float for test statistics only (src/cluster_erp/modules/analytics/distributions.py:11-17). See the discrepancy on analytics module.
• All engines are built at one point in the service, so every answer uses the same quantile type and gates (src/cluster_erp/modules/analytics/service.py:242-253).

Terms introduced¶

Related pages¶

• Analytics module
• Recipes and query builder
• Forecasting and classification
• Reports, summaries, and cross

Verified against commit 92f8051 on 2026-11-13.