Metric Forecasting

Forecasts help you anticipate trajectory and spot divergence early—before lagging KPIs confirm it. Segflow uses a Prophet-based service to generate forward-looking values for any metric with sufficient history, storing both point forecasts and uncertainty bands (P10 / P50 / P90).

What you get

• Predicted values for the next N days (yHat)
• Uncertainty intervals (yP10, yP50, yP90) for each future date
• Run metadata (model version, parameters, training size, horizon)
• Quality metrics (MAE/RMSE/MAPE) when available for the run

These forecasts are saved to:

• metric_forecast_run: one record per forecast run (model, horizon, parameters, quality, status)
• metric_forecast: many future-dated predictions for that run (yHat, yP10, yP50, yP90)

How it works (conceptual)

Segflow trains a time-series model (Prophet) on your metric’s historical events and projects it forward day-by-day.

Key behaviors:

• Seasonality & trend: Prophet decomposes the series into trend and seasonal components and extrapolates them forward.
• Uncertainty bands: We return a central estimate (≈ P50) with lower/upper bounds (≈ P10 / P90) so you see the plausible range.
• Data hygiene: Duplicate dates are averaged to keep the series well-formed.
• Bounded history: Extremely long histories are capped to a configured max (keeps runs snappy; preserves recent signal).
• Daily cadence: Forecasts are generated at daily frequency; higher-level intervals (weekly/monthly) can be rolled up in views.

Inputs, parameters & outputs (practical)

Inputs

• Historical events: a time-ordered list of { date, value } for the metric.
• Minimum history: You need at least min_training_points to run a forecast (configurable).

If there are fewer than the minimum required points, the service raises an InsufficientDataError.

Parameters we expose (Prophet)

We also cap max training points (config) to ensure performance on very long histories.

Outputs we store

For each future date (strictly after the last observed point):

Run metadata

• modelVersion (e.g., prophet-1.1.5)
• forecastHorizon
• trainingDataPoints
• parameters (the full parameter set used)
• quality (e.g., MAE/RMSE/MAPE) when computed

Running a forecast (UI flow)

Interpreting forecasts

• P50 path: Our best single-line estimate of where the metric is headed.
• P10–P90 band: Expected range given historical volatility and trend.
• Early warning: If actual values trend below P10 (or above P90), investigate drivers or consider a strategic response.
• Compare runs: Use forecast runs to see how the expected path changes as new data arrives.

Quality & data readiness

Good forecasts start with good data. Aim for:

• Sufficient history: At least the configured min_training_points (more is better).
• Consistent cadence: Regular measurement intervals reduce noise.
• Proper aggregation: Use an appropriate roll-up (sum/average/increase/weighted_average/last_month_available) for the metric’s nature.
• Stable definitions: Avoid mid-stream changes to how a metric is calculated.

Quality metrics (when available):

• MAE (Mean Absolute Error): Average absolute deviation.
• RMSE: Penalizes larger errors more strongly.
• MAPE: Percentage-based error; intuitive for scale-free comparison.

Use these to compare different parameterizations and to gauge fit over the training window.

Edge cases & limitations

• Insufficient data → InsufficientDataError (add more history or reduce horizon).
• Highly erratic series may yield wide uncertainty bands—use relationships & analyses for context.
• Sudden structural breaks (e.g., pricing change) won’t be known to the model until post-change data accumulates.
• Holiday/special events: If applicable, consider enabling or modeling explicit seasonal components.

How forecasts feed the rest of the system

• Driver Analysis: Compare expected vs. actual to spot emerging driver shifts.
• Bet Impact Analysis: Use forecasts as the “business-as-usual” baseline; compare post-bet trajectories to estimate lift.
• Growth Loop Analysis: Overlay forecasts to test whether compounding effects are strengthening or decaying.

Best practices

• Start with default parameters; only tune if you see systematic under/over-fit.
• Use 80% intervals for planning; widen for higher uncertainty.
• Re-run on a regular cadence (e.g., weekly) to keep context fresh.
• Treat the band as the signal: persistent band breaks merit action.

FAQ

Q: Why daily frequency if my metric is weekly/monthly? A: Daily forecasts provide a consistent base cadence; views can roll up to higher intervals.

Q: Can I forecast with gaps or duplicates? A: Duplicates are averaged during preprocessing. Large gaps reduce quality; aim for consistent coverage.

Q: Do forecasts include seasonality by default? A: Yearly/weekly/daily seasonality can be toggled; choose what matches your metric’s behavior.

Under the hood (for the curious)

Segflow’s forecast service:

• Validates minimum history; caps max training size for performance.
• Sorts and deduplicates by date (averaging duplicates).
• Trains Prophet with your parameters.
• Generates a future dataframe for your chosen horizon (daily).
• Maps Prophet outputs to P10/P50/P90 for consistent bands.
• Returns run metadata (model version, parameters, training size).

This is captured in:

• metric_forecast_run (configuration, quality, status, model version)
• metric_forecast (per-date yHat, yP10, yP50, yP90)

Next steps

• Explore Driver Analysis to explain why a forecasted shift might occur.
• Use Bet Impact Analysis to compare expected (forecast) vs. observed outcomes post-launch.
• Review the Metrics Introduction to ensure your metrics are defined and connected well for forecasting.