firthmodels 0.1.0__tar.gz

firthmodels-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,46 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+      - run: uv sync --frozen
+      - run: uv run ruff check
+      - run: uv run ruff format --check
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+      - run: uv sync --frozen
+      - run: uv run mypy src/
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        include:
+          - python-version: "3.11"
+            uv-args: "--resolution lowest-direct"
+          - python-version: "3.12"
+            uv-args: ""
+          - python-version: "3.13"
+            uv-args: ""
+          - python-version: "3.14"
+            uv-args: ""
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync ${{ matrix.uv-args }}
+      - run: uv run pytest

firthmodels-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,101 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.12"
+
+      - name: Verify tag matches package version
+        run: |
+          TAG_VERSION=${GITHUB_REF_NAME#v}
+          PKG_VERSION=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])")
+          echo "Git Tag: $TAG_VERSION"
+          echo "Pkg Ver: $PKG_VERSION"
+          if [ "$TAG_VERSION" != "$PKG_VERSION" ]; then
+            echo "::error::Tag version ($TAG_VERSION) doesn't match pyproject.toml ($PKG_VERSION)"
+            exit 1
+          fi
+
+      - run: uv build --no-sources
+      - uses: actions/upload-artifact@v5
+        with:
+          name: dist
+          path: dist/
+
+  publish-testpypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/project/firthmodels/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v6
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          skip-existing: true
+
+  test-testpypi:
+    needs: publish-testpypi
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Install from TestPyPI
+        run: |
+          VERSION=${GITHUB_REF_NAME#v}
+          for i in {1..30}; do
+            if uv pip install --system \
+              --index-url https://test.pypi.org/simple/ \
+              --extra-index-url https://pypi.org/simple/ \
+              "firthmodels==$VERSION"; then
+              exit 0
+            fi
+            echo "Attempt $i failed, waiting 10s..."
+            sleep 10
+          done
+          echo "Failed to install after 30 attempts"
+          exit 1
+
+      - name: Verify import and run tests
+        run: |
+          python -c "from firthmodels import FirthLogisticRegression; print('Import OK')"
+          uv pip install --system pytest
+          pytest tests/
+
+  publish-pypi:
+    needs: test-testpypi
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/firthmodels/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v6
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

firthmodels-0.1.0/.gitignore

@@ -0,0 +1,209 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer,
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+.DS_Store

firthmodels-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,20 @@
+repos:
+-   repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+    -   id: check-yaml
+    -   id: end-of-file-fixer
+    -   id: trailing-whitespace
+- repo: https://github.com/astral-sh/ruff-pre-commit
+  # Ruff version.
+  rev: v0.14.7
+  hooks:
+    # Run the linter.
+    - id: ruff-check
+      args: [ --fix ]
+    # Run the formatter.
+    - id: ruff-format
+-   repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.19.0
+    hooks:
+    -   id: mypy

firthmodels-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

firthmodels-0.1.0/CITATION.cff

@@ -0,0 +1,11 @@
+cff-version: 1.2.0
+title: firthmodels
+message: "If you use this software, please cite it as below."
+type: software
+version: 0.1.0
+authors:
+  - family-names: Luo
+    given-names: Jonathan Z.
+    orcid: https://orcid.org/0000-0003-2567-1516
+repository-code: https://github.com/jzluo/firthmodels
+license: MIT

firthmodels-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jon Luo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

firthmodels-0.1.0/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.4
+Name: firthmodels
+Version: 0.1.0
+Summary: Firth-penalized models in Python
+Project-URL: Homepage, https://github.com/jzluo/firthmodels
+Project-URL: Repository, https://github.com/jzluo/firthmodels
+Project-URL: Issues, https://github.com/jzluo/firthmodels/issues
+Author-email: Jon Luo <20971593+jzluo@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bias reduction,bias-reduced logistic regression,complete separation,data separation,firth logistic regression,firth penalization,logistic regression,penalized likelihood,quasi-complete separation,rare events,small sample,statistics
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.11
+Requires-Dist: numpy>=1.24
+Requires-Dist: scikit-learn>=1.6
+Requires-Dist: scipy>=1.12
+Description-Content-Type: text/markdown
+
+# firthmodels
+
+[![CI](https://github.com/jzluo/firthmodels/actions/workflows/ci.yml/badge.svg)](https://github.com/jzluo/firthmodels/actions/workflows/ci.yml)
+![Python Version from PEP 621 TOML](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2Fjzluo%2Ffirthmodels%2Frefs%2Fheads%2Fmain%2Fpyproject.toml)
+![GitHub License](https://img.shields.io/github/license/jzluo/firthmodels)
+
+
+Firth-penalized logistic regression in Python.
+
+## Why Firth penalization?
+
+Standard maximum-likelihood logistic regression fails when your data has complete or quasi-complete separation: when a predictor (or combination of predictors) perfectly separates the outcome classes. In these cases, MLE produces infinite coefficient estimates.
+
+Firth's method adds a penalty term that:
+- Produces **finite, well-defined estimates** even with separated data
+- **Reduces small-sample bias** in coefficient estimates
+- Works as a drop-in replacement for standard logistic regression
+
+This is common in:
+- Case-control studies with rare exposures
+- Small clinical trials
+- Genome-wide or Phenome-wide association studies (GWAS/PheWAS)
+- Any dataset where events are rare relative to predictors
+
+## Installation
+
+```bash
+pip install firthmodels
+```
+
+Requires Python 3.11+ and depends on NumPy, SciPy, and scikit-learn.
+
+## Quick start
+
+```python
+import numpy as np
+from firthmodels import FirthLogisticRegression
+
+# Separated data: x=1 perfectly predicts y=1
+X = np.array([[0], [0], [0], [1], [1], [1]])
+y = np.array([0, 0, 0, 1, 1, 1])
+
+# Standard logistic regression would fail here
+model = FirthLogisticRegression().fit(X, y)
+
+print(model.coef_)        # array([3.89181893])
+print(model.intercept_)   # -2.725...
+print(model.pvalues_)     # Wald p-values
+print(model.bse_)         # Standard errors
+```
+
+## Features
+
+### scikit-learn compatible
+
+`FirthLogisticRegression` follows the scikit-learn estimator API (`fit`, `predict`, `predict_proba`, `get_params`, `set_params`, etc.), and can be used with pipelines, cross-validation, and other sklearn tools:
+
+```python
+from sklearn.model_selection import cross_val_score
+from sklearn.pipeline import make_pipeline
+from sklearn.preprocessing import StandardScaler
+
+pipe = make_pipeline(StandardScaler(), FirthLogisticRegression())
+scores = cross_val_score(pipe, X, y, cv=5)
+```
+
+### Likelihood ratio tests
+
+Compute LRT p-values for individual coefficients. These are more reliable than Wald p-values for small samples.
+
+Standard errors are back-corrected from the LRT chi-squared statistic (as in regenie), ensuring that (beta/SE)² = chi². This is useful for meta-analysis where studies are weighted by 1/SE²:
+
+```python
+model.fit(X, y).lrt()  # Compute LRT for all features
+
+model.lrt_pvalues_     # LRT p-values
+model.lrt_bse_         # Back-corrected standard errors
+```
+
+Each feature requires a separate constrained model fit, so you can test selectively to avoid unnecessary computation:
+
+```python
+model.lrt(0)              # Single feature by index
+model.lrt([0, 2])         # Multiple features
+model.lrt(['snp', 'age']) # By name (if fitted with DataFrame)
+```
+
+### Confidence intervals
+
+```python
+model.conf_int()                    # 95% Wald CIs
+model.conf_int(alpha=0.1)           # 90% CIs
+model.conf_int(method='pl')         # Profile likelihood CIs (more accurate)
+```
+
+### Sample weights and offsets
+
+```python
+model.fit(X, y, sample_weight=weights)
+model.fit(X, y, offset=offset)
+```
+
+## API reference
+
+### Parameters
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `fit_intercept` | `True` | Whether to fit an intercept term |
+| `max_iter` | `25` | Maximum Newton-Raphson iterations |
+| `tol` | `1e-4` | Convergence tolerance |
+| `max_step` | `5.0` | Maximum step size per coefficient |
+| `max_halfstep` | `25` | Maximum step-halvings per iteration |
+
+### Attributes (after fitting)
+
+| Attribute | Description |
+|-----------|-------------|
+| `coef_` | Coefficient estimates |
+| `intercept_` | Intercept (0.0 if `fit_intercept=False`) |
+| `bse_` | Wald standard errors; includes intercept if `fit_intercept=True` |
+| `pvalues_` | Wald p-values; includes intercept if `fit_intercept=True` |
+| `loglik_` | Penalized log-likelihood |
+| `n_iter_` | Number of iterations |
+| `converged_` | Whether the solver converged |
+| `lrt_pvalues_` | LRT p-values (after calling `lrt()`); includes intercept if `fit_intercept=True` |
+| `lrt_bse_` | Back-corrected SEs (after calling `lrt()`); includes intercept if `fit_intercept=True` |
+
+### Methods
+
+| Method | Description |
+|--------|-------------|
+| `fit(X, y)` | Fit the model |
+| `predict(X)` | Predict class labels |
+| `predict_proba(X)` | Predict class probabilities |
+| `predict_log_proba(X)` | Predict log class probabilities |
+| `decision_function(X)` | Return linear predictor values |
+| `lrt(features)` | Compute LRT p-values; `features` can be indices or column names. If `None`, tests all features. |
+| `conf_int(alpha, method)` | Confidence intervals; `method='wald'` (default) or `'pl'` for profile likelihood |
+
+## Roadmap
+
+Current implementation uses a damped Newton–Raphson solver.
+
+Add additional solvers (IRLS, L-BFGS, etc) and models (Cox proportional hazards).
+
+## References
+
+Firth D (1993). Bias reduction of maximum likelihood estimates. *Biometrika* 80, 27-38.
+
+Heinze G, Schemper M (2002). A solution to the problem of separation in logistic regression. *Statistics in Medicine* 21, 2409-2419.
+
+Mbatchou J et al. (2021). Computationally efficient whole-genome regression for
+quantitative and binary traits. *Nature Genetics* 53, 1097-1103.
+
+Venzon, D.J. and Moolgavkar, S.H. (1988). "A Method for Computing Profile-Likelihood-Based Confidence Intervals." Applied Statistics, 37(1), 87-94.
+
+## License
+
+MIT