Ask your data

You'll end with the questions worth asking of your own table, and an answer or an honest refusal for each. Every step below runs first on a free sample; swap in your own dataset_id when it works. Your own data needs a live key and a card on file (Your data).

1. Get the table in

A record is past cases with a yes/no outcome (The record). Four ways in:

dg_add_dataset returns a dataset_id (ds_…). A stored dataset is deleted 24 hours after it was last used.

2. Find the questions worth trying

dg_suggest lists the yes/no questions a table could be asked. It fits nothing and is free.

curl https://api.datagoat.io/v1/suggest -H "Authorization: Bearer $DATAGOAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"data": {"dataset_id": "sample:telco_churn"}, "entity_column": "account_id", "include_categories": true}'

On the telco sample, one candidate passes and the rest do not:

{"candidates": [
  {"outcome_column": "churned", "positive_values": ["yes"], "prevalence": 0.1275, "worth_asking": true, "defined_by": [],
   "question": {"type": "yesno", "outcome_column": "churned", "positive_values": ["yes"]}},
  {"outcome_column": "contract", "positive_values": ["month-to-month"], "worth_asking": false, "why_not": "too_few_patterns", …}, …],
 "considered": 8, "not_checked": ["tenure_months", "monthly_charges", "total_charges"]}

Ask the worth_asking ones first. It is a screen, not an answer: about half of what it passes is answered. defined_by names columns that almost restate the outcome. More in Find the questions.

3. Check the table

dg_preflight (free, fits nothing) reports what each column is, whether one row is one kind of thing, and whether there are enough outcomes for the columns you have:

{"grain": {"verdict": "single_grain", …},
 "fitness": {"n_labelled": 800, "n_positive": 102, "n_usable_predictors": 5, "events_per_predictor": 20.4,
             "verdict": "proceed: 20.4 events per predictor over 5 predictors"},
 "blocking": [],
 "advisory": ["churned: ambiguous — boolean (100%); geo.country (87%). Not eligible as a predictor until resolved.",
              "internet_service: 68% of labelled rows filled, floor is 80%"]}

A blocking entry means an answer from this table would not be believable: fix it first. advisory entries are worth reading. Here, internet_service is too often empty to be used, and the note on churned concerns its use as a predictor, which an outcome column never is.

4. Ask

Put every question about the record in one call (The ask call). Questions on the same outcome and the same outcome_is_desirable share one fit.

{"data": {"dataset_id": "sample:telco_churn"}, "entity_column": "account_id", "subject_kind": "org",
 "questions": {"churn": {"type": "yesno", "outcome_column": "churned", "outcome_is_desirable": false}},
 "cases": {"ids": ["acct_0001"]}}

A first ask on a large record can come back status: "pending" with a task_id: poll it with dg_poll (the SDKs wait for you). Never send the ask again; that would start a second fit.

5. Read the answer

Read state first (The answer state):

• answered: each case has p, up to four reasons, and a signed Verdict.
• refused: the record holds no pattern that held up on rows the model never saw. The same call returns the same refusal. Change the record (more columns, an activity log) or the question.
• not_yet: too few labeled rows; needs.labeled_rows says how many more.

What can go wrong

Every code, with its fix: Errors.

Next

Score a customer's cases every day without fitting again: Ship a product.