cbps 0.2.0__py3-none-any.whl

cbps/datasets/continuous.py

@@ -0,0 +1,223 @@
+"""
+Continuous Treatment Dataset Loaders
+=====================================
+
+This module provides datasets for continuous treatment CBPS methods, including
+simulation data and real-world application data from Fong, Hazlett, and Imai (2018).
+
+The simulation data enables systematic evaluation of CBPS estimators under
+various model misspecification scenarios. The political ads dataset provides
+a real-world application for continuous treatment effect estimation.
+
+References
+----------
+Fong, C., Hazlett, C., and Imai, K. (2018). Covariate balancing propensity
+score for a continuous treatment: Application to the efficacy of political
+advertisements. *The Annals of Applied Statistics*, 12(1), 156-177.
+DOI: 10.1214/17-AOAS1101
+
+Urban, C. and Niebler, S. (2014). Dollars on the sidewalk: Should U.S.
+Presidential candidates advertise in uncontested states? *American Journal
+of Political Science*, 58(2), 322-336.
+"""
+from pathlib import Path
+from typing import Tuple, Dict, Any
+import pandas as pd
+import numpy as np
+
+
+def load_continuous_simulation(
+    dgp: int = 1,
+    seed: int = 12345
+) -> Tuple[pd.DataFrame, Dict[str, Any]]:
+    """Load continuous treatment simulation data (Fong et al. 2018, Section 4).
+
+    Parameters
+    ----------
+    dgp : {1, 2, 3, 4}, default=1
+        Data generating process type:
+
+        - **DGP1**: Both treatment and outcome correctly specified (linear)
+        - **DGP2**: Treatment model misspecified (contains (X2+0.5)² nonlinear term)
+        - **DGP3**: Outcome model misspecified (contains 2(X2+0.5)² nonlinear term)
+        - **DGP4**: Doubly misspecified (both models incorrect)
+
+    seed : int, default=12345
+        Random seed (current CSV files use seed=12345).
+
+    Returns
+    -------
+    data : DataFrame
+        Simulation data (200 observations × 12 columns: T, Y, X1-X10).
+    metadata : dict
+        Metadata dictionary containing:
+
+        - ``'dgp'``: DGP type (1-4)
+        - ``'n'``: Number of observations (200)
+        - ``'k'``: Number of covariates (10)
+        - ``'true_ate'``: True ATE (1.0)
+        - ``'cov_structure'``: Covariance structure (equicorrelated MVN, ρ=0.2)
+
+    Notes
+    -----
+    Based on Fong, Hazlett, and Imai (2018) Section 4.1 simulation design.
+
+    **Column Ordering**: T (treatment), Y (outcome), X1-X10 (covariates).
+
+    **Paper Benchmarks** (500 Monte Carlo replications):
+
+    - DGP1: CBGPS balance F-statistic < 0.01 (near-perfect balance)
+    - DGP2: CBGPS F < 0.1 (robust despite treatment misspecification)
+    - DGP3: CBGPS F < 0.1 (robust despite outcome misspecification)
+    - DGP4: All methods biased (double misspecification, expected)
+
+    References
+    ----------
+    Fong, C., Hazlett, C., and Imai, K. (2018). Covariate balancing propensity
+    score for a continuous treatment: Application to the efficacy of political
+    advertisements. *The Annals of Applied Statistics*, 12(1), 156-177.
+
+    Examples
+    --------
+    >>> data, meta = load_continuous_simulation(dgp=1, seed=12345)
+    >>> data.shape
+    (200, 12)
+    >>> meta['true_ate']
+    1.0
+    >>> list(data.columns)
+    ['T', 'Y', 'X1', 'X2', 'X3', 'X4', 'X5', 'X6', 'X7', 'X8', 'X9', 'X10']
+    """
+    if dgp not in [1, 2, 3, 4]:
+        raise ValueError(f"dgp must be one of [1, 2, 3, 4], got: {dgp}")
+    
+    # Get data directory (supports both installed and development modes)
+    package_data_dir = Path(__file__).parent.parent / "data"
+    if package_data_dir.exists():
+        data_dir = package_data_dir
+    else:
+        # Fall back to project root data directory (development mode)
+        current_file = Path(__file__)
+        cbps_package = current_file.parent.parent
+        cbps_python = cbps_package.parent
+        project_root = cbps_python.parent
+        data_dir = project_root / "data"
+
+        if not data_dir.exists():
+            raise FileNotFoundError(
+                f"Cannot find data directory. Tried:\n"
+                f"  1. Package data: {package_data_dir}\n"
+                f"  2. Project data: {data_dir}\n"
+                f"Please ensure the package is properly installed with data files."
+            )
+
+    # Construct filename
+    filename = f"simulation_dgp{dgp}_seed{seed}.csv"
+    filepath = data_dir / filename
+    
+    # Read CSV file
+    df = pd.read_csv(filepath, dtype=np.float64)
+    
+    # Metadata
+    metadata = {
+        'dgp': dgp,
+        'n': 200,
+        'k': 10,
+        'true_ate': 1.0,
+        'cov_structure': 'Equicorrelated MVN with rho=0.2',
+        'sigma_xi_sq': 4.0 if dgp == 1 else 2.25,
+        'sigma_epsilon_sq': 25.0,
+        'misspecified_treatment': dgp in [2, 4],
+        'misspecified_outcome': dgp in [3, 4]
+    }
+    
+    return df, metadata
+
+
+def load_political_ads() -> Tuple[pd.DataFrame, Dict[str, Any]]:
+    """Load political advertising data (Urban and Niebler 2014).
+
+    Returns
+    -------
+    data : DataFrame
+        Political advertising data (16265 observations × 155 columns).
+    metadata : dict
+        Metadata containing:
+
+        - ``'n'``: 16265 (number of observations)
+        - ``'p'``: 155 (number of columns)
+        - ``'treatment_col'``: 'TotAds' (total advertising count)
+        - ``'boxcox_lambda'``: -0.16 (transformation parameter)
+        - ``'paper_f_stat_cbgps'``: 9.33e-5 (paper benchmark)
+
+    Notes
+    -----
+    **Treatment Variable**: TotAds (advertising count, range: 0-22,380).
+
+    The treatment requires Box-Cox transformation (λ=-0.16) for approximate
+    normality before applying continuous treatment CBPS.
+
+    **Paper Benchmarks** (Fong et al. 2018, Section 5):
+
+    - Table 1: 15 covariates with Pearson correlation < 0.001 (CBGPS)
+    - Figure 3: Full model F-statistic = 9.33e-5 (CBGPS) vs 215.3 (MLE)
+
+    References
+    ----------
+    Urban, C. and Niebler, S. (2014). Dollars on the sidewalk: Should U.S.
+    Presidential candidates advertise in uncontested states? *American Journal
+    of Political Science*, 58(2), 322-336.
+
+    Fong, C., Hazlett, C., and Imai, K. (2018). Covariate balancing propensity
+    score for a continuous treatment. *The Annals of Applied Statistics*,
+    12(1), 156-177.
+
+    Examples
+    --------
+    >>> data, meta = load_political_ads()
+    >>> data.shape
+    (16265, 155)
+    >>> 'TotAds' in data.columns
+    True
+    >>> meta['boxcox_lambda']
+    -0.16
+    """
+    # Get data directory (supports both installed and development modes)
+    package_data_dir = Path(__file__).parent.parent / "data"
+    if package_data_dir.exists():
+        data_dir = package_data_dir
+    else:
+        # Fall back to project root data directory (development mode)
+        current_file = Path(__file__)
+        cbps_package = current_file.parent.parent
+        cbps_python = cbps_package.parent
+        project_root = cbps_python.parent
+        data_dir = project_root / "data"
+
+        if not data_dir.exists():
+            raise FileNotFoundError(
+                f"Cannot find data directory. Tried:\n"
+                f"  1. Package data: {package_data_dir}\n"
+                f"  2. Project data: {data_dir}\n"
+                f"Please ensure the package is properly installed with data files."
+            )
+
+    filepath = data_dir / "political_ads_urban_niebler.csv"
+    
+    # Read CSV file
+    df = pd.read_csv(filepath, low_memory=False)
+    
+    metadata = {
+        'n': 16265,
+        'p': 155,
+        'treatment_col': 'TotAds',
+        'treatment_range': (0, 22380),
+        'boxcox_lambda': -0.16,
+        'paper_f_stat_cbgps': 9.33e-5,
+        'paper_f_stat_mle': 215.3,
+        'covariates_count': 15,
+        'squared_terms_count': 8
+    }
+    
+    return df, metadata
+
+

