A.U.R.O.R.A

A.U.R.O.R.A is an R package that seamlessly integrates weather, economic, and global‑event data into a unified macro‑economic dataset for easy analysis and visualization.

Motivation

Macroeconomic analysis often requires integrating multiple external data sources such as weather data, economic indicators, and global event sentiment data. These datasets are typically accessed through different APIs and data formats, making the data collection and preprocessing workflow time-consuming and error-prone.

A.U.R.O.R.A (Analysis of Upstream Risks and Observed Regional Anomalies) addresses this challenge by providing a unified interface that automatically fetches, processes, and integrates these datasets into a single, analysis-ready macroeconomic dataset. This allows data analysts to focus more on insight generation rather than data collection and preprocessing.

Installation

You can install the development version of the package from GitHub with:

# install.packages("devtools")
devtools::install_github("mzikkhan/a.u.r.o.r.a")

Configuration

To use the economic data functions, you need a FRED API key.

1. Get a Key: Request one for free at fred.stlouisfed.org.
2. Local Usage: Set it in your .Renviron file or export it in your shell:

   FRED_API_KEY=abcdef123456...

   Or in R before running:

   Sys.setenv(FRED_API_KEY = "your_key_here")

3. CI/CD (GitHub Actions): Add FRED_API_KEY to your repository secrets (Settings > Secrets and variables > Actions > New repository secret).

Data Sources

Aurora integrates data from the following external sources:

• Open-Meteo API – Provides daily weather summaries including temperature and precipitation.
• FRED API – Provides key economic indicators such as GDP, CPI, inflation rate, and unemployment rate.
• GDELT Project – Provides global event data and sentiment indicators related to political unrest, disasters, and global news activity.

Main Functions

Function	Description
get_macroeconomic_data()	Fetches integrated macroeconomic dataset combining weather, economic, and event data
get_daily_weather()	Retrieves weather data for specified location and date range
get_daily_economic_data()	Retrieves economic indicators from FRED
gdelt_timeline_daily()	Retrieves event sentiment data from GDELT
revenue_merge()	Merges macro dataset with revenue CSV by Date
plotter()	Plots revenue vs selected variables with scaling

Usage

Here is an example of how to use the AURORA package to fetch data, merge it with revenue, and visualize the results.

# 1. Load the package
library(aurora)

# 2. Fetch Macroeconomic Data
# Provide start/end dates and location coordinates (e.g., Canada)
my_analysis_data <- get_macroeconomic_data(
  start_date = "2025-01-01",
  end_date   = "2025-12-01",
  latitude   = 55.6761, 
  longitude  = 12.5683
)

# 3. View the fetched data
head(my_analysis_data)

# 4. Integrate Revenue Data
# Merge with your internal revenue data (must have a 'Date' column)
rev_data <- revenue_merge(my_analysis_data, "Scripts/revenue_data_2025.csv")
head(rev_data)

# 5. Visualize Correlations
# Select columns to analyze against Revenue
plots <- c("avg_temp", "max_temp", "tot_rain", 
           "natural_disaster_score", "political_unrest_score",
           "interest_rate", "mortgage_rate", "unemployment", 
           "cpi_inflation", "gdp", "public_debt")

# Generate scaled plots (z-score)
plotter(rev_data,
        cols = plots,
        date_col = "Date",
        revenue_col = "Revenue",
        ncol = 3,
        scale_method = "zscore")

Error Handling

A.U.R.O.R.A is designed with robust error handling to ensure reliability during API communication. If an external data source is temporarily unavailable or returns an error, A.U.R.O.R.A gracefully handles the failure by returning missing values (NA) instead of interrupting execution. This ensures downstream workflows remain stable.

License

This project is licensed under the MIT License.
See the LICENSE file for full details.