coxdev 0.1.3__tar.gz → 0.1.5__tar.gz

coxdev-0.1.5/.Rbuildignore

@@ -0,0 +1,2 @@
+^R_pkg$
+^src$

coxdev-0.1.5/.claude/settings.local.json

@@ -0,0 +1,39 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(EIGEN_LIBRARY_PATH=/opt/homebrew/include/eigen3 uv pip install:*)",
+      "Bash(git add:*)",
+      "Bash(R CMD INSTALL:*)",
+      "Bash(Rscript:*)",
+      "Bash(uv run pytest:*)",
+      "Bash(PYTHONPATH=/Users/naras/GitHub/adelie:$PYTHONPATH uv run python:*)",
+      "Bash(uv run python:*)",
+      "Bash(python:*)",
+      "Bash(pip show:*)",
+      "Bash(source .venv312/bin/activate)",
+      "Bash(pip install:*)",
+      "Bash(.venv312/bin/python:*)",
+      "Bash(uv pip install:*)",
+      "Bash(ls:*)",
+      "Bash(R CMD build:*)",
+      "Bash(R -e:*)",
+      "Bash(R -q --vanilla -e:*)",
+      "Bash(CPATH=/opt/homebrew/include/eigen3 uv pip install:*)",
+      "Bash(CPATH=/opt/homebrew/include/eigen3 CXXFLAGS=\"-Wno-error=unknown-pragmas\" uv pip install:*)",
+      "Bash(CPATH=/opt/homebrew/include/eigen3 CXXFLAGS=\"-Wno-error\" pip install:*)",
+      "Bash(source:*)",
+      "Bash(/Users/naras/GitHub/coxdev/.venv312/bin/python -m pip install:*)",
+      "Bash(/Users/naras/GitHub/coxdev/.venv312/bin/python:*)",
+      "Bash(EIGEN_LIBRARY_PATH=/opt/homebrew/include/eigen3 /Users/naras/GitHub/coxdev/.venv312/bin/pip install:*)",
+      "Bash(EIGEN_LIBRARY_PATH=/opt/homebrew/include/eigen3 /Users/naras/GitHub/coxdev/.venv312/bin/python:*)",
+      "Bash(.venv312/bin/pytest:*)",
+      "Bash(.venv312/bin/pip install:*)",
+      "Bash(VIRTUAL_ENV=/Users/naras/GitHub/coxdev/.venv312 uv pip install:*)",
+      "Bash(EIGEN_LIBRARY_PATH=/opt/homebrew/include/eigen3 VIRTUAL_ENV=/Users/naras/GitHub/coxdev/.venv312 uv pip install:*)",
+      "Bash(git stash push:*)",
+      "Bash(git stash:*)",
+      "Bash(git checkout:*)",
+      "Bash(uv pip uninstall:*)"
+    ]
+  }
+}

coxdev-0.1.5/.github/workflows/build_wheel.yml

