Title:	Empirical Discovery of Differential Equations from Time Series Data
Version:	0.1.2
Description:	A comprehensive toolkit for discovering differential and difference equations from empirical time series data using symbolic regression. The package implements a complete workflow from data preprocessing (including Total Variation Regularized differentiation for noisy economic data), visual exploration of dynamical structure, and symbolic equation discovery via genetic algorithms. It leverages a high-performance 'Julia' backend ('SymbolicRegression.jl') to provide industrial-grade robustness, physics-informed constraints, and rigorous out-of-sample validation. Designed for economists, physicists, and researchers studying dynamical systems from observational data.
License:	MIT + file LICENSE
Encoding:	UTF-8
RoxygenNote:	7.3.3
SystemRequirements:	Julia (>= 1.6)
Depends:	R (≥ 4.0.0)
Imports:	JuliaCall (≥ 0.17), CVXR (≥ 1.0), minpack.lm (≥ 1.2), signal (≥ 0.7), lmtest (≥ 0.9), tseries (≥ 0.10), ggplot2 (≥ 3.4.0), gridExtra (≥ 2.3), stats, graphics, grDevices, utils, methods
Suggests:	osqp (≥ 0.6), ECOSolveR (≥ 0.5), testthat (≥ 3.0.0), knitr (≥ 1.40), rmarkdown (≥ 2.20), covr, mgcv
Config/testthat/edition:	3
VignetteBuilder:	knitr
URL:	https://github.com/IsadoreNabi/EmpiricalDynamics
BugReports:	https://github.com/IsadoreNabi/EmpiricalDynamics/issues
NeedsCompilation:	no
Packaged:	2026-01-11 21:28:53 UTC; ROG
Author:	José Mauricio Gómez Julián [aut, cre]
Maintainer:	José Mauricio Gómez Julián <isadore.nabi@pm.me>
Repository:	CRAN
Date/Publication:	2026-01-16 11:30:34 UTC

Create Analysis Summary

Description

Creates a concise text summary of the analysis.

Usage

analysis_summary(results, verbose = TRUE)

Arguments

Value

Character string with summary.

Analyze Bifurcations

Description

Examines how fixed points change as a parameter varies.

Usage

analyze_bifurcations(
  equation,
  variable,
  parameter,
  param_range = c(-5, 5),
  n_param = 50,
  z_range = c(-10, 10),
  exogenous_values = list()
)

Arguments

Value

Object of class "bifurcation_analysis".

Analyze Fixed Points

Description

Finds and characterizes fixed points of the discovered equation.

Usage

analyze_fixed_points(
  equation,
  variable,
  range = c(-10, 10),
  n_grid = 100,
  exogenous_values = list()
)

Arguments

Value

Data frame of fixed points with stability classification.

Examples

# Toy example: dZ = 2*Z - Z^2 (Logistic growth)
data <- data.frame(Z = seq(0.1, 3, length.out=50))
data$dZ <- 2*data$Z - data$Z^2
model <- stats::lm(dZ ~ I(Z) + I(Z^2) + 0, data = data)

# Analyze (note: linear models on dZ aren't direct ODEs, but this demonstrates structure)
# For correct usage, 'equation' should be from fit_specified_equation
fp <- analyze_fixed_points(model, variable = "Z", range = c(0, 3))

Annotate Hypotheses

Description

Records researcher hypotheses based on visual exploration, to be used as constraints or guides in subsequent symbolic search.

Usage

annotate_hypotheses(data, hypotheses)

Arguments

Value

Data frame with hypotheses attached as attribute.

Examples

# Toy example
data <- data.frame(Z = 1:10)
data <- annotate_hypotheses(data, c(
  "Z exhibits logistic saturation around Z=100",
  "Effect of X appears linear"
))

ARCH-LM Test

Description

ARCH-LM Test

Usage

arch_test(x, lags = 5)

Block Bootstrap Indices

Description

Block Bootstrap Indices

Usage

block_bootstrap_indices(n, block_size)

Bootstrap Confidence Intervals for Parameters

Description

Computes bootstrap confidence intervals for equation parameters.

Usage

bootstrap_parameters(
  equation,
  data,
  response = NULL,
  derivative_col = NULL,
  n_boot = 500,
  conf_level = 0.95,
  block_size = NULL
)

Arguments

Value

Data frame with parameter estimates and confidence intervals.

