cbps 0.2.0__tar.gz

cbps-0.2.0/CHANGELOG.md

@@ -0,0 +1,97 @@
+# Changelog
+
+All notable changes to the CBPS Python package will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Changed
+- Minimum Python version raised to 3.10 (Python 3.9 reached end-of-life October 2025)
+- Added Python 3.13 support
+- `[all]` extra no longer includes `dev` and `docs` dependencies (user-facing only)
+- Replaced invalid PyPI classifier `Topic :: Scientific/Engineering :: Statistics` with `Topic :: Scientific/Engineering :: Information Analysis`
+- Removed unused `setuptools_scm` from build dependencies
+- Separated `[test]` optional dependencies from `[dev]` for cleaner CI installs
+
+### Added
+- Documentation build check in CI pipeline
+- mypy hook in pre-commit configuration
+- `numpydoc` added to docs dependencies for NumPy-style docstring support
+- `pre-commit` added to dev dependencies
+- Package build verification step in CI workflow
+- Bandit security scanning in pre-commit hooks
+- McCabe complexity checking in flake8 configuration (max-complexity=15)
+- CodeQL security scanning workflow for automated vulnerability detection
+- `Framework :: Pytest` PyPI classifier
+- `sphinx-copybutton` extension for documentation code blocks
+- `numpydoc` and `sphinx.ext.todo` Sphinx extensions for improved documentation rendering
+- Version tag validation step in publish workflow
+- `timeout-minutes` for all CI jobs to prevent hanging builds
+- LaTeX packages in ReadTheDocs configuration for reliable PDF builds
+- `statistics` and `count` options in flake8 configuration for summary output
+
+### Fixed
+- Codecov action token configuration updated to recommended `with: token:` syntax
+- Removed E501 from flake8 extend-ignore to properly enforce line length via black
+- Fixed truncated `[tool.black]` include regex pattern in pyproject.toml
+- Set `nbsphinx_allow_errors = False` in Sphinx configuration for production quality
+- Removed redundant `Download` URL from pyproject.toml project URLs
+- Updated copyright year range in documentation configuration
+
+## [0.1.0] - 2025-12-04
+
+### Added
+
+#### Core Estimation Algorithms
+- **CBPS** — Main function for binary/multi-valued/continuous treatments
+  - Binary treatments (0/1): ATT and ATE estimation with GMM and over-identified GMM
+  - Multi-valued treatments (3–4 levels): Multinomial logit propensity scores
+  - Continuous treatments: Generalized propensity score (GPS)
+  - Automatic treatment type detection for integer arrays (≤4 unique values)
+  - Formula interface with automatic intercept handling
+  - SVD preprocessing for numerical stability
+  - Over-identified GMM with J-statistic
+- **Optimal CBPS (oCBPS)** — Doubly-robust estimation (Fan et al. 2022)
+- **CBMSM** — Marginal structural models for longitudinal data
+- **npCBPS** — Nonparametric CBPS using empirical likelihood
+- **hdCBPS** — High-dimensional CBPS with LASSO variable selection
+- **CBIV** — CBPS for instrumental variables
+
+#### Inference Methods
+- **AsyVar** — Sandwich variance estimator for CBPS coefficients
+- **vcov_outcome** — Robust variance estimation for weighted outcome regression
+
+#### Diagnostic and Visualization Tools
+- **balance** — Covariate balance assessment (SMD for discrete, correlation for continuous)
+- **summary** — Statistical summary with coefficient table and J-statistic
+- **plot** — Balance plots, weight distribution plots for binary and continuous treatments
+
+#### Data and Examples
+- LaLonde NSW dataset, Blackwell dataset, continuous treatment simulation data
+- 13 Python example scripts, 4 Jupyter notebook tutorials
+
+#### scikit-learn Integration
+- **CBPSEstimator** — sklearn-compatible wrapper with `fit()`, `predict_proba()`, `predict()`, `get_weights()`
+
+#### Development Infrastructure
+- Testing framework with pytest (400+ tests, >80% coverage)
+- Code quality tools: black, isort, flake8, mypy
+- CI/CD: GitHub Actions with multi-OS, multi-Python testing
+- Documentation: Sphinx + ReadTheDocs with PDF/ePub output
+
+### Numerical Accuracy
+- Core algorithms validated to ±1e-6 precision against R CBPS package v0.23
+- Benchmark tests using LaLonde and Blackwell datasets
+
+### References
+
+1. Imai, K., & Ratkovic, M. (2014). Covariate balancing propensity score. *JRSS-B*, 76(1), 243–263.
+2. Fan, J., et al. (2022). Optimal covariate balancing conditions in propensity score estimation. *JBES*, 41(1), 97–110.
+3. Imai, K., & Ratkovic, M. (2015). Robust estimation of inverse probability weights for marginal structural models. *JASA*, 110(511), 1013–1023.
+4. Fong, C., Hazlett, C., & Imai, K. (2018). Covariate balancing propensity score for a continuous treatment. *AOAS*, 12(1), 156–177.
+5. Ning, Y., Peng, S., & Imai, K. (2020). Robust estimation of causal effects via a high-dimensional covariate balancing propensity score. *Biometrika*, 107(3), 533–554.
+
+[Unreleased]: https://github.com/gorgeousfish/CBPS-py/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/gorgeousfish/CBPS-py/releases/tag/v0.1.0

