Results

The result classes subclass hdfe-stream’s RegressionResult, so the reporting methods (summary, tidy, confint, wald_test, with_vcov, summary_dict, summary_json, to_pyfixest) are hdfe-stream’s own and behave identically. The binary logit returns hdfe-stream’s HDFEResult (its reference).

class logit_stream.MultinomialLogitResult

The result of mlogit_stream.

The coefficients are those of each non-base level against the base level (the first of levels), named "<level>:<covariate>"; the base level’s are zero. With an absorbed fixed effect, each of its levels has an effect for every outcome level but its reference, see fixef.

Attributes:

• levels (list) – The outcome’s levels, base first.

• base (object) – The base level.

• (and those of `LogitResult`)

summary(logger=None, level=20)

Print the report, or write it to logger (one record, at level).

summary_text()

The summary() report as a string.

summary_dict(coefficients=False)

The model-level information of summary() as a dict of plain Python types (JSON-ready; nan is None). Fit statistics not defined for the model (e.g. r2 for a GLM) are absent. coefficients=True adds the tidy() table as a list of row dicts.

summary_json(path=None, indent=2, coefficients=False)

The model-level information of summary() as a JSON string (see summary_dict); with path, also written there as UTF-8. Reload with json.loads or json.load.

tidy()

Coefficient table. p-values use the t distribution with df_t degrees of freedom, or the normal for GLMs, as in pyfixest.

coef()

The coefficients, as {name: estimate}.

coef_matrix()

The coefficients as a table: a row per covariate, a column per non-base level.

confint(alpha=0.05, keep=None, drop=None, exact_match=False, joint=False, reps=10000, seed=None)

Confidence intervals, one coefficient at a time or simultaneous.

Pointwise intervals use the t distribution with df_t degrees of freedom, or the normal for GLMs, as tidy does. With joint=True, the intervals cover all the selected coefficients at once with probability 1 - alpha: the critical value is the 1 - alpha quantile of the largest absolute t statistic, simulated from the normal with the coefficients’ correlation (the multiplier bootstrap of pyfixest’s confint(joint=True); Chernozhukov et al., Applied Causal Inference Powered by ML and AI, remark 4.4.1).

Parameters:

• alpha (float, default 0.05) – One minus the coverage.

• keep (str or list of str, optional) – Regular expressions selecting coefficients by name, as in pyfixest: those matching a keep pattern, in the order of the patterns (all, by default), less those matching a drop pattern. A joint interval covers exactly these.

• drop (str or list of str, optional) – Regular expressions selecting coefficients by name, as in pyfixest: those matching a keep pattern, in the order of the patterns (all, by default), less those matching a drop pattern. A joint interval covers exactly these.

• exact_match (bool, default False) – Match names exactly instead of as regular expressions.

• joint (bool, default False) – Simultaneous intervals.

• reps (int, default 10000) – Draws for the joint critical value.

• seed (int, optional) – Seed for those draws.

Returns:

polars.DataFrame – Coefficient and the lower and upper bounds, in columns named by their percentiles ("2.5%", "97.5%").

wald_test(R=None, q=None, distribution=None, keep=None, drop=None, exact_match=False)

Wald test of the linear hypothesis R beta = q, under the current vcov (see with_vcov).

By default the hypothesis is that every coefficient is zero; keep and drop narrow it to some of them (the coefficients of an event study’s leads, say), and R and q state any other.

The statistic is W = (R b - q)’ (R V R’)^+ (R b - q), and F = W / m for m restrictions. F is referred to the F distribution with m and df_t degrees of freedom, so that for one coefficient the p-value is the one tidy reports; W, to the chi-squared with m. Two differences from pyfixest’s wald_test: it reports chi-squared whenever R is not the identity or q is not zero, where this test reports what is asked for; and its F’s denominator degrees of freedom, without clustering, subtract every fixed-effect level, including the redundant ones that df_t does not.

Parameters:

• R (array-like, optional) – m x k, one row per restriction, one column per coefficient in the order of coefnames; a 1-d array is one restriction.

• q (float or array-like, optional) – The m right-hand sides; zero by default.

• distribution ({"F", "chi2"}, optional) – Default “F” for OLS and “chi2” for GLMs, whose tidy p-values are normal.