Build Pareto Front from Results

Description

Build Pareto Front from Results

Usage

build_pareto_front(results)

Check Qualitative Behavior

Description

Comprehensive check of whether the discovered equation exhibits expected qualitative features.

Usage

check_qualitative_behavior(
  equation,
  data,
  variable,
  expected_features = list()
)

Arguments

Value

Object of class "qualitative_check".

Coefficient Change Between Equations

Description

Coefficient Change Between Equations

Usage

coefficient_change(eq1, eq2)

Generate Coefficient Table

Description

Creates a publication-ready table of estimated coefficients.

Usage

coefficient_table(
  equation,
  bootstrap_results = NULL,
  format = c("data.frame", "latex", "markdown", "html"),
  caption = "Estimated Coefficients",
  label = "tab:coefficients"
)

Arguments

Value

Formatted table.

Compare Differentiation Methods

Description

Applies multiple differentiation methods to the same data and produces a comparison plot.

Usage

compare_differentiation_methods(
  Z,
  t = NULL,
  methods = c("tvr", "savgol", "spline", "finite_diff"),
  plot = TRUE
)

Arguments

Value

List of derivative vectors from each method.

Compare OLS and GLS Estimation

Description

Produces a comparison of drift estimates from ordinary least squares versus iterative GLS.

Usage

compare_estimation_methods(ols_model, gls_model, data)

Arguments

Value

Invisibly returns comparison statistics

Compare Simulated and Observed Trajectories

Description

Computes metrics comparing simulated trajectories to observed data.

Usage

compare_trajectories(
  simulation,
  observed_data,
  time_col = "time",
  var_col = NULL
)

Arguments

Value

Data frame with comparison metrics.

Compute Derivative of a Time Series

Description

Main dispatcher function for numerical differentiation. Supports multiple methods appropriate for different data characteristics.

Usage

compute_derivative(
  Z,
  t = NULL,
  method = c("tvr", "savgol", "spline", "finite_diff", "spectral"),
  ...
)

Arguments

Details

Available methods:

• tvr: Total Variation Regularized differentiation (recommended for economic data with trends and shocks).

• savgol: Savitzky-Golay filter (moderate noise, preserves peaks).

• spline: Smoothing spline (high noise, prioritizes trend).

• finite_diff or fd: Centered finite differences (low noise).

• spectral: FFT-based (periodic data only).

Value

Numeric vector of estimated derivatives with diagnostic attributes.

See Also

compute_derivative_tvr, suggest_differentiation_method

Examples

t <- seq(0, 10, by = 0.1)
Z <- sin(t) + rnorm(length(t), sd = 0.1)

# Finite differences (fast, no dependencies)
dZ_fd <- compute_derivative(Z, t, method = "finite_diff")

# Access the derivative vector for plotting
plot(t, dZ_fd$derivative, type = "l", main = "Derivative Comparison")
lines(t, cos(t), col = "red", lty = 2) # True derivative


# TVR (requires CVXR)
if (requireNamespace("CVXR", quietly = TRUE)) {
  dZ_tvr <- compute_derivative(Z, t, method = "tvr")
}

Centered Finite Differences

Description

Computes derivatives using centered finite differences.

Usage

compute_derivative_fd(Z, t = NULL, ...)

Arguments

Value

List with derivative vector.

Savitzky-Golay Derivative

Description

Computes derivatives using the Savitzky-Golay filter.

Usage

compute_derivative_savgol(Z, t = NULL, p = 3, n = NULL, m = 1, ...)

Arguments

Value

List with derivative vector.

Spectral (FFT) Differentiation

Description

Computes derivatives using the Fourier transform.

Usage

compute_derivative_spectral(Z, t = NULL, ...)

Arguments

Value

List with derivative vector.

Warning

This method assumes the signal is periodic.

Smoothing Spline Derivative

Description

Computes derivatives by fitting a smoothing spline and differentiating it.

Usage

compute_derivative_spline(Z, t = NULL, spar = NULL, df = NULL, ...)

Arguments

Value

List with derivative vector.

Total Variation Regularized Differentiation

Description

Computes derivatives by solving a convex optimization problem that balances fidelity to the data against smoothness of the derivative.

Usage

compute_derivative_tvr(Z, t = NULL, lambda = "auto", solver = "osqp", ...)

Arguments

Value

