GitHub

Model analysis

UniversalDiffEq.jl provides several functions to analyze the characteristics of the fitted models. The most basic of these is the get_right_hand_side function. This function takes a UDE model as an argument and returns the right-hand side of the fitted differential or difference equation. This function can then be treated like any dynamic model and analyzed for equilibrium points, stability, tipping points, and other dynamics of interest.

UniversalDiffEq.get_right_hand_side — Method
get_right_hand_side(UDE::UDE)

Returns the right-hand side of the differential equation (or difference equation) used to build the process model.

The function will take the state vector u and time t if the model does not include covariates. If covariates are included, then the arguments are the state vector u , covariates vector x, and time t.

source

In addition to get_right_hand_side, UniversalDiffEq.jl provides some predefined functions for analyzing the equilibrium points of the dynamic system. The simplest is equilibrium_and_stability which searches for the equilibrium points of the UDE model and analyzes their stability using a linear stability analysis.

UniversalDiffEq.equilibrium_and_stability — Method
equilibrium_and_stability(UDE,lower,upper;t=0,Ntrials=100,tol=10^-3)

Attempts to find all the equilibrium points for the UDE model between the upper and lower bounds, and then returns the real component of the dominant eigenvalue to analyze stability.

...

kwargs

  • t = 0: The point in time where the UDE model is evaluated, only relevant for time aware UDEs.
  • Ntrials = 100: the number of initializations of the root finding algorithm.
  • tol = 10^-3: The threshold Euclidean distance between points beyond which a new equilibrium is sufficiently different to be retained.

...

source

The package also has built-in functions to generate bifurcation diagrams for models that include covariates, by plotting the equilibrium points of the model as a function of the covariates.

UniversalDiffEq.bifurcation_data — Method
bifurcation_data(model::UDE;N=25)

Calcualtes the equilibrium values of the state variabels $y_t$ as a function of the covariates X_t and return the value in a data frame. The funciton calcualtes the equilibrium values on a grid of $N$ evenly spaced point for each covariate.

source
UniversalDiffEq.plot_bifurcation_diagram — Method
plot_bifurcation_diagram(model::UDE, xvariable; N = 25, color_variable= nothing, conditional_variable = nothing, size= (600, 400))

This function returns a plot of the equilibrium values of the state varaibles $y_t$ as a funciton of the covariates $X_t$. The arguemnt xvariable determines the covariate plotted on the x-axis. Additional variables can be visualized in sperate panel by specifying the conditional_variable key word argument or visualized by the color scheme using the color_variable argument.

The key word arguent size controls the dimensions of the final plot.

source

The function phase_plane plots forecasted trajectories of state variables for a given number of timesteps T. All phase plane functions also work with the MultiUDE model type, and plot phase planes for each series in the data.

UniversalDiffEq.phase_plane — Method
phase_plane(UDE::UDE; idx=[1,2], u1s=-5:0.25:5, u2s=-5:0.25:5, u3s = 0, T = 100)

Plots the trajectory of state variables as forecasted by the model. Runs a forecast for each permutation of u1 and u2 out to T timesteps. Change the state variables that are plotted by changing idx such that it equals the indexes of the desired state variables as they appear in the data.

source
UniversalDiffEq.phase_plane — Method
phase_plane(UDE::UDE, u0s::AbstractArray; idx=[1,2],T = 100)

Plots the trajectory of state variables as forecasted by the model. Runs a forecast for each provided initial condition out to T timesteps. Change the state variables that are plotted by changing idx such that it equals the indexes of the desired state variables as they appear in the data.

source
UniversalDiffEq.phase_plane_3d — Method
phase_plane_3d(UDE::UDE; idx=[1,2,3], u1s=-5:0.25:5, u2s=-5:0.25:5, u3s=-5:0.25:5, T = 100)

The same as phase_plane(), but displays three dimensions/state variables instead of two.

source

The library also has functions to evaluate model predictions. The forecast function will run a simulation of the model starting at the initial point u0 and returning the value of the state variables at each point in the times vector. The results of these forecasts can be displayed using the plot_forecast function.

UniversalDiffEq.forecast — Method
forecast(UDE::UDE, u0::AbstractVector{}, times::AbstractVector{})

Predictions from the trained UDE model starting at u0 and saving values at times. Assumes u0 is the value at initial time times[1]

source

Finally, the parameters of the process model, the weights and biases of the neural network, and the estimated parameter values of the known dynamics can be displayed using the functions get_parameters, get_NN_parameters, and print_parameter_estimates, respectively.