Package: idcempy
IDCeMPy: Python Package for Inflated Discrete Choice ModelsNguyen K. Huynh, Sergio Bejar, Vineeta Yadav, Bumba MukherjeeIDCeMPyis a Python package that provides functions to fit and assess the performance of the following distinct
sets of “inflated” discrete choice models.Fit the Zero-Inflated Ordered Probit (ZIOP) model without and with correlated errors (ZIOPC
model) to evaluate zero-inflated ordered choice outcomes that result from a dual data generating
process (d.g.p.).Fit the Middle-Inflated Ordered Probit (MIOP) model without and with correlated errors (MIOPC) to account for the inflated middle-category in ordered choice measures related to a dual d.g.p.Fit Generalized Inflated Multinomial Logit (GIMNL) models account for the predominant and heterogeneous share of observations in the baseline or any lower category in unordered polytomous choice outcomes.Compute AIC and Log-likelihood statistics and the Vuong Test statistic to assess the performance of each inflated discrete choice model in the package.IDCeMPyuses Newton numerical optimization methods to estimate the inflated discrete choice models listed above via Maximum Likelihood Estimation (MLE).IDCeMPYis compatible withPython3.7+WhyIDCeMPy?An excessive (“inflated”) share of observations—stemming from two distinct d.g.p’s—fall into a single choice category in many ordered and unordered polytomous outcome variables. Standard Ordered Probit and Multinomial Logit models cannot account for such category inflation which leads to biased inferences. Examples include,The inflated zero-category of "no smoking" in ordered measures of self-reported smoking behavior is generated from nonsmokers who never smoke cigarettes and those who smoked previously but temporarily stopped smoking because of high cigarette prices.The inflated "indifference" middle-category in ordered measures of immigration attitudes includes respondents truly indifferent to immigration and those that choose indifference for social desirability reasons.The inflated baseline or other lower outcome categories of unordered polytomous outcome measures of vote choice include nonvoters who temporarily abstain from voting and routine nonvoters who always abstain.IDCeMPyincludes the ZIOP(C) models for evaluating zero-inflated ordered choice outcomes that result from a dual d.g.p, the MIOP(C) models that address inflated middle-category ordered outcome measures arising from distinct d.g.p’s, and GIMNL models that account for inflated baseline or other categories for unordered polytomous outcomes.Each inflated discrete choice model in this package addresses category inflation in one’s discrete outcome—unordered or unordered polytomous—of interest by jointly estimating a binary split-stage equation and an ordered or multinomial discrete choice outcome equation.Functions in theIDCeMPyPackageFunctionDescriptionopmod;iopmod;iopcmodFits the ordered probit model, the Zero-Inflated (ZIOP) & Middle-Inflated ordered probit (MIOP) models without correlated errors, and the ZIOPC & MIOPC models that incorporate correlated errors.opresults;iopresults;iopcresultsPresents covariate estimates, Variance-Covariance (VCV) matrix, and goodness-of-fit statistics (Log-Likelihood and AIC) ofopmod,iopmod,iopcmod.iopfit;iopcfitComputes fitted probabilities from each estimated model's object.vuong_opiop;vuong_opiopcCalculates Vuong test statistic for comparing the OP model's performance to ZiOP(C) and MiOP(C) models.split_effects;ordered_effectsEstimates marginal effects of covariates from the split and outcome-stage respectively.mnlmod;gimnlmodFits MNL model and Generalized-Inflated MNL models.mnlresults;gimnlresults;vuong_gimnlPresents covariate estimates, VCV matrix, and goodness-of-fit statistics ofmnlmod,gimnlmod. Vuong test statistic for comparing MNL to GIMNL models obtained fromvuong_gimnlDependenciesscipynumpypandasInstallationFromPyPi:pipinstallidcempyFromGitHubgitclonehttps://github.com/hknd23/idcempy.gitcdidcempy
pythonsetup.pyinstallOnreadthedocsyou will find the installation guide, a complete overview of each feature included inIDCeMPy, and example scripts of all the models.Using the PackageExample 1: Zero-inflated Ordered Probit Model with Correlated Errors (ZIOPC)We illustrate howIDCeMPycan be used to estimate the OP and ZIOP(C) models for zero-inflated ordered outcome variables by using the CDC's 2018National Youth Tobacco Dataset. The self-reported ordered tobacco consumption outcome variable in this data ranges from 0 for "no smoking" to 4 for "15 or more cigarettes". The zero "no smoking" category contains excessive observations that include permanent nonsmokers who never smoke (non-inflated cases) and transient nonsmokers (inflated cases) who temporarily stopped smoking because of high cigarette prices.IDCeMPyallows users to fit the ordered probit (OP) and Zero-inflated Ordered Probit (ZIOP) model without and with correlated errors (ZIOPC). The application of the OP model (available fromopmod) and ZIOP model without correlated errors (seeiopmod) to the CDC's 2018 Tobacco Consumption data is provided in the package's documentation. We fit the Zero-Inflated Ordered Probit Model with correlated errors to this data below.First, install pandas and matplotlib to import and visualize data (if the packages are not already installed):pipinstallpandas
pipinstallmatplotlib
pipinstallurllibThen, importIDCeMPy, required packages, and dataset.fromidcempyimportzmiopcimportpandasaspdimportmatplotlib.pyplotasplotimporturlliburl='https://github.com/hknd23/idcempy/raw/main/data/tobacco_cons.csv'data=pd.read_csv(url)Users can define the lists with the names of the covariates to include in the ZIOPC model's split-stage (Z), the OP outcome-stage (X) as well as the zero-inflated ordered outcome variable (Y).X=['age','grade','gender_dum']Y=['cig_count']Z=['gender_dum']The default value of the starting parameters is set to .01. Users can, however, define an array of starting parameters before estimating theziopcmodel and add it as an argument in theiopcmodfunction.The following line of code creates a ziopc regression object model.ziopc_tob=zmiopc.iopcmod('ziopc',data,X,Y,Z,method='bfgs',weights=1,offsetx=0,offsetz=0)Users can estimate the ZIOP model without correlated errors by usingzmiopc.iopmodand the parameter 'ziop'. Please note that the models with correlated errors estimated withzmiopc.iopcmodhave substantially higher run-time thanzmiopc.iopmod. The above model takes roughly 1 hour and 8 minutes (on Windows 10, Intel Core i7-2600, 16GB RAM).The results from the ZIOPC model for this application are stored in a class (ZiopcModel) with the following attributes:coefs: Model coefficients and standard errorsllik: Log-likelihoodAIC: Akaike information criterionvcov: Variance-covariance matrixWe can generate the covariate estimates, standard errors,pvalue andtstatistics in the ZIOPC case by typing:print(ziopc_tob.coefs)CoefSEtscorep2.5%97.5%ProbitSplit-stage-----------------------intercept9.5380723.4706892.7481785.992748e-032.73552116.340623gender_dum-9.1659633.420056-2.6800627.360844e-03-15.869273-2.462654OPOutcome-stage-----------------------age-0.0286060.008883-3.2203691.280255e-03-0.046016-0.011196grade0.1775410.01016517.4654520.000000e+000.1576170.197465gender_dum0.6021360.05308411.3430200.000000e+000.4980910.706182cut11.6961600.04472637.9235840.000000e+001.6084971.783822cut2-0.7580950.033462-22.6556780.000000e+00-0.823679-0.692510cut3-1.8120770.060133-30.1344410.000000e+00-1.929938-1.694217cut4-0.7058360.041432-17.0361100.000000e+00-0.787043-0.624630rho-0.4157700.074105-5.6105262.017123e-08-0.561017-0.270524The Akaike Information Criterion (AIC) statistics for the ZIOPC model is given by,print(ziopc_tob.AIC)16061.716497590078The AIC of the OP and ZIOP models reported in the documentation is 8837.44 and 10138.32, respectively.split_effectscreates a dataframe that provides values to illustrate via boxplots (with 95% Confidence Intervals) the marginal effect of the ZIOP(C) model's split-stage covariates on the first difference in the predicted probability that the zero-category observations are non-inflated. In the tobacco consumption example,split_effectsprovides and illustrates via boxplots (with 95% CIs) the first difference in the predicted probability of zero-category observations being permanent nonsmokers (non-inflated cases) when the dummy split-stage covariate 'gender_dum' changes from 0 (female) to 1 (male).ziopcgender_split=zmiopc.split_effects(ziopc_tob,1)ziopcgender_split.plot.box(grid='False')plot.show()Fig. 1: Marginal Effect of Gender on Probability of Permanent Nonsmokerordered_effectscreates a dataframe that provides values to illustrate the marginal effect of the ZIOP(C) model's outcome-stage covariates on the first difference in the predicted probability of each ordered outcome category conditional on the zero-category observations being non-inflated. In the example below,ordered_effectsprovides and illustrate via boxplots (with 95% CIs) the first difference in the predicted probability (with 95% CIs) of each 0 to 4 ordered category of the tobacco consumption outcome when the dummy outcome-stage covariate 'gender_dum' changes from 0 to 1, conditional on zero-category observations being non-inflated.ziopcgender_ordered=zmiopc.ordered_effects(ziopc_tob,2)ziopcgender_ordered.plot.box(grid='False')plot.show()Fig. 2: Marginal Effect of Gender on Self-Reported Tobacco ConsumptionModulezmiopcalso provides the functionvuong_opiopcthat employs the Vuong test statistic to compare the performance of the standard OP model (also available throughopmod) versus the ZIOPC model and also the OP versus ZIOP model. The Vuong statistics from comparing the OP and the ZIOPC model is given by,op_tob=zmiopc.opmod(data,X,Y)zmiopc.vuong_opiopc(op_tob,ziopc_tob)6.576246015382724The Vuong test statistic favors the OP over both the ZIOPC model and ZIOP model (see documentation).Example 2: Middle-inflated Ordered Probit Models with Correlated Errors (MIOPC)We next illustrate howIDCeMPycan be employed to fit the OP and MIOP(C) models for inflated middle-category ordered outcome variables. This is done by using Elgün and Tillman's (2007) survey-response data in which the ordered outcome measure of support for the European Union (EU) by Europeans is given by 1 for “a bad thing,” 2 for “neither good nor bad,” and 3 for “a good thing.” The middle (neither good nor bad) category in this ordered measure contains excessive observations that include informed respondents who opt for this category based on their knowledge about the EU and uninformed respondents who choose this category to save face.IDCeMPyallows users to fit the OP and Middle-inflated Ordered Probit (MIOP) model without and with correlated errors (MIOPC). The application of the OP model fromopmodand MIOP model without correlated errors fromiopmodto the EU support data is provided in the package's documentation. Users can estimate the MIOP model without correlated errors by simply substituting 'miop' for 'miopc'.We turn to fit the Middle-Inflated Ordered Probit Model with correlated errors (MIOPC) to the aforementioned data. To this end, first load the dataset.url='https://github.com/hknd23/idcempy/raw/main/data/EUKnowledge.dta'data=pd.read_stata(url)Users can define the lists with names of the covariates they would like to include in the MIOPC model's split-stage (Z) and the second-stage (X) as well as the name of the ordered "middle-inflated" outcome variable (Y).Y=["EU_support_ET"]X=['Xenophobia','discuss_politics']Z=['discuss_politics','EU_Know_obj']Run the model and print the results (this MiOPC specification takes roughly 31 minutes to finish):miopc_EU=zmiopc.iopcmod('miopc',data,X,Y,Z)print(miopc_EU.coefs)CoefSEtscorep2.5%97.5%ProbitSplit-stage---------------------------int-0.1290.021-6.1880.000-0.170-0.088discuss_politics0.1920.0267.4590.0000.1420.243EU_Know_obj0.1940.0277.1540.0000.1410.248OPOutcome-stage---------------------------Xenophobia-0.5910.045-13.1360.000-0.679-0.502discuss_politics-0.0290.021-1.3980.162-0.0700.012cut1-1.3700.044-30.9480.000-1.456-1.283cut2-0.3220.103-3.1230.002-0.524-0.120rho-0.7070.106-6.6940.000-0.914-0.500The AIC statistic for the MIOPC model is obtained from,print(miopc_EU.AIC)21669.96812802041The AIC statistics for the MIOP model is 21729.39 and the OP model is 22100.90 (see documentation).In this EU support example, thesplit_effectsdataframe provides and illustrates via boxplots (with 95% CI) the first difference in the predicted probability of middle-category observations being informed respondents (non-inflated cases) when the split-stage covariate 'EU_know_obj' is increased by one standard deviation from its mean value (for continuous variables, the "=0" and "=1" box plots represents the mean and one standard deviation above mean value, respectively).Fig. 3: Marginal Effect of EU Knowledge on Probability of Informed Respondentsordered_effects()calculates and illustrates via boxplots (with 95% CI) the first difference in predicted probabilities of each ordered outcome category of "EU Support" when the outcome-stage Xenophobia covariate is increased by 1 standard deviation from its mean value, conditional on middle-category observations being informed respondents.xeno=zmiopc.ordered_effects(miopc_EU,2)xeno.plot.box(grid='False')Fig. 4: Marginal Effect of Xenophobia on EU SupportUsers can call the functionvuong_opiopcto employ the Vuong test stastic to compare the OP model to the MIOPC model and also the OP to the MIOP model. The Vuong test statistics from comparing the OP to the MIOPC model is,op_EU=zmiopc.opmod(DAT,X,Y)zmiopc.vuong_opiopc(op_EU,miopc_EU)-10.435718518003675The Vuong test statistic thus favors the MIOPC over the OP model, and also the MIOP over the OP model (see documentation).Example 3: Generalized Inflated Multinomial Logit Models (GIMNL)IDCeMPyalso includes functions to fit the GIMNL and standard MNL models. The Generalized Inflated Multinomial Logit Models account for the inflated and thus heterogeneous share of observations that can exist in the baseline or any other category of unordered polytomous outcome variables. To save space, we focus on just presenting the "Baseline" Inflated MNL (i.e., BIMNL) model that addresses excessive observations in the baseline category of unordered outcome measures. We fit this BIMNL model to the 2004 Presidential vote choice data fromCampbell and Monson (2008). The 0,1,2 unordered-polytomous Presidential vote choice dependent variable in their data includes the following options: abstained (their MNL baseline category), Bush, or Kerry. The inflated baseline category incorporates excessive observations of abstained nonvoters who did not vote in the said elections due to temporary factors and routine nonvoters who never vote.Users can fit the standard MNL model(available frommnlmod) to the Campbell and Monson (2008) data, which is described in the documentation. To illustrate how users can fit the BIMNL model to this data, however, we begin by importing thegimnlmodule.fromidcempyimportgimnlurl='https://github.com/hknd23/idcempy/raw/main/data/replicationdata.dta'data=pd.read_stata(url)Define the unordered vote choice outcome variable in the BIMNL asY, whose unordered categories are given by 0,1,2. Denote the covariates in this model's logit split-stage asZandXfor the MNL-outcome stage for each unordered category 1 and 2.x=['educ','party7','agegroup2']z=['educ','agegroup2']y=['vote_turn']reference=[0,1,2]inflatecat="baseline"The argumentinflatecatcan be used to specify any unordered category as the inflated category in their unordered-polytomous outcome measure. Further, from the argumentreference, users can select which category of the unordered outcome variable is the baseline ("reference") category by placing it first. Since the baseline ("0") category in the Presidential vote choice outcome measure is inflated, the following code fits the BIMNL Model,gimnl_2004vote=gimnl.gimnlmod(data,x,y,z,reference,inflatecat)Print the estimates:CoefSEtscorep2.5%97.5%LogitSplit-stage----------------------intercept-4.9352.777-1.7770.076-10.3790.508educ1.8860.2936.4410.0001.3122.460agegroup21.2950.7681.6850.092-0.2112.800MNLOutcomeCategory1---------------------intercept-4.1801.636-2.5560.011-7.387-0.974educ0.3340.1851.8030.071-0.0290.697party70.4540.0577.9940.0000.3430.566agegroup20.9540.2483.8420.0000.4671.441MNLOutcomeCategory2----------------------intercept0.9001.5640.5760.565-2.1663.966educ0.1570.2030.7720.440-0.2410.554party7-0.5770.058-9.9280.000-0.691-0.463agegroup20.9160.2353.9050.0000.4561.376The AIC statistic for the BIMNL model is given by,print(gimnl_2004vote.AIC)1656.8324085039708The AIC for the standard MNL model (see documentation) is 1657.19. The Vuong statistic for comparing the MNL to the BIMNL model in this case is,mnl_2004vote=gimnl.mnlmod(data,x,y,reference)gimnl.vuong_gimnl(mnl_2004vote,gimnl_2004vote)-1.2835338187781173Users can employ the argumentinflatecatto specify any unordered category as the inflated category (dictated by the distribution) in their unordered-polytomous outcome measure. If a higher category (say 1 or 2) is inflated in the 0,1,2 unordered-polytomous outcome measure, then users can specifyreferenceandinflatecatas follows,gimnl.gimnlmod(data,x,y,z,reference,inflatecat="second")gimnl.gimnlmod(data,x,y,z,reference,inflatecat="third")ContributionsThe authors welcome and encourage new contributors to help testIDCeMPyand add new functionality. Issues can be raised by any users for questions and bug reports. For further details, seeGuidelines for Contributors.