cbps/datasets/lalonde.py

@@ -0,0 +1,272 @@
+"""
+LaLonde Dataset Loaders
+========================
+
+This module provides functions to load the National Supported Work (NSW)
+demonstration dataset, widely used as a benchmark in propensity score and
+causal inference research.
+
+The NSW demonstration was a labor training program conducted in the mid-1970s.
+LaLonde (1986) used this dataset to evaluate econometric methods for estimating
+treatment effects from observational data by comparing results to experimental
+benchmarks.
+
+References
+----------
+LaLonde, R. J. (1986). Evaluating the econometric evaluations of training
+programs with experimental data. *American Economic Review*, 76(4), 604-620.
+
+Dehejia, R. H. and Wahba, S. (1999). Causal effects in nonexperimental
+studies: Reevaluating the evaluation of training programs. *Journal of the
+American Statistical Association*, 94(448), 1053-1062.
+"""
+
+from pathlib import Path
+from typing import Tuple, Union
+import pandas as pd
+import numpy as np
+
+
+def _get_data_dir() -> Path:
+    """
+    Get the absolute path to the data directory.
+
+    Supports two modes:
+    1. Installed mode: Load from package data directory (site-packages/cbps/data/)
+    2. Development mode: Fall back to project root data directory
+
+    Priority is given to the package data directory; if it does not exist,
+    falls back to the project root data directory.
+
+    Returns
+    -------
+    Path
+        Absolute path to the data directory.
+    """
+    # Option 1: Try package data directory (installed mode)
+    package_data_dir = Path(__file__).parent.parent / "data"
+    if package_data_dir.exists():
+        return package_data_dir
+
+    # Option 2: Fall back to project root data directory (development mode)
+    current_file = Path(__file__)
+    cbps_package = current_file.parent.parent
+    cbps_python = cbps_package.parent
+    project_root = cbps_python.parent
+    project_data_dir = project_root / "data"
+
+    if project_data_dir.exists():
+        return project_data_dir
+
+    # Raise clear error if neither exists
+    raise FileNotFoundError(
+        f"Cannot find data directory. Tried:\n"
+        f"  1. Package data: {package_data_dir}\n"
+        f"  2. Project data: {project_data_dir}\n"
+        f"Please ensure the package is properly installed with data files."
+    )
+
+
+def load_lalonde(
+    dehejia_wahba_only: bool = True,
+    return_X_y: bool = False
+) -> Union[pd.DataFrame, Tuple[pd.DataFrame, pd.Series]]:
+    """Load the LaLonde dataset (NSW job training program evaluation).
+
+    Parameters
+    ----------
+    dehejia_wahba_only : bool, default=True
+        If True, load the Dehejia-Wahba subsample (445 observations).
+        If False, load the full LaLonde dataset (3212 observations).
+    return_X_y : bool, default=False
+        If True, return (X, y) tuple; otherwise return DataFrame.
+
+    Returns
+    -------
+    DataFrame or (DataFrame, Series)
+        If return_X_y=False: Complete DataFrame with standardized column names.
+        If return_X_y=True: (covariates, treatment) tuple.
+
+    Notes
+    -----
+    The dataset contains data from the National Supported Work (NSW)
+    demonstration, a labor training program conducted in the mid-1970s.
+
+    **Variables**
+
+    - ``treat``: Treatment indicator (1=received training, 0=control)
+    - ``age``: Age in years
+    - ``educ``: Years of education
+    - ``black``: African American indicator
+    - ``hisp``: Hispanic indicator
+    - ``married``: Marital status indicator
+    - ``nodegr``: No high school degree indicator
+    - ``re74``, ``re75``: Real earnings in 1974, 1975 (pre-treatment)
+    - ``re78``: Real earnings in 1978 (outcome)
+
+    **Data Dimensions**
+
+    - Dehejia-Wahba subsample: 445 observations, 11 columns
+    - Full dataset: 3212 observations, 12 columns
+
+    References
+    ----------
+    LaLonde, R. J. (1986). Evaluating the econometric evaluations of training
+    programs with experimental data. *American Economic Review*, 76(4), 604-620.
+
+    Dehejia, R. H. and Wahba, S. (1999). Causal effects in nonexperimental
+    studies: Reevaluating the evaluation of training programs. *Journal of the
+    American Statistical Association*, 94(448), 1053-1062.
+
+    Examples
+    --------
+    >>> df = load_lalonde(dehejia_wahba_only=True)
+    >>> df.shape
+    (445, 11)
+    >>> 'educ' in df.columns
+    True
+    """
+    data_dir = _get_data_dir()
+    
+    if dehejia_wahba_only:
+        # Load Dehejia-Wahba subsample
+        filepath = data_dir / "nsw_dw.csv"
+        df = pd.read_csv(filepath)
+        
+        # Standardize column names
+        column_mapping = {
+            'education': 'educ',
+            'hispanic': 'hisp', 
+            'nodegree': 'nodegr'
+        }
+        df = df.rename(columns=column_mapping)
+        
+        # Set appropriate dtypes
+        df = df.astype({
+            'treat': np.int64, 'age': np.int64, 'educ': np.int64,
+            'black': np.int64, 'hisp': np.int64, 'married': np.int64,
+            'nodegr': np.int64, 're74': np.float64, 're75': np.float64,
+            're78': np.float64
+        })
+    else:
+        # Load full LaLonde dataset
+        filepath = data_dir / "LaLonde.csv"
+        df = pd.read_csv(filepath)
+        # Column names already standardized in this file
+    
+    if return_X_y:
+        y = df['treat']
+        X = df.drop('treat', axis=1)
+        return X, y
+    else:
+        return df
+
+
+def load_lalonde_psid_combined(
+    psid_version: str = 'main',
+    return_combined: bool = True
+) -> Union[Tuple[pd.DataFrame, pd.DataFrame], pd.DataFrame]:
+    """Load NSW experimental and PSID control group data for evaluation bias tests.
+
+    Parameters
+    ----------
+    psid_version : {'main', 'controls2', 'controls3'}, default='main'
+        PSID control group version:
+
+        - ``'main'``: Full PSID controls (2490 observations)
+        - ``'controls2'``: Restricted PSID controls (253 observations)
+        - ``'controls3'``: Further restricted PSID controls (128 observations)
+
+    return_combined : bool, default=True
+        If True (default), return combined DataFrame.
+        If False, return (nsw_exp, psid_ctrl) tuple.
+
+    Returns
+    -------
+    combined : DataFrame (default)
+        Combined DataFrame with standardized column names.
+
+        - main version: (3212, 11)
+        - controls2 version: (975, 11)
+        - controls3 version: (850, 11)
+
+    (nsw_exp, psid_ctrl) : tuple of DataFrame (when return_combined=False)
+        Tuple of NSW experimental sample and PSID control sample.
+
+        - nsw_exp: (722, 10) - NSW experimental sample (missing re74)
+        - psid_ctrl: (2490, 11) or (253, 11) or (128, 11) - PSID controls
+
+    Notes
+    -----
+    Used for reproducing evaluation bias tests from Smith and Todd (2005) and
+    the original CBPS paper. The NSW sample contains experimental participants,
+    while the PSID samples serve as observational comparison groups.
+
+    **Data Dimensions**
+
+    - main: nsw=(722, 10), psid=(2490, 11), combined=(3212, 11)
+    - controls2: nsw=(722, 10), psid=(253, 11), combined=(975, 11)
+    - controls3: nsw=(722, 10), psid=(128, 11), combined=(850, 11)
+
+    References
+    ----------
+    Smith, J. A. and Todd, P. E. (2005). Does matching overcome LaLonde's
+    critique of nonexperimental estimators? *Journal of Econometrics*,
+    125(1-2), 305-353.
+
+    Examples
+    --------
+    >>> df = load_lalonde_psid_combined()
+    >>> df.shape
+    (3212, 11)
+    >>> int((df['treat'] == 0).sum()), int((df['treat'] == 1).sum())
+    (2915, 297)
+    >>> 'educ' in df.columns
+    True
+
+    >>> # Return separate DataFrames
+    >>> nsw_exp, psid_ctrl = load_lalonde_psid_combined(return_combined=False)
+    >>> nsw_exp.shape, psid_ctrl.shape
+    ((722, 10), (2490, 11))
+    """
+    data_dir = _get_data_dir()
+    
+    # Load NSW experimental sample (722 observations, 10 columns - missing re74)
+    nsw = pd.read_csv(data_dir / "nsw.csv")
+    
+    # Standardize column names to match package convention
+    column_mapping = {
+        'education': 'educ',
+        'hispanic': 'hisp',
+        'nodegree': 'nodegr'
+    }
+    nsw = nsw.rename(columns=column_mapping)
+
+    # Load corresponding PSID control group
+    psid_files = {
+        'main': 'psid_controls.csv',
+        'controls2': 'psid_controls2.csv',
+        'controls3': 'psid_controls3.csv'
+    }
+    
+    if psid_version not in psid_files:
+        raise ValueError(
+            f"psid_version must be one of {list(psid_files.keys())}, "
+            f"got: {psid_version}"
+        )
+    
+    psid = pd.read_csv(data_dir / psid_files[psid_version])
+    # Standardize column names for PSID control sample
+    psid = psid.rename(columns=column_mapping)
+
+    if return_combined:
+        # Return combined DataFrame with consistent column ordering
+        # NSW sample is missing re74, which will be filled with NaN
+        nsw_with_re74 = nsw.copy()
+        if 're74' not in nsw_with_re74.columns:
+            nsw_with_re74['re74'] = np.nan
+        combined = pd.concat([nsw_with_re74, psid], ignore_index=True)
+        return combined
+    else:
+        # Return separate DataFrames: (nsw_exp, psid_ctrl)
+        return nsw, psid

