diff-diff 3.0.1__cp314-cp314-macosx_11_0_arm64.whl

diff_diff/__init__.py

@@ -0,0 +1,382 @@
+"""
+diff-diff: A library for Difference-in-Differences analysis.
+
+This library provides sklearn-like estimators for causal inference
+using the difference-in-differences methodology.
+
+For rigorous analysis, follow the 8-step practitioner workflow in
+docs/llms-practitioner.txt (based on Baker et al. 2025). After
+estimation, call ``practitioner_next_steps(results)`` for context-aware
+guidance on remaining diagnostic steps.
+
+AI agent reference: docs/llms.txt
+"""
+
+# Import backend detection from dedicated module (avoids circular imports)
+from diff_diff._backend import (
+    HAS_RUST_BACKEND,
+    _rust_bootstrap_weights,
+    _rust_compute_robust_vcov,
+    _rust_project_simplex,
+    _rust_solve_ols,
+    _rust_synthetic_weights,
+)
+
+from diff_diff.bacon import (
+    BaconDecomposition,
+    BaconDecompositionResults,
+    Comparison2x2,
+    bacon_decompose,
+)
+from diff_diff.diagnostics import (
+    PlaceboTestResults,
+    leave_one_out_test,
+    permutation_test,
+    placebo_group_test,
+    placebo_timing_test,
+    run_all_placebo_tests,
+    run_placebo_test,
+)
+from diff_diff.linalg import (
+    InferenceResult,
+    LinearRegression,
+)
+from diff_diff.estimators import (
+    DifferenceInDifferences,
+    MultiPeriodDiD,
+    SyntheticDiD,
+    TwoWayFixedEffects,
+)
+from diff_diff.honest_did import (
+    DeltaRM,
+    DeltaSD,
+    DeltaSDRM,
+    HonestDiD,
+    HonestDiDResults,
+    SensitivityResults,
+    compute_honest_did,
+    sensitivity_plot,
+)
+from diff_diff.power import (
+    PowerAnalysis,
+    PowerResults,
+    SimulationMDEResults,
+    SimulationPowerResults,
+    SimulationSampleSizeResults,
+    compute_mde,
+    compute_power,
+    compute_sample_size,
+    simulate_mde,
+    simulate_power,
+    simulate_sample_size,
+)
+from diff_diff.pretrends import (
+    PreTrendsPower,
+    PreTrendsPowerCurve,
+    PreTrendsPowerResults,
+    compute_mdv,
+    compute_pretrends_power,
+)
+from diff_diff.prep import (
+    aggregate_survey,
+    aggregate_to_cohorts,
+    balance_panel,
+    create_event_time,
+    generate_continuous_did_data,
+    generate_did_data,
+    generate_ddd_data,
+    generate_event_study_data,
+    generate_factor_data,
+    generate_panel_data,
+    generate_staggered_data,
+    generate_staggered_ddd_data,
+    generate_survey_did_data,
+    make_post_indicator,
+    make_treatment_indicator,
+    rank_control_units,
+    summarize_did_data,
+    trim_weights,
+    validate_did_data,
+    wide_to_long,
+)
+from diff_diff.results import (
+    DiDResults,
+    MultiPeriodDiDResults,
+    PeriodEffect,
+    SyntheticDiDResults,
+)
+from diff_diff.survey import (
+    DEFFDiagnostics,
+    SurveyDesign,
+    SurveyMetadata,
+    compute_deff_diagnostics,
+)
+from diff_diff.staggered import (
+    CallawaySantAnna,
+    CallawaySantAnnaResults,
+    CSBootstrapResults,
+    GroupTimeEffect,
+)
+from diff_diff.imputation import (
+    ImputationBootstrapResults,
+    ImputationDiD,
+    ImputationDiDResults,
+    imputation_did,
+)
+from diff_diff.two_stage import (
+    TwoStageBootstrapResults,
+    TwoStageDiD,
+    TwoStageDiDResults,
+    two_stage_did,
+)
+from diff_diff.stacked_did import (
+    StackedDiD,
+    StackedDiDResults,
+    stacked_did,
+)
+from diff_diff.sun_abraham import (
+    SABootstrapResults,
+    SunAbraham,
+    SunAbrahamResults,
+)
+from diff_diff.triple_diff import (
+    TripleDifference,
+    TripleDifferenceResults,
+    triple_difference,
+)
+from diff_diff.staggered_triple_diff import (
+    StaggeredTripleDifference,
+)
+from diff_diff.staggered_triple_diff_results import (
+    StaggeredTripleDiffResults,
+)
+from diff_diff.continuous_did import (
+    ContinuousDiD,
+    ContinuousDiDResults,
+    DoseResponseCurve,
+)
+from diff_diff.efficient_did import (
+    EfficientDiD,
+    EfficientDiDResults,
+    EDiDBootstrapResults,
+)
+from diff_diff.trop import (
+    TROP,
+    TROPResults,
+    trop,
+)
+from diff_diff.wooldridge import WooldridgeDiD
+from diff_diff.wooldridge_results import WooldridgeDiDResults
+from diff_diff.utils import (
+    WildBootstrapResults,
+    check_parallel_trends,
+    check_parallel_trends_robust,
+    equivalence_test_trends,
+    wild_bootstrap_se,
+)
+from diff_diff.visualization import (
+    plot_bacon,
+    plot_dose_response,
+    plot_event_study,
+    plot_group_effects,
+    plot_group_time_heatmap,
+    plot_honest_event_study,
+    plot_power_curve,
+    plot_pretrends_power,
+    plot_sensitivity,
+    plot_staircase,
+    plot_synth_weights,
+)
+from diff_diff.practitioner import practitioner_next_steps
+from diff_diff.datasets import (
+    clear_cache,
+    list_datasets,
+    load_card_krueger,
+    load_castle_doctrine,
+    load_dataset,
+    load_divorce_laws,
+    load_mpdta,
+)
+
+# Estimator aliases — short names for convenience
+DiD = DifferenceInDifferences
+TWFE = TwoWayFixedEffects
+EventStudy = MultiPeriodDiD
+SDiD = SyntheticDiD
+CS = CallawaySantAnna
+CDiD = ContinuousDiD
+SA = SunAbraham
+BJS = ImputationDiD
+Gardner = TwoStageDiD
+DDD = TripleDifference
+SDDD = StaggeredTripleDifference
+Stacked = StackedDiD
+Bacon = BaconDecomposition
+EDiD = EfficientDiD
+ETWFE = WooldridgeDiD
+
+__version__ = "3.0.1"
+__all__ = [
+    # Estimators
+    "DifferenceInDifferences",
+    "TwoWayFixedEffects",
+    "MultiPeriodDiD",
+    "SyntheticDiD",
+    "CallawaySantAnna",
+    "ContinuousDiD",
+    "SunAbraham",
+    "ImputationDiD",
+    "TwoStageDiD",
+    "TripleDifference",
+    "TROP",
+    "StackedDiD",
+    # Estimator aliases (short names)
+    "DiD",
+    "TWFE",
+    "EventStudy",
+    "SDiD",
+    "CS",
+    "CDiD",
+    "SA",
+    "BJS",
+    "Gardner",
+    "DDD",
+    "SDDD",
+    "Stacked",
+    "Bacon",
+    # Bacon Decomposition
+    "BaconDecomposition",
+    "BaconDecompositionResults",
+    "Comparison2x2",
+    "bacon_decompose",
+    # Results
+    "DiDResults",
+    "MultiPeriodDiDResults",
+    "SyntheticDiDResults",
+    "PeriodEffect",
+    "CallawaySantAnnaResults",
+    "CSBootstrapResults",
+    "GroupTimeEffect",
+    "ContinuousDiDResults",
+    "DoseResponseCurve",
+    "SunAbrahamResults",
+    "SABootstrapResults",
+    "ImputationDiDResults",
+    "ImputationBootstrapResults",
+    "imputation_did",
+    "TwoStageDiDResults",
+    "TwoStageBootstrapResults",
+    "two_stage_did",
+    "TripleDifferenceResults",
+    "triple_difference",
+    "StaggeredTripleDifference",
+    "StaggeredTripleDiffResults",
+    "TROPResults",
+    "trop",
+    "StackedDiDResults",
+    "stacked_did",
+    # EfficientDiD
+    "EfficientDiD",
+    "EfficientDiDResults",
+    "EDiDBootstrapResults",
+    "EDiD",
+    # WooldridgeDiD (ETWFE)
+    "WooldridgeDiD",
+    "WooldridgeDiDResults",
+    "ETWFE",
+    # Visualization
+    "plot_bacon",
+    "plot_event_study",
+    "plot_group_effects",
+    "plot_sensitivity",
+    "plot_honest_event_study",
+    "plot_power_curve",
+    "plot_pretrends_power",
+    "plot_synth_weights",
+    "plot_staircase",
+    "plot_dose_response",
+    "plot_group_time_heatmap",
+    # Parallel trends testing
+    "check_parallel_trends",
+    "check_parallel_trends_robust",
+    "equivalence_test_trends",
+    # Wild cluster bootstrap
+    "WildBootstrapResults",
+    "wild_bootstrap_se",
+    # Placebo tests / diagnostics
+    "PlaceboTestResults",
+    "run_placebo_test",
+    "placebo_timing_test",
+    "placebo_group_test",
+    "permutation_test",
+    "leave_one_out_test",
+    "run_all_placebo_tests",
+    # Data preparation utilities
+    "make_treatment_indicator",
+    "make_post_indicator",
+    "wide_to_long",
+    "balance_panel",
+    "trim_weights",
+    "validate_did_data",
+    "summarize_did_data",
+    "generate_did_data",
+    "generate_staggered_data",
+    "generate_factor_data",
+    "generate_ddd_data",
+    "generate_panel_data",
+    "generate_event_study_data",
+    "generate_staggered_ddd_data",
+    "generate_survey_did_data",
+    "generate_continuous_did_data",
+    "create_event_time",
+    "aggregate_survey",
+    "aggregate_to_cohorts",
+    "rank_control_units",
+    # Honest DiD sensitivity analysis
+    "HonestDiD",
+    "HonestDiDResults",
+    "SensitivityResults",
+    "DeltaSD",
+    "DeltaRM",
+    "DeltaSDRM",
+    "compute_honest_did",
+    "sensitivity_plot",
+    # Power analysis
+    "PowerAnalysis",
+    "PowerResults",
+    "SimulationMDEResults",
+    "SimulationPowerResults",
+    "SimulationSampleSizeResults",
+    "compute_mde",
+    "compute_power",
+    "compute_sample_size",
+    "simulate_mde",
+    "simulate_power",
+    "simulate_sample_size",
+    # Pre-trends power analysis
+    "PreTrendsPower",
+    "PreTrendsPowerResults",
+    "PreTrendsPowerCurve",
+    "compute_pretrends_power",
+    "compute_mdv",
+    # Survey support
+    "SurveyDesign",
+    "SurveyMetadata",
+    "DEFFDiagnostics",
+    "compute_deff_diagnostics",
+    # Rust backend
+    "HAS_RUST_BACKEND",
+    # Linear algebra helpers
+    "LinearRegression",
+    "InferenceResult",
+    # Datasets
+    "load_card_krueger",
+    "load_castle_doctrine",
+    "load_divorce_laws",
+    "load_mpdta",
+    "load_dataset",
+    "list_datasets",
+    "clear_cache",
+    # Practitioner guidance
+    "practitioner_next_steps",
+]