@@ -0,0 +1,80 @@
+name: Build Wheels
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+
+jobs:
+  build_wheels:
+    name: Build wheels on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        # Add windows-latest to the build matrix
+        os: [ubuntu-latest, macos-latest]
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Build wheels
+        uses: pypa/cibuildwheel@v3.3.1 # Use the latest version
+
+      - name: Upload wheel artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: wheels-${{ matrix.os }}
+          path: ./wheelhouse/*.whl # cibuildwheel puts wheels in this directory
+
+  build_windows_wheels:
+    name: Build wheels on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        # Add windows-latest to the build matrix
+        os: [windows-latest]
+
+    steps:
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          architecture: "x64"
+
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Build wheels
+        uses: pypa/cibuildwheel@v3.3.1 # Use the latest version
+        env:
+          # Only build 64-bit wheels (skips the broken win32 build)
+          CIBW_ARCHS: auto64
+
+      - name: Upload wheel artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: wheels-${{ matrix.os }}
+          path: ./wheelhouse/*.whl # cibuildwheel puts wheels in this directory
+
+  make_sdist:
+    name: Make SDist
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        submodules: recursive
+    
+    - name: Build SDist
+      run: pipx run build --sdist
+
+    - uses: actions/upload-artifact@v4
+      with:
+        name: sdist
+        path: dist/*.tar.gz

coxdev-0.1.5/.github/workflows/test.yml

@@ -0,0 +1,44 @@
+# Run all tests
+
+name: Run tests (Linux)
+
+# Controls when the workflow will run
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.12"]
+
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        submodules: recursive
+
+    - name: Set up Python  ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Set up R
+      uses: r-lib/actions/setup-r@v2
+      with:
+        r-version: '4.2'
+        use-public-rspm: true
+
+    - name: Install Python dependencies
+      run: |
+        Rscript -e "install.packages('glmnet', repos='http://cloud.r-project.org')"
+        pip install .[test]
+        pip install .
+
+    - name: Test pyglmnet
+      run: |
+        pytest tests --test-size=100

coxdev-0.1.5/.gitignore

@@ -0,0 +1,60 @@
+*~
+coxdev/*~
+
+# Prerequisites
+*.d
+
+# Object files
+*.o
+*.ko
+*.obj
+*.elf
+
+# Linker output
+*.ilk
+*.map
+*.exp
+
+# Precompiled Headers
+*.gch
+*.pch
+
+# Libraries
+*.lib
+*.a
+*.la
+*.lo
+
+# Shared objects (inc. Windows DLLs)
+*.dll
+*.so
+*.so.*
+*.dylib
+
+# Executables
+*.exe
+*.out
+*.app
+*.i*86
+*.x86_64
+*.hex
+
+# Debug files
+*.dSYM/
+*.su
+*.idb
+*.pdb
+
+# Kernel Module Compile Results
+*.mod*
+*.cmd
+.tmp_versions/
+modules.order
+Module.symvers
+Mkfile.old
+dkms.conf
+
+# Documentation files (generated/private)
+doc/saturated_likelihood_calc.tex
+CLAUDE.md
+2026-02-02-implement-the-following-plan.txt

coxdev-0.1.5/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "eigen"]
+	path = eigen
+	url = https://gitlab.com/libeigen/eigen.git

coxdev-0.1.5/CLAUDE.md

@@ -0,0 +1,181 @@
+# CLAUDE.md
+
+Guidance for Claude Code when working with this repository.
+
+## Project Overview
+
+Cox proportional hazards model deviance, gradients, and Hessian computations for survival analysis. Header-only C++ library (`include/coxdev.hpp`) with separate bindings for Python (pybind11) and R (Rcpp), handling stratified and unstratified models.
+
+## Build & Test Commands
+
+```bash
+# Install (Homebrew Eigen)
+EIGEN_LIBRARY_PATH=/opt/homebrew/include/eigen3 uv pip install -e .
+
+# Alternative: Use Eigen submodule
+git submodule update --init --recursive && uv pip install -e .
+
+# Tests
+uv run pytest tests/                           # All tests
+uv run pytest tests/test_compareR.py -v        # R comparison (requires rpy2, glmnet, survival)
+uv run pytest tests/test_compare_adelie.py -v  # Adelie comparison (requires rpy2, R adelie)
+uv run pytest tests/test_compareR.py::test_simple  # Single test
+```
+
+## File Structure (Adapter Pattern)
+
+| Location | Purpose |
+|----------|---------|
+| `include/coxdev.hpp` | **Canonical header-only C++ library** (single source of truth) |
+| `src/coxdev_py.cpp` | Python pybind11 bindings |
+| `R_pkg/coxdev/src/coxdev_r.cpp` | R Rcpp bindings |
+| `R_pkg/coxdev/inst/include/coxdev.hpp` | Symlink to `../../../../include/coxdev.hpp` |
+| `coxdev/base.py` | Python `CoxDeviance`, `CoxIRLSState` wrappers |
+| `coxdev/stratified.py` | Python `StratifiedCoxDeviance` wrapper |
+| `coxdev/stratified_cpp.py` | Python `StratifiedCoxDevianceCpp` direct C++ wrapper |
+| `R_pkg/coxdev/R/coxdev.R` | R wrappers: `make_cox_deviance()`, `make_stratified_cox_deviance()` |
+| `doc/main.tex` | Score/Hessian derivations (Breslow & Efron) |
+| `doc/saturated_likelihood_calc.tex` | Saturated log-likelihood derivation |
+| `doc/architecture.md` | Architecture diagrams and glmnetpp integration |
+
+## Key APIs
+
+### Python
+
+```python
+# Constructor accepts sample_weight (init-time, not call-time)
+cox = CoxDeviance(event, status, start=None, sample_weight=None, tie_breaking='efron')
+result = cox(eta)  # Returns CoxDevianceResult with deviance, gradient, diag_hessian
+info = cox.information(eta)  # LinearOperator for Hessian-vector products
+
+# Stratified version
+strat_cox = StratifiedCoxDeviance(event, status, strata, start=None, sample_weight=None)
+result = strat_cox(eta)
+```
+
+### Stateful IRLS/Coordinate Descent Interface
+
+```python
+from coxdev import CoxDeviance, CoxIRLSState
+
+cox = CoxDeviance(event, status, sample_weight=weights)
+irls = CoxIRLSState(cox)
+
+# Outer IRLS loop
+irls.recompute_outer(eta)        # O(15n), once per outer iteration
+w = irls.working_weights()       # O(1), accessor
+z = irls.working_response()      # O(1), accessor
+
+# Inner coordinate descent loop
+for j in range(p):
+    grad_j, hess_jj = irls.weighted_inner_product(X[:, j])  # O(n)
+    delta = grad_j / hess_jj
+    beta[j] += delta
+    irls.update_residuals(delta, X[:, j])  # O(n), incremental
+```
+
+### R
+
+```r
+# Constructor accepts sample_weight (init-time, not call-time)
+cox <- make_cox_deviance(event, status, start = NA, sample_weight = NULL, tie_breaking = 'efron')
+result <- cox$coxdev(eta)  # Returns list with deviance, gradient, diag_hessian
+info <- cox$information(eta)  # Returns matvec function for Hessian-vector products
+
+# Stratified version
+strat_cox <- make_stratified_cox_deviance(event, status, strata, start = NA, sample_weight = NULL)
+result <- strat_cox$coxdev(eta)
+
+# IRLS/Coordinate Descent Interface
+irls <- make_cox_irls_state(cox)
+
+# Outer IRLS loop
+irls$recompute_outer(eta)        # O(15n), once per outer iteration
+w <- irls$working_weights()      # O(1), accessor
+z <- irls$working_response()     # O(1), accessor
+
+# Inner coordinate descent loop
+for (j in 1:p) {
+  x_j <- X[, j]
+  gh <- irls$weighted_inner_product(x_j)  # O(n)
+  delta <- gh["gradient"] / gh["hessian"]
+  beta[j] <- beta[j] + delta
+  irls$update_residuals(delta, x_j)  # O(n), incremental
+}
+```
+
+### C++ (header-only)
+
+```cpp
+#include "coxdev.hpp"
+// Structs: CoxPreprocessed, CoxWorkspace, StratifiedCoxData, CoxIRLSState*
+// Use namespace coxdev:: (or glmnetpp::coxdev:: if GLMNET_INTERFACE defined)
+```
+
+## Architecture Layers
+
+```
+Layer 1: CoxPreprocessed  - event_order, risk sets, tie groups (computed once per dataset)
+Layer 2: CoxIRLSState     - exp(eta), risk_sums, working weights/response (once per outer IRLS)
+Layer 3: CD Primitives    - coordinate_gradient, update_residual (per inner iteration)
+```
+
+## Current Status
+
+- **Python IRLS interface**: Complete (`CoxIRLSState` in `coxdev/base.py`)
+- **R IRLS interface**: Complete (`make_cox_irls_state()` in `R_pkg/coxdev/R/coxdev.R`)
+- **glmnetpp integration**: Not yet started (Phase 5)
+
+## Design Principles
+
+### 1. Independence Constraint (CRITICAL)
+
+**coxdev must NOT depend on glmnetpp.** Dependency is one-way: glmnet depends on coxdev.
+
+- coxdev may only depend on: Eigen, standard C++, other coxdev classes
+- coxdev must NOT depend on: glmnetpp classes, elastic net logic, glmnet-specific code
+- Deployment: copy `include/coxdev.hpp` to glmnet unmodified, define `GLMNET_INTERFACE` before including
+
+### 2. Single Source of Truth
+
+`include/coxdev.hpp` is the only C++ implementation. Bindings are thin wrappers:
+- Python: `src/coxdev_py.cpp` uses pybind11 array mapping
+- R: `R_pkg/coxdev/src/coxdev_r.cpp` uses `Eigen::Map` for zero-copy
+
+### 3. Buffer Access Annotations
+
+Document RO (read-only), RW (read-write), RW-PERSIST (preserved across calls), SCRATCH (temporary):
+```cpp
+Eigen::VectorXd grad_buffer;      // RW: output
+Eigen::VectorXd exp_w_buffer;     // RW-PERSIST: reused in hessian_matvec
+Eigen::VectorXd forward_scratch;  // SCRATCH: temporary
+```
+
+### 4. Unified Code Paths
+
+Stratified code with n strata naturally handles n=1 (unstratified). No separate implementations.
+
+### 5. Thread Safety via Isolation
+
+Each `CoxDeviance` instance (Python class) or closure (R) has its own `StratifiedCoxData` with dedicated workspace buffers, enabling safe parallel execution.
+
+### 6. Empty Strata Optimization
+
+Pass empty strata vector for unstratified models:
+- Python: `np.array([], dtype=np.int32)`
+- R: `integer(0)`
+
+## Algorithm Notes
+
+**DO NOT simplify the algorithm.** Cox deviance involves complex cumsum operations, Efron correction terms (C_01, C_02, C_11, C_21, C_22), and careful gradient/Hessian calculations. See `include/coxdev.hpp`.
+
+Key functions:
+- `preprocess_single_stratum()`, `compute_sat_loglik_stratum()`
+- `cox_dev_single_stratum()` (COMPLEX), `hessian_matvec_single_stratum()`
+
+Tie-breaking: **Efron** (default, more accurate) or **Breslow** (glmnet compatible).
+
+## Related Projects
+
+- glmnet repo: `/Users/naras/GitHub/glmnet`
+- glmnet working copy: `/Users/naras/research/glmnet/pkg_src`

coxdev-0.1.5/LICENSE

@@ -0,0 +1,11 @@
+Copyright 2025 Jonathan Taylor, Narasimhan Balasubrimanian
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

coxdev-0.1.5/PKG-INFO

@@ -0,0 +1,271 @@
+Metadata-Version: 2.1
+Name: coxdev
+Version: 0.1.5
+Summary: Library for computing Cox deviance
+Keywords: Cox model
+Author-Email: Jonathan Taylor <jonathan.taylor@stanford.edu>, Trevor Hastie <hastie@stanford.edu>, Balasubramanian Narasimhan <naras@stanford.edu>
+Maintainer-Email: Jonathan Taylor <jonathan.taylor@stanford.edu>
+License: BSD-3-Clause
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.9
+Requires-Dist: numpy
+Requires-Dist: scipy
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pandas; extra == "test"
+Requires-Dist: joblib; extra == "test"
+Requires-Dist: rpy2; extra == "test"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: scipy; extra == "dev"
+Requires-Dist: ninja; extra == "dev"
+Requires-Dist: meson; extra == "dev"
+Requires-Dist: meson-python; extra == "dev"
+Requires-Dist: pybind11; extra == "dev"
+Requires-Dist: setuptools_scm; extra == "dev"
+Provides-Extra: doc
+Requires-Dist: myst-parser; extra == "doc"
+Requires-Dist: jupyter-book; extra == "doc"
+Requires-Dist: pandas; extra == "doc"
+Requires-Dist: matplotlib; extra == "doc"
+Requires-Dist: rpy2; extra == "doc"
+Description-Content-Type: text/markdown
+
+# coxdev
+
+A high-performance Python library for computing Cox proportional hazards model deviance, gradients, and Hessian information matrices. Built with C++ and Eigen for optimal performance, this library provides efficient survival analysis computations with support for different tie-breaking methods.
+
+## Features
+
+- **High Performance**: C++ implementation with Eigen linear algebra library
+- **Comprehensive Support**: Handles both Efron and Breslow tie-breaking methods
+- **Left-Truncated Data**: Support for left-truncated survival data
+- **Efficient Computations**: Optimized algorithms for deviance, gradient, and Hessian calculations
+- **Memory Efficient**: Uses linear operators for large-scale computations
+- **Cross-Platform**: Works on Linux, macOS, and Windows
+
+## Installation
+
+### Prerequisites
+
+This package requires the Eigen C++ library headers. The Eigen library is included as a git submodule.
+
+1. **Initialize Eigen submodule**: The Eigen library is included as a git submodule. Make sure it's initialized:
+   ```bash
+   git submodule update --init --recursive
+   ```
+
+2. **Check Eigen availability**: Run the check script to verify Eigen headers are available:
+   ```bash
+   python check_eigen.py
+   ```
+
+### Standard Installation
+
+```bash
+pip install .
+```
+
+### With Custom Eigen Path
+
+If you have Eigen installed elsewhere, you can specify its location:
+```bash
+env EIGEN_LIBRARY_PATH=/path/to/eigen pip install .
+```
+
+### Development Installation
+
+```bash
+pip install pybind11 meson-python ninja setuptools_scm
+pip install -e . --no-build-isolation
+```
+
+## Quick Start
+
+```python
+import numpy as np
+from coxdev import CoxDeviance
+
+# Generate sample survival data
+n_samples = 1000
+event_times = np.random.exponential(1.0, n_samples)
+status = np.random.binomial(1, 0.7, n_samples)  # 70% events, 30% censored
+linear_predictor = np.random.normal(0, 1, n_samples)
+
+# Create CoxDeviance object
+coxdev = CoxDeviance(event=event_times, status=status, tie_breaking='efron')
+
+# Compute deviance and related quantities
+result = coxdev(linear_predictor)
+
+print(f"Deviance: {result.deviance:.4f}")
+print(f"Saturated log-likelihood: {result.loglik_sat:.4f}")
+print(f"Gradient norm: {np.linalg.norm(result.gradient):.4f}")
+```
+
+## Advanced Usage
+
+### Left-Truncated Data
+
+```python
+# With start times (left-truncated data)
+start_times = np.random.exponential(0.5, n_samples)
+coxdev = CoxDeviance(
+    event=event_times, 
+    status=status, 
+    start=start_times,
+    tie_breaking='efron'
+)
+```
+
+### Computing Information Matrix
+
+```python
+# Get information matrix as a linear operator
+info_matrix = coxdev.information(linear_predictor)
+
+# Matrix-vector multiplication
+v = np.random.normal(0, 1, n_samples)
+result_vector = info_matrix @ v
+
+# For small problems, you can compute the full matrix
+X = np.random.normal(0, 1, (n_samples, 10))
+beta = np.random.normal(0, 1, 10)
+eta = X @ beta
+
+# Information matrix for coefficients: X^T @ I @ X
+I = info_matrix @ X
+information_matrix = X.T @ I
+```
+
+### Different Tie-Breaking Methods
+
+```python
+# Efron's method (default)
+coxdev_efron = CoxDeviance(event=event_times, status=status, tie_breaking='efron')
+
+# Breslow's method
+coxdev_breslow = CoxDeviance(event=event_times, status=status, tie_breaking='breslow')
+```
+
+## API Reference
+
+### CoxDeviance
+
+The main class for computing Cox model quantities.
+
+#### Parameters
+
+- **event**: Event times (failure times) for each observation
+- **status**: Event indicators (1 for event occurred, 0 for censored)
+- **start**: Start times for left-truncated data (optional)
+- **tie_breaking**: Method for handling tied event times ('efron' or 'breslow')
+
+#### Methods
+
+- **`__call__(linear_predictor, sample_weight=None)`**: Compute deviance and related quantities
+- **`information(linear_predictor, sample_weight=None)`**: Get information matrix as linear operator
+
+### CoxDevianceResult
+
+Result object containing computation results.
+
+#### Attributes
+
+- **linear_predictor**: The linear predictor values used
+- **sample_weight**: Sample weights used
+- **loglik_sat**: Saturated log-likelihood value
+- **deviance**: Computed deviance value
+- **gradient**: Gradient of deviance with respect to linear predictor
+- **diag_hessian**: Diagonal of Hessian matrix
+
+## Performance
+
+The library is optimized for performance:
+
+- **C++ Implementation**: Core computations in C++ with Eigen
+- **Memory Efficient**: Reuses buffers and uses linear operators
+- **Vectorized Operations**: Leverages Eigen's optimized linear algebra
+- **Minimal Python Overhead**: Heavy computations done in C++
+
+## Building from Source
+
+### Prerequisites
+
+- Python 3.9+
+- C++ compiler with C++17 support
+- Eigen library headers
+- pybind11
+
+### Build Steps
+
+1. Clone the repository with submodules:
+   ```bash
+   git clone --recursive https://github.com/jonathan-taylor/coxdev.git
+   cd coxdev
+   ```
+
+2. Install build dependencies:
+   ```bash
+   pip install build wheel setuptools pybind11 numpy
+   ```
+
+3. Build the package:
+   ```bash
+   python -m build
+   ```
+
+### Building Wheels
+
+For wheel building:
+```bash
+# Standard wheel build
+python -m build
+
+# With custom Eigen path
+env EIGEN_LIBRARY_PATH=/path/to/eigen python -m build
+```
+
+## Testing
+
+Run the test suite:
+```bash
+python -m pytest tests/
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests for new functionality
+5. Ensure all tests pass
+6. Submit a pull request
+
+## License
+
+This project is licensed under the BSD-3-Clause License - see the [LICENSE](LICENSE) file for details.
+
+## Citation
+
+If you use this library in your research, please cite:
+
+```bibtex
+@software{coxdev2024,
+  title={coxdev: High-performance Cox proportional hazards deviance computation},
+  author={Taylor, Jonathan and Hastie, Trevor and Narasimhan, Balasubramanian},
+  year={2024},
+  url={https://github.com/jonathan-taylor/coxdev}
+}
+```
+
+## Acknowledgments
+
+- Built with [Eigen](http://eigen.tuxfamily.org/) for efficient linear algebra
+- Uses [pybind11](https://pybind11.readthedocs.io/) for Python bindings
+- Inspired by the R `glmnet` package for survival analysis