This function updates the forecast agent with the latest data and inputs.
If new time series are detected in the data (up to 20\
with a floor of 10), simple forecasts are automatically created for them
using default local model inputs without LLM involvement. If the number
of new series exceeds the cap, an error directs the user to use
iterate_forecast() instead.
update_forecast(
agent_info,
weighted_mape_goal = 0.1,
allow_iterate_forecast = FALSE,
max_iter = 3,
parallel_processing = NULL,
inner_parallel = FALSE,
num_cores = NULL,
seed = 123
)Agent info from set_agent_info()
Weighted MAPE goal the agent is trying to achieve for each time series
Logical indicating if the forecast iteration should be allowed if poor performance is detected, meaning >40% of time series with >20% worse weighted MAPE than previous agent run
Numeric indicating the maximum number of iterations if iterate_forecast is ran
Default of NULL runs no parallel processing and forecasts each individual time series one after another. 'local_machine' leverages all cores on current machine Finn is running on. 'spark' runs time series in parallel on a spark cluster in Azure Databricks or Azure Synapse.
Run components of forecast process inside a specific time series in parallel. Can only be used if parallel_processing is set to NULL or 'spark'.
Number of cores to run when parallel processing is set up. Used when running parallel computations on local machine or within Azure. Default of NULL uses total amount of cores on machine minus one. Can't be greater than number of cores on machine minus 1.
Set seed for random number generator. Numeric value.
Nothing
If individual time series fail during the global or local model update
process, they are automatically re-forecast using default local model
inputs (the same treatment as new time series). If more than 20\
existing series (with a floor of 10) fail to update, an error is raised
directing the user to use iterate_forecast() instead.
Reused forecasts are checked against original-scale prepared actuals
after refitting and retuning. Quality-rejected series receive one default
reforecast through the same path as new series, without LLM quality judgments.
Quality-only rejections do not count toward the ordinary execution-failure
limit; existing data/provider failures retain that limit. Replacement models
are evaluated using final_models() and cannot trigger an unbounded retry.
Both new-series defaults and failed-update replacements may select a
complete finite least-issues fallback with a warning. Existing rejected
defaults are reconsidered from saved usable predictions without fitting.
This fallback does not change ordinary update or retuning acceptance.
Reused fits do not call final_models(); their components must pass hard
eligibility and their selected combination must pass applicable quality checks
before any reconciliation, including after retuning. Global updates recover
each series' saved winning single model or average from existing source
forecasts, refit the union of required components, and preserve each selected
subset. Requested but unselected models are not added back to the average.
All globally selected series must reference one winning global iteration.
Mixed global iteration metadata is rejected before refitting rather than
split into multiple global updates. Different model subsets within that
single iteration and separately selected local winners remain supported.
Missing or ambiguous saved winners or selected fits normally require
restoring the original artifacts. For older hierarchical global updates
whose source files are wholly absent, valid reconciled output and saved
global fits permit an explicit compatibility path: reuse each actual fitted
model/recipe component, averaging them equally at every source node when
there is more than one. This warns once per global group; requested but
unfitted models are never invented. Partial source sets, malformed content
and storage failures cannot trigger that compatibility path. Earlier Agent
versions are not searched to reconstruct lost per-node choices.
These are checks on newly generated predictions, not repeated assessments of
past iteration winners. A reused hierarchy that
is incomplete or contains a rejected node is not reconciled; its covered
current series follow the existing default-local forecast path. Existing
nodes are matched by identity and surviving bottom membership, not position
or node count. Reassigned generated aggregate labels are treated as new
nodes rather than inheriting another aggregate's selection. When every
predecessor source node has the same selected model or average, new inner
hierarchy source nodes inherit that uniform choice. Their component and
average forecasts must pass the same checks before publication. This keeps
existing global series usable without promoting newly added series to
global winners: their ordinary new-series/default-local routing is unchanged.
Heterogeneous selections are not extrapolated, removed nodes are not
published, and reassigned-label safeguards still apply. An incomplete inner
hierarchy continues to use default-local recovery. Stable default run
identities and saved forecasts preserve restart safety without an additional
acceptance-status column. Unpublished defaults are reassessed from saved
predictions before reuse, without fitting. The
selected mixture is then reconciled without post-reconciliation future
evaluation, whole-set replacement, or late quality-triggered refitting.
Legacy second-order differenced original targets without their own starting
values require regeneration of prepared data from the original input.
On restart, the driver checks fitted objects and required selected forecasts
only for series with current best-run metadata. Missing or damaged current
results remain eligible for refitting. Every selected forecast must match
the expected dates and scenarios from saved preparation, including expanded
weekly days. Required preparation and predecessor metadata access failures
propagate rather than triggering default fitting. CSV identities remain text.
Shared global results are checked and
updated as one group, preserving valid local winners. Workers independently
check current outputs before refitting and can finish missing best-run logging
from complete saved forecasts and existing run-log metrics. Reuse does not
repeat quality selection, date conversion, or forecast writes.
Every accepted hierarchical global update saves and validates its component
and selected-average source files before publishing best-run records.
Unselected average files are overwritten with schema-correct empty tables
to prevent stale winners after interrupted refits. Restart also checks
per-node selections, not just the union of fitted models. Preparation
caching and artifact formats are unchanged. Required predecessor and storage
access failures remain errors. These checks do not coordinate concurrent
writers or guarantee that another attempt cannot overwrite a checked file.
if (FALSE) { # \dontrun{
# load example data
hist_data <- timetk::m4_monthly %>%
dplyr::filter(date >= "2013-01-01") %>%
dplyr::rename(Date = date) %>%
dplyr::mutate(id = as.character(id))
# set up Finn project
project <- set_project_info(
project_name = "Demo_Project",
combo_variables = c("id"),
target_variable = "value",
date_type = "month"
)
# set up LLM
llm <- ellmer::chat_azure_openai(model = "gpt-4o-mini")
# set up agent info
agent_info <- set_agent_info(
project_info = project,
llm = llm,
input_data = hist_data,
forecast_horizon = 6,
hist_end_date = as.Date("2014-12-01")
)
# run the forecast iteration process
iterate_forecast(
agent_info = agent_info,
max_iter = 3,
weighted_mape_goal = 0.03
)
# update the forecast with latest data and inputs
agent_info <- set_agent_info(
project_info = project,
llm = llm,
input_data = hist_data,
forecast_horizon = 6,
hist_end_date = as.Date("2014-12-01"),
overwrite = TRUE # required to update the agent for latest data and inputs
)
update_forecast(
agent_info = agent_info,
weighted_mape_goal = 0.03
)
} # }