Summarize a plan's wells
The distribution of one per-well metric over a plan's wells under one design, without downloading the wells: how many have a value, min, max, mean, quantiles and a histogram, as PlanStats describes them.
Summarize a plan's wells
/plans/{id}/statsThe distribution of one per-well metric over a plan's wells under one design, without downloading the wells: how many have a value, min, max, mean, quantiles and a histogram, as PlanStats describes them.
What it measures
eur_boe by default on a plan made with eur: true, else cum_boe at ip_day 1080; values are rounded to 0.1, in unit. On a plan made with scenarios, every figure pools all its scenarios' wells unless scenario picks one; group_by=scenario measures each beside that pooled top level.
Quantiles and bins
Quantiles interpolate linearly between the closest ranks (NumPy's default, Hyndman and Fan type 7): q10 is the low end, 10% of wells below it. They are the spread across wells, not a forecast's uncertainty: P10/P90 bands (Novi's P10 is the low curve, the reverse of SPE PRMS) are per well, from bands: true. The histogram has bins equal-width bins from min to max, each from its lower edge up to its upper one (the last includes max); when every value is the same it is one bin.
While it runs
The figures cover the wells finished so far, with partial: true, Retry-After: 1 and no ETag. A done plan's answer carries an ETag; send it as If-None-Match for a 304. A failed plan answers 409.
Parameters
Path parameters
idstringRequiredFormat
uuidPlan id from POST /plans.
Query parameters
metricstringOptionalThe metric: eur_boe by default on a plan with EUR, else cum_boe.
Per-well metrics:
eur_oil(bbl),eur_gas(mcf) andeur_boe(BOE) are each well's EUR and need a plan made witheur: true(400 otherwise);cum_oil,cum_gasandcum_boeare the forecast's cumulative volume atip_day. BOE is oil + gas / 6, only for wells with both."eur_boe""eur_oil""eur_gas""cum_boe""cum_oil""cum_gas"designintegerOptionalDefault
0≥ 0, ≤ 9the design whose forecasts are measured, as its index in the plan's
designs; 400 past the last one.ip_dayintegerOptionalDefault
1080≥ 1for a cum_ metric, the ip_day (days since first production) whose cumulative volume is measured: one of GET /dataset
ip_days, default 1080 (3 years). 400 with an eur_ metric.binsintegerOptionalDefault
20≥ 1, ≤ 100Histogram bins.
includestringOptionalvaluesadds every well's value, ascending (ties by plan index), with its plan index: for probit plots, and for linking a point to its well. Up to the plan's wells (GET /datasetlimits.plan_wells)."values"quantilesstringOptionalWhich quantiles to return, comma-separated: whole percentiles 1 to 99, at most 9 different ones, as 10,25,50,75,90 for a box plot;
quantilesthen holds exactlyq10,q25and so on. Quantiles of wells' values (type 7, q10 the low end), not P-level bands. Absent: q10, q50 and q90.group_bystringOptionalAlso measure each group of wells:
design,formation,scenarioorpad. The top-level figures stay those ofdesign, 0 by default.design: every design of the plan; a 400 with thedesignparameter.formation: each well's target formation, wells without one askey: null.scenario: each scenario of a plan made with them; a 400 on another plan and with thescenarioparameter.pad: each stored pad key (after scenario scoping), wells without one asnull, never folded intoOther. A plan whose wells name no pads is a 400: sendwells[].pad.
Each group has its own counts, min, max, mean, quantiles and histogram, and
valueswithinclude=values, all on the sameedges(forformationandscenariothe top-level edges, fordesignevery design's), so groups plot side by side. PlanStatsgroupsgives their order;design,formationandscenariogive at most 50 groups, the rest summed in oneOtherrow withothers."design""formation""scenario""pad"normalize_lateral_ftnumberOptional≥ 100, ≤ 20000
Scale each well's value to this lateral length before measuring: value × normalize_lateral_ft / its lateral_length_ft, so 1000 gives values per 1,000 ft of lateral. Every figure is then normalised, the response echoes it, and
unitstill names the volume. 100 to 20,000.scenariostringOptional1 to 60 characters
Measure one scenario of a plan made with them: every figure, the histogram's bins and any
group_by=formationorgroup_by=designgroups cover only its wells, and the response echoes the name.Send the name exactly as the plan's
scenarioslist it, URL-encoded:660 ftisscenario=660%20ft. Withinclude=values,indexstays the well's index in the whole plan, so a point still links to its well. While the plan runs, the figures cover the scenario's wells finished so far.An empty name, or one the plan doesn't have, is a 400 whose
details.scenarioslists the plan's scenarios (empty on a plan without them, where any name is a 400). A name over 60 characters is a 400 without the list. Withgroup_by=scenarioit is a 400 ongroup_by:scenariopicks one, so leavegroup_by=scenarioout.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 distribution.
idstringRequiredFormat
uuidPlan id.
designintegerRequired≥ 0
The design, as its index in
designs.metricstringRequiredThe metric measured.
"eur_boe""eur_oil""eur_gas""cum_boe""cum_oil""cum_gas"ip_dayinteger or nullRequiredFor a cum_ metric, the ip_day measured; null for an eur_ metric.
unitstringRequiredThe unit of every value: bbl (oil), mcf (gas) or BOE.
"bbl""mcf""BOE"partialbooleanRequiredTrue while the plan runs: the figures cover the wells finished so far.
wellsintegerRequired≥ 0
Wells with a value; every figure describes them.
missingintegerRequired≥ 0
Wells finished without a value: no forecast, a failed EUR fit, or BOE without both oil and gas.
minnumber or nullRequiredSmallest value; null when no well has one.
maxnumber or nullRequiredLargest value; null when no well has one.
meannumber or nullRequiredMean value; null when no well has one.
quantilesobjectRequiredQuantiles across wells (linear interpolation between the closest ranks), not P-level bands: q10 (the 10th percentile of the wells' values, the low end), q50 (the median) and q90 (the high end), or with quantiles= exactly the asked ones; each null when no well has a value.
Show all 18 fields
histogramobjectRequiredEqual-width bins from min to max.
ShowHide 2 child fields
edgesarray of numbersRequiredBin edges, ascending, one more than counts; empty when no well has a value.
countsarray of integersRequiredItems ≥ 0
Wells per bin; they add up to wells.
normalize_lateral_ftnumberOptionalWith normalize_lateral_ft: the lateral every value was scaled to, ft.
scenariostringOptionalWith scenario: the scenario measured.
valuesobjectOptionalWith include=values: every well with a value, ascending.
ShowHide 2 child fields
indexarray of integersRequiredItems ≥ 0
The wells, by plan index, in value order.
valuearray of numbersRequiredTheir values, ascending (ties by index).
group_bystringOptionalWith group_by: what groups is by.
"design""formation""scenario""pad"groupsarray of objectsOptionalWith group_by: each design in order, each formation in GET /formations order, then wells without one, or each scenario in the order of the plan's
scenarios; pad lists all keys in first measured well order, null last, never folded into Other. For other groupings, at most 50, the rest in one Other row.ShowHide 11 child fields in each item
keystring or integer or nullRequiredThe design's index (group_by=design), the formation, null for wells without one, the scenario, the pad key (null for wells without one), or Other on the summed row. Pads never fold into Other.
wellsintegerRequired≥ 0
Wells in the group with a value.
missingintegerRequired≥ 0
Wells in the group without one.
minnumber or nullRequiredSmallest value; null when none has one.
maxnumber or nullRequiredLargest value; null when none has one.
meannumber or nullRequiredMean value; null when none has one.
quantilesobjectRequiredThe same quantiles as the top level, over this group's wells.
histogramobjectRequiredCounts on edges every group shares, so groups plot side by side.
ShowHide 2 child fields
edgesarray of numbersRequiredThe same for every group: bins bins from the smallest to the largest value of all the groups (for group_by=formation or scenario, the top-level edges); empty when no group has a value.
countsarray of integersRequiredItems ≥ 0
This group's wells per bin; they add up to its wells.
namestringOptionalWith group_by=pad, the pad's name when the plan gives one in
pads[].name; absent otherwise.keystays the pad key.valuesobjectOptionalWith include=values: this group's wells, ascending.
Same fields as PlanStatsValues.
othersintegerOptional≥ 1
On the Other row only: how many groups it sums.
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 |
Shared errors400401403500503What they mean