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
/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.
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
idstringRequiredFormat
uuidPlan id from POST /plans.
designintegerRequired≥ 0, ≤ 9
The design's position in the plan's
designs, from 0.
Query parameters
streamstringOptionalDefault
"oil"The stream whose model is explained:
oilorgas, 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_dayintegerOptionalDefault
1080The 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 indetails.allowed). A value that isn't digits is refused before anything is computed. Default 1080, as GET /plans/{id}/stats.includestringOptionalpathadds the plan's SHAP decision path:expected_value, where it starts; each driver'smean_shap, its signed mean over the explained wells; andmean_forecastandmean_residual, where it ends.PlanDrivers has each. An input a well's row leaves out counts as 0.
expected_valueplus the sum ofmean_shapequals the mean of each explained well'sexpected_valueplus itsvalues, to float rounding; addingmean_residualgivesmean_forecast. On a causal model set (GET /model-sets?include=model_type)mean_residualcan 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 indetails.allowed."path"scenariostringOptional1 to 60 characters
On a plan made with scenarios, the alternative to explain: the 100-well cap,
placedand 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.scenarioslists 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_setstringOptionalpattern ^[a-z0-9][a-z0-9-]{0,62}$
The model set to answer from, an
idfrom GET /model-sets. Absent: the set GET /model-sets names asdefault, the base dataset unless the server answers from a published set.model_set=defaultreaches 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 oncedefaultis 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'splan.id, or a comparison'sa.planandb.plan, also undersource.comparison) reaches it withoutmodel_set. - An explicit
model_setwins; naming resources of two sets in one request is a 400.
Responses
200 OK
The plan's drivers.
idstringRequiredFormat
uuidPlan id.
designintegerRequired≥ 0
The design's position in the plan's
designs, from 0.streamstringRequiredThe stream whose model is explained.
"oil""gas"ip_dayintegerRequiredThe ip_day explained.
unitstringRequiredbbl for oil, mcf for gas, as the explanation's.
"bbl""mcf"placedintegerRequired≥ 0
The plan's placed wells;
wellslists the first 100.explainedintegerRequired≥ 0
Wells listed with SHAP; the means are over these.
driversarray of objectsRequiredSorted by mean_abs_shap, largest first, ties by feature.
ShowHide 4 child fields in each item
featurestringRequiredThe model input as explanation SHAP rows name it.
mean_abs_shapnumberRequiredMean |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_shapnumberOptionalWith include=path: mean SHAP over the explained wells in
unit, signed, an input a row leaves out counting as 0.
wellsarray of objectsRequiredup 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.
labelstringRequiredThe well's label.
expected_valuenumber or nullRequiredThe model's expected value, as the explanation's SHAP row.
valuesobjectRequiredValues by feature, as an explanation SHAP row's
values.namestringOptionalThe name the request gave the well, trimmed; only when it gave one.
labeldoesn't change.
PlanDriverWellError object
A well without a forecast to explain.
indexintegerRequired≥ 0
The well's position in the plan, from 0.
labelstringRequiredThe well's label.
errorstringRequiredWhy the well has no forecast to explain.
namestringOptionalThe name the request gave the well, trimmed; only when it gave one.
labeldoesn't change.
scenariostringOptionalThe scenario explained, when
scenariowas sent.expected_valuenumber or nullOptionalWith 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 nullOptionalWith include=path: the explained wells' mean served forecast at
ip_dayinunit, where the path ends; null when no well is explained or one has no forecast served there.mean_residualnumber or nullOptionalWith include=path:
mean_forecast−expected_value− the sum ofmean_shap, unrounded: the part of the mean forecast the SHAP values don't attribute. Null whenmean_forecastorexpected_valueis null.
304 Unchanged since the ETag in If-None-Match.Errors
| Status | When |
|---|---|
| 404 | No such well, grid, plan or route. |
| 409 | The request conflicts with the state of the plan or resource it names, and |
| 502 | A model worker returned an error. |
Shared errors400401403500503What they mean