Probit

Probit estimates a binary probit regression model by maximum likelihood. It shares the general API shape with Logit (data/y/x/options constructor, .fit(), predict()/pred_table()/marginal_effects()) and differs only in the link function: Probit uses the standard normal CDF (Φ) in place of the logistic CDF (Λ).

Standard error types

ProbitOptions.cov_type supports "classical" (observed-information / Hessian-based), "opg" (outer product of gradients), "hc0", "hc1", and "cluster" (requires cluster). As with Logit, HC2/HC3 and HAC are not available.

Solver options

ProbitOptions.solver selects the optimization algorithm used to maximize the log-likelihood: "newton" (default, Newton-Raphson), "bfgs", or "lbfgs". All three converge to the same maximum-likelihood estimate; they differ in iteration cost and behavior on ill-conditioned problems. max_iter and tol control the iteration limit and the gradient-norm convergence threshold. When the solver does not converge within max_iter iterations, a ComputationError is raised unless raise_on_non_convergence=False, in which case ProbitResults.converged is False instead.

Marginal effects

ProbitResults.marginal_effects() computes dy/dx with delta-method standard errors, evaluated at "overall" (average marginal effects, the default), "mean", or "median". The constant term is excluded from the output. The API is identical to Logit; see the Getting Started example there (substitute Probit/ProbitOptions).

econometricsmodels.Probit(data, y, x, options=None)

Binary probit regression estimator.

Parameters:

Name	Type	Description	Default
data	DataFrame	A polars DataFrame containing the dependent and independent variables.	required
y	str	Column name of the dependent variable (coded 0/1).	required
x	list[str]	List of column names of the independent variables.	required
options	ProbitOptions | None	Estimation options. Defaults to ProbitOptions() (classical, with intercept, Newton-Raphson, confidence_level=0.95) when omitted.	None

Examples:

>>> import polars as pl
>>> from econometricsmodels import Probit
>>> df = pl.DataFrame({"y": [0.0, 1.0], "x1": [1.0, 2.0]})
>>> result = Probit(df, y="y", x=["x1"]).fit()
>>> result.params["x1"]

fit()

Estimate the Probit model by maximum likelihood.

Returns:

Type	Description
ProbitResults	The estimation results.

Raises:

Type	Description
TypeError	An argument has the wrong type (for example x is a string instead of a list of column names). A builtin exception, not a ValidationError.
ValidationError	The input or options are invalid (a column is missing, contains missing values or NaN/infinity, y contains a value other than 0.0/1.0, insufficient observations, confidence_level out of range, an unknown cov_type/solver string, etc.). A subclass of ValueError.
ComputationError	A problem was detected during computation (e.g. non-convergence, a singular Hessian/OPG matrix). A subclass of RuntimeError.

econometricsmodels.ProbitOptions

Estimation options for Probit.

See docs/spec/nonlinear-common.md for the rationale behind each field's meaning and default value. Field-for-field identical to LogitOptions (the two models share the same option surface, docs/spec/nonlinear-common.md section 7).

start_params (user-specified initial values) is intentionally omitted: the underlying engine (ProbitEstimator::fit) does not accept it yet (deferred, same as LogitOptions). It will be added once the engine side supports it.

cluster property

Column name to use as the cluster group key when cov_type="cluster". Refers to a column in data rather than being passed as a separate array. Specifying it with any other cov_type raises ValidationError.

confidence_level property

Confidence level for confidence intervals, in the range (0, 1). Defaults to 0.95 (a 95% confidence interval).

cov_type property

Standard error type: one of "classical", "opg", "hc0", "hc1", "cluster". Case-insensitive.

include_intercept property

Whether the engine should automatically add an intercept column. When true, a column of all 1.0 is prepended to the design matrix. If the user's x already contains a constant column while this is true, the resulting perfect collinearity raises ComputationError (singular Hessian).

max_iter property

Maximum number of solver iterations, an integer from 1 to 10,000 (anything else raises ValidationError).

raise_on_non_convergence property