Object of class "tvr_derivative" (also a list with $derivative).

Compute Derivatives for Specified Variables

Description

Convenience function to compute derivatives for all endogenous variables in a specified dataset.

Usage

compute_derivatives(data, method = "tvr", prefix = "d_", ...)

Arguments

Value

Data frame with derivative columns added.

Compute Excess Kurtosis

Description

Compute Excess Kurtosis

Usage

compute_kurtosis(x)

Compute Residuals from Symbolic Equation

Description

Calculates residuals from a fitted symbolic equation or SDE model.

Usage

compute_residuals(model, data, target = NULL)

Arguments

Value

Numeric vector of residuals

Compute Skewness

Description

Compute Skewness

Usage

compute_skewness(x)

Construct Stochastic Differential Equation Model

Description

Combines a drift equation and diffusion model into a complete SDE: dZ = f(Z, X, Y) dt + g(Z, X, Y) dW

Usage

construct_sde(
  drift,
  diffusion = NULL,
  variable = NULL,
  refine_with_gls = FALSE,
  gls_max_iter = 10,
  gls_tolerance = 1e-04,
  data = NULL,
  target = NULL
)

Arguments

Value

An object of class "sde_model"

Create Block Folds (for time series)

Description

Create Block Folds (for time series)

Usage

create_block_folds(n, k, block_size = NULL)

Create Random Folds

Description

Create Random Folds

Usage

create_random_folds(n, k)

Create Rolling Folds (walk-forward validation)

Description

Create Rolling Folds (walk-forward validation)

Usage

create_rolling_folds(n, k, horizon = 1)

Create Candidate Transformations

Description

Generates derived variables based on specified transformations that may be theoretically relevant.

Usage

create_transformations(
  data,
  transformations = NULL,
  variables = NULL,
  cols = NULL
)

Arguments

Value

Data frame with transformation columns added.

Examples

data <- data.frame(X = 1:10, Y = 10:1)

# Simple interface
data <- create_transformations(data, variables = c("X", "Y"))

# Formula interface
data <- create_transformations(data, transformations = list(
  ratios = ~ X/Y
))

Cross-Validate Discovered Equation

Description

Performs k-fold or block cross-validation to assess out-of-sample predictive performance of the discovered equation.

Usage

cross_validate(
  equation,
  data,
  response = NULL,
  derivative_col = NULL,
  k = 5,
  method = c("block", "random", "rolling"),
  block_size = NULL,
  horizon = 1,
  refit_derivative = FALSE,
  diff_method = "tvr",
  verbose = TRUE
)

Arguments

Value

Object of class "cv_result" containing:

Examples

# Toy example using lm
data <- data.frame(
  time = 1:50,
  y = seq(1, 10, length.out = 50) + stats::rnorm(50, sd = 0.1)
)
# Simple linear model as a proxy for a discovered equation
model <- stats::lm(y ~ time, data = data)

# Run cross-validation
cv_res <- cross_validate(
  equation = model,
  data = data,
  response = "y",
  k = 3,
  method = "random"
)
print(cv_res)

Define Custom Operators

Description

Defines custom mathematical operators for use in symbolic search.

Usage

define_custom_operators(...)

Arguments

Value

List of operator definitions suitable for symbolic_search.

Examples

ops <- define_custom_operators(
  logistic = function(x, k = 1, x0 = 0) 1 / (1 + exp(-k * (x - x0))),
  threshold = function(x, c) ifelse(x > c, 1, 0)
)

Data Frame to HTML Table

Description

Data Frame to HTML Table

Usage

df_to_html(df, caption = NULL)

Data Frame to LaTeX Table

Description

Data Frame to LaTeX Table

Usage

df_to_latex(df, caption = NULL, label = NULL)

Data Frame to Markdown Table

Description

Data Frame to Markdown Table

Usage

df_to_markdown(df)

Diagnose Sampling Frequency

Description

Evaluates whether the sampling frequency is appropriate for capturing the dynamics of the phenomenon.

Usage

diagnose_sampling_frequency(Z, t = NULL)

Arguments

Value

List with diagnostic information and recommendations.

Default ggplot2 Theme for EmpiricalDynamics

Description

A clean, publication-ready theme for all diagnostic plots.

Usage

ed_theme(base_size = 11, base_family = "")

Arguments

Value

A ggplot2 theme object.