• keep – Without R: test that the coefficients they select are zero (or q), as in confint.

• drop – Without R: test that the coefficients they select are zero (or q), as in confint.

• exact_match – Without R: test that the coefficients they select are zero (or q), as in confint.

Returns:

dict – statistic (F or W), pvalue, df1 (m), df2 (df_t for F, None for chi-squared) and distribution.

with_vcov(vcov)

A copy of this result with another of the vcovs computed at fit time: "iid", "hetero", or a clustering given as {"CRV1": var} or "CRV1:var" (likewise CRV3, when it was the fit’s vcov). Ask for clusterings at fit time with vcov= or cluster=.

predict(newdata=None, type='response', prefix=None)

Predictions as a lazy frame: newdata (default: the fit’s source, every row) with columns added.

type=”response”

The probability of each level, prob_<level>.

type=”link”

The linear predictor of each non-base level, xb_<level> (with its fixed effect).

type=”class”

The most probable level, predicted.

A row with a null or non-finite covariate, or a fixed-effect level the fit did not estimate, gets nulls. prefix renames the columns’ prefix (or, for “class”, the column).

resid()

The estimation sample, lazily: row_id (the row’s position in the source), the outcome, each level’s probability prob_<level>, and each level’s response residual resid_<level> = 1[y = level] - prob. Computed from the source when collected (nothing is stored).

fixef(name=None)

The absorbed fixed effects: one row per level of the dimension, with its effects (see the subclass) and its number of observations. The table is held in memory; this is a lazy view of it.

ranef(name=None)

A random grouping’s predicted intercepts (their modes given the data, the conditional means’ Laplace approximation): one row per group, with one column per outcome level (the base level’s 0) for the multinomial logit, one for the ordered logit, and the group’s number of observations. predict adds every grouping’s to the linear predictor, using 0 for a group the fit did not see. name: the grouping, needed when there are several.

varcorr()

The random intercepts’ standard deviations and correlations, one row each per grouping, with their standard errors and 95% Wald intervals on the scales that respect their bounds (log sd, Fisher’s z of a correlation).

sample(check=True)

The source, lazily, with row_id (the row’s position) first and two columns added: in_sample, and dropped_because (null for the rows used; "missing" for a null or non-finite value in a column the model uses, "incomplete set" for the other alternatives of a choice set with such a row (conditional logit, without altwise=True), "separation" for a fixed-effect level whose outcome never varies).

to_pyfixest()

A pyfixest Feols (Feiv for IV) view of this result, for pf.etable, pf.summary, pf.coefplot and pf.iplot. Only the stored results are available; methods that need the data (recomputing the vcov, the wild bootstrap) are not, and predict is this result’s own predict.

__init__(*, fml, depvar, coefnames, beta, vcov, vcov_type, df_t, n_obs, all_vcovs=<factory>, n_clusters=<factory>, collin_vars=<factory>, diagnostics=<factory>, weights=None, weights_type='aweights', model, loglik, loglik_null, pseudo_r2, aic, bic, n_params, converged, fe_names=<factory>, n_levels=<factory>, random_effects=<factory>, l2=0.0, loglik_fe_null=nan, pseudo_r2_within=nan, firth=False, _spec=None, levels, base=None)

classmethod __new__(*args, **kwargs)

class logit_stream.OrderedLogitResult

The result of ologit_stream.

P(y <= level j) = F(cut_j - x’b), F the logistic distribution: positive coefficients move probability toward the higher levels. The cutpoints are the last coefficients, cut1 … cut{J-1}, cut_j between levels j and j + 1. With an absorbed fixed effect, cut1 is normalized to zero (the effects carry the location) and is not reported.

Attributes:

• levels (list) – The outcome’s levels, lowest first.

• (and those of `LogitResult`)

property cutpoints

All J - 1 cutpoints (with a fixed effect, the first is 0).

predict(newdata=None, type='response', prefix=None)

Predictions as a lazy frame, as MultinomialLogitResult.predict: type="response" the probability of each level (prob_<level>), "link" the linear predictor x’b (with the fixed effect), "class" the most probable level.

resid()

