# Forecasts and curves

Source: https://developers.novilabs.com/forecasts/guides/forecasts-and-curves/

> Forecast drawn wells in one request, read what a forecast and its curve points mean, and how Novi labels Low and High.

A forecast is
cumulative oil, gas and water by day on production, for one well and one completion design.

## Low, Mid and High

> **Novi's P-level convention:**
> Novi labels P-levels by percentile: **P10 is the Low curve and P90 the High curve**, the reverse of SPE PRMS, where
> P90 is the low, proved case. Field names keep Novi's labels: `p10`, `P10`, `p90`, `P90`. See [P-levels](https://developers.novilabs.com/concepts/p-levels/).

- Mid (P50) is the point forecast. Without bands, a forecast is Mid alone.
- Low (P10) and High (P90) are split conformal prediction bands around one well's forecast. Ask with `bands: true`;
  `GET /dataset` says which streams have them.
- A plan's Low total is the sum of its wells' Low curves, not the plan's own Low. The same goes for High.
- The spread across a plan's wells is well quantiles (q10, q50, q90), not P-levels.

## Forecast drawn wells

`POST /forecasts` runs up to 50 drawn wells (`limits.forecast_wells`) together, spaced against each other and existing
wells, once per design, up to 25 designs.

**curl**

```sh
curl -sS --fail-with-body -X POST \
  -H "Authorization: Bearer $NOVI_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "wells": [
      {"name": "Hawk 14-2H", "shl": [-101.93, 31.93], "bhl": [-101.93, 31.957], "formation": "WOLFCAMP A"}
    ],
    "designs": [
      {"name": "Recent median"},
      {"name": "Upsized", "fluid_bbl_per_ft": 60, "proppant_lb_per_ft": 3000}
    ],
    "summary": true,
    "eur": true,
    "ip_days": [360, 720, 1080]
  }' \
  "$NOVI_API_BASE/forecasts"
```

**Python**

```python
import os

import requests

BASE = os.environ["NOVI_API_BASE"]
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['NOVI_API_TOKEN']}"

body = {
    "wells": [{"name": "Hawk 14-2H", "shl": [-101.93, 31.93], "bhl": [-101.93, 31.957],
               "formation": "WOLFCAMP A"}],
    "designs": [{"name": "Recent median"},
                {"name": "Upsized", "fluid_bbl_per_ft": 60, "proppant_lb_per_ft": 3000}],
    "summary": True,
    "eur": True,
    "ip_days": [360, 720, 1080],
}
r = session.post(f"{BASE}/forecasts", json=body, timeout=120)
r.raise_for_status()
result = r.json()

for well in result["wells"]:
    for forecast in well.get("forecasts", []):
        oil = forecast.get("oil") or {"error": forecast.get("error", "no oil stream")}
        if "error" in oil:
            print(well["label"], "design", forecast["design"], "oil failed:", oil["error"])
            continue
        print(well["label"], "design", forecast["design"],
              dict(zip(oil["ip_days"], oil["values"])), "EUR:", oil.get("eur", {}).get("value"))
```

Each well returns one `forecasts` entry per design. Each stream (`oil`, `gas`, `water`) holds:

| Field | Meaning |
| --- | --- |
| `unit` | `bbl` for oil and water, `mcf` for gas. |
| `ip_days`, `values` | Cumulative volume at each day on production. |
| `eur` | With `eur: true`: `value`, the day it is reached (`days`) and the decline fit (`arps`). |
| `bands` | With `bands: true`: `p10` (Low) and `p90` (High), each with its `values`, and an `eur` with `band_eur: true`. |
| `error` | In place of the above, why this stream has no forecast. |