Automatic Initial Value Estimation

Description

Estimates reasonable starting values for nonlinear least squares.

Usage

estimate_initial_values(
  expression,
  data,
  response = NULL,
  derivative_col = NULL,
  method = c("grid_search", "random", "heuristic"),
  n_tries = 100
)

Arguments

Value

Named list of initial values.

Iterative GLS Estimation for SDEs

Description

Refines drift and diffusion estimates using iterative Generalized Least Squares, which is more appropriate when heteroscedasticity is substantial.

Usage

estimate_sde_iterative(
  target,
  predictors,
  data,
  initial_drift = NULL,
  max_iter = 10,
  tol = 1e-04
)

Arguments

Value

An sde_model object with refined estimates

Evaluate equation with modified coefficients

Description

Evaluate equation with modified coefficients

Usage

eval_with_coefs(equation, data, new_coefs)

Visual Exploration of Dynamical Structure

Description

Functions for visually exploring the structure of dynamical systems before formal model fitting. These diagnostics should be used BEFORE any symbolic search to inform hypotheses about functional forms.

Comprehensive Dynamics Exploration

Description

Generates a battery of diagnostic plots to explore the dynamical structure of the data and suggests potential functional forms.

Usage

explore_dynamics(
  data,
  target,
  predictors = NULL,
  time = NULL,
  n_bins = 10,
  include = "all"
)

Arguments

Value

A list containing:

• suggestions: Character vector of suggested functional forms

• statistics: Data frame of diagnostic statistics

• plots: List of ggplot objects (if available)

Examples

# Toy example
data <- data.frame(
  time = 1:50,
  Z = sin(seq(0, 10, length.out = 50)),
  X = cos(seq(0, 10, length.out = 50))
)
data$dZ <- c(diff(data$Z)/diff(data$time), NA)
data <- na.omit(data)

result <- explore_dynamics(data, 
  target = "dZ",
  predictors = c("Z", "X")
)
print(result$suggestions)

Export Results to Multiple Formats

Description

Exports analysis results to various file formats.

Usage

export_results(
  results,
  output_dir,
  prefix = "empirical_dynamics",
  formats = c("rds", "csv")
)

Arguments

Value

List of paths to created files.

Examples

# Toy example
tmp_dir <- tempdir()
mock_results <- list(
  equation = stats::lm(mpg ~ wt, data = mtcars)
)

# Export
paths <- export_results(mock_results, output_dir = tmp_dir, formats = c("csv", "rds"))

Find Knee Point in Pareto Front

Description

Uses the maximum curvature method to find the "elbow" of the Pareto front.

Usage

find_knee_point(x, y)

Fit Residual Distribution

Description

Fits candidate probability distributions to residuals, optionally with parameters that depend on state variables.

Usage

fit_residual_distribution(
  residuals,
  candidates = c("normal", "t", "skew-normal"),
  conditional_on = NULL,
  data = NULL
)

Arguments

Value

List with best fitting distribution and parameters

Fit Specified Equation

Description

Fits a researcher-specified functional form, estimating only the parameters. Uses Levenberg-Marquardt algorithm for robustness.

Usage

fit_specified_equation(
  expression,
  data,
  response = NULL,
  derivative_col = NULL,
  start = NULL,
  method = c("LM", "nls", "optim"),
  weights = NULL,
  lower = -Inf,
  upper = Inf
)

Arguments

Value

An object of class "symbolic_equation" containing the fitted model.

Examples

# Toy example
data <- data.frame(Z = seq(1, 10, length.out = 20))
data$dZ <- 0.5 * data$Z * (1 - data$Z / 20) + rnorm(20, sd = 0.01)

# Fit logistic equation
eq <- fit_specified_equation(
  expression = "r * Z * (1 - Z/K)",
  data = data,
  response = "dZ",
  start = list(r = 0.5, K = 20)
)
print(eq)

Fit Student's t Distribution

Description

Fit Student's t Distribution

Usage

fit_t_distribution(x)

Fit Using General Optimization

Description

Fit Using General Optimization

Usage

fit_with_optim(target_name, expression, data, start, weights, lower, upper)

Format Equation for Display

Description

Creates a nicely formatted string representation of the equation.

Usage

format_equation(
  equation,
  format = c("text", "latex", "markdown"),
  precision = 4
)

Arguments

Value

Formatted string.