The estimation sample, lazily: row_id, the outcome, xb, each level’s probability and response residual (1[y = level] - prob), and two residuals for the ordered outcome as a whole: resid_prob, the probability-scale residual P(Y < y) - P(Y > y) (Li and Shepherd 2012; statsmodels’ resid_prob), in [-1, 1] and mean zero; and resid_gen, the generalized residual d log P(y) / d xb (Stata’s predict, scores), positive when the outcome is higher than the fit expects. For the logit the two are equal (both are F(cut_{y-1} - xb) + F(cut_y - xb) - 1, since the logistic density is F (1 - F)); for the probit they differ.

fixef(name=None)

The absorbed fixed effects: one row per level of the dimension, with its effects (see the subclass) and its number of observations. The table is held in memory; this is a lazy view of it.

ranef(name=None)

A random grouping’s predicted intercepts (their modes given the data, the conditional means’ Laplace approximation): one row per group, with one column per outcome level (the base level’s 0) for the multinomial logit, one for the ordered logit, and the group’s number of observations. predict adds every grouping’s to the linear predictor, using 0 for a group the fit did not see. name: the grouping, needed when there are several.

varcorr()

The random intercepts’ standard deviations and correlations, one row each per grouping, with their standard errors and 95% Wald intervals on the scales that respect their bounds (log sd, Fisher’s z of a correlation).

sample(check=True)

The source, lazily, with row_id (the row’s position) first and two columns added: in_sample, and dropped_because (null for the rows used; "missing" for a null or non-finite value in a column the model uses, "incomplete set" for the other alternatives of a choice set with such a row (conditional logit, without altwise=True), "separation" for a fixed-effect level whose outcome never varies).

__init__(*, fml, depvar, coefnames, beta, vcov, vcov_type, df_t, n_obs, all_vcovs=<factory>, n_clusters=<factory>, collin_vars=<factory>, diagnostics=<factory>, weights=None, weights_type='aweights', model, loglik, loglik_null, pseudo_r2, aic, bic, n_params, converged, fe_names=<factory>, n_levels=<factory>, random_effects=<factory>, l2=0.0, loglik_fe_null=nan, pseudo_r2_within=nan, firth=False, _spec=None, levels)

classmethod __new__(*args, **kwargs)

class logit_stream.OrderedProbitResult

The result of oprobit_stream: as OrderedLogitResult, with F the standard normal distribution.

__init__(*, fml, depvar, coefnames, beta, vcov, vcov_type, df_t, n_obs, all_vcovs=<factory>, n_clusters=<factory>, collin_vars=<factory>, diagnostics=<factory>, weights=None, weights_type='aweights', model, loglik, loglik_null, pseudo_r2, aic, bic, n_params, converged, fe_names=<factory>, n_levels=<factory>, random_effects=<factory>, l2=0.0, loglik_fe_null=nan, pseudo_r2_within=nan, firth=False, _spec=None, levels)

classmethod __new__(*args, **kwargs)

class logit_stream.ConditionalLogitResult

The result of clogit_stream: McFadden’s conditional logit on long-format data, one row per alternative in each choice set.

Attributes:

• case (list of str) – The columns that identify a choice set.

• n_cases (int) – Choice sets used. n_obs is the same number (the sum of the weights with frequency weights); diagnostics["n_rows"] counts the rows (alternatives).

• (and those of `LogitResult`)

predict(newdata=None, type='response', prefix=None, case=None)

Predictions as a lazy frame, one per row (alternative): type="response" the choice probability within the row’s choice set (prob), "link" the utility x’b (xb). The choice sets are identified by case (default: the fit’s). The probabilities are a window over each set, which Polars evaluates set by set.

resid()

The estimation sample, lazily, a row per alternative: row_id, the case columns, the outcome, xb, prob and the response residual resid = y - prob.

sample(check=True)

The source, lazily, with row_id (the row’s position) first and two columns added: in_sample, and dropped_because (null for the rows used; "missing" for a null or non-finite value in a column the model uses, "incomplete set" for the other alternatives of a choice set with such a row (conditional logit, without altwise=True), "separation" for a fixed-effect level whose outcome never varies).