cbps-0.2.0/CITATION.cff

@@ -0,0 +1,111 @@
+cff-version: 1.2.0
+title: "cbps: Covariate Balancing Propensity Score for Python"
+message: >-
+  If you use this software, please cite it using the metadata from this file,
+  as well as the relevant methodology paper(s) listed below.
+type: software
+authors:
+  - given-names: Xuanyu
+    family-names: Cai
+    email: xuanyuCAI@outlook.com
+    affiliation: City University of Macau
+  - given-names: Wenli
+    family-names: Xu
+    email: wlxu@cityu.edu.mo
+    affiliation: City University of Macau
+repository-code: "https://github.com/gorgeousfish/CBPS-py"
+url: "https://cbps.readthedocs.io"
+license: AGPL-3.0
+version: 0.1.0
+date-released: "2026-02-16"
+keywords:
+  - causal-inference
+  - propensity-score
+  - covariate-balancing
+  - treatment-effects
+  - observational-studies
+  - inverse-probability-weighting
+  - generalized-method-of-moments
+references:
+  - type: article
+    title: "Covariate balancing propensity score"
+    authors:
+      - given-names: Kosuke
+        family-names: Imai
+      - given-names: Marc
+        family-names: Ratkovic
+    journal: "Journal of the Royal Statistical Society: Series B (Statistical Methodology)"
+    year: 2014
+    volume: 76
+    issue: 1
+    start: 243
+    end: 263
+    doi: "10.1111/rssb.12027"
+  - type: article
+    title: "Robust estimation of inverse probability weights for marginal structural models"
+    authors:
+      - given-names: Kosuke
+        family-names: Imai
+      - given-names: Marc
+        family-names: Ratkovic
+    journal: "Journal of the American Statistical Association"
+    year: 2015
+    volume: 110
+    issue: 511
+    start: 1013
+    end: 1023
+    doi: "10.1080/01621459.2014.956872"
+  - type: article
+    title: "Covariate balancing propensity score for a continuous treatment: Application to the efficacy of political advertisements"
+    authors:
+      - given-names: Christian
+        family-names: Fong
+      - given-names: Chad
+        family-names: Hazlett
+      - given-names: Kosuke
+        family-names: Imai
+    journal: "The Annals of Applied Statistics"
+    year: 2018
+    volume: 12
+    issue: 1
+    start: 156
+    end: 177
+    doi: "10.1214/17-AOAS1101"
+  - type: article
+    title: "Robust estimation of causal effects via a high-dimensional covariate balancing propensity score"
+    authors:
+      - given-names: Yang
+        family-names: Ning
+      - given-names: Sida
+        family-names: Peng
+      - given-names: Kosuke
+        family-names: Imai
+    journal: "Biometrika"
+    year: 2020
+    volume: 107
+    issue: 3
+    start: 533
+    end: 554
+    doi: "10.1093/biomet/asaa020"
+  - type: article
+    title: "Optimal covariate balancing conditions in propensity score estimation"
+    authors:
+      - given-names: Jianqing
+        family-names: Fan
+      - given-names: Kosuke
+        family-names: Imai
+      - given-names: Inbeom
+        family-names: Lee
+      - given-names: Han
+        family-names: Liu
+      - given-names: Yang
+        family-names: Ning
+      - given-names: Xiaolin
+        family-names: Yang
+    journal: "Journal of Business & Economic Statistics"
+    year: 2022
+    volume: 41
+    issue: 1
+    start: 97
+    end: 110
+    doi: "10.1080/07350015.2021.2002159"