cbps/datasets/npcbps_sim.py

@@ -0,0 +1,101 @@
+"""
+npCBPS Simulation Data Loaders
+===============================
+
+This module provides functions to load continuous treatment simulation data
+for validating nonparametric CBPS (npCBPS) implementations.
+
+The npCBPS methodology estimates stabilizing inverse propensity score weights
+using empirical likelihood without requiring a parametric model for the
+generalized propensity score, as described in Fong, Hazlett, and Imai (2018).
+
+References
+----------
+Fong, C., Hazlett, C., and Imai, K. (2018). Covariate balancing propensity
+score for a continuous treatment: Application to the efficacy of political
+advertisements. *The Annals of Applied Statistics*, 12(1), 156-177.
+"""
+
+from pathlib import Path
+import pandas as pd
+
+
+def load_npcbps_continuous_sim() -> pd.DataFrame:
+    """Load npCBPS continuous treatment simulation data.
+
+    Returns
+    -------
+    pd.DataFrame
+        Simulation data (500 rows × 7 columns).
+
+    Notes
+    -----
+    **Variables**
+
+    - ``Y``: Outcome variable (continuous)
+    - ``T``: Treatment variable (continuous)
+    - ``X1``-``X5``: Covariates (multivariate normal, correlation=0.5)
+
+    **Data Characteristics**
+
+    - Observations: 500
+    - Covariate structure: Multivariate normal with pairwise correlation 0.5
+
+    Raises
+    ------
+    FileNotFoundError
+        If simulation data file does not exist.
+
+    Examples
+    --------
+    >>> from cbps.datasets import load_npcbps_continuous_sim
+    >>> df = load_npcbps_continuous_sim()
+    >>> df.shape
+    (500, 7)
+    >>> list(df.columns)
+    ['Y', 'T', 'X1', 'X2', 'X3', 'X4', 'X5']
+    """
+    # Get data directory (supports both installed and development modes)
+    package_data_dir = Path(__file__).parent.parent / "data"
+    if package_data_dir.exists():
+        data_dir = package_data_dir
+    else:
+        # Fall back to project root data directory (development mode)
+        data_dir = Path(__file__).parent.parent.parent.parent / "data"
+
+        if not data_dir.exists():
+            raise FileNotFoundError(
+                f"Cannot find data directory. Tried:\n"
+                f"  1. Package data: {package_data_dir}\n"
+                f"  2. Project data: {data_dir}\n"
+                f"Please ensure the package is properly installed with data files."
+            )
+
+    filepath = data_dir / "npcbps_continuous_sim.csv"
+
+    if not filepath.exists():
+        raise FileNotFoundError(
+            f"Simulation data not found: {filepath}\n"
+            "Please ensure the package is properly installed with data files."
+        )
+    
+    df = pd.read_csv(filepath)
+    
+    # Validate data dimensions
+    expected_shape = (500, 7)
+    if df.shape != expected_shape:
+        raise ValueError(
+            f"Unexpected data shape: {df.shape}\n"
+            f"Expected: {expected_shape}"
+        )
+    
+    # Validate column names
+    expected_columns = ['Y', 'T', 'X1', 'X2', 'X3', 'X4', 'X5']
+    if list(df.columns) != expected_columns:
+        raise ValueError(
+            f"Unexpected columns: {list(df.columns)}\n"
+            f"Expected: {expected_columns}"
+        )
+    
+    return df
+

