Copy page

Cookbook

Forecast weekly or monthly totals

Your table is one row per day, but you plan by the week. Name a coarser time level in selector, and every day is added into its week before the forecast runs:

Code
{
  "input": {
    "source": {
      "inline": {
        "date":  ["2024-01-01", "2024-01-02", "2024-01-03", "2024-01-04", "2024-01-05", "2024-01-06", "2024-01-07",
                  "2024-01-08", "2024-01-09", "2024-01-10", "2024-01-11", "2024-01-12", "2024-01-13", "2024-01-14"],
        "sales": [142, 137, 145, 139, 160, 188, 95,
                  150, 141, 139, 144, 158, 191, 99]
      }
    },
    "columns": {
      "date":  { "kind": "time", "frequency": "daily" },
      "sales": { "kind": "target", "aggregate": "sum" }
    }
  },
  "selector": { "weekly": "any" },
  "prediction_length": 4
}

Post it to https://api.retrocast.com/v1-beta/forecast?model=t0-alpha. model names the forecasting model and is required — without it the request is rejected with missing field "model".

What each part does:

• "weekly" is a time level the API adds for you. Daily data gets weekly, monthly, quarterly and yearly; monthly data gets quarterly and yearly. Weeks run Monday to Sunday.
• "aggregate": "sum" says how days combine into a week, so this forecasts weekly totals. "mean" would forecast the average day of each week instead. Every variable column needs an aggregate once you roll up — the request is rejected without one.
• "prediction_length": 4 is four weeks: once the forecast is weekly, a step is a week. "4w" and "28d" mean the same; "1mo" doesn't fit a whole number of weeks and is rejected.

Weeks your data only partly covers, at either end, are left out, so no total is missing days. The history above starts on a Monday and ends on a Sunday, so it makes exactly two weeks.

Per city, per week

Time combines with the other levels of a selector. Add an identifier level to get one weekly series per city:

Code
"selector": { "city": "any", "weekly": "any" }

Leave time out of the selector and the forecast stays at the time column's own frequency — daily here.

Only part of the history

A range keeps the weeks inside it and drops the rest:

Code
"selector": { "weekly": { "from": "2024-04-01" } }

Your own time levels

The default levels cover most calendars. Declare others under the time column's partitions, keyed by the name you'll use in selector:

Code
"date": {
  "kind": "time",
  "frequency": "daily",
  "partitions": {
    "fortnightly": { "interval": "2w", "anchor": "2024-01-01" },
    "weekly":      { "anchor": "sunday" }
  }
}

fortnightly is a new level of two-week periods starting on 1 January 2024. weekly replaces the default weekly level with weeks starting on Sunday. An anchor names where the periods start: a date, or a weekday for weekly periods.

What comes back

The same shape as any forecast, one row per week: time is the Monday each week starts on, and span is P7D. lead_time counts up a week per row: PT0S, P7D, P14D, P21D.