Forecast Baseline Estimator

Code

<?php

/*
 * Copyright (c) 2026 Jeffery L. Paris <jparis@phpog.com>.
 * Free for personal and internal use. Paid project use requires visible credit
 * to Jeffery L. Paris. Corporate use requires a paid license fee unless a
 * separate written license states otherwise.
 */

/**
 * Creates a simple baseline forecast using recent average and trend adjustment.
 *
 * This is a planning estimate, not a predictive guarantee.
 *
 * @param array $values Numeric time-series values.
 * @param array $options Options: horizon, window.
 * @return array Baseline forecast rows.
 */
function ogEstimateBaselineForecast($values = array(), $options = array()) {
	$result = array(
		'success' => false,
		'message' => '',
		'data' => array()
	);

	if (!is_array($values)) {
		$result['message'] = 'Values must be an array.';
		return $result;
	}

	if (!is_array($options)) {
		$options = array();
	}

	$numbers = array();
	foreach ($values as $value) {
		if (is_numeric($value)) {
			$numbers[] = (float)$value;
		}
	}
	if (count($numbers) < 2) {
		$result['message'] = 'At least two numeric values are required.';
		return $result;
	}

	$horizon = 3;
	if (!empty($options['horizon'])) {
		$horizon = (int)$options['horizon'];
	}
	if ($horizon < 1) {
		$horizon = 3;
	}

	$window = 3;
	if (!empty($options['window'])) {
		$window = (int)$options['window'];
	}
	if ($window < 1) {
		$window = 3;
	}
	if ($window > count($numbers)) {
		$window = count($numbers);
	}

	$recent = array_slice($numbers, -$window);
	$average = array_sum($recent) / count($recent);
	$first = $numbers[0];
	$last = $numbers[count($numbers) - 1];
	$trend = ($last - $first) / (count($numbers) - 1);

	$forecast = array();
	$current = $last;
	for ($period = 1; $period <= $horizon; $period++) {
		$current = (($current + $average) / 2) + $trend;
		$forecast[] = array(
			'period' => $period,
			'estimate' => $current,
			'note' => 'Baseline estimate only.'
		);
	}

	$result['success'] = true;
	$result['message'] = 'Baseline forecast built.';
	$result['data'] = array(
		'horizon' => $horizon,
		'window' => $window,
		'recent_average' => $average,
		'trend_per_period' => $trend,
		'forecast' => $forecast
	);

	return $result;
}