cbps-0.2.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,135 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at:
+
+* **Cai Xuanyu**: xuanyuCAI@outlook.com
+* **Xu Wenli**: wlxu@cityu.edu.mo
+
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

cbps-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,285 @@
+# Contributing to cbps
+
+Thank you for your interest in contributing to the cbps Python package! We welcome contributions from everyone and are grateful for every contribution, whether it's a bug report, feature suggestion, documentation improvement, or code contribution.
+
+## Code of Conduct
+
+By participating in this project, you agree to abide by our [Code of Conduct](CODE_OF_CONDUCT.md). Please read it before contributing.
+
+## First-Time Contributors
+
+New to open source? We're happy to help you get started! Here are some ways to make your first contribution:
+
+- **Fix a typo** in the documentation or docstrings
+- **Improve an example** or add a new one
+- **Report a bug** you've encountered
+- **Add a test case** for an existing function
+
+Look for issues labeled [`good first issue`](https://github.com/gorgeousfish/CBPS-py/labels/good%20first%20issue) for beginner-friendly tasks.
+
+## How to Contribute
+
+### Reporting Bugs
+
+If you find a bug, please open an issue on our [GitHub Issues](https://github.com/gorgeousfish/CBPS-py/issues) page with:
+
+1. A clear, descriptive title
+2. A detailed description of the problem
+3. Steps to reproduce the issue
+4. Expected behavior vs. actual behavior
+5. Your environment (Python version, OS, package version)
+6. If possible, a minimal code example that reproduces the issue
+
+### Suggesting Features
+
+We welcome feature suggestions! Please open an issue with:
+
+1. A clear description of the feature
+2. The motivation/use case for the feature
+3. Any relevant references (papers, other implementations, etc.)
+
+### Contributing Code
+
+1. **Open an issue first**: Before submitting a pull request with new features or significant changes, please open an issue to discuss your proposed changes. This helps avoid duplicate work and ensures your contribution aligns with the project's direction.
+
+2. **Fork the repository**: Create your own fork of the project.
+
+3. **Create a feature branch**: Use a descriptive branch name.
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+4. **Make your changes**: Follow the code style guidelines below.
+
+5. **Write tests**: All new code should include appropriate tests.
+
+6. **Submit a pull request**: Include a clear description of the changes and reference any related issues.
+
+## Development Environment Setup
+
+### Prerequisites
+
+- Python 3.10 or higher
+- Git
+- Virtual environment tool (venv, conda, etc.)
+
+### Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/gorgeousfish/CBPS-py.git
+cd CBPS-py
+
+# Create and activate virtual environment
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+
+# Install in development mode with all dependencies
+pip install -e ".[dev]"
+
+# Install pre-commit hooks
+pre-commit install
+```
+
+## Code Style Guidelines
+
+### Formatting
+
+We use automated tools to ensure consistent code style:
+
+- **Black** for code formatting (88 characters per line)
+- **isort** for import sorting (with black profile)
+- **flake8** for linting
+- **mypy** for type checking
+
+```bash
+# Format code
+black cbps/
+isort cbps/
+
+# Check code style
+black --check cbps/
+isort --check cbps/
+flake8 cbps/
+mypy cbps/
+```
+
+### Type Annotations
+
+All functions must have complete type annotations. Use `# type: ignore` sparingly and only when necessary (e.g., for third-party libraries without type stubs).
+
+### Documentation
+
+- All public functions, classes, and methods must have docstrings
+- Use NumPy-style docstrings
+- Include type information in docstrings for complex types
+- Add examples where appropriate
+
+Example:
+
+```python
+def compute_weights(
+    probs: np.ndarray,
+    treatment: np.ndarray,
+    estimand: str = "ATE"
+) -> np.ndarray:
+    """Compute inverse probability weights.
+
+    Parameters
+    ----------
+    probs : np.ndarray
+        Estimated propensity scores, shape (n,).
+    treatment : np.ndarray
+        Binary treatment indicator, shape (n,).
+    estimand : str, optional
+        Target estimand, either "ATE" or "ATT". Default is "ATE".
+
+    Returns
+    -------
+    np.ndarray
+        Computed weights, shape (n,).
+
+    Examples
+    --------
+    >>> probs = np.array([0.3, 0.7, 0.5])
+    >>> treatment = np.array([0, 1, 1])
+    >>> weights = compute_weights(probs, treatment, estimand="ATE")
+    """
+```
+
+## Numerical Precision Requirements
+
+**Critical**: This package maintains high numerical precision (±1e-6) for all core algorithms. This is essential for reproducing results from the original R CBPS package.
+
+### Key Constraints
+
+1. **Float64 only**: All floating-point operations must use `numpy.float64`
+   ```python
+   X = np.array(data, dtype=np.float64)
+   ```
+
+2. **Generalized inverse**: Use `scipy.linalg.pinv(V, rcond=None)` for numerical stability
+   ```python
+   invV = scipy.linalg.pinv(V, rcond=None)
+   ```
+
+3. **GLM initialization**: Use `statsmodels.GLM` for propensity score estimation
+   ```python
+   glm_fit = sm.GLM(y, X, family=sm.families.Binomial()).fit(tol=1e-8, maxiter=25)
+   ```
+
+4. **Probability clipping**: Use `np.clip(probs, 1e-6, 1-1e-6)`
+   ```python
+   probs = np.clip(probs, 1e-6, 1-1e-6)
+   ```
+
+5. **Sample weights normalization**: First step in all modules
+   ```python
+   sw = sw / sw.mean()  # Ensures sw.sum() = n
+   ```
+
+## Testing Guidelines
+
+### Running Tests
+
+```bash
+# Run all tests
+pytest
+
+# Run with coverage
+pytest --cov=cbps --cov-report=html
+
+# Run specific test file
+pytest tests/test_cbps.py
+
+# Run tests with specific markers
+pytest -m "not slow"  # Skip slow tests
+pytest -m "r_benchmark"  # Only R benchmark tests
+```
+
+### Writing Tests
+
+- All new code should have tests with coverage ≥90%
+- Use `numpy.testing.assert_allclose(atol=1e-6, rtol=0)` for numerical comparisons
+- Set random seeds for reproducibility: `np.random.seed(12345)`
+- Use pytest markers appropriately:
+  - `@pytest.mark.slow` for tests taking >10 seconds
+  - `@pytest.mark.r_benchmark` for R comparison tests
+  - `@pytest.mark.integration` for end-to-end tests
+
+Example test:
+
+```python
+import pytest
+import numpy as np
+from numpy.testing import assert_allclose
+
+def test_cbps_lalonde():
+    """Test CBPS on LaLonde data."""
+    from cbps.datasets import load_lalonde
+    import cbps
+
+    data = load_lalonde(dehejia_wahba_only=True)
+    fit = cbps.CBPS(formula="treat ~ age + educ", data=data, att=1)
+
+    # Verify convergence and basic properties
+    assert fit.converged
+    assert len(fit.coefficients) == 3  # intercept + 2 covariates
+
+@pytest.mark.r_benchmark
+def test_cbps_matches_r():
+    """Test that Python results match R CBPS package."""
+    # ... comparison with R results
+    assert_allclose(python_coef, r_coef, atol=1e-6)
+```
+
+## Pull Request Process
+
+1. **Ensure all checks pass**:
+   ```bash
+   black cbps/
+   isort cbps/
+   flake8 cbps/
+   mypy cbps/
+   pytest
+   ```
+
+2. **Update documentation** if you've changed APIs or added features.
+
+3. **Add changelog entry** in `CHANGELOG.md` under "Unreleased" section.
+
+4. **Commit with clear messages** following conventional commits:
+   ```bash
+   git commit -m "feat(cbps): add support for clustered standard errors"
+   git commit -m "fix(multitreat): correct weight normalization"
+   git commit -m "docs: update installation instructions"
+   ```
+
+5. **Push and create pull request**:
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+
+6. **PR Requirements**:
+   - All CI checks pass (GitHub Actions)
+   - Code coverage does not decrease
+   - No new linter warnings
+   - Numerical tests pass (±1e-6 precision)
+   - Documentation updated if needed
+
+## Getting Help
+
+- **Questions**: Open a [GitHub Discussion](https://github.com/gorgeousfish/CBPS-py/discussions) or Issue
+- **Bug Reports**: Use [GitHub Issues](https://github.com/gorgeousfish/CBPS-py/issues)
+- **Documentation**: See [https://cbps.readthedocs.io](https://cbps.readthedocs.io)
+
+## Maintainers
+
+- **Cai Xuanyu** - xuanyuCAI@outlook.com
+- **Xu Wenli** - wlxu@cityu.edu.mo
+
+## Attribution
+
+Contributors will be acknowledged in the project's documentation. We use the all-contributors specification to recognize all types of contributions.
+
+Thank you for contributing to cbps!