Package: balance
balance: a python package for balancing biased data samplesbalanceis currentlyin betaand under active development. Follow uson github!What isbalance?balanceis a Python packageoffering a simple workflow and methods fordealing with biased data sampleswhen looking to infer from them to some population of interest.Biased samples often occur insurvey statisticswhen respondents presentnon-response biasor survey suffers fromsampling bias(that are notmissing completely at random). A similar issue arises inobservational studieswhen comparing the treated vs untreated groups, and in any data that suffers from selection bias.Under the missing at random assumption (MAR), bias in samples could sometimes be (at least partially) mitigated by relying on auxiliary information (a.k.a.: “covariates” or “features”) that is present for all items in the sample, as well as present in a sample of items from the population. For example, if we want to infer from a sample of respondents to some survey, we may wish to adjust for non-response using demographic information such as age, gender, education, etc. This can be done by weighing the sample to the population using auxiliary information.The package is intended for researchers who are interested in balancing biased samples, such as the ones coming from surveys, using a Python package. This need may arise by survey methodologists, demographers, UX researchers, market researchers, and generally data scientists, statisticians, and machine learners.InstallationRequirementsYou need Python 3.8 or later to runbalance.balancecan be built and run from Linux, OSX, and Windows (NOTE:method="ipw"is currently not supported on Windows).The required Python dependencies are:REQUIRES=["numpy","pandas<=1.4.3","ipython","scipy<=1.9.2","patsy","seaborn<=0.11.1","plotly","matplotlib","statsmodels","scikit-learn","ipfn","session-info",]Note that glmnet_python must be installed from theGithub sourceSeesetup.pyfor more details.InstallingbalanceAs a prerequisite, you must install glmnet_python from source:python -m pip install git+https://github.com/bbalasub1/glmnet_python.git@1.0Installing via PyPiWe recommend installingbalancefrom PyPi via pip for the latest stable version:python -m pip install balanceInstallation will use Python wheels from PyPI, available forOSX, Linux, and Windows.Installing from Source/GitYou can install the latest (bleeding edge) version from Git:python -m pip install git+https://github.com/facebookresearch/balance.gitAlternatively, if you have a local clone of the repo:cd balance
python -m pip install .Getting startedbalance’s workflow in high-levelThe core workflow inbalancedeals with fitting and evaluating weights to a sample. For each unit in the sample (such as a respondent to a survey), balance fits a weight that can be (loosely) interpreted as the number of people from the target population that this respondent represents. This aims to help mitigate the coverage and non-response biases, as illustrated in the following figure.The weighting of survey data throughbalanceis done in the following main steps:Loading data of the respondents of the survey.Loading data about the target population we would like to correct for.Diagnostics of the sample covariates so to evaluate whether weighting is needed.Adjusting the sample to the target.Evaluation of the results.Use the weights for producing population level estimations.Saving the output weights.You can see a step-by-step description (with code) of the above steps in theGeneral Frameworkpage.Code example of usingbalanceYou may run the following code to play withbalance's basic workflow (these are snippets taken from thequickstart tutorial):We start by loading data, and adjusting it:frombalanceimportload_data,Sample# load simulated example datatarget_df,sample_df=load_data()# Import sample and target data into a Sample objectsample=Sample.from_frame(sample_df,outcome_columns=["happiness"])target=Sample.from_frame(target_df)# Set the target to be the target of samplesample_with_target=sample.set_target(target)# Check basic diagnostics of sample vs target before adjusting:# sample_with_target.covars().plot()You can read more on evaluation of the pre-adjusted data in thePre-Adjustment Diagnosticspage.Next, we adjust the sample to the population by fitting balancing survey weights:# Using ipw to fit survey weightsadjusted=sample_with_target.adjust()You can read more on adjustment process in theAdjusting Sample to Populationpage.The above code gets us anadjustedobject with weights. We can evaluate the benefit of the weights to the covariate balance, for example by running:print(adjusted.summary())# Covar ASMD reduction: 62.3%, design effect: 2.249# Covar ASMD (7 variables):0.335 -> 0.126# Model performance: Model proportion deviance explained: 0.174adjusted.covars().plot(library="seaborn",dist_type="kde")And get:We can also check the impact of the weights on the outcome using:# For the outcome:print(adjusted.outcomes().summary())# 1 outcomes: ['happiness']# Mean outcomes:#             happiness# source# self        54.221388# unadjusted  48.392784## Response rates (relative to number of respondents in sample):#    happiness# n     1000.0# %      100.0adjusted.outcomes().plot()You can read more on evaluation of the post-adjusted data in theEvaluating and using the adjustment weightspage.Finally, the adjusted data can be downloaded using:adjusted.to_download()# Or:# adjusted.to_csv()To see a more detailed step-by-step code example with code output prints and plots (both static and interactive), please go over to thetutorials section.Implemented methods for adjustmentsbalancecurrently implements various adjustment methods. Click the links to learn more about each:Logistic regression using L1 (LASSO) penalization.Covariate Balancing Propensity Score (CBPS).Post-stratification.Raking.Implemented methods for diagnostics/evaluationFor diagnostics the main tools (comparing before, after applying weights, and the target population) are:Plotsbarplotsdensity plots (for weights and covariances)qq-plotsStatistical summariesWeights distributionsKish’s design effectMain summaries (mean, median, variances, quantiles)Covariate distributionsAbsolute Standardized Mean Difference (ASMD). For continuous variables, it isCohen's d. Categorical variables are one-hot encoded, Cohen's d is calculated for each category and ASMD for a categorical variable is defined as Cohen's d, average across all categories.You can read more on evaluation of the post-adjusted data in theEvaluating and using the adjustment weightspage.More detailsGetting help, submitting bug reports and contributing codeYou are welcome to:Learn more in thebalancewebsite.Ask for help on:https://stats.stackexchange.com/questions/tagged/balanceSubmit bug-reports and features' suggestions at:https://github.com/facebookresearch/balance/issuesSend a pull request on:https://github.com/facebookresearch/balance. See theCONTRIBUTINGfile for how to help out. And ourCODE OF CONDUCTfor our expectations from contributors.CitingbalanceTODO: TBD.LicenseThebalancepackage is licensed under theGPLv2 license, and all the documentation on the site is underCC-BY.NewsYou can follow updates on our:BlogChangelogAcknowledgements / PeopleThebalancepackage is actively maintained by people from theCore Data Scienceteam (in Tel Aviv and Boston), byTal Sarig,Tal GaliliandSteve Mandala.Thebalancepackage was (and is) developed by many people, including:Roee Eilat,Tal Galili,Daniel Haimovich,Kevin Liou,Steve Mandala,Adam Obeng(author of the initial internal Meta version),Tal Sarig,Luke Sonnet,Sean Taylor,Barak Yair Reif, and others. If you worked on balance in the past, please email us to be added to this list.Thebalancepackage was open-sourced byTal Sarig,Tal GaliliandSteve Mandalain late 2022.Branding created byDana Beaty, from the Meta AI Design and Marketing Team. For logo files, seehere.