If true (default), raise ComputationError when the solver fails to converge within max_iter iterations. If false, return the result at the final iterate instead (with converged=False).

solver property

Optimization solver: one of "newton" (default), "bfgs", "lbfgs". Case-insensitive.

tol property

Convergence tolerance. For solver="newton", an absolute threshold on the total gradient norm (default 1e-6). For solver="bfgs"/"lbfgs", a per-observation-average gradient threshold (the total gradient norm divided by the number of observations must fall below tol, default 1e-8), matching how statsmodels/scipy normalize convergence checks by nobs. The two defaults are not interchangeable: Newton's absolute semantics with a 1e-8 threshold (or bfgs/lbfgs's normalized semantics with a 1e-6 threshold) measurably degrades either speed or precision. Passing tol explicitly always uses the semantics of the chosen solver. For bfgs/lbfgs, the solver also reports convergence when the gradient norm is within 100 * tol of the target and the line search can no longer make progress because the log-likelihood has reached floating-point precision (common with very large samples); this window scales with tol, so it widens if you loosen tol. Note: the solver-dependent default is resolved once, at construction time. Changing solver afterwards via the setter does not re-resolve tol — set both together (or set tol explicitly) if you change solver after construction.

econometricsmodels.ProbitResults(raw)

Probit estimation results.

Array-valued properties (params, std_errors, etc.) are exposed as dictionaries keyed by coefficient name (for O(1) lookup of a single parameter). Use coef_table() for a row-oriented listing (docs/spec/nonlinear-common.md section 5).

marginal_effects(), predict(), and pred_table() are provided as separate methods rather than fields on this class (they depend on a representative point / threshold not fixed at fit() time; see docs/spec/nonlinear-common.md section 6).

Parameters:

Name	Type	Description	Default
raw	ProbitResult	The estimation result object returned by _lib.fit_probit (_lib.ProbitResult).	required

Note

Users normally do not construct this directly; it is returned by Probit.fit().

aic property

Akaike Information Criterion (AIC).

bic property

Bayesian Information Criterion (BIC).

conf_int property

Coefficient name to confidence interval (lower, upper).

converged property

Whether the solver converged within max_iter iterations.

cov_type property

Standard error type actually used (normalized to lowercase).

dep_var_name property

Column name of the dependent variable.

df_model property

Model degrees of freedom (k - 1).

df_resid property

Residual degrees of freedom (n - k).

log_likelihood property

Log-likelihood at the fitted parameters.

log_likelihood_null property

Log-likelihood of the intercept-only model.

lr_df property

Degrees of freedom of the chi-squared likelihood-ratio test (lr_statistic). None when there are no slope coefficients.

lr_p_value property

P-value of the likelihood-ratio test (chi-squared distribution).

lr_statistic property

