Analysis Guide

The analysis layer is a reasoning substrate for AI agents. Not a calculator — a system that produces structured explanations agents can parse, chain, and act on.

The Difference

Without analysis:

Agent: "Revenue is £17.7M"

With analysis:

Agent: "Revenue dropped 20% last month, driven by Germany (-72% of change).
        94% of revenue is concentrated in 3 countries — critical risk.
        Churned customers are independent of high spenders (Jaccard=0.049) —
        churn is a frequency problem, not a value problem."

Same data. Different level of understanding.

All 22 Primitives

See the complete reference for every primitive with parameters and examples.

Core (7 — available on Free plan)

Primitive	Question it answers
health	Is this metric behaving normally?
trends	Is this accelerating or decelerating?
drivers	Which dimension explains the most variance?
segment_performance	How does this vary across segments?
contribution	What drove the change between periods?
compare	How do two groups or time periods differ?
anomalies	Which data points are outliers?

Advanced (15 — Team plan and above)

Primitive	Question it answers
correlate	Do two metrics move together?
root_cause	Why did this metric change?
sensitivity	What's the concentration risk?
forecast	Where is this metric heading?
causal_impact	Did a specific event change the metric?
scenario	What if we change a segment by X%?
benchmark	How does this compare to its historical range?
cohort	How do user cohorts retain over time?
funnel	Where do users drop off in a process?
metric_impact	If metric A changes, how does B respond?
counterfactual	What would the total be without a segment?
monitor	Is a threshold condition currently triggered?
data_quality	Nulls, duplicates, freshness, schema health
pareto	Which segments account for 80% of the total?
threshold	What's the optimal natural breakpoint?

Response Contract

Every analysis method returns:

{
    "value": {},
    "explanation": "one sentence, plain English",
    "confidence": 0.85,
    "warnings": [],
    "suggested_actions": [],
    "metric_health": {}
}

Agents don't need to interpret numbers. The explanation is readable. The suggested_actions are actionable. The confidence tells them when to trust it.

Agent Reasoning Chain

The analysis methods compose. An agent investigating "why is churn increasing?" would:

# 1. What's happening?
trends = om.analysis.trends("churn_risk")
# → momentum: accelerating

# 2. Which dimensions explain it?
drivers = om.analysis.drivers("churn_by_country", dimensions=["country", "tier"])
# → country CV=5.7 (explains most variance)

# 3. Where is it concentrated?
sensitivity = om.analysis.sensitivity("churn_by_country", "country", scenario="remove_top_3")
# → 94% in top 3 countries, risk=critical

# 4. Is it related to spending?
correlation = om.analysis.correlate("churned_customers", "high_spenders")
# → Jaccard=0.049, independent

# 5. What would happen without the worst country?
counterfactual = om.analysis.counterfactual("churn_by_country", remove={"country": "UK"})
# → churn would drop 35%

# Agent builds explanation:
# "Churn is accelerating, concentrated in 3 countries (94%),
#  and independent of spending level. Removing UK alone would
#  reduce churn by 35%. This is a frequency/engagement problem,
#  not a value problem."

Six calls. One coherent explanation. That's the reasoning substrate.