name

using-openretailscience

description

Guidance for writing correct, performant retail analytics with the openretailscience Python package. Use when a task involves customer, basket, or transaction data and mentions any openretailscience analysis (RFM / HML / NLR / threshold segmentation, cross-shop Venn overlap, gain-loss switching, cohort retention, product association / market-basket, revenue-tree KPI decomposition, customer decision hierarchy, composite rank, haversine, customer-lifetime-value / Pareto-NBD / BTYD model-input prep), any of its plots (bar, line, area, scatter, histogram, waterfall, venn, heatmap, cohort, time, period-on-period, broken-timeline, price, index) or trendlines, its options/ColumnHelper configuration system, or connecting analyses to a database via Ibis. Also use whenever the user imports `openretailscience`.

Using openretailscience

openretailscience is a retail data-science toolkit. Every analysis accepts a pandas DataFrame or an Ibis Table (DuckDB, BigQuery, Snowflake, Databricks, PySpark, MSSQL, Oracle), so the same code runs on a laptop sample or a 1B–10B-row warehouse table. Prefer an Ibis table for large data so filtering and aggregation are pushed into the engine.

There are no top-level re-exports — always import from the full module path, e.g. from openretailscience.analysis.cross_shop import CrossShop.

Core workflow

Configure column names once with the options system, so analyses find your schema without per-call column arguments.
Instantiate an analysis class (or call a plot function) with your data.
Read results from .df (pandas) or .table (Ibis), and/or render with .plot() / .draw_tree() or a plots.* function.

import ibis
from openretailscience.options import set_option
from openretailscience.segmentation.segstats import SegTransactionStats

con = ibis.duckdb.connect()
transactions = con.read_parquet("data/transactions.parquet")

set_option("column.customer_id", "cust_id")          # map your schema once
q1 = transactions.filter(transactions.transaction_date.between("2023-01-01", "2023-03-31"))
stats = SegTransactionStats(data=q1, segment_col="category_0_name", grouping_sets="total")
print(stats.df)                                      # aggregation runs in the engine

Reference files

Read the relevant reference file for full constructor arguments, result shapes, and examples — do not guess signatures:

references/analysis.md — every analysis and segmentation class, the utils labelling/date helpers, and the experimental metrics.
references/clv.md — experimental.clv.CLVStats, which prepares the per-customer BTYD summary (frequency / recency / T / monetary_value) for the pymc-marketing Pareto/NBD and Gamma-Gamma models.
references/plotting.md — every plots.* function, trendlines (add_trend_line), and the styling / color / font helpers.
references/configuration.md — the options system, ColumnHelper, the openretailscience.toml file, connecting to each Ibis backend, and the constants.COLORS palette.

Runnable examples

Every capability has a complete, copy-pasteable script at scripts/example_<name>.py, such as scripts/example_cohort_analysis.py, scripts/example_waterfall.py, or scripts/example_rfm_segmentation.py. List the scripts/ directory to find the one matching your task, then adapt it to the user's data. Each script runs end-to-end against the installed package and is executed in the package's test suite, so it stays correct as the API evolves. Prefer reading the relevant script over assembling calls from signatures alone.

Picking an analysis

Task	Import
Transaction KPIs by segment/dimension (rollup/cube/total)	`segmentation.segstats.SegTransactionStats`
RFM / HML / threshold / NLR customer segments	`segmentation.rfm` / `.hml` / `.threshold` / `.nlr`
Category/brand overlap (Venn)	`analysis.cross_shop.CrossShop`
Customers/spend gained, lost, switched between periods	`analysis.gain_loss.GainLoss`
Retention by acquisition cohort	`analysis.cohort.CohortAnalysis`
Market-basket / co-purchase rules	`analysis.product_association.ProductAssociation`
KPI decomposition tree (spend = customers × visits × ...)	`analysis.revenue_tree.RevenueTree`
Substitutable-product dendrogram	`analysis.customer_decision_hierarchy.CustomerDecisionHierarchy`
Per-customer purchase / recency / churn metrics	`analysis.customer` (Purchases/Days/Churn classes)
BTYD summary (frequency/recency/T/monetary) for pymc-marketing CLV models	`experimental.clv.CLVStats`
Rank items by several weighted metrics	`analysis.composite_rank.CompositeRank`
Great-circle customer-to-store distance	`analysis.haversine.haversine_distance`

