DOCSEARCHbyAlgolia
Submit Docs

Microsoft Finance Time Series Forecasting Framework (FinnTS)

repository·main·Indexed 42 days ago

https://github.com/microsoft/finnts

An automated R-based framework for producing financial forecasts using AI agents. FinnTS automates the pipeline from feature engineering and model selection to backtesting and explanation, utilizing LLMs via the ellmer package to iterate forecasts until target accuracy goals are met.

Tokens
1.8K
Snippets
8
Records
9
Agent score
5%

What's inside FinnTS

  1. Optional dependencies for feature selection: `vip` and `ranger`

    main

    FinnTS uses several packages for optional feature selection tasks. These are listed under Suggests and do not impact the installation of core workflows:

    • vip (>= 0.5.0): Used for feature selection reports. Available via https://bgreenwell.r-universe.dev.
    • ranger: Invoked via the parsnip engine during optional feature selection and used by the Boruta importance adapter.
    • Boruta: Used for feature selection.
    • corrr: Used for feature selection.

    Core workflows will function correctly even if these packages are not installed.

  2. Install the optional `vip` package for feature selection

    main

    The vip (>= 0.5.0) package provides optional feature-selection capabilities in FinnTS. It is not a required dependency for core workflows and can be installed from the maintainer's r-universe repository. If you require feature selection reports, you must install vip separately.

    Note that vip requires R 4.1 or newer. FinnTS core workflows remain compatible with R 4.0 without this package.

    # vip is available from the following r-universe repository:
# https://bgreenwell.r-universe.dev

  3. Install the finnts package

    main

    You can install the stable version of finnts from CRAN or the development version from GitHub using devtools.

    # CRAN version
install.packages("finnts")

# Development version
# install.packages("devtools")
devtools::install_github("microsoft/finnts")

  4. Run an automated forecast with the finnts agent

    main

    The finnts framework uses an AI agent to automate feature engineering, model selection, and backtesting. The typical workflow involves preparing historical data, connecting an LLM (via ellmer), setting up project and agent information, and then iterating the forecast until a target accuracy goal is met.

    library(finnts)

# 1. Prepare historical data
hist_data <- timetk::m4_monthly %>%
  dplyr::rename(Date = date) %>%
  dplyr::mutate(id = as.character(id))
  
# 2. Connect LLM
llm <- ellmer::chat_azure_openai(model = "gpt-4o-mini")

# 3. Set up new forecast project and agent run
project <- set_project_info(project_name = "Demo_Project", 
                            combo_variables = c("id"),
                            target_variable = "value",
                            date_type = "month")
                            
agent <- set_agent_info(project_info = project,
                        llm = llm,
                        input_data = hist_data,
                        forecast_horizon = 6)

# 4. Iterate forecast via agent
iterate_forecast(agent_info = agent,
                 max_iter = 3,
                 weighted_mape_goal = 0.03)

# 5. Load final forecast output
forecast_output <- get_agent_forecast(agent_info = agent)

# 6. Ask agent to explain results
eda_answer <- ask_agent(agent_info = agent,
                        question = "Summarize the exploratory data analysis, what stands out?")

  5. Retrieve forecast results with get_agent_forecast()

    main

    After the agent has completed its iterations, use get_agent_forecast() to extract the final forecast output.

    forecast_output <- get_agent_forecast(agent_info = agent)

  6. Set up a forecast project with set_project_info()

    main

    Use set_project_info() to define the metadata for your forecasting task. This establishes the structure for the time series data.

    Parameters:

    • project_name: A string identifier for the project.
    • combo_variables: A character vector of columns that identify unique time series (e.g., c("id")).
    • target_variable: The name of the column containing the values to forecast.
    • date_type: The frequency of the data (e.g., "month").
    project <- set_project_info(project_name = "Demo_Project", 
                            combo_variables = c("id"),
                            target_variable = "value",
                            date_type = "month")

  7. Query the agent with ask_agent()

    main

    Use ask_agent() to interact with the AI agent in natural language. You can ask questions about the exploratory data analysis (EDA), model accuracy, or the reasoning behind specific model selections.

    # Example: Asking about model selection
model_answer <- ask_agent(agent_info = agent,
                          question = "Explain why the best model was selected. How does that model work?")

  8. Configure the forecasting agent with set_agent_info()

    main

    Use set_agent_info() to initialize the AI agent that will drive the forecasting process. This links your project configuration, the LLM, and the actual data.

    Parameters:

    • project_info: The object returned by set_project_info().
    • llm: An LLM object (e.g., from the ellmer package).
    • input_data: The historical data frame.
    • forecast_horizon: The number of periods to forecast ahead.
    agent <- set_agent_info(project_info = project,
                        llm = llm,
                        input_data = hist_data,
                        forecast_horizon = 6)

  9. Iterate forecasts using iterate_forecast()

    main

    The iterate_forecast() function triggers the agent's optimization loop. The agent will attempt to improve the forecast accuracy through multiple iterations of feature engineering and model selection.

    Parameters:

    • agent_info: The object returned by set_agent_info().
    • max_iter: The maximum number of optimization iterations to perform.
    • weighted_mape_goal: The target Weighted Mean Absolute Percentage Error (WMAPE) the agent should aim for.
    iterate_forecast(agent_info = agent,
                 max_iter = 3,
                 weighted_mape_goal = 0.03)