__init__(*, fml, depvar, coefnames, beta, vcov, vcov_type, df_t, n_obs, all_vcovs=<factory>, n_clusters=<factory>, collin_vars=<factory>, diagnostics=<factory>, weights=None, weights_type='aweights', model, loglik, loglik_null, pseudo_r2, aic, bic, n_params, converged, fe_names=<factory>, n_levels=<factory>, random_effects=<factory>, l2=0.0, loglik_fe_null=nan, pseudo_r2_within=nan, firth=False, _spec=None, case, n_cases=0)

classmethod __new__(*args, **kwargs)

class logit_stream.ConditionalFELogitResult

The result of cfelogit_stream: Chamberlain’s conditional fixed-effects logit. The unit effects are conditioned out, not estimated, so there are none to report or predict with: predict gives the linear predictor x’b only (the probabilities need the unit’s effect), and loglik is the conditional log-likelihood (its null: every arrangement of a unit’s 1s equally likely).

Attributes:

• unit (list of str) – The columns that identify a unit (the formula’s fixed effect).

• n_units (int) – Units whose outcome varies, the ones the likelihood uses; n_obs is the same number (the sum of their weights with frequency weights).

• n_units_dropped (int) – Units whose outcome is all 0 or all 1, which carry no information.

• n_rows (int) – The rows of the units used.

• (and those of `LogitResult`)

predict(newdata=None, type='link', prefix=None)

The linear predictor x’b (xb), lazily; only type="link": the unit effects were conditioned out, so probabilities cannot be formed.

__init__(*, fml, depvar, coefnames, beta, vcov, vcov_type, df_t, n_obs, all_vcovs=<factory>, n_clusters=<factory>, collin_vars=<factory>, diagnostics=<factory>, weights=None, weights_type='aweights', model, loglik, loglik_null, pseudo_r2, aic, bic, n_params, converged, fe_names=<factory>, n_levels=<factory>, random_effects=<factory>, l2=0.0, loglik_fe_null=nan, pseudo_r2_within=nan, firth=False, _spec=None, unit, n_units=0, n_units_dropped=0, n_rows=0)

classmethod __new__(*args, **kwargs)

class logit_stream.MixedLogitResult

The result of mixlogit_stream (prototype).

The coefficients are the fixed coefficients and the means of the random ones (named as the covariates; for a lognormal coefficient, the mean of its log), then the standard deviations of the random ones, "sd.<name>" (of the log, for a lognormal one). The sign of a standard deviation is not identified, so its absolute value is reported (the signed estimates are in diagnostics["sd_signed"]; the standard errors are the same). n_obs is the number of choosers (panels), the unit of the likelihood; the robust variance is clustered by them, "CRV1:<panel>" ("hetero" without panel, each choice set its own chooser).

Attributes:

• case, panel (list of str) – The columns identifying the choice sets and the choosers.

• n_cases, n_panels (int) – Their numbers.

• random (dict) – Each random coefficient’s distribution.

• draws, halton, seed, drop – The simulation: draws per chooser, Halton or pseudo-random, the pseudo-random seed, the Halton points discarded at the start.

• loglik_clogit (float) – The conditional logit’s log-likelihood (the starting point).

• (and those of `LogitResult`)

__init__(*, fml, depvar, coefnames, beta, vcov, vcov_type, df_t, n_obs, all_vcovs=<factory>, n_clusters=<factory>, collin_vars=<factory>, diagnostics=<factory>, weights=None, weights_type='aweights', model, loglik, loglik_null, pseudo_r2, aic, bic, n_params, converged, fe_names=<factory>, n_levels=<factory>, random_effects=<factory>, l2=0.0, loglik_fe_null=nan, pseudo_r2_within=nan, firth=False, _spec=None, case, panel, n_cases=0, n_panels=0, random=<factory>, draws=0, halton=True, seed=0, drop=100, loglik_clogit=nan)

classmethod __new__(*args, **kwargs)

class logit_stream.NestedLogitResult

The result of nlogit_stream (prototype).

The coefficients are those of the utilities, then each nest’s dissimilarity parameter, "lambda.<nest>", in the order of nests= (RU2: the model is the conditional logit when they are all 1; nests of one child have none). n_obs is the number of choice sets (their weight, with frequency weights).

Attributes:

• case (list of str) – The columns identifying the choice sets.

• alt (str) – The column naming the alternatives.

• nests (dict) – Each nest’s alternatives (all of them, for a nest of nests).

• n_cases (int) – The number of choice sets.

