Explain a plan well
Why a done plan's well forecasts what it does under one design, from the model rows the plan kept: per stream, SHAP per ip_day and the top 25 training wells by tree weight, with their header details.
Explain a plan well
/plans/{id}/wells/{index}/explanations/{design}Why a done plan's well forecasts what it does under one design, from the model rows the plan kept: per stream, SHAP per ip_day and the top 25 training wells by tree weight, with their header details.
SHAP
expected_value, the model's average, plus values by feature approximates the forecast, exactly only where the model's SHAP is additive. Formation's one-hot columns are summed into one.
Options
top and ip_day cut the answer; compare, spread, analogs (with analogs_detail and analog_weights), inputs, residual, driver and weight_counts add to it, each as its parameter says; format=csv downloads the analogs as a table. spread comes from a new explanation each time, not the one the plan keeps.
Computing and caching
The explanation is computed on the first request, its streams in parallel, and kept with the plan. A forecast worker answers one request at a time, so that request waits behind a running plan. The answer carries an ETag; send it as If-None-Match for a 304.
Parameters
Path parameters
idstringRequiredFormat
uuidPlan id from POST /plans.
indexintegerRequired≥ 0
The well's position in the plan, from 0.
designintegerRequired≥ 0, ≤ 9
The design's position in the plan's
designs, from 0.
Query parameters
topintegerOptional≥ 1, ≤ 50
How many features per SHAP row and contributing wells to keep, 1 to 50.
It keeps the largest features (by absolute contribution) and heaviest wells. Default: all features, 25 wells.
The features cut are summed into one
(other)entry (never a feature name; left out when nothing is cut), and the wells cut add toother_weight. A row's contributions still sum to the uncut row's (null contributions are left out), and the response keeps its shape with fewer entries; with residual, each row'sforecastandresidualare the uncut row's.ip_dayintegerOptional≥ 1
Only this ip_day's SHAP row in each stream, for "why at 1 year" without every day: one of the ip_days in the explanation's
shaprows, which are GET /datasetip_days. Without it, every ip_day.Another value is a 400 with them in
details.allowed; a value that isn't digits is refused before the explanation is computed. Withtop, the row is picked first and then cut.contributing_wellsandother_weightare one list per stream, not per ip_day, so they are the same with or without it. A design with no forecast to explain has no rows, so any ip_day is a 400 there: ask without it to read why.comparestringOptionalThe references to compare with, comma-separated:
formation,dataset,analogs.Each explained stream gains
comparisons, one per reference.formationis the wells the model explained in this well's formation (a typical Wolfcamp A well, say),datasetevery well it explained. At each ip_day,valuesholds, by feature, this well's SHAP contribution minus the reference wells' mean: read an entry as "compared with a typical Wolfcamp A well, this input adds (or removes) N". It rearranges the same SHAP values, so it can't contradict them.valueis the reference wells' meanexpected_valueplus their mean contributions (start_fromreference), or this well's ownexpected_valueplus theirs where no mean is stored (start_fromwell).(baseline)invaluesis this well'sexpected_valueless the reference mean: mostly its lateral length against theirs, in models that scale by lateral. It comes only withstart_fromreference, not when it rounds to 0, and never counts towardtopor(other).valueplusvaluesis this well'sexpected_valueplus its SHAP values (each rounded to 0.001); the SHAP row'sresidualis what they leave out of the forecast.wellscounts the reference at that ip_day (long ip_days rest on older wells); under 5,valueis null,valuesempty andstart_fromabsent.topfolds small differences into(other);ip_daykeeps one row. A reference without a baseline (a formation the model never saw) is{reference, error}; GET /models/{model_num}/baselines lists them.
analogs, on model sets that store their analogs' SHAP, averages this forecast's own first 15 analogs per stream the same way (a missing feature counts 0), in the analogs list's ranking (reweighed byanalog_weightswhen sent), whether or notanalogsis asked;analogsitself comes only when asked. Itskeysname them, nearest first. It is{reference, error}when the dataset has no analog index, the set stores no analog SHAP or it can't be read (tried again after a minute), the analogs can't be ranked, or the model has no training analogs of this forecast in its formation.spreadbooleanOptionalDefault
falsetrueaddsanalog_spreadto each explained stream.An analog spread, not the model's uncertainty: for the model's own P10/P90, send
bands: true.It is the 10th, 50th and 90th percentiles (q10 the low end) of what the model's 50 heaviest contributing training wells actually produced by each ip_day, each scaled to this well's lateral length (wells without one are left out). Only wells whose production reached the ip_day count (
wells); under 5, the quantiles are null.contributing_wellsstill lists 25, ortopwhen that is fewer, andother_weightis re-summed from 50 weights, so it can differ in the last digit.forecastsays whether the served forecast (as GET /plans/{id}/wells/{index} serves it; on POST /forecasts,forecasts[d]beforeip_dayscuts it) is below, within or above q10 to q90, compared before rounding; null without quantiles or a served value.drivernames the input that moves it there.analogsbooleanOptionalDefault
falsetrueaddsanalogsto each explained stream, from the explanation the plan keeps (no new model call).The model's own analog wells for this forecast, from its training wells, each stream from its own model.
They are the 50 nearest wells of the same formation and parent/child status whose lateral is within 25% of this well's (widened to 50%, then 100%, until 5 pass), by distance over the model's inputs at its last ip_day, standard-scored and weighted by mean |SHAP| (
weights).wellslists them nearest first, whatevertop.spreadis the 10th, 50th and 90th percentiles of what they produced by ip_day, scaled to this well's lateral, asanalog_spread: an analog spread, not the model's uncertainty. Unlesscoveragepasses, it is{error}with the measured figure (the wells are still listed): on the model's held-out wells, q10 to q90 must have held 70% to 90% of actual production atcoverage.ip_day(nominal 80%) over at least 300 wells.coverage.measuredis always given.Their type curve: POST /wells/typecurve with their keys as
wells,normalize_lateral_ft=spread.lateral_length_ftandquantiles: [10, 50, 90]matchesspreadwhile that lateral is within 100 to 20,000 ft.A dataset without an analog index (the default dataset), or a set before its index is installed, answers
analogs: {error}with the reason;analog_spreadis unchanged.inputsbooleanOptionalDefault
falsetrueaddsinputsto each SHAP row: the value of each feature itsvalueslists (not(other)), as the model read it in that ip_day's model row, so a driver reads with its input ("proppant 2,800 lb/ft adds X bbl"). Goes withip_dayandtop; withformat=csvit changes nothing.residualbooleanOptionalDefault
falsetrueaddsforecastandresidualto each SHAP row; show the residual beside the drivers ("not attributed") so the parts add up to the forecast.forecastis the forecast served at that ip_day for this design, as GET /plans/{id}/wells/{index} serves it (on POST /forecasts,forecasts[d]beforeip_dayscuts it), or null.residual=forecast−expected_value− the sum ofvalues, unrounded, on the uncut row, sotopandip_daydon't change it; null when either is null. On a causal model set (GET /model-sets?include=model_type) SHAP values approximate the treatment effect, so the residual can be large. Withformat=csvit changes nothing.driverbooleanOptionalDefault
falsetrue(400 withoutspread=trueoranalogs=true) addsdriverto every analog spread row: the model input that moves this forecast furthest the way the row'sforecastflag points.It is
{feature, value, reference}: withbelow, the most negative contribution; withabove, the most positive; in the stream's unit to 0.001, from the uncut SHAP row. Withreferenceformation, a contribution is this well's SHAP value minus the typical well's of its formation at that ip_day (thecompare=formationbaseline, when it has at least 5 wells there; a missing feature counts 0); otherwisemodel, the raw SHAP value. Null when the flag iswithinor null, or no input moves it that way (a contribution rounding to 0 counts as none).comparisonsstill come only withcompare.weight_countsbooleanOptionalDefault
falsetrueaddsweighted_wellsandeffective_wellsto each explained stream: how many training wells carry weight, and how concentrated it is.They count every training well, not only those
contributing_wellslists: check them before saying a forecast rests on the listed wells. Both are null, withweights_error, for a fit without tree weights or counts; all-zero weights giveweighted_wells0 andeffective_wellsnull. Withformat=csvit changes nothing.analogs_detailbooleanOptionalDefault
falsetrue(400 withoutanalogs=true) adds each analog's production, EURs and model inputs toanalogs.wells.cum_oil_360,cum_oil_720,cum_oil_1080,cum_gas_360,cum_gas_720,cum_gas_1080: actual cumulative oil and gas (bbl, mcf) at 1, 2 and 3 years of 30-day months, unscaled; null where it hasn't produced that long.cum_oil_life,cum_gas_life: to date.eur_oil,eur_gas: EUR (bbl, mcf) from Novi's type-curve decline fit, aseur: trueruns it, on its actual cumulative at every 30-day ip_day (its last 400), unscaled.inputs: the model's raw inputs for it at the distance's ip_day (basis), inweightsorder, null where missing.
An EUR is null when the fit fails, without production at every 30-day ip_day from 30 to 360, with a history longer than
eur_years, or below the cumulative to date. One not above its last 30-day cumulative is a flat extension, kept only for an analog without production in its last 90 days (Novi's dry-well rule). An EUR from under 3 years of production (a nullcum_oil_1080orcum_gas_1080) is less certain.analogs.inputsgives this forecast's own inputs the same way.analogs.eurgives thebasis, thedeclinesettings and how many got each EUR (fitted); it is{error}when the server has no EUR or the fit failed or took over 30 s. The settings are each well's own once a layer below the plan reaches any well with a setting other thanwater; else the plan's (made witheur: true), the forecast'sdecline, or GET /dataseteur.defaults.Each analog is fit once per request; the worker keeps recent fits, so a repeat is cheaper. Nothing else in the answer changes.
formatstringOptionalDefault
"json"csv(withanalogs=true, else 400) downloads the analogs as a CSV table instead of the JSON explanation;jsonis the default.The file is
text/csv, an attachment namedplan-well-<n>-design-<m>-analogs-<YYYY-MM-DD>.csv(positions from 1, the server's UTC day;analogs-weightedwithanalog_weights), without an ETag.Per stream with analogs, oil, gas then water: a row for this well (
rank0,well_name"This well", its formation, lateral, inputs andeur_basis:analogs.eur.basisor its error), then one per analog, nearest first (rank1 to 50). A stream whose analogs or explanation is{error}adds no rows (the JSON answer says why), so the table can be its header alone.Columns:
stream,rank,key,distance,well_name,operator,formation,first_prod,lateral_length,heel_lon,heel_lat,bhl_lon,bhl_lat, the cumulatives and EURs ofanalogs_detail,eur_basis(withanalog_weights, thenanalogs_basison rank 0 rows), then each model input by highest weight, then name; blank where a model lacks it. An input header that would repeat another getsinput_in front until unique. Text starting with=,+,-,@, a tab or a carriage return gets a leading', so a spreadsheet doesn't run it.ip_day,top,compareandspreadare checked but don't change the table."json""csv"analog_weightsstringOptionalComma-separated
feature:weightpairs, asnovi_lateral_length:0.4,novi_tvd:0, sent once (400 withoutanalogs=trueor when repeated); send a+(as in1e+2) as%2B, since a bare+in a query is a space.Your weights for the analog distance, as shares on the scale of
analogs.weights[].weight, one map for every stream's model. A named input takes exactly its share and the model's other inputs split the rest as the model weighs them; when nothing takes the rest, the shares sent are rescaled to sum to 1. A model with none of the names answers as without them.Weights are finite, from 0 (which drops an input), summing to 1 at most. A 400: a name no model in the set takes (
details.allowedlists their inputs), a malformed pair, a repeated name, a negative or non-finite weight, or a sum over 1. Weights that all come to 0, or weighted inputs that don't vary across the candidates, answeranalogs: {error}.A reweighted stream gives
analogs.analog_weights(yours),weights(the distance's, heaviest first, each with itsmodel_weight) andbasis, naming the inputs you weighted;methodstaysshap_weighted. Itsspreadis{error}unless it lists the wells the model's weights list, sincecoverage(still given) was measured with those. The filters don't change;analogs_detailandformat=csvfollow the reweighted analogs. Without an analog index, names aren't checked.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 explanation; with format=csv, the analogs table.
Returns text/csv.
One of
PlanWellExplanationStreams object
Explanations per stream. Only the streams the model set serves (GET /model-sets
streams): a set serving gas alone answers gas alone.indexintegerRequired≥ 0
The well's position in the plan.
labelstringRequiredDisplay name, as Plan well 2.
designintegerRequired≥ 0
The design, as its index in
designs.namestringOptionalThe name the request gave the well, trimmed; only when it gave one.
labeldoesn't change.oilobjectOptionalOne stream model's explanation of the forecast, or why it couldn't run.
ShowHide 2 variants
One of
An explained stream object
An explained stream.
model_numstringRequiredModel explained.
unitstringRequiredVolume unit of the contributions.
"bbl""mcf"shaparray of objectsRequiredSHAP per ip_day, ascending.
ShowHide 6 child fields in each item
ip_dayintegerRequiredDays since first production.
expected_valuenumber or nullRequiredThe model's average forecast at this ip_day (its baseline).
valuesobjectRequiredContribution of each feature (non-zero only), in the stream's unit; expected_value plus these approximates the forecast, exactly only where the model's SHAP is additive (
residualsays how far it is). With explain_top / top, the largest ones and(other), the sum of the rest.inputsobjectOptionalWith explain_inputs (POST /forecasts) or inputs=true (plan well): the value of each feature
valueslists (not(other)) as the model read it in this ip_day's model row. Numbers are unrounded, in the feature's unit (GET /models/{model_num} lists each input with its training range); categories such as novi_formation are strings; null where the row had none.forecastnumber or nullOptionalWith residual=true (plan well) or explain_residual (POST /forecasts): the forecast served at this ip_day for this design, in the stream's unit, the same number GET /plans/{id}/wells/{index} serves there (on POST /forecasts, the well's
forecasts[d]value beforeip_dayscuts it); null where none is served.residualnumber or nullOptionalWith residual=true or explain_residual: forecast − expected_value − the sum of values (of the uncut row, whatever top keeps), unrounded: the part of the forecast the SHAP values don't attribute. Null when forecast or expected_value is null.
contributing_wellsarray of objectsRequiredTraining wells sharing the forecast's tree leaves, heaviest first (top 25, or explain_top / top). On a causal model set (GET /model-sets?include=model_type), they are the training wells sharing the leaves its baseline (associative) model's prediction used, weighted before the completion effect is applied. Empty when the model's fit has no tree weights: SHAP still explains the forecast.
ShowHide 10 child fields in each item
keystringRequiredWellbore key; GET /wells/{key} has its details.
weightnumberRequired≥ 0, ≤ 1
Share of the forecast's tree weight.
well_namestring or nullRequiredWell name.
operatorstring or nullRequiredOperator.
formationstring or nullRequiredFormation.
first_prodstring or nullRequiredFormat
dateFirst production date.
heel_lonnumber or nullRequiredHeel longitude.
heel_latnumber or nullRequiredHeel latitude.
bhl_lonnumber or nullRequiredBottom hole longitude.
bhl_latnumber or nullRequiredBottom hole latitude.
other_weightnumberRequired≥ 0, ≤ 1
Weight of every other training well (1 minus the listed weights); 1 when the fit has no tree weights and
contributing_wellsis empty.weighted_wellsinteger or nullOptional≥ 0
With weight_counts or explain_weight_counts: training wells with nonzero weight, of which
contributing_wellslists the heaviest; null when the fit has no tree weights or the model worker sent no counts for it, 0 when every weight is 0.effective_wellsnumber or nullOptional≥ 1
With weight_counts or explain_weight_counts: the effective number of training wells the weight rests on, 1/Σw² over every training well's weight (weights sum to 1), to 0.001. It equals
weighted_wellswhen the weight is spread evenly and nears 1 when one well carries it; null when the fit has no tree weights, the model worker sent no counts for it or every weight is 0.weights_errorstringOptionalWith weight_counts or explain_weight_counts, when the fit has no tree weights: why, so
weighted_wellsandeffective_wellsare null; also when the model worker sent no counts for the fit.comparisonsarray of objectsOptionalWith compare or explain_compare: one per reference, in the order asked.
ShowHide 2 variants in each item
One of
A comparison object
A comparison.
referencestringRequiredThe reference.
"formation""dataset""analogs"formationstring or nullRequiredWith formation, the formation the reference covers; null for dataset; with analogs, this well's.
labelstringRequiredThe reference in words, as Typical Wolfcamp A well.
sourcestringRequiredThe population the reference's mean SHAP is over, in words, as "mean SHAP over the WOLFCAMP A wells of the existing wells the model explained (…), per ip_day".
rowsarray of objectsRequiredOne per SHAP row (one with ip_day).
ShowHide 5 child fields in each item
ip_dayintegerRequiredDays since first production.
wellsintegerRequired≥ 0
Reference wells at this ip_day.
valuenumber or nullRequiredThe reference wells' average model forecast here as SHAP gives it: their mean expected_value plus their mean contributions, in the stream's unit; with no stored mean expected_value, this well's expected_value plus their mean contributions (start_from says which). Null with fewer than 5 wells.
valuesobjectRequiredThis well's contribution minus the reference's mean contribution, by feature, in the stream's unit. value plus these is this well's expected_value plus its SHAP values, which approximates its forecast.
(baseline), when it rounds to non-zero: this well's expected_value less the reference wells' mean, which SHAP assigns to no input. In models that scale by lateral length it is mostly this well's lateral against theirs.- Add the SHAP row's residual for the forecast.
- With top, the largest feature differences and
(other), plus(baseline), which top never counts or folds.
start_fromstringOptionalWhere value starts: reference, the reference wells' stored mean expected_value; well, this well's own expected_value, where no mean is stored (values then has no (baseline)). Only on a row with a value.
"reference""well"
keysarray of stringsOptionalWith analogs only: the wells averaged, nearest first, the first 15 (or fewer) of the stream's analogs list.
No comparison object
No comparison.
referencestringRequiredThe reference.
"formation""dataset""analogs"errorstringRequiredWhy there is no baseline, as the model has no baseline for DEAN.
analog_spreadobjectOptionalWith spread or explain_spread: what the contributing wells actually produced, scaled to this lateral. For a fit without tree weights,
{error}with the model's reason.ShowHide 2 variants
One of
A spread object
A spread.
basisstringRequiredWhat the spread is of, in words.
lateral_length_ftintegerRequiredThis well's lateral, ft: every contributing well is scaled to it.
wells_consideredintegerRequired≥ 0
Contributing wells taken (the 50 heaviest).
min_wellsintegerRequired≥ 1
Fewest wells for quantiles.
rowsarray of objectsRequiredOne per ip_day of the SHAP rows.
ShowHide 7 child fields in each item
ip_dayintegerRequiredDays since first production.
wellsintegerRequired≥ 0
Contributing wells whose production reached this ip_day.
q10number or nullRequired10th percentile of their scaled cumulatives, the low end; null with fewer than min_wells.
q50number or nullRequiredMedian; null with fewer than min_wells.
q90number or nullRequired90th percentile, the high end; null with fewer than min_wells.
forecaststring or nullRequiredWhere the served forecast at this ip_day falls against q10 to q90; null without quantiles or a served forecast.
"below""within""above"driverobject or nullOptionalWith driver=true or explain_driver: the input that moves the forecast furthest the way
forecastpoints; null when it is within or null, or when no input moves it that way.ShowHide 3 child fields
featurestringRequiredThe model input, as novi_spacing_parent_daysonline; GET /models/{model_num} lists them.
valuenumberRequiredIts contribution in the stream's unit, rounded to 0.001: negative when the flag is below, positive when above. Against the formation's typical well with reference formation, else the raw SHAP value.
referencestringRequiredWhat the contribution is measured against: formation, the typical well of this well's formation at this ip_day (its mean SHAP over at least 5 wells, as compare=formation); model, the model's average well (the raw SHAP value).
"formation""model"
No spread object
No spread.
errorstringRequiredWhy there is no spread.
analogsobjectOptionalWith analogs or explain_analogs: the model's analog wells for this forecast and, when their measured coverage passes the gate, their spread; for fits with or without tree weights.
ShowHide 2 variants
One of
The model analogs object
The model analogs.
methodstringRequiredHow they were chosen: two stages, hard filters then the distance over standard scores weighted by the model's mean |SHAP|, unless
analog_weightsis present, then by those weights for the inputs it names."shap_weighted"notestringRequiredAlways "Analog spread, not the model's uncertainty".
basisstringRequiredWho they are, in words: the filters, how many wells passed them and the ip_day of the distance.
formationstringRequiredThe formation they share with this well.
childboolean or nullRequiredThis well's parent (false) or child (true) status, which they share; null when its spacing features don't say, and then both count.
lateral_band_pctinteger or nullRequiredHow far their laterals may be from this well's, %: 25, widened to 50 then 100 until 5 wells pass; null when fewer pass even at 100, and then any lateral counts.
2550100candidatesintegerRequired≥ 0
Training wells that passed the filters; the nearest 50 are listed.
weightsarray of objectsRequiredEvery numeric model input, heaviest first.
ShowHide 3 child fields in each item
featurestringRequiredA numeric model input.
weightnumberRequired≥ 0, ≤ 1
Its share of the distance: the model's mean |SHAP| for it at its last ip_day, over the wells the build explained, or with analog_weights the share the distance used; they sum to 1. Formation is a filter, not a weight.
model_weightnumberOptional≥ 0, ≤ 1
With analog_weights: the model's own weight for it, as
weightis without them.
wellsarray of objectsRequiredup to 50 items
Up to 50, nearest first (ties by key);
topdoesn't cut them.ShowHide 22 child fields in each item
keystringRequiredWellbore key; GET /wells/{key} has its details.
distancenumberRequired≥ 0
Its distance from this forecast in the model's weighted standard scores; 0 is the same inputs.
well_namestring or nullRequiredWell name.
operatorstring or nullRequiredOperator.
formationstring or nullRequiredFormation.
first_prodstring or nullRequiredFormat
dateFirst production date.
lateral_lengthnumber or nullRequiredLateral length, ft.
heel_lonnumber or nullRequiredHeel longitude.
heel_latnumber or nullRequiredHeel latitude.
bhl_lonnumber or nullRequiredBottom hole longitude.
bhl_latnumber or nullRequiredBottom hole latitude.
cum_oil_360number or nullOptionalWith analogs_detail: its actual cumulative oil at ip_day 360, bbl, unscaled; null when it hasn't produced that long.
Show all 22 fields
cum_oil_720number or nullOptionalWith analogs_detail: its actual cumulative oil at ip_day 720, bbl, unscaled; null when it hasn't produced that long.
cum_oil_1080number or nullOptionalWith analogs_detail: its actual cumulative oil at ip_day 1080, bbl, unscaled; null when it hasn't produced that long.
cum_gas_360number or nullOptionalWith analogs_detail: its actual cumulative gas at ip_day 360, mcf, unscaled; null when it hasn't produced that long.
cum_gas_720number or nullOptionalWith analogs_detail: its actual cumulative gas at ip_day 720, mcf, unscaled; null when it hasn't produced that long.
cum_gas_1080number or nullOptionalWith analogs_detail: its actual cumulative gas at ip_day 1080, mcf, unscaled; null when it hasn't produced that long.
cum_oil_lifenumber or nullOptionalWith analogs_detail: its cumulative oil to date, bbl.
cum_gas_lifenumber or nullOptionalWith analogs_detail: its cumulative gas to date, mcf.
eur_oilnumber or nullOptionalWith analogs_detail: its oil EUR, bbl, from the decline fit on its actual cumulative oil at every 30-day ip_day it has produced (
analogs.eur); null when it can't be fit.Null when the well lacks production at any 30-day ip_day from 30 to 360 (its first 12 months), has a history longer than
eur_years, or the fit failed, and when the EUR is below its cumulative to date or not above its last 30-day cumulative (a flat extension, kept only after 90 days without production).eur_gasnumber or nullOptionalWith analogs_detail: its gas EUR, mcf, as
eur_oilis fit.inputsobjectOptionalWith analogs_detail: the model's raw inputs for this well, in
weightsorder.
coverageobject or nullRequiredHow often this model's analog spread held held-out wells' actual production, measured once when the index was built; null when the build has no held-out wells with production.
ShowHide 7 child fields
ip_dayintegerRequiredThe ip_day measured: the model's last one that enough held-out wells reach with production.
kintegerRequiredAnalogs per held-out well, as here.
nominalnumberRequiredThe share q10 to q90 would hold if it were a calibrated 80% interval.
measurednumber or nullRequiredThe share of held-out wells whose actual production at ip_day fell within their own analogs' q10 to q90, each against the training wells alone; to 0.001.
wellsintegerRequired≥ 0
Held-out wells measured (each with at least 5 analogs with production at ip_day).
gateobjectRequiredWhat the spread must pass to be shown.
ShowHide 3 child fields
minnumberRequiredLowest measured share shown.
maxnumberRequiredHighest measured share shown.
wellsintegerRequiredFewest held-out wells measured.
shownbooleanRequiredWhether
measuredandwellspass the gate, sospreadis given; withanalog_weights, only when the wells listed are the ones the model's weights list, as coverage was measured with those.
spreadobjectRequiredWith
coverage.shown, q10, q50 and q90 of these wells' actual cumulatives, each scaled to this well's lateral, asanalog_spread: an analog spread, not the model's uncertainty.{error}instead:- without
coverage.shown, saying what was measured; - with fewer than 5 analogs listed (
candidatesunder 5), whatevercoveragesays, saying how many training wells passed the filters; - with
analog_weights, unless the wells listed are the ones the model's weights list, since coverage was measured with the model's weights.
Same fields as AnalogSpread.
- without
analog_weightsobjectOptionalWith analog_weights, when it names some of this model's inputs: the weights sent for them, as sent; the distance then used
weights, these shares with the rest shared by the model's other inputs, or these rescaled to 1 when nothing takes the rest. Absent otherwise.inputsobjectOptionalWith analogs_detail: this forecast's own inputs, as each well's, so a table can put this well first.
eurobjectOptionalWith analogs_detail: how the wells'
eur_oilandeur_gaswere fit, or why there are none.ShowHide 2 variants
One of
The fit object
The fit.
basisstringRequiredIn words: the fit, the curves it ran on, the settings' source, what an analog needs to get an EUR (as ModelAnalogWell
eur_oilsays), how many got one and, by reason, how many didn't.declineobjectRequiredThe decline settings used: each well's own once a layer below the plan reaches any well with a setting other than
water; else a plan's own when it was made with eur: true, a forecast's decline with eur: true, else GET /dataset eur.defaults.ShowHide 8 child fields
eur_yearsintegerRequired≥ 10, ≤ 50
Years to EUR: the extension runs to the last 30-day step within eur_years × 365 days.
terminal_declinenumberRequired≥ 0.01, ≤ 0.2
Terminal decline, a fraction per year: the hyperbolic switches to exponential at this rate.
b_minnumberRequired≥ 0, ≤ 2.5
Lowest hyperbolic b the fit may use; below b_max.
b_maxnumberRequired≥ 0, ≤ 2.5
Highest hyperbolic b the fit may use; above b_min.
oilobjectOptionalWith per-stream settings, the settings oil was fit with.
ShowHide 3 child fields
terminal_declinenumberRequired≥ 0.01, ≤ 0.2
Terminal decline, a fraction per year: the hyperbolic switches to exponential at this rate.
b_minnumberRequired≥ 0, ≤ 2.5
Lowest hyperbolic b the fit may use; below b_max.
b_maxnumberRequired≥ 0, ≤ 2.5
Highest hyperbolic b the fit may use; above b_min.
gasobjectOptionalWith per-stream settings, the settings gas was fit with.
Same fields as StreamDecline.
waterobjectOptionalOnly with eur_water: true: the settings water was fit with. Its presence is the echo of the flag.
Same fields as StreamDecline.
per_wellbooleanOptionalOnly when a well has its own settings: these are the request's or plan's, not every well's;
inputs.resolved.declinegives each well's.true
fittedobjectRequiredHow many of the listed analogs got an EUR, per stream.
ShowHide 2 child fields
oilintegerRequired≥ 0
Analogs with an eur_oil.
gasintegerRequired≥ 0
Analogs with an eur_gas.
No EUR object
No EUR.
errorstringRequiredWhy there is no EUR: the server has none (as eur: true answers 503), or the fit failed.
No analogs object
No analogs.
errorstringRequiredWhy there are none, as the dataset has no analog index.
A stream that failed object
A stream that failed.
errorstringRequiredWhy this stream has no explanation.
gasobjectOptionalOne stream model's explanation of the forecast, or why it couldn't run.
Same fields as StreamExplanation.
waterobjectOptionalOne stream model's explanation of the forecast, or why it couldn't run.
Same fields as StreamExplanation.
PlanWellExplanationError object
No explanation.
indexintegerRequired≥ 0
The well's position in the plan.
labelstringRequiredDisplay name, as Plan well 2.
designintegerRequired≥ 0
The design, as its index in
designs.errorstringRequiredWhy there is no explanation (no forecast).
namestringOptionalThe name the request gave the well, trimmed; only when it gave one.
labeldoesn't change.
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