{"id":37761914,"url":"https://github.com/statmlben/nonlinear-causal","last_synced_at":"2026-01-16T14:37:54.902Z","repository":{"id":134788759,"uuid":"348216369","full_name":"statmlben/nonlinear-causal","owner":"statmlben","description":"nl-causal: nonlinear causal inference based on IV regression in Python","archived":false,"fork":false,"pushed_at":"2024-07-09T04:07:24.000Z","size":37382,"stargazers_count":16,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-27T11:46:02.058Z","etag":null,"topics":["2sls","causal-inference","gwas","instrumental-variables","nonlinear"],"latest_commit_sha":null,"homepage":"https://github.com/nl-causal/nonlinear-causal","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/statmlben.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-03-16T04:44:28.000Z","updated_at":"2025-10-06T09:09:54.000Z","dependencies_parsed_at":"2024-02-22T07:48:04.134Z","dependency_job_id":null,"html_url":"https://github.com/statmlben/nonlinear-causal","commit_stats":null,"previous_names":["statmlben/nonlinear-causal"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/statmlben/nonlinear-causal","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statmlben%2Fnonlinear-causal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statmlben%2Fnonlinear-causal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statmlben%2Fnonlinear-causal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statmlben%2Fnonlinear-causal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/statmlben","download_url":"https://codeload.github.com/statmlben/nonlinear-causal/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statmlben%2Fnonlinear-causal/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28479399,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T11:59:17.896Z","status":"ssl_error","status_checked_at":"2026-01-16T11:55:55.838Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["2sls","causal-inference","gwas","instrumental-variables","nonlinear"],"created_at":"2026-01-16T14:37:54.182Z","updated_at":"2026-01-16T14:37:54.896Z","avatar_url":"https://github.com/statmlben.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":" ![Pypi](https://badge.fury.io/py/nonlinear-causal.svg)\n[![Python](https://img.shields.io/badge/python-3-blue.svg)](https://www.python.org/)\n[![MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n\u003c!-- [![Youtube](https://img.shields.io/badge/YouTube-Channel-red)]()\n![Downloads](https://static.pepy.tech/badge/nl-causal)\n![MonthDownloads](https://pepy.tech/badge/nl-causal/month)\n[![Conda](https://img.shields.io/conda/vn/conda-forge/???.svg)]() --\u003e\n\u003c!-- [![image](https://pepy.tech/badge/leafmap)](https://pepy.tech/project/leafmap) --\u003e\n\u003c!-- [![image](https://github.com/giswqs/leafmap/workflows/build/badge.svg)](https://github.com/giswqs/leafmap/actions?query=workflow%3Abuild) --\u003e\n\n# 🧬 nonlinear-causal \u003ca href=\"https://github.com/statmlben/nonlinear-causal\"\u003e\u003cimg src=\"logo/logo_c.png\" align=\"right\" height=\"150\" /\u003e\u003c/a\u003e\n\n**nonlinear-causal** is a Python module for nonlinear causal inference, including **hypothesis testing** and **confidence interval** for causal effect, built on top of instrument variables and Two-Stage least squares ([2SLS](https://en.wikipedia.org/wiki/Instrumental_variables_estimation)). \n\n- GitHub repo: [https://github.com/nl-causal/nonlinear-causal](https://github.com/nl-causal/nonlinear-causal)\n- PyPi: [https://pypi.org/project/nonlinear-causal/](https://pypi.org/project/nonlinear-causal/)\n- Paper: [PMLR@CLeaR2024](https://proceedings.mlr.press/v236/dai24a/dai24a.pdf)\n- Documentation: [https://nonlinear-causal.readthedocs.io](https://nonlinear-causal.readthedocs.io/en/latest/index.html)\n\n## Models\n\n**nonlinear-causal** considers two instrument variable causal models:\n\n\u003ca href=\"https://openreview.net/pdf?id=cylRvJYxYI\"\u003e\u003cimg src=\"./logo/nl_causal.png\" class=\"center\" style=\"height:80%;\" /\u003e\u003c/a\u003e\n\nIllustrated by the above image example, let's denote $\\mathbf{z}$ as the valid/invalid instrument variables (such as SNPs), $x$ as the exposure (such as gene expression), and $y$ as the outcome (such as AD). \n\n### **Two-Stage least squares ([2SLS](https://doi.org/10.1080/01621459.2014.994705))**\n\n$$\nx = \\mathbf{z}^\\prime \\mathbf{\\theta} + w, \\quad y = \\beta x + \\mathbf{z}^\\prime \\mathbf{\\alpha} + \\epsilon,\n$$\n\nwhere $(w,\\varepsilon)$ are the error terms independent of the instruments $\\mathbf{z}$, however, $w$ and $\\varepsilon$ may be correlated due to underlying *confounders*, and $\\beta\\in\\mathbb{R}$, $\\mathbf{\\alpha}\\in\\mathbb{R}^p$, $\\mathbf{\\theta}\\in\\mathbb{R}^p$ are unknown parameters.\n\n### **Two-Stage Sliced Inverse Regression ([2SIR](https://openreview.net/pdf?id=cylRvJYxYI))** \n\n$$\n\\phi(x) = \\mathbf{z}^\\prime \\mathbf{\\theta} + w, \\quad y = \\beta \\phi(x) + \\mathbf{z}^\\prime \\mathbf{\\alpha} + \\epsilon,\n$$\n\nwhere $(w,\\varepsilon)$ are the error terms independent of the instruments $\\mathbf{z}$, however, $w$ and $\\varepsilon$ may be correlated due to underlying *confounders*, and $\\beta\\in\\mathbb{R}$, $\\mathbf{\\alpha}\\in\\mathbb{R}^p$, $\\mathbf{\\theta}\\in\\mathbb{R}^p$ are unknown parameters.\n\n**Remarks**\n- **2SLS / 2SIR.** $\\mathbf{\\alpha} \\neq \\mathbf{0}$ indicates the violation of the second and/or third IV assumptions. The models may not be identifiable with the presence of invalid IVs. In the literature, additional structural constraints are imposed to avoid this issue, such as $\\|\\mathbf{\\alpha}\\|_0 \u003c p/2$.\n- **2SIR.** $\\beta$ and $\\phi$ are identifiable by fixing $\\|\\mathbf{\\theta}\\|_2 = 1$ and $\\beta \\geq 0$.\n\n**Strengths** of **2SIR**\n- Model assumptions of 2SIR are weaker than the classical 2SLS: the model admits an *arbitrary* nonlinear transformation $\\phi(\\cdot)$ across $\\mathbf{z}$, $x$ and $y$, relaxing the linearity assumption in the standard TWAS/2SLS.\n- 2SIR includes 2SLS and Yeo-Johnson power transformation 2SLS (PT-2SLS) as special cases. It is worth mentioning that the proposed method remains competitive against 2SLS/PT-2SLS even if the linear assumption holds.\n- The implicit linear structure in both 2SLS and 2SIR allows the *use of GWAS summary data* of our method, in contrast to requiring individual-level data by the other (non-linear) models.\n\n## What We Can Do:\n\n**2SLS**\n\n- Estimate $\\beta$: marginal causal effect from $X \\to Y$\n- Hypothesis testing (HT) and confidence interval (CI) for marginal causal effect $\\beta$.\n\n**2SIR**\n\n- Estimate $\\beta$: marginal causal effect from $X \\to Y$\n- Hypothesis testing (HT) and confidence interval (CI) for marginal causal effect $\\beta$.\n- Estimate nonlinear causal link $\\phi(\\cdot)$.\n\nFor implementation usage of **nonlinear_causal**, kindly refer to the provided examples and notebooks.\n\n## Installation\n\n```bash\n# Install the latest version `nonlinear-causal` in Github:\npip install git+https://github.com/nl-causal/nonlinear-causal\n# or Install `nonlinear-causal` lib from `pypi`\npip install nonlinear-causal\n```\n\n## Examples and notebooks\n\n- [User guide](./md/user_guide.md)\n- [Simulated examples](https://colab.research.google.com/drive/1c7nzsh5lFY6zaKB0LmP_9z6BZJ7m5F-H?usp=sharing)\n- [Simulated examples with invalid IVs](https://colab.research.google.com/drive/1PTw8VIH3ygvTkQZU0aI23Imh48aWDNMT?usp=sharing)\n- [Real application](app_test.ipynb)\n\n## Simulation Performance\n- We examine four cases: (i) $\\beta = 0$, (ii) $\\beta = .05$, (iii) $\\beta = .10$, (iv) $\\beta = .15$. Note that case (i) is for Type I error analysis, while $\\beta \u003e 0$ in (ii) - (iv), suggests power analysis. \n\n- Six transformations are considered: (1) linear: $\\phi(x) = x$; (2) logarithm: $\\phi(x) = \\log(x)$; (3) cube root: $\\phi(x) = x^{1/3}$; (4) inverse: $\\phi(x) = 1/x$; (5) piecewise linear: $\\phi(x) = xI(x\\leq 0) + 0.5 x I(x \u003e 0)$; (6) quadratic: $\\phi(x) = x^2$.  \n\n![result](./figs/sim_test_n5p10.png)\n\nFor more information, please check [our paper](https://openreview.net/pdf?id=cylRvJYxYI) (Section 3) or the [Jupyer Notebook](./nb/sim_main.ipynb) for the simulation examples.\n\n## Reference\n\nIf you use this code please star 🌟 the repository and cite the following paper:\n\n- Dai, B., Li, C., Xue, H., Pan, W., \u0026 Shen, X. (2024). Inference of nonlinear causal effects with GWAS summary data. In *Conference on Causal Learning and Reasoning*. PMLR.\n\n```latex\n@inproceedings{dai2022inference,\n  title={Inference of nonlinear causal effects with GWAS summary data},\n  author={Dai, Ben and Li, Chunlin and Xue, Haoran and Pan, Wei and Shen, Xiaotong},\n  booktitle={Conference on Causal Learning and Reasoning},\n  pages={},\n  year={2024},\n  rganization={PMLR}\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstatmlben%2Fnonlinear-causal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstatmlben%2Fnonlinear-causal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstatmlben%2Fnonlinear-causal/lists"}