diff_diff/_backend.py

@@ -0,0 +1,134 @@
+"""
+Backend detection and configuration for diff-diff.
+
+This module handles:
+1. Detection of optional Rust backend
+2. Environment variable configuration (DIFF_DIFF_BACKEND)
+3. Exports HAS_RUST_BACKEND and Rust function references
+
+Other modules should import from here to avoid circular imports with __init__.py.
+"""
+
+import os
+
+# Check for backend override via environment variable
+# DIFF_DIFF_BACKEND can be: 'auto' (default), 'python', or 'rust'
+_backend_env = os.environ.get("DIFF_DIFF_BACKEND", "auto").lower()
+
+# Try to import Rust backend for accelerated operations
+try:
+    from diff_diff._rust_backend import (
+        generate_bootstrap_weights_batch as _rust_bootstrap_weights,
+        compute_synthetic_weights as _rust_synthetic_weights,
+        project_simplex as _rust_project_simplex,
+        solve_ols as _rust_solve_ols,
+        compute_robust_vcov as _rust_compute_robust_vcov,
+        # TROP estimator acceleration (local method)
+        compute_unit_distance_matrix as _rust_unit_distance_matrix,
+        loocv_grid_search as _rust_loocv_grid_search,
+        bootstrap_trop_variance as _rust_bootstrap_trop_variance,
+        # TROP estimator acceleration (global method)
+        loocv_grid_search_global as _rust_loocv_grid_search_global,
+        bootstrap_trop_variance_global as _rust_bootstrap_trop_variance_global,
+        # SDID weights (Frank-Wolfe matching R's synthdid)
+        compute_sdid_unit_weights as _rust_sdid_unit_weights,
+        compute_time_weights as _rust_compute_time_weights,
+        compute_noise_level as _rust_compute_noise_level,
+        sc_weight_fw as _rust_sc_weight_fw,
+        # Diagnostics
+        rust_backend_info as _rust_backend_info,
+    )
+
+    _rust_available = True
+except ImportError:
+    _rust_available = False
+    _rust_bootstrap_weights = None
+    _rust_synthetic_weights = None
+    _rust_project_simplex = None
+    _rust_solve_ols = None
+    _rust_compute_robust_vcov = None
+    # TROP estimator acceleration (local method)
+    _rust_unit_distance_matrix = None
+    _rust_loocv_grid_search = None
+    _rust_bootstrap_trop_variance = None
+    # TROP estimator acceleration (global method)
+    _rust_loocv_grid_search_global = None
+    _rust_bootstrap_trop_variance_global = None
+    # SDID weights (Frank-Wolfe matching R's synthdid)
+    _rust_sdid_unit_weights = None
+    _rust_compute_time_weights = None
+    _rust_compute_noise_level = None
+    _rust_sc_weight_fw = None
+    _rust_backend_info = None
+
+# Determine final backend based on environment variable and availability
+if _backend_env == "python":
+    # Force pure Python mode - disable Rust even if available
+    HAS_RUST_BACKEND = False
+    _rust_bootstrap_weights = None
+    _rust_synthetic_weights = None
+    _rust_project_simplex = None
+    _rust_solve_ols = None
+    _rust_compute_robust_vcov = None
+    # TROP estimator acceleration (local method)
+    _rust_unit_distance_matrix = None
+    _rust_loocv_grid_search = None
+    _rust_bootstrap_trop_variance = None
+    # TROP estimator acceleration (global method)
+    _rust_loocv_grid_search_global = None
+    _rust_bootstrap_trop_variance_global = None
+    # SDID weights (Frank-Wolfe matching R's synthdid)
+    _rust_sdid_unit_weights = None
+    _rust_compute_time_weights = None
+    _rust_compute_noise_level = None
+    _rust_sc_weight_fw = None
+    _rust_backend_info = None
+elif _backend_env == "rust":
+    # Force Rust mode - fail if not available
+    if not _rust_available:
+        raise ImportError(
+            "DIFF_DIFF_BACKEND=rust but Rust backend is not available. "
+            "Install with: pip install diff-diff[rust]"
+        )
+    HAS_RUST_BACKEND = True
+else:
+    # Auto mode - use Rust if available
+    HAS_RUST_BACKEND = _rust_available
+
+
+def rust_backend_info():
+    """Return compile-time BLAS feature information for the Rust backend.
+
+    Returns a dict with keys:
+    - 'blas': True if any BLAS backend is linked
+    - 'accelerate': True if Apple Accelerate is linked (macOS)
+    - 'openblas': True if OpenBLAS is linked (Linux)
+
+    If the Rust backend is not available, all values are False.
+    """
+    if _rust_backend_info is not None:
+        return _rust_backend_info()
+    return {"blas": False, "accelerate": False, "openblas": False}
+
+
+__all__ = [
+    "HAS_RUST_BACKEND",
+    "rust_backend_info",
+    "_rust_bootstrap_weights",
+    "_rust_synthetic_weights",
+    "_rust_project_simplex",
+    "_rust_solve_ols",
+    "_rust_compute_robust_vcov",
+    # TROP estimator acceleration (local method)
+    "_rust_unit_distance_matrix",
+    "_rust_loocv_grid_search",
+    "_rust_bootstrap_trop_variance",
+    # TROP estimator acceleration (global method)
+    "_rust_loocv_grid_search_global",
+    "_rust_bootstrap_trop_variance_global",
+    # SDID weights (Frank-Wolfe matching R's synthdid)
+    "_rust_sdid_unit_weights",
+    "_rust_compute_time_weights",
+    "_rust_compute_noise_level",
+    "_rust_sc_weight_fw",
+]