feNmlm {fixest} | R Documentation |
This function estimates maximum likelihood models (e.g., Poisson or Logit) with non-linear in parameters right-hand-sides and is efficient to handle any number of fixed effects. If you do not use non-linear in parameters right-hand-side, use femlm
or feglm
instead (design is simpler).
feNmlm(fml, data, family = c("poisson", "negbin", "logit", "gaussian"), NL.fml, fixef, na_inf.rm = getFixest_na_inf.rm(), NL.start, lower, upper, NL.start.init, offset, start = 0, jacobian.method = "simple", useHessian = TRUE, hessian.args = NULL, opt.control = list(), nthreads = getFixest_nthreads(), verbose = 0, theta.init, fixef.tol = 1e-05, fixef.iter = 1000, deriv.tol = 1e-04, deriv.iter = 1000, warn = TRUE, notes = getFixest_notes(), combine.quick, ...)
fml |
A formula. This formula gives the linear formula to be estimated (it is similar to a |
data |
A data.frame containing the necessary variables to run the model. The variables of the non-linear right hand side of the formula are identified with this |
family |
Character scalar. It should provide the family. The possible values are "poisson" (Poisson model with log-link, the default), "negbin" (Negative Binomial model with log-link), "logit" (LOGIT model with log-link), "gaussian" (Gaussian model). |
NL.fml |
A formula. If provided, this formula represents the non-linear part of the right hand side (RHS). Note that contrary to the |
fixef |
Character vector. The name/s of a/some variable/s within the dataset to be used as fixed-effects. These variables should contain the identifier of each observation (e.g., think of it as a panel identifier). |
na_inf.rm |
Logical, default is |
NL.start |
(For NL models only) A list of starting values for the non-linear parameters. ALL the parameters are to be named and given a staring value. Example: |
lower |
(For NL models only) A list. The lower bound for each of the non-linear parameters that requires one. Example: |
upper |
(For NL models only) A list. The upper bound for each of the non-linear parameters that requires one. Example: |
NL.start.init |
(For NL models only) Numeric scalar. If the argument |
offset |
A formula or a numeric vector. An offset can be added to the estimation. If equal to a formula, it should be of the form (for example) |
start |
Starting values for the coefficients in the linear part (for the non-linear part, use NL.start). Can be: i) a numeric of length 1 (e.g. |
jacobian.method |
(For NL models only) Character scalar. Provides the method used to numerically compute the Jacobian of the non-linear part. Can be either |
useHessian |
Logical. Should the Hessian be computed in the optimization stage? Default is |
hessian.args |
List of arguments to be passed to function |
opt.control |
List of elements to be passed to the optimization method |
nthreads |
Integer: Number of nthreads to be used (accelerates the algorithm via the use of openMP routines). The default is to use the total number of nthreads available minus two. You can set permanently the number of nthreads used within this package using the function |
verbose |
Integer, default is 0. It represents the level of information that should be reported during the optimisation process. If |
theta.init |
Positive numeric scalar. The starting value of the dispersion parameter if |
fixef.tol |
Precision used to obtain the fixed-effects (ie cluster coefficients). Defaults to |
fixef.iter |
Maximum number of iterations in the step obtaining the fixed-effects (only in use for 2+ clusters). Default is 10000. |
deriv.tol |
Precision used to obtain the fixed-effects derivatives. Defaults to |
deriv.iter |
Maximum number of iterations in the step obtaining the derivative of the fixed-effects (only in use for 2+ clusters). Default is 1000. |
warn |
Logical, default is |
notes |
Logical. By default, two notes are displayed: when NAs are removed (to show additional information) and when some observations are removed because of only 0 (or 0/1) outcomes in a fixed-effect (in Poisson/Neg. Bin./Logit models). To avoid displaying these messages, you can set |
combine.quick |
Logical. When you combine different variables to transform them into a single fixed-effects you can do e.g. |
... |
Not currently used. |
This function estimates maximum likelihood models where the conditional expectations are as follows:
Gaussian likelihood:
E(Y|X) = X*beta
Poisson and Negative Binomial likelihoods:
E(Y|X) = exp(X*beta)
where in the Negative Binomial there is the parameter theta used to model the variance as mu+mu^2/theta, with mu the conditional expectation. Logit likelihood:
E(Y|X) = exp(X*beta) / (1 + exp(X*beta))
When there are one or more clusters, the conditional expectation can be written as:
E(Y|X) = h(Xβ+∑_{k}∑_{m}γ_{m}^{k}\times C_{im}^{k}),
where h(.) is the function corresponding to the likelihood function as shown before. C^k is the matrix associated to cluster k such that C^k_{im} is equal to 1 if observation i is of category m in cluster k and 0 otherwise.
When there are non linear in parameters functions, we can schematically split the set of regressors in two:
f(X,β)=X^1β^1 + g(X^2,β^2)
with first a linear term and then a non linear part expressed by the function g. That is, we add a non-linear term to the linear terms (which are X*beta and the cluster coefficients). It is always better (more efficient) to put into the argument NL.fml
only the non-linear in parameter terms, and add all linear terms in the fml
argument.
To estimate only a non-linear formula without even the intercept, you must exclude the intercept from the linear formula by using, e.g., fml = z~0
.
The over-dispersion parameter of the Negative Binomial family, theta, is capped at 10,000. If theta reaches this high value, it means that there is no overdispersion.
An femlm
object.
coefficients |
The named vector of coefficients. |
coeftable |
The table of the coefficients with their standard errors, z-values and p-values. |
loglik |
The loglikelihood. |
iterations |
Number of iterations of the algorithm. |
n |
The number of observations. |
nparams |
The number of parameters of the model. |
call |
The call. |
fml |
The linear formula of the call. |
ll_null |
Log-likelihood of the null model (i.e. with the intercept only). |
pseudo_r2 |
The adjusted pseudo R2. |
message |
The convergence message from the optimization procedures. |
sq.cor |
Squared correlation between the dependent variable and the expected predictor (i.e. fitted.values) obtained by the estimation. |
hessian |
The Hessian of the parameters. |
fitted.values |
The fitted values are the expected value of the dependent variable for the fitted model: that is E(Y|X). |
cov.unscaled |
The variance-covariance matrix of the parameters. |
se |
The standard-error of the parameters. |
scores |
The matrix of the scores (first derivative for each observation). |
family |
The ML family that was used for the estimation. |
residuals |
The difference between the dependent variable and the expected predictor. |
sumFE |
The sum of the fixed-effects for each observation. |
offset |
The offset formula. |
NL.fml |
The nonlinear formula of the call. |
bounds |
Whether the coefficients were upper or lower bounded. – This can only be the case when a non-linear formula is included and the arguments 'lower' or 'upper' are provided. |
isBounded |
The logical vector that gives for each coefficient whether it was bounded or not. This can only be the case when a non-linear formula is included and the arguments 'lower' or 'upper' are provided. |
fixef_vars |
The names of each cluster. |
fixef_id |
The list (of length the number of clusters) of the cluster identifiers for each observation. |
fixef_sizes |
The size of each cluster. |
obsRemoved |
In the case there were clusters and some observations were removed because of only 0/1 outcome within a cluster, it gives the row numbers of the observations that were removed. |
fixef_removed |
In the case there were clusters and some observations were removed because of only 0/1 outcome within a cluster, it gives the list (for each cluster) of the cluster identifiers that were removed. |
theta |
In the case of a negative binomial estimation: the overdispersion parameter. |
@seealso
See also summary.fixest
to see the results with the appropriate standard-errors, fixef.fixest
to extract the cluster coefficients, and the functions esttable
and esttex
to visualize the results of multiple estimations.
And other estimation methods: feols
, femlm
, feglm
, fepois
, fenegbin
.
Laurent Berge
Berge, Laurent, 2018, "Efficient estimation of maximum likelihood models with multiple fixed-effects: the R package FENmlm." CREA Discussion Papers, 13 (https://wwwen.uni.lu/content/download/110162/1299525/file/2018_13).
For models with multiple fixed-effects:
Gaure, Simen, 2013, "OLS with multiple high dimensional category variables", Computational Statistics & Data Analysis 66 pp. 8–18
On the unconditionnal Negative Binomial model:
Allison, Paul D and Waterman, Richard P, 2002, "Fixed-Effects Negative Binomial Regression Models", Sociological Methodology 32(1) pp. 247–265
# This section covers only non-linear in parameters examples # For linear relationships: use femlm instead # Generating data for a simple example n = 100 x = rnorm(n, 1, 5)**2 y = rnorm(n, -1, 5)**2 z1 = rpois(n, x*y) + rpois(n, 2) base = data.frame(x, y, z1) # Estimating a 'linear' relation: est1_L = femlm(z1 ~ log(x) + log(y), base) # Estimating the same 'linear' relation using a 'non-linear' call est1_NL = feNmlm(z1 ~ 1, base, NL.fml = ~a*log(x)+b*log(y), NL.start = list(a=0, b=0)) # we compare the estimates with the function esttable (they are identical) esttable(est1_L, est1_NL) # Now generating a non-linear relation (E(z2) = x + y + 1): z2 = rpois(n, x + y) + rpois(n, 1) base$z2 = z2 # Estimation using this non-linear form est2_NL = feNmlm(z2~0, base, NL.fml = ~log(a*x + b*y), NL.start = list(a=1, b=2), lower = list(a=0, b=0)) # we can't estimate this relation linearily # => closest we can do: est2_L = femlm(z2~log(x)+log(y), base) # Difference between the two models: esttable(est2_L, est2_NL) # Plotting the fits: plot(x, z2, pch = 18) points(x, fitted(est2_L), col = 2, pch = 1) points(x, fitted(est2_NL), col = 4, pch = 2)