Format Equation String

Description

Format Equation String

Usage

format_equation_string(expression, coefficients)

Generate Analysis Report

Description

Creates a comprehensive report of the entire analysis workflow.

Usage

generate_report(
  results,
  output_file,
  format = c("markdown", "html", "latex"),
  title = "Empirical Dynamics Analysis Report",
  author = "EmpiricalDynamics",
  include_plots = TRUE
)

Arguments

Value

Path to generated report.

Examples

# Toy example to demonstrate report generation
# Using a temporary file to avoid writing to user's working directory
tmp_file <- tempfile("report_example")

# Mock results object
mock_results <- list(
  data = data.frame(time = 1:10, Z = runif(10)),
  equation = stats::lm(Z ~ time, data = data.frame(time = 1:10, Z = runif(10)))
)

# Generate report
report_path <- generate_report(mock_results, output_file = tmp_file, format = "markdown")
if(file.exists(report_path)) unlink(report_path)

Get Analysis Template

Description

Returns a template script for running a complete analysis.

Usage

get_analysis_template(output_file = NULL)

Arguments

Value

Template code as character string (invisibly).

Examples

# Save template to a temporary file
tmp_file <- tempfile("analysis_template", fileext = ".R")
get_analysis_template(tmp_file)

# Clean up
if (file.exists(tmp_file)) unlink(tmp_file)

Get Full Pareto Set

Description

Returns all equations on the Pareto front as a list.

Usage

get_pareto_set(results)

Arguments

Value

List of symbolic_equation objects.

List Available Example Datasets

Description

Returns information about the example datasets included with the package.

Usage

list_example_data()

Value

A data.frame with dataset names and descriptions.

Examples

list_example_data()

Load Example Dataset

Description

Load one of the example datasets included with the package.

Usage

load_example_data(name)

Arguments

Value

A data.frame containing the time series data.

Examples

# Load logistic growth data if available
if(requireNamespace("utils", quietly = TRUE)) {
  try({
    data <- load_example_data("logistic_growth")
    head(data)
  })
}

Generate Model Comparison Table

Description

Creates a table comparing multiple candidate equations.

Usage

model_comparison_table(
  equations,
  data,
  derivative_col,
  format = c("data.frame", "latex", "markdown"),
  caption = "Model Comparison"
)

Arguments

Value

Comparison table.

Model Conditional Variance

Description

Estimates how the residual variance depends on state variables, used for constructing the diffusion term of an SDE.

Usage

model_conditional_variance(
  residuals,
  predictors,
  data = NULL,
  method = c("symbolic", "linear", "quadratic", "gam", "constant"),
  transform = c("absolute", "squared", "log_squared"),
  ...
)

Arguments

Value

An object of class "variance_model" containing the fitted model

Output and Report Generation

Description

Functions for generating publication-ready outputs including LaTeX equations, comprehensive reports, and formatted summaries.

Plot Bifurcation Diagram

Description

Plot Bifurcation Diagram

Usage

## S3 method for class 'bifurcation_analysis'
plot(x, ...)

Arguments

Value

A ggplot object.

Plot CV Results

Description

Plot CV Results

Usage

## S3 method for class 'cv_result'
plot(x, type = c("predictions", "folds", "both"), ...)

Arguments

Value

A ggplot object or a list of ggplot objects.

Plot Simulated Trajectories

Description

Plot Simulated Trajectories

Usage

## S3 method for class 'trajectory_simulation'
plot(
  x,
  observed_data = NULL,
  show_trajectories = TRUE,
  n_show = 20,
  alpha_traj = 0.2,
  ...
)

Arguments

Value

A ggplot object.

Plot Method for TVR Derivative

Description

Plot Method for TVR Derivative

Usage

## S3 method for class 'tvr_derivative'
plot(x, t = NULL, ...)

Arguments

Value

Invisibly returns the input object (called for side effects).

Plot Validation Results

Description

Plot Validation Results

Usage

## S3 method for class 'validation_result'
plot(x, ...)

Arguments

Value

A list of ggplot objects (invisible).

Bivariate Scatter Plot

Description

Creates a scatter plot with optional nonparametric fit and marginal distributions.

Usage

plot_bivariate(
  data,
  x_var,
  y_var,
  color_var = NULL,
  show_fit = TRUE,
  show_marginals = FALSE
)

Arguments

Value

