plot_lm_loglik: Plot of the log-likelihood surface of a lineair model
In lmvar: Linear Regression with Non-Constant Variances

Description Usage Arguments Details Examples

Creates a 3-d plot of the maximum log-likelihood of a lineair model. The maximum log-likelihood is plotted as a function of two elements of the parameter vector β. Optionally, the maximum of a quadratic approximation to the log-likelihood surface is plotted.

This function is intended for development purposes only.

1 2	plot_lm_loglik(y, X, beta_or, beta_x, beta_y, add_qa = FALSE, plot_width = 3, plot_points = 20)

`y`	Vector of observations
`X`	Model matrix
`beta_or`	Vector of beta values around which the plot is centered. Also the origin of the quadratic appriximation.
`beta_x`	Component of beta to be plotted at the x-axis. Can be an index of `beta_or` or a name in case `beta_or` is a named vector
`beta_y`	Component of beta to be plotted at the y-axis. Can be an index of `beta_or` or a name in case `beta_or` is a named vector
`add_qa`	Boolean, specifies whether or not a quadratic approximation of the maximum log-likelihood surface is plotted
`plot_width`	Single numeric value, half the range of x- and y-values
`plot_points`	Integer, number of points in the x- and y-dimension at which the maximum-likelihood surface is calculated.

The function plots the maximum log-likelihood of linear model as a function of two components of the vector β. Optionally, it also plots a quadratic approximation to the log-likelihood and plot its maximum.

The quadratic approximation is defined as

log L_q (β) = log L(β_o) + g (β - β_o) + 0.5 (β - β_o) H (β - β_o)

where log L_q is the quadratic approximation of the log-likelihood, β_o the value of β at the origin, g the gradient and H the Hessian of the log-likelihood at β_o.

For each point (β_x, β_y), the other components of the vector β are chosen such that the log-likelihood is at its maximum. This maximum is plotted.

The same is true for a quadratic approximation of the log-likelihood, except when it has no maximum (i.e. the Hessian H is not negative-definite at β_o). In that case, a waning is issued and the other components of β are set to the value they have in beta_or. The resulting quadratic approximation is plotted. This does not affect the plot of the maximum of the true log-likelihood.

To create the plot, the package plotly needs to be installed. A warning is issued if that is not the case.

## Not run: 

# Carry out a linear regression with the 'iris' data set
fit = lm( Petal.Length ~ Species, data = iris, x = TRUE, y = TRUE)
X = fit$x
y = fit$y

# We center the plot at the maximum-likelihood
beta_or = coef(fit)

# Plot the maximum log-likelihood
lmvar:::plot_lm_loglik( y, X, beta_or = beta_or, beta_x = "(Intercept)",
                        beta_y = "Speciesversicolor")

# Plot against the two species
lmvar:::plot_lm_loglik( y, X, beta_or = beta_or, beta_x = "Speciesversicolor",
                        beta_y = "Speciesvirginica")

# Increase the resolution
lmvar:::plot_lm_loglik( y, X, beta_or = beta_or, beta_x = "Speciesversicolor",
                        beta_y = "Speciesvirginica", plot_points = 40)

# Remove the intercept term from the model matrix and fit again
XX = X[,-1]
fit = lm( y ~ . - 1, data = as.data.frame(XX))

# Estimate the effect of adding an intercept term in a quadratic approximation and compare
# with exact result
beta_or = c( 0, coef(fit))
lmvar:::plot_lm_loglik( y, X, beta_or = beta_or, beta_x = 1, beta_y = "Speciesversicolor",
                        add_qa = TRUE, plot_points = 40, plot_width = 5)

# Note that in the last case the quadratic approximation has no maximum. Hence the beta for
# "Speciesvirginica" is kept at beta_or[3] in the calculation of the surface of the
# quadratic approximation.

## End(Not run)