cbps/diagnostics/__init__.py

@@ -0,0 +1,101 @@
+"""
+Diagnostics and Visualization Module
+=====================================
+
+This module provides tools for assessing covariate balance before and after
+propensity score weighting, a critical step in evaluating causal inference
+methodology.
+
+Balance Assessment
+------------------
+For binary and multi-valued treatments, balance is measured via **standardized
+mean differences (SMD)**. Following Austin (2009) and Stuart (2010), an SMD
+below 0.1 indicates acceptable balance.
+
+For continuous treatments, balance is assessed via **weighted Pearson
+correlations** between covariates and the treatment variable. An absolute
+correlation near zero indicates that the treatment is conditionally independent
+of covariates given the weights.
+
+Functions
+---------
+balance_cbps
+    Compute standardized mean differences for binary/multi-valued treatments.
+
+balance_cbps_continuous
+    Compute weighted correlations for continuous treatments.
+
+plot_cbps
+    Visualize SMD before and after weighting (requires matplotlib).
+
+plot_cbps_continuous
+    Visualize correlation reduction for continuous treatments.
+
+References
+----------
+Imai, K. and Ratkovic, M. (2014). Covariate balancing propensity score.
+Journal of the Royal Statistical Society, Series B, 76(1), 243-263.
+
+Fong, C., Hazlett, C., and Imai, K. (2018). Covariate balancing propensity
+score for a continuous treatment. The Annals of Applied Statistics, 12(1),
+156-177.
+
+Austin, P.C. (2009). Balance diagnostics for comparing the distribution of
+baseline covariates between treatment groups in propensity-score matched
+samples. Statistics in Medicine, 28(25), 3083-3107.
+
+Stuart, E.A. (2010). Matching methods for causal inference: A review and a
+look forward. Statistical Science, 25(1), 1-21.
+"""
+
+from .balance import balance_cbps, balance_cbps_continuous, omnibus_balance_test
+from .continuous_diagnostics import (
+    diagnose_cbgps_quality,
+    print_balance_diagnosis,
+    compute_f_statistic as compute_f_statistic_continuous,
+    compute_weighted_correlations
+)
+from .weights_diag import weight_diagnostics
+from .overlap import check_overlap
+from .normality import test_treatment_normality
+from .ocbps_conditions import verify_ocbps_conditions
+
+# plots module is imported as optional dependency
+try:
+    from .plots import (
+        plot_cbps, plot_cbps_continuous,
+        love_plot, plot_weight_distribution, plot_ps_overlap,
+    )
+    __all__ = [
+        'balance_cbps',
+        'balance_cbps_continuous',
+        'omnibus_balance_test',
+        'plot_cbps',
+        'plot_cbps_continuous',
+        'love_plot',
+        'plot_weight_distribution',
+        'plot_ps_overlap',
+        'diagnose_cbgps_quality',
+        'print_balance_diagnosis',
+        'compute_f_statistic_continuous',
+        'compute_weighted_correlations',
+        'weight_diagnostics',
+        'check_overlap',
+        'test_treatment_normality',
+        'verify_ocbps_conditions',
+    ]
+except ImportError:
+    # When matplotlib is not installed, only export balance functions
+    __all__ = [
+        'balance_cbps', 
+        'balance_cbps_continuous',
+        'omnibus_balance_test',
+        'diagnose_cbgps_quality',
+        'print_balance_diagnosis',
+        'compute_f_statistic_continuous',
+        'compute_weighted_correlations',
+        'weight_diagnostics',
+        'check_overlap',
+        'test_treatment_normality',
+        'verify_ocbps_conditions',
+    ]