A ggplot object.

Plot Pareto Front

Description

Visualizes the trade-off between equation complexity and fit quality.

Usage

plot_pareto_front(results, highlight_selection = "knee", show_all = FALSE)

Arguments

Value

A ggplot object.

1D Phase Diagram

Description

Creates a phase diagram plotting dZ vs Z, useful for visualizing autonomous dynamics and identifying fixed points.

Usage

plot_phase_1d(
  data,
  z_var,
  dz_var = NULL,
  show_zero_line = TRUE,
  show_fit = TRUE,
  fit_method = "loess"
)

Arguments

Details

In the phase diagram:

• Points where the curve crosses dZ = 0 are fixed points

• Negative slope at crossing indicates stability

• Positive slope indicates instability

Value

A ggplot object.

Plot Residual Diagnostics Panel

Description

Creates a multi-panel diagnostic plot for residual analysis.

Usage

plot_residual_diagnostics_panel(x, ...)

Arguments

Value

Invisibly returns the input object

3D Response Surface

Description

Creates a 3D surface or contour plot showing how the target variable depends on two predictors.

Usage

plot_surface_3d(
  data,
  x_var,
  y_var,
  z_var,
  type = c("contour", "filled_contour", "persp"),
  n_grid = 30,
  method = "loess"
)

Arguments

Value

A plot (base graphics for persp, ggplot for contour).

Time Series Plot

Description

Creates a time series plot with optional trend line and change point detection.

Usage

plot_timeseries(
  data,
  var,
  time = NULL,
  show_trend = TRUE,
  highlight_changes = TRUE
)

Arguments

Value

A ggplot object.

2D Trajectory Plot

Description

Plots the trajectory of a system in the (Z, X) plane, useful for visualizing attractors and limit cycles.

Usage

plot_trajectory_2d(
  data,
  x_var,
  y_var,
  time_var = NULL,
  show_arrows = TRUE,
  arrow_spacing = 10,
  show_start_end = TRUE
)

Arguments

Value

A ggplot object.

Diagnostic Plot for TVR Differentiation

Description

Produces a four-panel diagnostic plot showing the original series, estimated derivative, reconstruction comparison, and residuals.

Usage

plot_tvr_diagnostic(Z, t = NULL, dZ_tvr)

Arguments

Value

Invisibly returns a list of diagnostic values.

Predict from Variance Model

Description

Predict from Variance Model

Usage

## S3 method for class 'variance_model'
predict(object, newdata, ...)

Arguments

Value

Numeric vector of predicted standard deviations.

Preprocessing Functions for Time Series Data

Description

Functions for data preparation, variable specification, and numerical differentiation including Total Variation Regularized (TVR) differentiation for noisy economic data.

Print CV Results

Description

Print CV Results

Usage

## S3 method for class 'cv_result'
print(x, ...)

Arguments

Value

Invisibly returns the input object (called for side effects).

Print Qualitative Check Results

Description

Print Qualitative Check Results

Usage

## S3 method for class 'qualitative_check'
print(x, ...)

Arguments

Value

Invisibly returns the input object (called for side effects).

Print Residual Diagnostics

Description

Print Residual Diagnostics

Usage

## S3 method for class 'residual_diagnostics'
print(x, ...)

Arguments

Value

Invisibly returns the input object (called for side effects).

Print Method for TVR Derivative

Description

Print Method for TVR Derivative

Usage

## S3 method for class 'tvr_derivative'
print(x, ...)

Arguments

Value

Invisibly returns the input object (called for side effects).

Print Validation Results

Description

Print Validation Results

Usage

## S3 method for class 'validation_result'
print(x, ...)

Arguments

Value

Invisibly returns the input object (called for side effects).

Print Analysis Summary

Description

Print Analysis Summary

Usage

print_summary(results)

Arguments

Value

Invisibly returns the input results object (called for side effects).

Convert R Expression to LaTeX

Description

Convert R Expression to LaTeX

Usage

r_to_latex_expr(expr, variable = "Z")

Read Empirical Data from File

Description

Reads time series or panel data from various file formats and prepares it for use with EmpiricalDynamics functions.

Usage

read_empirical_data(file, time_col = NULL, date_format = NULL, ...)

Arguments

Value

A data.frame with time column converted to numeric if needed.

Residual Analysis and Stochastic Differential Equations

Description