• loglik_clogit (float) – The conditional logit’s log-likelihood (the starting point).

• (and those of `LogitResult`)

__init__(*, fml, depvar, coefnames, beta, vcov, vcov_type, df_t, n_obs, all_vcovs=<factory>, n_clusters=<factory>, collin_vars=<factory>, diagnostics=<factory>, weights=None, weights_type='aweights', model, loglik, loglik_null, pseudo_r2, aic, bic, n_params, converged, fe_names=<factory>, n_levels=<factory>, random_effects=<factory>, l2=0.0, loglik_fe_null=nan, pseudo_r2_within=nan, firth=False, _spec=None, case, n_cases=0, alt, nests=<factory>, loglik_clogit=nan)

classmethod __new__(*args, **kwargs)

class logit_stream.LogitResult

What every logit result has; see the subclasses.

Attributes:

• fml, depvar, coefnames, beta, vcov, vcov_type, df_t, n_obs, all_vcovs, n_clusters, collin_vars, diagnostics, weights, weights_type – As in hdfe_stream.HDFEResult. df_t is used only by wald_test with distribution="F"; p-values and intervals are normal.

• model (str) – "multinomial logit", "ordered logit" or "conditional logit".

• loglik (float) – The log-likelihood at the estimates (without the L2 or Firth penalty).

• loglik_null (float) – The null model’s: the outcome’s sample shares (multinomial, ordered), or equal probabilities within each choice set (conditional).

• pseudo_r2 (float) – McFadden’s, 1 - loglik / loglik_null: with a fixed effect, it credits the covariates and the fixed effect together.

• loglik_fe_null (float) – With an absorbed fixed effect, the log-likelihood of the model with it and no covariates: each level’s outcome shares (multinomial), or a location per level and common cutpoints (ordered); computed from the outcome counts per level, without reading the data. Else nan.

• pseudo_r2_within (float) – 1 - loglik / loglik_fe_null: what the covariates add beyond the fixed effect (fixest’s “within pseudo R2”); nan without one.

• aic, bic (float) – -2 loglik + 2 k and -2 loglik + k log N, with k the estimated parameters, fixed effects included.

• n_params (int) –

• fe_names (list of str) – The absorbed fixed-effect dimension, if any.

• random_effects (dict) – With random intercepts (random=): the grouping (group), its number of groups, the covariance of the intercepts (Sigma, over the non-base outcome levels; 1 x 1 for the ordered logit), its form (cov), the outcome levels it is over, the method, and Sigma’s standard errors: Sigma_se (each element’s), sd and sd_se, corr and corr_se (delta method), and vcov_Sigma with its Sigma_params (the (j, l) elements it is over). Empty otherwise.

• n_levels (dict) – Its number of levels.

• l2 (float) – The L2 penalty (0: maximum likelihood).

• firth (bool) – Whether the estimates maximize Firth’s penalized likelihood (firth=True).

• converged (bool) – Whether Newton’s method met its tolerance.

__init__(*, fml, depvar, coefnames, beta, vcov, vcov_type, df_t, n_obs, all_vcovs=<factory>, n_clusters=<factory>, collin_vars=<factory>, diagnostics=<factory>, weights=None, weights_type='aweights', model, loglik, loglik_null, pseudo_r2, aic, bic, n_params, converged, fe_names=<factory>, n_levels=<factory>, random_effects=<factory>, l2=0.0, loglik_fe_null=nan, pseudo_r2_within=nan, firth=False, _spec=None)

classmethod __new__(*args, **kwargs)

class logit_stream.LogitMulti

Results of a formula that expands to several models (several outcomes, sw(), csw(), …): iterate over it, or take one with fetch_model; len() counts them.

fetch_model(i)

The i-th model, in the formula’s order.

tidy()

Every model’s coefficient table, with a column fml first.

summary(logger=None, level=20, per_model=False)

Print all reports, or write them to logger: one record in total, or one per model with per_model=True.

summary_dict(coefficients=False)

{formula: HDFEResult.summary_dict(...)} for each model.

summary_json(path=None, indent=2, coefficients=False)

JSON object keyed by formula, each value as HDFEResult.summary_json; with path, also written there.

__init__(results)

classmethod __new__(*args, **kwargs)