Likelihood-ratio test statistic (overall significance; the Probit analogue of OLS's F-statistic).

n_iter property

Actual number of solver iterations.

n_obs property

Number of observations.

p_values property

Coefficient name to two-sided p-value.

param_names property

List of coefficient names ("const" first when include_intercept=True).

params property

Coefficient name to coefficient value.

pseudo_r_squared property

McFadden pseudo R-squared.

solver property

Optimization solver actually used (normalized to lowercase).

stat_df property

Degrees of freedom of the t distribution behind test_stats, or None when stat_dist is "normal". May differ from df_resid (e.g. cluster-robust inference uses G - 1), so use this to recompute p-values from test_stats.

stat_dist property

Distribution of test_stats: "t" (t-statistics) or "normal" (z-statistics).

std_errors property

Coefficient name to standard error.

test_stats property

Coefficient name to z-statistic.

Probit uses a z-test (standard normal), not a t-test (see docs/spec/nonlinear-common.md section 4).

augment(new_data=None)

Source data with the predicted probabilities appended as a column.

Same new_data semantics as predict(), but returns a polars DataFrame (the training data, or new_data when given, plus a new "predicted_probability" column) instead of a row-oriented list. See OLSResults.augment() for the project's general policy on this DataFrame-returning exception.

Parameters:

Name	Type	Description	Default
new_data	DataFrame | None	Same as predict(). If None (default), returns the training data used in fit() with the predicted probabilities appended.	None

Returns:

Type	Description
DataFrame	A polars DataFrame: the source data's columns plus
DataFrame	"predicted_probability", in the same row order as the source.

Raises:

Type	Description
ValidationError	Same as predict(), or the source data already has a column named "predicted_probability" (which would otherwise be silently overwritten).

coef_table()

Row-oriented summary table of the coefficients.

Shaped to be usable almost as-is in a REST API response. Same shape as OLSResults.coef_table(); test_stat is a z-statistic here (see stat_dist).

Returns:

Type	Description
list[dict[str, float | str]]	A list of dictionaries, one per coefficient. Keys are
list[dict[str, float | str]]	param, coef, std_err, test_stat, p_value,
list[dict[str, float | str]]	conf_lower, conf_upper.

marginal_effects(at='overall', confidence_level=0.95)

Marginal effects (dy/dx) with delta-method standard errors.

Independent of the confidence_level used in fit() (may differ from it; see docs/spec/nonlinear-common.md section 6). The constant term (intercept) is excluded from the output.

Parameters:

Name	Type	Description	Default
at	str	The representative point at which to evaluate the marginal effects. One of "overall" (default, average marginal effects), "mean", or "median". Case-insensitive.	'overall'
confidence_level	float	Confidence level for the confidence interval, in the range (0, 1). Defaults to 0.95.	0.95

Returns:

Type	Description
list[dict[str, float | str]]	A list of dictionaries, one per explanatory variable
list[dict[str, float | str]]	(excluding the intercept). Keys are param, effect,
list[dict[str, float | str]]	std_err, test_stat, p_value, conf_lower, conf_upper (see
list[dict[str, float | str]]	docs/spec/nonlinear-common.md section 6). test_stat is
list[dict[str, float | str]]	always a z-statistic (normal distribution). effect is
list[dict[str, float | str]]	the marginal effect estimate (corresponds to dy/dx in
list[dict[str, float | str]]	Stata's margins, dydx(*) and statsmodels).

Raises:

Type	Description
ValidationError	at is not one of "overall", "mean", "median", or confidence_level is out of range. A subclass of ValueError.

pred_table(threshold=0.5)

Classification (confusion) table.

actual always uses a fixed 0.5 split; only the predicted class depends on threshold (matches statsmodels' BinaryResults.pred_table(threshold)). Unlike predict(), out-of-sample data (a new_data argument) is not yet supported (tracked separately).

Parameters:

Name	Type	Description	Default
threshold	float	Probability threshold above which an observation is classified as the positive class. Defaults to 0.5.	0.5

Returns:

Type	Description
list[dict[str, float]]	A list of two dictionaries, one per actual class (0 then
list[dict[str, float]]	1). Keys are actual, predicted_0, predicted_1
list[dict[str, float]]	(observation counts).

predict(new_data=None)

Predicted probabilities p_i = Φ(x_i'β̂).

Note

Returns a probability in [0, 1], not a 0/1 class prediction — unlike OLSResults.predict(), whose "predicted" key is a point prediction of y itself. This is the standard statsmodels convention. To get a classification, apply a threshold to this output yourself, or use pred_table() (training data only).

Parameters:

Name	Type	Description	Default
new_data	DataFrame | None	New data to predict on. Must contain columns with the same names as the x columns passed at fit time (matched by name; column order does not matter). If include_intercept=True was used at fit time, the constant column is added automatically and must not be included here. If None (default), returns the predicted probabilities for the training data used in fit().	None

Returns:

Type	Description
list[dict[str, float]]	Row-oriented predictions, one dict per observation. Each
list[dict[str, float]]	dict currently has a single key, "probability".

Raises:

Type	Description
ValidationError	new_data is missing a required x column, or a column contains missing/NaN/infinite values.