Skip to content
Developers
Get an API token

Describe a forecast model

One stream's forecast model, as GET /models lists it.

Describe a forecast model

GET/models/{model_num}

One stream's forecast model, as GET /models lists it.

Send a Novi API token as a bearer token on every request. Authentication
The card

What a stream's forecast model is and what it saw.

Inputs

inputs are the training ranges forecast checks compare against: p01 and p99 over training rows, without the no-neighbor fill value. A design input is in checks.out_of_range only when it is more than 5% of p99 minus p01 outside them; neighbors' production features (novi_spacing_sum_prior_, novi_spacing_delgados_p) outside them, with no margin, go to checks.context instead.

Accuracy

The served all fit was refit on the holdout wells too. Held-out accuracy is the pre-refit train fit's (GET /models/{model_num}/evaluation; evaluation.available and reason say whether there is one), and holdout.rule says how holdout wells were chosen. Cached, with an ETag; on the sample stack every figure is a sample (sample_data: true).

Includes

include=groups adds each input's catalog group, include=distribution its training distribution, and include=served_fit_wells the distinct wells the served all fit was trained on.

Errors

An unknown model number is a 404.

Parameters

Path parameters

Query parameters

  • includestringOptional

    groups, distribution or served_fit_wells, comma-separated or repeated, each once; any other value is a 400 with details.field include.

    groups adds each input's Intel basin report catalog group; distribution the card's distribution and each input's training distribution (five quantiles and a 20-bin histogram, or level counts); served_fit_wells the card's count.

    "groups""distribution""served_fit_wells""groups,distribution""groups,served_fit_wells""distribution,groups""distribution,served_fit_wells""served_fit_wells,groups""served_fit_wells,distribution""groups,distribution,served_fit_wells""groups,served_fit_wells,distribution""distribution,groups,served_fit_wells""distribution,served_fit_wells,groups""served_fit_wells,groups,distribution""served_fit_wells,distribution,groups"
  • 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 model's card.

  • model_numstringRequired

    Model number, as GET /dataset models[] names it.

  • streamstringRequired

    Stream.

    "oil""gas""water"
  • targetstring or nullRequired

    Target column, as novi_oil; null when the dataset doesn't record it.

  • unitstringRequired

    Unit of its predictions.

    "bbl""mcf"
  • sample_databooleanRequired

    True when the figures come from synthetic sample data.

  • served_fitstringRequired

    The fit that serves forecasts: all, refit on training and holdout wells.

    "all"
  • trained_onstringRequired

    What the served fit saw, in words.

  • ip_daysarray of integersRequired

    ip_days the model predicts.

  • versionsobject or nullRequired

    Package versions of the fit, by package name; null when the build records none, as on the sample stack.

  • trainingobject or nullRequired

    The pre-refit train fit's training wells; null when the build doesn't record them.

    ShowHide 3 child fields
    • wellsintegerRequired

      ≥ 0

      Training wells.

    • rowsintegerRequired

      ≥ 0

      Training rows (well × ip_day).

    • first_productionobjectRequired

      First production range.

      ShowHide 2 child fields
      • fromstring or nullRequired

        Format date

        Earliest first production.

      • tostring or nullRequired

        Format date

        Latest first production.

  • holdoutobject or nullRequired

    The train fit's holdout wells; null when the build has no stored predictions.

    ShowHide 3 child fields
    • wellsintegerRequired

      ≥ 0

      Holdout wells.

    • rulestringRequired

      How they were chosen, in words.

    • first_productionobjectRequired

      First production range.

      Same fields as ModelSpan.

  • inputsarray of objectsRequired

    Each input in feature order with its training range; empty without training statistics.

    ShowHide 10 child fields in each item
    • featurestringRequired

      Model feature, as novi_lateral_length.

    • labelstringRequired

      Its display name, as Lateral length.

    • kindstringRequired

      numeric or category.

      "numeric""category"
    • p01number or nullRequired

      1st percentile over training rows, leaving out the no-neighbor value; null for a category.

    • p99number or nullRequired

      99th percentile over training rows, the same way; null for a category.

    • blank_sharenumberRequired

      ≥ 0, ≤ 1

      Share of training rows where it is blank.

    • levelsarray of strings or nullRequired

      A category's levels in training, sorted; null for a number.

    • fillnumber or nullRequired

      The features' value for no such neighbor (days online -1, distances at the spacing defaults), which p01 and p99 leave out; null when it has none.

    • groupstringOptional

      With include=groups: the input's group as Novi's Intel basin report catalog groups model features: geology, spacing, depletion (parents' prior production: novi_spacing_sum_prior_* and novi_spacing_delgados_p*, as the depletion chain reads them), completion, location, or other.

      "geology""spacing""depletion""completion""location""other"
    • distributionobject or nullOptional

      With include=distribution. Null when the card's distribution is unavailable or the model's file has no row for this input.

      ShowHide 10 child fields
      • unitstringRequired

        The input's unit (ft, lb/ft, bbl/ft, deg, fraction and so on). An empty string when the input is unitless or its unit isn't documented.

      • rowsintegerRequired

        ≥ 0

        The model's training rows (well x ip_day).

      • blankintegerRequired

        ≥ 0

        Rows that are null or NaN.

      • fillintegerRequired

        ≥ 0

        Rows holding the features' no-neighbor value. See the input's fill.

      • rangedintegerRequired

        ≥ 0

        rows - blank - fill. Only these rows enter min, max, quantiles and histogram.

      • minnumber or nullRequired

        Minimum ranged value. Null for a category or without ranged rows.

      • maxnumber or nullRequired

        Maximum ranged value. Null for a category or without ranged rows.

      • quantilesobject or nullRequired

        Null for a category or without ranged values. Compare a planned well input with these quantiles to place it in the training data.

        ShowHide 5 child fields
        • p01numberRequired

          Exact 1st percentile. Equal to the input's p01.

        • p10numberRequired

          Exact 10th percentile.

        • p50numberRequired

          Exact median.

        • p90numberRequired

          Exact 90th percentile.

        • p99numberRequired

          Exact 99th percentile. Equal to the input's p99.

      • histogramobject or nullRequired

        Null for a category or without ranged values. Add counts below a planned well input to place it in the training data.

        ShowHide 4 child fields
        • edgesarray of numbersRequired

          21 edges of 20 equal-width bins from p01 to p99. When p01 = p99 there is one bin with edges [p01, p99].

        • countsarray of integersRequired

          Items ≥ 0

          Bin i holds edges[i] <= x < edges[i+1]. The last bin also holds x = p99.

        • belowintegerRequired

          ≥ 0

          Ranged rows under p01.

        • aboveintegerRequired

          ≥ 0

          Ranged rows over p99.

      • levelsarray of objects or nullRequired

        Category counts ordered by rows descending, then level. A category has no quantiles or histogram. Null for a numeric input.

        ShowHide 2 child fields in each item
        • levelstringRequired

          Category level.

        • rowsintegerRequired

          ≥ 0

          Rows at this level.

Show all 17 fields
  • bandsobjectRequired

    P10/P90 bands, as GET /dataset bands reports them for this stream.

    ShowHide 3 child fields
    • availablebooleanRequired

      Whether the model has a stored P10/P90 bands fit.

    • methodstring or nullRequired

      How the bands are made.

    • reasonstring or nullRequired

      Why not, when it hasn't.

  • eurobjectRequired

    EUR.

    ShowHide 1 child field
    • availablebooleanRequired

      Whether eur: true extends this stream's forecasts to EUR (oil and gas, when the server fits EUR). False for water, which takes eur_water: true.

  • evaluationobjectRequired

    Held-out accuracy.

    ShowHide 3 child fields
    • availablebooleanRequired

      Whether GET /models/{model_num}/evaluation has figures for this model.

    • reasonstring or nullRequired

      Why not, when it hasn't.

    • hrefstringRequired

      Its evaluation's path.

  • served_fit_wellsinteger or nullOptional

    ≥ 0

    With include=served_fit_wells: the distinct wells the served all fit was trained on, the training and holdout wells of the build's stored predictions with a well in both counted once; null unless the build stores predictions for both splits.

  • distributionobjectOptional

    With include=distribution.

    ShowHide 2 child fields
    • availablebooleanRequired

      Whether the training distribution was read.

    • reasonstring or nullRequired

      Why not, when it isn't available.

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

Errors

StatusWhen
404

No such well, grid, plan or route.

Shared errors400401403500503What they mean