Performance & correctness rules

Assume 1B–10B rows. Pass an Ibis table; let the engine aggregate and filter. Don't call .execute() / .to_pandas() until you need the (small) result.
Avoid redundant work (e.g. no .nunique() on already-deduplicated data).
Timestamps must be timezone-naive; convert before analysis.
Configure column names through the options system rather than hardcoding — the package owns a canonical name for each column (see references/configuration.md).
Use vectorized pandas/numpy on result frames — never .iterrows().

When NOT to use this skill

Generic pandas wrangling, plotting outside the package, or non-retail data.

Using openretailscience

There are no top-level re-exports — always import from the full module path, e.g. from openretailscience.analysis.cross_shop import CrossShop.

Core workflow

Configure column names once with the options system, so analyses find your schema without per-call column arguments.

Instantiate an analysis class (or call a plot function) with your data.

Read results from .df (pandas) or .table (Ibis), and/or render with .plot() / .draw_tree() or a plots.* function.

import ibis from openretailscience.options import set_option from openretailscience.segmentation.segstats import SegTransactionStats con = ibis.duckdb.connect() transactions = con.read_parquet("data/transactions.parquet") set_option("column.customer_id", "cust_id") # map your schema once q1 = transactions.filter(transactions.transaction_date.between("2023-01-01", "2023-03-31")) stats = SegTransactionStats(data=q1, segment_col="category_0_name", grouping_sets="total") print(stats.df) # aggregation runs in the engine

Reference files

Read the relevant reference file for full constructor arguments, result shapes, and examples — do not guess signatures:

references/analysis.md — every analysis and segmentation class, the utils labelling/date helpers, and the experimental metrics.

references/clv.md — experimental.clv.CLVStats, which prepares the per-customer BTYD summary (frequency / recency / T / monetary_value) for the pymc-marketing Pareto/NBD and Gamma-Gamma models.

references/plotting.md — every plots.* function, trendlines (add_trend_line), and the styling / color / font helpers.

references/configuration.md — the options system, ColumnHelper, the openretailscience.toml file, connecting to each Ibis backend, and the constants.COLORS palette.

Runnable examples

Picking an analysis

Task

Import

Transaction KPIs by segment/dimension (rollup/cube/total)

segmentation.segstats.SegTransactionStats

RFM / HML / threshold / NLR customer segments

segmentation.rfm / .hml / .threshold / .nlr

Category/brand overlap (Venn)

analysis.cross_shop.CrossShop

Customers/spend gained, lost, switched between periods

analysis.gain_loss.GainLoss

Retention by acquisition cohort

analysis.cohort.CohortAnalysis

Market-basket / co-purchase rules

analysis.product_association.ProductAssociation

KPI decomposition tree (spend = customers × visits × ...)

analysis.revenue_tree.RevenueTree

Substitutable-product dendrogram

analysis.customer_decision_hierarchy.CustomerDecisionHierarchy

Per-customer purchase / recency / churn metrics

analysis.customer (Purchases/Days/Churn classes)

BTYD summary (frequency/recency/T/monetary) for pymc-marketing CLV models

experimental.clv.CLVStats

Rank items by several weighted metrics

analysis.composite_rank.CompositeRank

Great-circle customer-to-store distance

analysis.haversine.haversine_distance

Performance & correctness rules

Assume 1B–10B rows. Pass an Ibis table; let the engine aggregate and filter. Don't call .execute() / .to_pandas() until you need the (small) result.

Avoid redundant work (e.g. no .nunique() on already-deduplicated data).

Timestamps must be timezone-naive; convert before analysis.

Configure column names through the options system rather than hardcoding — the package owns a canonical name for each column (see references/configuration.md).

Use vectorized pandas/numpy on result frames — never .iterrows().

When NOT to use this skill

Generic pandas wrangling, plotting outside the package, or non-retail data.