| Option | Effect |
| --- | --- |
| `summary: true` | Each well as a compact summary |
| `ip_days` | Only the days you list |
| `boe: true` | BOE (oil plus gas at 6 mcf per bbl) beside the streams |
| `totals: true` | Totals per design |
| `explain: true` | Each forecast's drivers and the training wells it leans on. Up to 10 wells × designs |
| `async: true` | Runs as a [job](https://developers.novilabs.com/forecasts/guides/jobs-and-retries/): read it with `GET /forecasts/{id}?wait=25` |

Every forecast carries `checks`. Show the flag beside any number from a flagged well.

| Check | Meaning |
| --- | --- |
| `out_of_range` | Inputs outside what the models saw in training |
| `missing` | Blank inputs the training rarely had blank |
| `flagged` | Any check applies |

## What a curve means

- A curve is cumulative volume at each `ip_day`, from 0 on day 0, straight from point to point. A period's volume is
  the cumulative at its end minus the cumulative at its start.
- EUR is opt-in: a decline-curve fit that extends the forecast to the EUR day (settings in `GET /dataset`
  `eur.defaults`). It is not a model output.
- With an EUR, a curve follows the extension to the EUR day, then stays flat. Without one, it ends at its last point.

## Read a plan's curves

`GET /plans/{id}/curves` pages through a done plan's wells: cumulative volume per stream every 30 days to EUR, the same
numbers the monthly export writes.

| Parameter | Default | Meaning |
| --- | --- | --- |
| `design` | `0` | The design, by its index in the plan's `designs`. |
| `streams` | every stream the plan serves | Comma-separated, as `oil,gas`. |
| `p_levels` | `P50` | Comma-separated from `P50`, `P10`, `P90`. Low and High need a plan made with bands. |
| `limit` | `100` | Wells per page, 1 to 200. |
| `cursor` | | `next_cursor` from the previous page. |
| `start_date` | | `til`, or a date as `YYYY-MM-DD`, to add volumes by calendar month. |

```json
{
  "plan_id": "e287ce51-430c-4871-87c2-e9c4191fb412",
  "design": 0,
  "step_days": 30,
  "streams": ["oil", "gas"],
  "p_levels": ["P50"],
  "wells": [
    {
      "index": 0,
      "key": "DRAWN-0",
      "well_uid": "54a872630fdca9a2660d598fe5467269",
      "label": "Plan well 1",
      "name": "Hawk 14-2H",
      "til_date": "2027-03-01",
      "shl": [-101.93, 31.93],
      "bhl": [-101.93, 31.957],
      "curves": {
        "oil": { "unit": "bbl", "P50": { "cum": [18412.35, 33021.8, 45210.06], "model_months": 36, "extension": "arps", "note": null } },
        "gas": { "error": "The forecast worker failed: gas model timed out" }
      }
    }
  ],
  "next_cursor": null
}
```

The `cum` array is cut short here. To read a well:

- `cum[m-1]` is the cumulative at day 30·m, to 0.01, or `null`. IP30 is `cum[0]`, IP540 `cum[17]`; divide by 30·m for
  the average daily rate.
- The first `model_months` points are the model's, the rest the decline extension. `extension` is `arps`, `flat` or
  `table`, or `null` with a `note` saying why the curve stops.
- An unplaced well, a failed stream or a missing band comes back as `{"error": "..."}` in place of its curves.
- `well_uid` (32 characters) is the same on every read of the plan. `key` is unique within one plan only.
- Only a done plan has curves. Send a page's `ETag` back as `If-None-Match` to learn that nothing changed.

### Calendar months

With `start_date`, each curve adds `calendar`: volume per calendar month from `first_month` (`YYYY-MM`).

- `start_date=til` starts each well at its TIL date, else the plan's day; `start_date_source` says which (`til`,
  `plan_day` or `request`). `start_date=YYYY-MM-DD` starts every well that day.
- The first month is partial unless the start is a 1st. The months add up to the last cumulative, within rounding.

## Curves you already have

`POST /declines` fits the same EUR decline to cumulative curves you send.

## Explanations

`GET /plans/{id}/wells/{index}/explanations/{design}` explains one plan well: each input's contribution per day
(SHAP), the training wells it leans on, and, on request, analog wells with their production. An analog spread is a
peer range, not Low and High.
