# xplain

> Python client for the Xplain Object Explorer (XOE) server: load a startup (dataset), run aggregations over an
> object tree (root -> children -> grandchildren), select states, build derived dimensions, export rows to pandas.

Install: `pip install xplain`. Agent skill with helpers, traps and verified recipes: run `xplain skill path` (or
`xplain skill install` for Claude Code). The skill is the most reliable way for an LLM to use this package.

## Start
```python
import xplain
# profile from ~/.xplainpyrc or XPLAIN_* env vars; or connect(url=..., user=..., password=..., startup=...)
with xplain.connect("local", startup="MyStartup") as s:
    q = xplain.QueryConfig()
    q.add_aggregation(object_name="Event", dimension_name="Type", type="COUNT")
    q.add_groupby(attribute_name="Type", object_name="Event", dimension_name="Type")
    df = s.execute_query(q, leaves_only=True, strict=True)
```
Object, dimension and attribute names differ per startup: list them with `s.get_full_object_structure()` first.
XOE behind Keycloak/OIDC: `xplain.connect(url=..., oidc_issuer=..., oidc_client_id=...)` (device login once, then a
cached token); in scripts without a terminal run `xplain login` beforehand.

## Semantics that cause silent wrong answers
- A selection on a child object never restricts its ancestors in `execute_query`: COUNT of the parent stays the full
  population. Count distinct parents with `{"object": child, "dimension": "<parent key>", "type": "COUNTENTITY"}`.
- `execute_query` ignores global selections (`select()`) unless `use_global_selections=True`; exports honour them.
- The server ignores unknown selection states. States are full labels as stored (e.g. `"J45 -- Asthma"`, not `"J45"`);
  find them with `s.explore.get_tree_containing_string(object, dimension, attribute, "J45")`. Use `strict=True`.
- Two or more group-bys return subtotal rows; pass `leaves_only=True` before summing.
- `COUNT` counts records (nulls included). `threshold=k` on an aggregation dimension means `>= k`, integers only.
- Flags have states `'yes'`/`'no'`. Dates are epoch milliseconds in the server's local zone (often Europe/Berlin).
- `QUANTILE` is nearest-rank, not interpolated like pandas `median()`.
- Relative time = event - reference: `TO_NEXT` is negative, `TO_PREVIOUS` positive.

## Docs
- README: https://github.com/peide-wang/xplainpy#readme
- Semantics and pitfalls: docs/pitfalls.rst
