Give the model examples
The table that carries the answers is called the context, and the table you want predictions for is called the query. Both contain the same feature columns, with the same names in the same order, and only the context contains the target column. Because the model reads the columns by position, a query whose columns are in a different order is refused with a 422 response that lists both orders.
There are two models. causilo-clf handles classification and
causilo-reg handles regression. If you want to see how they
compare with gradient-boosted trees, the
Causilo vs XGBoost example runs
XGBoost and LightGBM at their default settings on the same table.
Context: known target
| region | spend | renewed · target |
|---|---|---|
| EU | 120 | yes |
| US | 340 | yes |
| EU | 0 | no |
Query: features only
| region | spend |
|---|---|
| EU | 200 |
| US | 50 |
Context conditions this query through Causilo.
Result shape
Causilo → one label per query row
| Query order | renewed · prediction |
|---|---|
| 1 · EU, 200 | returned label |
| 2 · US, 50 | returned label |
Placeholders show the response shape; they are not recorded prediction values.
Check the data conditions
What a column may hold
Each kind of column is handled as follows. Every refusal is a 422 response whose detail names the column.
| In your table | What happens |
|---|---|
| Missing values in a feature | Accepted as they are. The model handles missing values natively, so there is no need to impute them first. |
| Strings | Accepted and treated as categories, with no encoding needed on your side. |
| Columns on very different scales | Accepted. No scaling or normalisation is needed. |
| A query column that is empty on every row | Refused, because the prediction would otherwise ignore that column without saying so. |
| Dates, times, durations | Refused. Split them into numeric parts such as year, month and day of week, or send epoch seconds. Preprocessing would treat a date as a category, and the predictions would be worse without any warning. |
Decimal columns |
Refused. A Postgres or BigQuery NUMERIC column becomes
this type in pandas, so cast it to float first. |
| Lists, dicts, structs | Refused. |
| Infinities, or values at or above the documented ceiling | Refused. Rescale the column or drop those rows. |
float16 | Widened to float32 for you. |
| Duplicate column names | Refused. |
| Your DataFrame index | Dropped and never sent, so put anything you need to keep in a column. |
The same column must hold the same kind of value in both tables. A context in which every feature column holds a single value is refused, since there is nothing in it to predict from.
What the target column may hold
The target column is present in the context and absent from the query. In a single Parquet file, the rows with an empty target are the rows to predict.
| Rule | Applies to |
|---|---|
| No missing values in the context's target | both models |
| At most 64 distinct values, and at least two | causilo-clf |
| Whole numbers or strings, not fractions | causilo-clf |
| Numeric, finite, under 3.4e38 | causilo-reg |
| Not a datetime | causilo-reg, whose predictions
would otherwise come back as epoch integers with no unit.
causilo-clf treats each distinct date as a class and
returns it as a string. |