Functions for analyzing residual structure, modeling conditional variance, constructing stochastic differential equations (SDEs), and iterative GLS estimation for heteroscedastic systems.

Comprehensive Residual Diagnostics

Description

Performs a battery of statistical tests on model residuals to check for autocorrelation, heteroscedasticity, and normality.

Usage

residual_diagnostics(
  residuals,
  data = NULL,
  predictors = NULL,
  max_lag = 10,
  plot = TRUE
)

Arguments

Value

A list of test results with class "residual_diagnostics"

Runs Test for Randomness

Description

Runs Test for Randomness

Usage

runs_test(x)

Save Diagnostic Plots

Description

Saves all diagnostic plots to files.

Usage

save_plots(
  results,
  output_dir,
  prefix = "empirical_dynamics",
  format = c("png", "pdf"),
  width = 8,
  height = 6,
  dpi = 300
)

Arguments

Value

List of paths to created files.

Create Section Header

Description

Create Section Header

Usage

section_header(title, format)

Select Equation from Pareto Front

Description

Selects the best equation from the Pareto front using a specified criterion.

Usage

select_equation(
  results,
  criterion = c("knee", "BIC", "AIC", "min_complexity", "min_error"),
  n = NULL
)

Arguments

Value

A symbolic_equation object.

Cross-Validation Selection of Lambda for TVR

Description

Selects the regularization parameter lambda using leave-one-out-like cross-validation.

Usage

select_lambda_cv_tvr(
  Z,
  t,
  A = NULL,
  D = NULL,
  solver = "osqp",
  lambda_seq = 10^seq(-4, 2, length.out = 30),
  verbose = FALSE
)

Arguments

Value

Selected lambda value.

Parameter Sensitivity Analysis

Description

Examines how sensitive the model predictions are to parameter perturbations.

Usage

sensitivity_analysis(
  equation,
  data,
  response = NULL,
  derivative_col = NULL,
  perturbation_pct = 10,
  n_bootstrap = 100
)

Arguments

Value

Data frame with sensitivity metrics for each parameter.

Setup Julia Backend

Description

Checks if Julia and the required SymbolicRegression.jl package are installed.

Usage

setup_julia_backend()

Value

Logical indicating if the backend is ready.

Simulate Trajectory from SDE

Description

Simulates trajectories using the discovered SDE to assess whether the model can reproduce observed dynamics.

Usage

simulate_trajectory(
  sde,
  initial_conditions,
  times,
  n_sims = 100,
  method = c("euler", "milstein", "rk4"),
  exogenous_data = NULL,
  seed = NULL
)

Arguments

Value

Object of class "trajectory_simulation" containing:

Examples

# Toy example: dX = 0.5 * X
# Mock SDE object structure
sde <- list(
  drift = list(expression = "0.5 * X"),
  diffusion = list(expression = "0.1"), # Add noise
  variable = "X"
)
class(sde) <- "sde_model"

# Simulation
sim <- simulate_trajectory(
  sde = sde,
  initial_conditions = c(X = 1),
  times = seq(0, 1, by = 0.1),
  n_sims = 10,
  seed = 123
)
print(sim$summary$mean)

Specify Variable Types for Dynamical Analysis

Description

Classifies variables in a dataset according to their role in the dynamical system being studied.

Usage

specify_variables(
  data,
  endogenous = NULL,
  endogenous_coupled = NULL,
  coupled = NULL,
  exogenous = NULL,
  slow_parameter = NULL,
  time = NULL,
  time_col = NULL
)

Arguments

Details

Variable types:

• endogenous: Variables whose dynamics are modeled (appear as dZ/dt).

• endogenous_coupled: Variables that co-evolve with endogenous vars.

• exogenous: Variables that influence the system but are not modeled.

• slow_parameter: Variables that change on much longer timescales.

Value

The input data.frame with variable specifications added as the "var_spec" attribute.

Examples

data <- data.frame(
  time = 1:10,
  profit_rate = runif(10),
  capital_stock = runif(10),
  interest_rate = runif(10)
)

data <- specify_variables(data,
  endogenous = "profit_rate",
  endogenous_coupled = "capital_stock",
  exogenous = "interest_rate"
)
attr(data, "var_spec")

Suggest Differentiation Method Based on Data Characteristics

Description

Analyzes the time series to recommend the most appropriate differentiation method based on detected features like trend, periodicity, shocks, and noise.

