Skip to content
Developers
Get an API token

Rank a plan's drivers

The fast way to rank what drives a done plan's forecasts: one stream's SHAP at one ip_day for the plan's first 100 placed wells, in plan order, from one model call, and each input's mean |SHAP| over the wells explained, largest first.

Rank a plan's drivers

GET/plans/{id}/drivers/{design}

The fast way to rank what drives a done plan's forecasts: one stream's SHAP at one ip_day for the plan's first 100 placed wells, in plan order, from one model call, and each input's mean |SHAP| over the wells explained, largest first.

Send a Novi API token as a bearer token on every request. Authentication
Each well

Its expected_value and values equal its explanation's SHAP row for that stream at ip_day (formation's one-hot columns summed into novi_formation). An input its row leaves out moved that forecast by 0: it counts as 0 in the mean, and wells counts the wells whose row has it. A placed well without a forecast (no target formation) is listed with its error and left out of explained and the means; wells that couldn't be placed aren't listed (GET /plans/{id}?include=wells names them).

One well

Its contributing wells, analogs, comparisons and other ip_days are in GET /plans/{id}/wells/{index}/explanations/{design}.

Caching

Each design, stream and scenario is explained once, at every ip_day, and kept in memory with the plan, so another ip_day answers without a model call; a restart explains it again.

Errors

409 while the plan runs, when it failed, or for a scenario plan without scenario; 404 for an unknown plan or a design index the plan doesn't have.

Parameters

Path parameters

  • idstringRequired

    Format uuid

    Plan id from POST /plans.

  • designintegerRequired

    ≥ 0, ≤ 9

    The design's position in the plan's designs, from 0.

Query parameters

  • streamstringOptional

    Default "oil"

    The stream whose model is explained: oil or gas, by default the first the model set serves (oil, else gas). A stream it doesn't serve is a 400 naming those it serves, and on a set serving neither, drivers are a 400. BOE has no model of its own; rank oil's or gas's.

    "oil""gas"
  • ip_dayintegerOptional

    Default 1080

    The ip_day to explain: one of the ip_days in the plan's model rows, which are GET /dataset ip_days (400 otherwise, with them in details.allowed). A value that isn't digits is refused before anything is computed. Default 1080, as GET /plans/{id}/stats.

  • includestringOptional

    path adds the plan's SHAP decision path: expected_value, where it starts; each driver's mean_shap, its signed mean over the explained wells; and mean_forecast and mean_residual, where it ends.

    PlanDrivers has each. An input a well's row leaves out counts as 0. expected_value plus the sum of mean_shap equals the mean of each explained well's expected_value plus its values, to float rounding; adding mean_residual gives mean_forecast. On a causal model set (GET /model-sets?include=model_type) mean_residual can be large: show it as a "not attributed" step so the path ends at the forecast. Any other name is a 400 with the allowed one in details.allowed.

    "path"
  • scenariostringOptional

    1 to 60 characters

    On a plan made with scenarios, the alternative to explain: the 100-well cap, placed and the means are then over its wells alone.

    A scenario plan answers 409 without it, so alternatives are never averaged together; the 409's details.scenarios lists the plan's scenario names in plan order, to pick from. An empty name, a name the plan doesn't have, or any name on a plan without scenarios is a 400.

  • model_setstringOptional

    pattern ^[a-z0-9][a-z0-9-]{0,62}$

    The model set to answer from, an id from GET /model-sets. Absent: the set GET /model-sets names as default, the base dataset unless the server answers from a published set.

    • model_set=default reaches the base dataset; once the server retires it, a 400 naming the set answering instead.
    • An unknown id, or a set scoped to other tenants, is a 400 listing the ids the caller may use in details.allowed (published sets only once default is retired); a set that can't load, a 503 with the reason.
    • Plans and exports stay in their set: a call naming them (by path, plan, ids, source.plan, a scenario's plan.id, or a comparison's a.plan and b.plan, also under source.comparison) reaches it without model_set.
    • An explicit model_set wins; naming resources of two sets in one request is a 400.

Responses

200 OK

The plan's drivers.

  • idstringRequired

    Format uuid

    Plan id.

  • designintegerRequired

    ≥ 0

    The design's position in the plan's designs, from 0.

  • streamstringRequired

    The stream whose model is explained.

    "oil""gas"
  • ip_dayintegerRequired

    The ip_day explained.

  • unitstringRequired

    bbl for oil, mcf for gas, as the explanation's.

    "bbl""mcf"
  • placedintegerRequired

    ≥ 0

    The plan's placed wells; wells lists the first 100.

  • explainedintegerRequired

    ≥ 0

    Wells listed with SHAP; the means are over these.

  • driversarray of objectsRequired

    Sorted by mean_abs_shap, largest first, ties by feature.

    ShowHide 4 child fields in each item
    • featurestringRequired

      The model input as explanation SHAP rows name it.

    • mean_abs_shapnumberRequired

      Mean |SHAP| over the explained wells in unit, an input a row leaves out counting as 0.

    • wellsintegerRequired

      ≥ 0

      The explained wells whose row has the input.

    • mean_shapnumberOptional

      With include=path: mean SHAP over the explained wells in unit, signed, an input a row leaves out counting as 0.

  • wellsarray of objectsRequired

    up to 100 items

    Placed wells in plan order.

    ShowHide 2 variants in each item

    One of

    • PlanDriverWell object

      An explained well.

      • indexintegerRequired

        ≥ 0

        The well's position in the plan, from 0.

      • labelstringRequired

        The well's label.

      • expected_valuenumber or nullRequired

        The model's expected value, as the explanation's SHAP row.

      • valuesobjectRequired

        Values by feature, as an explanation SHAP row's values.

      • namestringOptional

        The name the request gave the well, trimmed; only when it gave one. label doesn't change.

    • PlanDriverWellError object

      A well without a forecast to explain.

      • indexintegerRequired

        ≥ 0

        The well's position in the plan, from 0.

      • labelstringRequired

        The well's label.

      • errorstringRequired

        Why the well has no forecast to explain.

      • namestringOptional

        The name the request gave the well, trimmed; only when it gave one. label doesn't change.

  • scenariostringOptional

    The scenario explained, when scenario was sent.

  • expected_valuenumber or nullOptional

    With include=path: the explained wells' mean expected value in unit, where the path starts; null when no well is explained or one has none.

  • mean_forecastnumber or nullOptional

    With include=path: the explained wells' mean served forecast at ip_day in unit, where the path ends; null when no well is explained or one has no forecast served there.

  • mean_residualnumber or nullOptional

    With include=path: mean_forecast − expected_value − the sum of mean_shap, unrounded: the part of the mean forecast the SHAP values don't attribute. Null when mean_forecast or expected_value is null.

Conditional requests 304 Unchanged since the ETag in If-None-Match.

Errors

StatusWhen
404

No such well, grid, plan or route.

409

The request conflicts with the state of the plan or resource it names, and message says how: for example a plan still running or failed, a stale If-Match, an Idempotency-Key reused with another body, or a server without a state store.

502

A model worker returned an error.

Shared errors400401403500503What they mean