results = model.fit(order=(1, 0, 1), garch_order=(1, 1), vol="GARCH")Fit options
All v2 configuration is passed to fit(), so separate model fits do not share mutable global state.
ARIMA/GARCH order
order=(p, q, d) controls the ARIMA mean process (AR, MA, integer differencing). garch_order=(k, m) controls the GARCH variance process. Set vol="GARCH" or vol="EGARCH".
ARMA exact log likelihood and RE/FE correction
exact_ll defaults to None (automatic):
| Value | Likelihood selection |
|---|---|
None |
Enable the Gaussian covariance correction for supported ARIMA models with garch_order=(0, 0), including time series and panels with FE/RE. Otherwise use conditional likelihood. |
True |
Force the correction on, including with GARCH; unsupported specifications still raise an error. |
False |
Force conditional likelihood with zero presample innovations. |
results.exact_ll records the resolved boolean, not None. Automatic selection leaves fractional, EGARCH, custom/non-Gaussian and censored models conditional. Static models (order=(0, 0, 0)) also remain conditional in automatic mode.
For constant-variance ARMA without effects, this gives exact stationary Gaussian likelihood, including the infinite AR history and all supplied regressors. It reuses the native inverse-MA column and a stationary Lyapunov prior. Factorizations are only r-by-r, where r = max(p, q); no time-by-time covariance is built. Work and storage grow linearly with history length for fixed orders and parameter count. The Hessian batches its derivative solves.
The corrected density replaces the conditional density once per entity. Analytic scores/Hessians, robust scores, whitening and forecasts use the same covariance. Ragged groups exclude padding and integer-differencing boundaries. After differencing this is not a diffuse likelihood for the original levels.
GARCH/effects/variance-regressor models retain the dense finite-history approximation C = diag(v) + v[0] * H @ H.T. Their variance paths and effects transforms are unchanged; this is not exact joint GARCH or marginal-effects likelihood, and long histories can be expensive.
Fixed or random effects do not remove the need to account for each series’ unobserved history. The correction remains applicable and is enabled automatically without GARCH. A small RE-only pilot suggested improved ARMA parameter RMSE, although this is preliminary evidence; the retained effects transformation does not provide exact joint integration over random effects.
Exact stationary GARCH likelihood would require integrating over unobserved past shocks and initial volatility, whose stationary distribution generally has no closed form. This requires specialized numerical methods and is not implemented here. The ARMA correction alone does not provide that integration or a reliable improvement in estimates: a small paired pilot found no consistent RMSE gain with GARCH, with or without random effects. This is preliminary evidence, not a general result; automatic mode keeps GARCH models conditional.
When enabled, the option requires regular observations and the built-in Gaussian model. Non-Gaussian/custom likelihoods, EGARCH, fractional differencing, censoring and IV are rejected. Invalid AR roots or nonpositive/clipped variances invalidate a trial. See the ARMA exact log likelihood and RE/FE correction section in paneltime_doc/main.tex for the implemented equations.
Evaluate without fitting
model.prepare_likelihood(FitOptions(...)) prepares the data once and returns a reusable evaluator. It does not optimize, build result tables, or impose a seasonal model. All regressors in the model formula remain in the coefficient vector, with the same analytic regression/ARMA/variance cross derivatives.
evaluator = model.prepare_likelihood(
pt.FitOptions(order=(2, 1, 0), garch_order=(0, 0), exact_ll=True))
parameters = evaluator.initial_parameters.copy()
evaluation = evaluator.evaluate(parameters)
evaluation.loglike, evaluation.score, evaluation.hessianparameter_names and parameter_groups describe the full vector, in engine coefficient coordinates. Supply all coefficients, including fixed ones: evaluate does not apply fit constraints. derivative_order=0, 1, or 2 requests density only, density and score, or all three. Invalid parameter trials raise ValueError. Only the last parameter vector and its computed derivatives are reused; returned derivative arrays are copies. Preparation uses the existing initializer, so its warnings can still appear.
For nonlinear coefficient relationships, an external optimizer can use this evaluator directly, without invoking fit at each trial. If a = f(b) maps optimizer coordinates to the full vector, transform derivatives as g_b = J.T @ g_a and H_b = J.T @ H_a @ J + sum(g_a[k] * Hessian(f[k])). The second term is required for products, log variances and other nonlinear maps. Explicitly fixing every coefficient in a final fit is supported: the full vector is retained and results are constructed with zero optimization iterations. Standard errors conditional on all coefficients being fixed are unavailable; inference for the external coordinates must use their transformed curvature.
Fractional differencing (ARFIMA)
Use fractional_d="estimate" to estimate one common fractional parameter across entities, or pass a number strictly between -0.5 and 0.5 to fix it. The default None leaves existing behavior unchanged; fixed 0.0 is equivalent to no fractional filtering.
# ARFIMA(1, d, 1)-GARCH(1, 1): the integer-difference entry stays zero.
results = model.fit(order=(1, 1, 0), garch_order=(1, 1),
fractional_d="estimate")
print(results.fractional_d)
# A fixed fractional parameter is not counted as an estimated coefficient.
fixed = model.fit(order=(1, 1, 0), fractional_d=0.25)Estimated d appears in the parameter and standard-error tables. Its numerical bounds are -0.5 + 1e-8 and 0.5 - 1e-8; constraints such as constraints={"d": (-0.3, 0.4)} can narrow these bounds or fix the parameter. results.fractional_d gives either the estimated or fixed value.
The conditional model filters regression residuals, including the intercept: (1-L)^d (Y-X beta) is passed through the existing ARMA filter, effects adjustment, and GARCH recursion. Fractional filtering is independent of the innovation distribution, variance link, and custom h-function. Effects retain their existing innovation-scale interpretation.
All available within-entity history is used, with residuals before each entity’s first observation set to zero. This is a conditional, finite-history likelihood, not the exact stationary ARFIMA likelihood. Histories never cross entity boundaries; unbalanced panels may have different history lengths. Each retained entity needs at least three regularly spaced numeric or datetime observations. Irregular observations/internal gaps and simultaneous integer differencing are rejected explicitly. The declared sampling frequency cannot be inferred when an entire regularly spaced series is subsampled.
One-step forecasts invert fractional differencing using the entity’s full observed residual history; the existing forecast-horizon limits still apply. The fractional filter and its analytic derivatives currently cost quadratic time in the longest history length, so benchmark long series before large simulations. Standard errors at active bounds require the usual boundary-inference caution.
Effects
Create pt.Effects(...) and pass it as the effects argument to Model.fit(), not to the Model constructor. group controls entity effects, time controls calendar-date effects, and variance controls effects in the variance transformation. Omitted fields keep their defaults.
The complete option table below is generated by setup_script.py from the same definitions used to validate fits.
| Option | Default | Permitted values | Description |
|---|---|---|---|
group |
'none' |
'none', 'fixed', 'random' |
Group effect specification. |
time |
'none' |
'none', 'fixed', 'random' |
Time effect specification. |
variance |
'none' |
'none', 'fixed', 'random' |
Variance effect specification. |
effects = pt.Effects(group="random", time="fixed", variance="none")
model = pt.Model("Y ~ X0 + X1", data, entity="IDs", time="dates")
results = model.fit(order=(2, 2, 0), garch_order=(2, 2), effects=effects)
# Inline configuration: entity fixed effects, no time or variance effects.
fixed = model.fit(effects=pt.Effects(group="fixed"))
# Disable all effects (also the default).
pooled = model.fit(effects=pt.Effects())Group and time effects are removed from the ARMA innovations, after the ARMA filter. This is exact when the effects enter the innovations of the ARMA process. When they are added directly to the serially correlated residuals, it is an approximation. In simulations the resulting error was small compared with ordinary finite-sample error.
Optimizer and covariance
Create pt.OptimizerOptions(...) and pass it as the optimizer argument to Model.fit(). These are configuration fields, not separate arguments to the Model constructor or fit(): for example, use model.fit(optimizer=pt.OptimizerOptions(max_iterations=300)), not model.fit(max_iterations=300). Omitted fields retain their defaults; pt.OptimizerOptions() supplies all defaults. Settings are per fit, not global.
All available controls, including constraints, initialization, numerical precision, reduction thresholds and covariance settings, are listed below. Defaults, permitted values and descriptions are generated from the central option schema whenever setup_script.py runs its normal build workflow.
| Option | Default | Permitted values | Description |
|---|---|---|---|
tolerance |
0.0001 |
Positive number. | Tolerance used by the numerical optimizer. |
max_iterations |
150 |
Positive integer. | Maximum number of optimization iterations. |
accuracy |
0 |
Non-negative integer. | Optimization accuracy level. |
initial_arima_garch_params |
0.1 |
Non-negative number. | Initial size of ARIMA-GARCH parameters. |
arma_constraint |
3 |
Positive number. | Maximum absolute value of ARMA coefficients. |
arma_round |
14 |
Positive integer. | Number of significant digits used in ARMA matrices. |
garch_min |
1e-12 |
Positive number. | Minimum absolute value of GARCH coefficients. |
garch_assist |
0 |
Non-negative number. | Weight assigned to the assisting GARCH variance. |
garch_ridge_wald |
0.2 |
Finite non-negative real number (excluding booleans). | Absolute squared-Wald-ratio threshold (strict) for attempting to fix the highest free gamma lag at zero. Negative variance uses a heuristic; zero variance is skipped. Accepted reductions get one release retry within the iteration budget; 0 disables ridge reduction. |
multicoll_threshold_report |
30 |
Positive number. | Condition-index threshold for reporting multicollinearity and gating automatic ARMA/GARCH reductions together with their Wald criteria. |
min_group_df |
1 |
Positive integer. | Minimum observations allowed in each group. |
robust_cov_lags |
(100, 30) |
Two integers greater than one. | Lags used for robust covariance calculations. |
variance_re_norm |
5e-06 |
Positive number. | Normalization point for variance random-effects calculations. |
kurtosis_adj |
0 |
Non-negative number. | Kurtosis adjustment. |
Both conventional and robust standard errors are available on the returned results object as bse and robust_bse; bse_at(params) evaluates robust standard errors at supplied parameter values. The cov_type keyword is accepted by Model.fit() but does not currently select between these covariance results.
optimizer = pt.OptimizerOptions(
tolerance=1e-5,
max_iterations=300,
robust_cov_lags=(100, 30),
garch_ridge_wald=0, # Disable automatic GARCH ridge reduction.
)
results = model.fit(
order=(2, 2, 0),
garch_order=(2, 2),
effects=pt.Effects(group="random", time="random"),
optimizer=optimizer,
)
# You can also update a configuration object before passing it to fit().
optimizer.max_iterations = 500
refit = model.fit(optimizer=optimizer)For most fits, start with the defaults and adjust max_iterations or tolerance if needed. Other fields are advanced controls; changing garch_assist or kurtosis_adj also changes the likelihood, not merely the optimization algorithm. Invalid settings raise an error when the fit is prepared. See the sections below for reduction and initialization details.
GARCH ridge reduction
Automatic ARMA common-factor and GARCH ridge reductions require both their Wald criterion and matching condition-index evidence from the current Hessian on free parameters. A dimension must have CI >= OptimizerOptions.multicoll_threshold_report (default 30), with variance-decomposition proportions > 0.5 for at least one free AR and one free MA coefficient (ARMA), or at least two free gamma lags (GARCH), in that same dimension. CI from unrelated parameters is insufficient. Raising this option therefore affects reduction eligibility as well as reporting. CI uses absolute eigenvalues and does not by itself establish concavity.
OptimizerOptions.garch_ridge_wald defaults to 0.2 and accepts finite non-negative real numbers (not booleans). Set it to 0 to disable automatic GARCH ridge reduction:
optimizer = pt.OptimizerOptions(garch_ridge_wald=0)
results = model.fit(optimizer=optimizer)For converged or stalled fits with at least two free gamma lags, the detector uses the squared Wald statistic W = far**2 / variance. Here far is the distance from the highest free gamma coefficient to the farther endpoint (zero or total free gamma persistence), and variance is that coefficient’s diagonal entry in the pseudoinverse of the negative Hessian. If the variance is nonzero and abs(W) < garch_ridge_wald, the highest free gamma lag is fixed at zero and the model is refitted. The reduction is retained only if the refit converges and 2 * (original_loglik - reduced_loglik) <= 3.841, the 5% chi-square(1) critical value. Otherwise the previous fit and constraints are restored. Accepted reductions are listed in the optimizer message. With negative variance, the absolute ratio is used only as a ridge heuristic, not a valid Wald test or proof of a flat ridge. Zero variance is skipped.
After accepting a reduction, the optimizer releases the newly fixed gamma lag and retries from the reduced solution once. This uses the remaining max_iterations budget; earlier automatic reductions and user constraints remain in force. The released fit is retained only if it converges, has a negative-definite Hessian on free parameters, has no detected gamma ridge, and has likelihood no lower than either the original or reduced fit. Otherwise the reduced fit and constraints are restored. An accepted release ends the reduction loop, and the optimizer message records the release. No restrictions are toggled during individual optimizer iterations.
The threshold is not a number of standard errors or a continuous ridge penalty. Larger values make reduction attempts more likely, subject to the same likelihood-ratio check. Fixed coefficients change the fitted model; their standard errors should not be compared as if all requested lags were still freely estimated.
Automatic starting values
When AR or MA terms are requested, the default single start uses the full requested order. An OLS regression is followed by Hannan–Rissanen-style auxiliary regressions and a short conditional-sum-of-squares (CSS) refinement of the regression and ARMA coefficients. The preliminary fit ignores GARCH; its innovations supply the initial innovation variance and the existing GARCH moment starts. No additional dependency is required. CSS refinement is limited to 10 iterations and stops early at a scaled gradient of 1e-4 or a relative objective improvement of 1e-4; it supplies a useful neighborhood, not a precise standalone ARMA estimate.
Internally, arma_start.fit_arma(panel) coordinates the working regression, scaling, auxiliary-regression seed, CSS refinement, and conversion back to original units. Orders, observation masks, differencing boundaries, and preliminary effects settings come from the panel object. The numerical filtering and optimization steps are separate helpers; initialization does not modify the panel’s data or masks. Innovations and their derivative channels are filtered using the existing C ARMA recursion. Each contiguous observation run is packed as an independent series, preserving zero-presample resets at gaps and differencing boundaries. This reuses the shipped native library without a new compiled entry point.
The CSS fit uses analytic first derivatives and reflection coordinates to keep its preliminary ARMA coefficients stationary and invertible. These safeguards do not change the final likelihood’s constraints or Hessian. Panel runs are filtered separately, with no lags crossing group boundaries. For effects models, this preliminary fit uses fixed, pre-transformed working data; the final likelihood still removes effects after ARMA filtering. An underidentified auxiliary regression, CSS iteration limit, or numerical stall produces an ARMAInitializationWarning rather than being presented as successful preliminary convergence. It does not abort the final likelihood fit: the best accepted preliminary coefficients remain usable. Other numerical warnings are still treated as errors. CSS damping adapts to the actual versus predicted objective reduction, not merely whether a step decreases the objective.
Models without ARMA terms retain their existing OLS initialization. Explicit starting arguments supplied through the engine bypass the automatic CSS fit. Like any single-start initialization, this does not guarantee a global likelihood maximum.
Local single-start execution
Fitting runs locally. Legacy node dispatch and GUI/browser progress channels have been removed, as has the Model(..., multiprocess=...) argument. Final summaries, inference, diagnostics and predictions remain available.
execute prepares the panel once and passes its initial parameters directly to the shared likelihood optimizer. processing/initreg.py selects ordinary static FE/RE starts during panel initialization, in the same place as the ARMA/GARCH starts. Mixed fixed/random effects, explicit constraints (including {}), censoring, variance regressors/effects, instruments and custom likelihoods/functions retain their existing starts. Explicit engine starts are not replaced. Every fit uses dfpmax and the same inference, diagnostics and forecasts. A converged initial point returns without a line search (optim_result.its == 0); otherwise the optimizer refines the starting estimates. Iterations count completed optimizer steps. Automatic starting values, explicit engine starting arguments, and coefficient constraints are retained. The multistart optimizer option and optim_result.multistart_results have been removed. The fit reports its own convergence status; it does not search or select among alternative starts.
Gaussian RE likelihood audit
An analytical Hessian differentiates the implemented criterion; it does not establish that the criterion is the marginal likelihood of the stated model. The reproducible audit reference in tests/re_likelihood_reference.py examines the simpler stationary Gaussian model
\[ y_{it}-x_{it}'\beta=a_i+c_t+u_{it},\qquad u_{it}=\rho u_{i,t-1}+\epsilon_{it}, \]
where the three innovation/effect families are independent, with variances \(\sigma^2,\tau_a^2,\tau_c^2\). For entity-major stacking,
\[ \Sigma = I_N\otimes\left\{\frac{\sigma^2}{1-\rho^2} [\rho^{|s-t|}]_{s,t=1}^T\right\} +\tau_a^2 I_N\otimes J_T+\tau_c^2 J_N\otimes I_T, \]
where \(J_k\) is the \(k\)-by-\(k\) all-ones matrix. Its exact marginal log-likelihood is
\[ \ell_{\rm exact} =-\tfrac12\{NT\log(2\pi)+\log|\Sigma|+r'\Sigma^{-1}r\}. \]
The reference checks dense Cholesky evaluation against an independent AR-innovations/Woodbury evaluation integrating out both effects. For a true covariance \(\Sigma_0\), expectations require no simulated data:
\[ E_0[\ell_{\rm exact}(\Sigma)] =-\tfrac12\{NT\log(2\pi)+\log|\Sigma| +\operatorname{tr}(\Sigma^{-1}\Sigma_0)\}. \]
The package instead applies the AR filter, quasi-demeans the filtered innovations, and sums univariate normal contributions. In this special case, with weights frozen, write \(A=I-\theta_a P_a-\theta_c P_c\), where \(P_a,P_c\) project onto centered group and time means, \(B=I_N\otimes(I_T-\rho L_T)\), and let \(D\) contain the variances used in those contributions. Then
\[ \ell_Q=-\tfrac12\{NT\log(2\pi)+\log|D| +r'B'A'D^{-1}AB r\}, \]
and its expectation replaces the last quadratic form by \(\operatorname{tr}(D^{-1}AB\Sigma_0B'A')\). The frozen weights use the moments of the filtered components: innovation variance \(\sigma^2\), filtered group effect \(a_i(1-\rho)\) and filtered time effect \(c_t-\rho c_{t-1}\). The tests reproduce the package transformation, likelihood, and AR score on a deterministic panel, accounting for its \(10^{-8}\) squared-residual stabilizer.
Two separate qualifications matter:
- Even for a fixed invertible transformation, a density for the original residuals requires the transformation’s log determinant. With frozen weights that determinant is constant with respect to \(\rho\), so adding it alone cannot correct a nonzero expected AR score. With residual-adaptive weights, the transformation’s Jacobian also includes derivatives of those weights; it is not simply \(|A|\).
- Scalar quasi-demeaning generally does not give \(AB\Sigma_0B'A'=D\) for serially correlated disturbances: the first period is not filtered, and the filtered time effect is serially correlated. The package preserves the grand mean; correcting that direction is sufficient for the iid benchmark with known variances, but still does not whiten the AR(1) cases.
For \(N=4,T=8,\rho=0.5,\sigma^2=2,\tau_a^2=\tau_c^2=1\), with theoretical moment-based weights fixed and the first variance fixed at \(\sigma^2/(1-\rho^2)\), the expected scores in the coordinates \((\rho,\log\sigma^2)\) are approximately \((1.6299,0.9500)\) for \(\ell_Q\) and \((0,0)\) for the exact marginal likelihood. Without effects, the whitening and zero-score checks pass.
Scope: the package recomputes its weights from residuals, whereas this expectation calculation freezes theoretical weights. It is not the expected score of the complete residual-adaptive estimator, a proof of its asymptotic bias, or a GARCH likelihood replacement. It establishes a concrete mismatch with the exact Gaussian marginal benchmark and explains why a determinant-only patch is insufficient. The production RE likelihood is unchanged pending a validated treatment of the full dynamic/heteroskedastic model.
From the package root, run python tests\re_likelihood_reference.py for the JSON audit report, or python -m unittest discover -s tests -p "test*py" -v for its regression checks and the package tests.
Constraints
Use constraints= for coefficient restrictions and add_intercept, subtract_means, tobit_limits, and suppress_output for fit behavior.
Custom model and h-function
Pass a likelihood instance with likelihood= or a SymPy expression with h_function=. See the custom likelihood guide and heteroskedasticity guide.
Migrating from pt.options
| v1 | v2 |
|---|---|
pqdkm |
order= and garch_order= |
EGARCH |
vol="EGARCH" |
fixed_random_group_eff, fixed_random_time_eff, fixed_random_variance_eff |
effects=pt.Effects(...) |
custom_model |
likelihood= (an instance) |
user_constraints |
constraints= |
use_analytical |
No corresponding v2 option; the current implementation uses analytical derivatives. |
supress_output |
suppress_output= |