Usage

suggest_differentiation_method(Z, t = NULL)

Arguments

Value

List with suggested method and diagnostic information.

Examples

t <- 1:100
Z <- 0.1 * t + rnorm(100) # Trend with noise
result <- suggest_differentiation_method(Z, t)
print(result$suggested_method)

Symbolic Regression and Equation Discovery

Description

Functions for discovering functional forms through symbolic regression using genetic algorithms. Interfaces with Julia's SymbolicRegression.jl for advanced search, with fallback to R-native methods for simpler cases.

Discovers the functional form of a differential equation from data using genetic/evolutionary algorithms. Returns a Pareto front of equations trading off complexity against fit.

Usage

symbolic_search(
  target,
  predictors,
  operators = NULL,
  constraints = NULL,
  n_runs = 5,
  complexity_penalty = 0.05,
  parsimony_pressure = c("adaptive", "constant", "none"),
  backend = c("r_genetic", "julia", "r_exhaustive"),
  julia_options = NULL,
  weights = NULL,
  verbose = TRUE
)

Arguments

Value

An object of class "symbolic_search_result" containing:

• pareto_front: Data frame of Pareto-optimal equations

• all_equations: All discovered equations

• best_by_complexity: Best equation at each complexity level

• run_diagnostics: Information about each run

Examples

# Toy example using R-native exhaustive search (fastest for demo)
data <- data.frame(
  x = seq(1, 10, length.out = 20),
  y = seq(1, 10, length.out = 20)^2 + rnorm(20, sd = 0.1)
)

# Discover y ~ x^2
results <- symbolic_search(
  target = data$y,
  predictors = data["x"],
  backend = "r_exhaustive"
)

print(head(results$pareto_front))

Julia Backend for Symbolic Search

Description

Uses SymbolicRegression.jl for advanced symbolic regression.

Usage

symbolic_search_julia(
  target,
  predictors,
  operators,
  constraints,
  n_runs,
  complexity_penalty,
  parsimony_pressure,
  julia_options,
  weights,
  verbose
)

Exhaustive Search for Simple Equations

Description

Exhaustive Search for Simple Equations

Usage

symbolic_search_r_exhaustive(
  target,
  predictors,
  operators,
  constraints,
  weights,
  verbose
)

R-Native Genetic Algorithm for Symbolic Regression

Description

A pure R implementation of symbolic regression using a genetic algorithm.

Usage

symbolic_search_r_genetic(
  target,
  predictors,
  operators,
  constraints,
  n_runs,
  complexity_penalty,
  parsimony_pressure,
  weights,
  verbose
)

Weighted Symbolic Search

Description

Performs symbolic search with weighted least squares.

Usage

symbolic_search_weighted(
  target,
  predictors,
  weights,
  operators = NULL,
  constraints = NULL,
  n_runs = 3,
  complexity_penalty = 0.05,
  verbose = TRUE
)

Arguments

Value

A symbolic_search_result object

Simple JSON Conversion

Description

Simple JSON Conversion

Usage

to_json(x, indent = 0)

Convert Equation to LaTeX

Description

Converts a discovered equation to LaTeX format for publication.

Usage

to_latex(
  equation,
  variable = "Z",
  precision = 3,
  scientific_notation = TRUE,
  include_uncertainty = FALSE,
  se_values = NULL
)

Arguments

Value

Character string with LaTeX equation.

Examples

# Toy example using a linear model
data <- data.frame(Z = 1:10, dZ = 2 * (1:10) + 3)
model <- stats::lm(dZ ~ Z, data = data)

# Convert to LaTeX
latex_eq <- to_latex(model, variable = "Z")
cat(latex_eq)

Utility Functions for EmpiricalDynamics

Description

Internal utility functions and helpers used across the package.

Comprehensive Model Validation

Description

Runs a battery of validation tests on the discovered equation.

Usage

validate_model(
  equation,
  sde = NULL,
  data,
  response = NULL,
  derivative_col = NULL,
  variable,
  time_col = "time",
  cv_folds = 5,
  n_sims = 50,
  expected_features = list(),
  verbose = TRUE
)

Arguments

Value

Object of class "validation_result".

Validation of Discovered Equations

Description

Functions for validating discovered differential equations through cross-validation, trajectory simulation, and qualitative behavior analysis.