risk-bridge 1.0.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (44) hide show
  1. risk_bridge-1.0.1/LICENSE +172 -0
  2. risk_bridge-1.0.1/PKG-INFO +220 -0
  3. risk_bridge-1.0.1/README.md +191 -0
  4. risk_bridge-1.0.1/pyproject.toml +69 -0
  5. risk_bridge-1.0.1/setup.cfg +4 -0
  6. risk_bridge-1.0.1/src/risk_bridge/__init__.py +72 -0
  7. risk_bridge-1.0.1/src/risk_bridge/api.py +72 -0
  8. risk_bridge-1.0.1/src/risk_bridge/calibration.py +162 -0
  9. risk_bridge-1.0.1/src/risk_bridge/cli.py +38 -0
  10. risk_bridge-1.0.1/src/risk_bridge/config.py +476 -0
  11. risk_bridge-1.0.1/src/risk_bridge/constraints.py +257 -0
  12. risk_bridge-1.0.1/src/risk_bridge/external.py +543 -0
  13. risk_bridge-1.0.1/src/risk_bridge/likelihood.py +132 -0
  14. risk_bridge-1.0.1/src/risk_bridge/metrics.py +189 -0
  15. risk_bridge-1.0.1/src/risk_bridge/optimize.py +130 -0
  16. risk_bridge-1.0.1/src/risk_bridge/output_schema.py +5 -0
  17. risk_bridge-1.0.1/src/risk_bridge/pipeline.py +295 -0
  18. risk_bridge-1.0.1/src/risk_bridge/preprocess.py +298 -0
  19. risk_bridge-1.0.1/src/risk_bridge/runs.py +2350 -0
  20. risk_bridge-1.0.1/src/risk_bridge/sampling.py +130 -0
  21. risk_bridge-1.0.1/src/risk_bridge/simulate.py +170 -0
  22. risk_bridge-1.0.1/src/risk_bridge/tabular.py +146 -0
  23. risk_bridge-1.0.1/src/risk_bridge/types.py +113 -0
  24. risk_bridge-1.0.1/src/risk_bridge.egg-info/PKG-INFO +220 -0
  25. risk_bridge-1.0.1/src/risk_bridge.egg-info/SOURCES.txt +42 -0
  26. risk_bridge-1.0.1/src/risk_bridge.egg-info/dependency_links.txt +1 -0
  27. risk_bridge-1.0.1/src/risk_bridge.egg-info/entry_points.txt +2 -0
  28. risk_bridge-1.0.1/src/risk_bridge.egg-info/requires.txt +7 -0
  29. risk_bridge-1.0.1/src/risk_bridge.egg-info/top_level.txt +1 -0
  30. risk_bridge-1.0.1/tests/test_api_unit.py +145 -0
  31. risk_bridge-1.0.1/tests/test_calibration_export_unit.py +80 -0
  32. risk_bridge-1.0.1/tests/test_calibration_unit.py +67 -0
  33. risk_bridge-1.0.1/tests/test_config_types.py +159 -0
  34. risk_bridge-1.0.1/tests/test_constraints_unit.py +118 -0
  35. risk_bridge-1.0.1/tests/test_likelihood_unit.py +73 -0
  36. risk_bridge-1.0.1/tests/test_metrics_unit.py +122 -0
  37. risk_bridge-1.0.1/tests/test_numerical_validation_unit.py +50 -0
  38. risk_bridge-1.0.1/tests/test_optimize_unit.py +38 -0
  39. risk_bridge-1.0.1/tests/test_pipeline_unit.py +56 -0
  40. risk_bridge-1.0.1/tests/test_preprocess_unit.py +84 -0
  41. risk_bridge-1.0.1/tests/test_sampling_unit.py +124 -0
  42. risk_bridge-1.0.1/tests/test_scenario1_pipeline_unit.py +422 -0
  43. risk_bridge-1.0.1/tests/test_simulate_unit.py +94 -0
  44. risk_bridge-1.0.1/tests/test_synthetic_transport_example.py +65 -0
@@ -0,0 +1,172 @@
1
+ Apache License
2
+ Version 2.0, January 2004
3
+ http://www.apache.org/licenses/
4
+
5
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
6
+
7
+ 1. Definitions.
8
+
9
+ "License" shall mean the terms and conditions for use, reproduction,
10
+ and distribution as defined by Sections 1 through 9 of this document.
11
+
12
+ "Licensor" shall mean the copyright owner or entity authorized by
13
+ the copyright owner that is granting the License.
14
+
15
+ "Legal Entity" shall mean the union of the acting entity and all
16
+ other entities that control, are controlled by, or are under common
17
+ control with that entity. For the purposes of this definition,
18
+ "control" means (i) the power, direct or indirect, to cause the
19
+ direction or management of such entity, whether by contract or
20
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
21
+ outstanding shares, or (iii) beneficial ownership of such entity.
22
+
23
+ "You" (or "Your") shall mean an individual or Legal Entity
24
+ exercising permissions granted by this License.
25
+
26
+ "Source" form shall mean the preferred form for making modifications,
27
+ including but not limited to software source code, documentation
28
+ source, and configuration files.
29
+
30
+ "Object" form shall mean any form resulting from mechanical
31
+ transformation or translation of a Source form, including but
32
+ not limited to compiled object code, generated documentation,
33
+ and conversions to other media types.
34
+
35
+ "Work" shall mean the work of authorship, whether in Source or
36
+ Object form, made available under the License, as indicated by a
37
+ copyright notice that is included in or attached to the work.
38
+
39
+ "Derivative Works" shall mean any work, whether in Source or Object
40
+ form, that is based on (or derived from) the Work and for which the
41
+ editorial revisions, annotations, elaborations, or other modifications
42
+ represent, as a whole, an original work of authorship. For the purposes
43
+ of this License, Derivative Works shall not include works that remain
44
+ separable from, or merely link (or bind by name) to the interfaces of,
45
+ the Work and Derivative Works thereof.
46
+
47
+ "Contribution" shall mean any work of authorship, including
48
+ the original version of the Work and any modifications or additions
49
+ to that Work or Derivative Works thereof, that is intentionally
50
+ submitted to Licensor for inclusion in the Work by the copyright owner
51
+ or by an individual or Legal Entity authorized to submit on behalf of
52
+ the copyright owner. For the purposes of this definition, "submitted"
53
+ means any form of electronic, verbal, or written communication sent
54
+ to the Licensor or its representatives, including but not limited to
55
+ communication on electronic mailing lists, source code control systems,
56
+ and issue tracking systems that are managed by, or on behalf of, the
57
+ Licensor for the purpose of discussing and improving the Work, but
58
+ excluding communication that is conspicuously marked or otherwise
59
+ designated in writing by the copyright owner as "Not a Contribution."
60
+
61
+ "Contributor" shall mean Licensor and any individual or Legal Entity
62
+ on behalf of whom a Contribution has been received by Licensor and
63
+ subsequently incorporated within the Work.
64
+
65
+ 2. Grant of Copyright License. Subject to the terms and conditions of
66
+ this License, each Contributor hereby grants to You a perpetual,
67
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
68
+ copyright license to reproduce, prepare Derivative Works of,
69
+ publicly display, publicly perform, sublicense, and distribute the
70
+ Work and such Derivative Works in Source or Object form.
71
+
72
+ 3. Grant of Patent License. Subject to the terms and conditions of
73
+ this License, each Contributor hereby grants to You a perpetual,
74
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
75
+ patent license to make, have made, use, offer to sell, sell, import,
76
+ and otherwise transfer the Work, where such license applies only to
77
+ those patent claims licensable by such Contributor that are necessarily
78
+ infringed by their Contribution(s) alone or by combination of their
79
+ Contribution(s) with the Work to which such Contribution(s) was
80
+ submitted. If You institute patent litigation against any entity
81
+ alleging that the Work or a Contribution incorporated within the Work
82
+ constitutes direct or contributory patent infringement, then any
83
+ patent licenses granted to You under this License for that Work shall
84
+ terminate as of the date such litigation is filed.
85
+
86
+ 4. Redistribution. You may reproduce and distribute copies of the
87
+ Work or Derivative Works thereof in any medium, with or without
88
+ modifications, and in Source or Object form, provided that You
89
+ meet the following conditions:
90
+
91
+ (a) You must give any other recipients of the Work or
92
+ Derivative Works a copy of this License; and
93
+
94
+ (b) You must cause any modified files to carry prominent notices
95
+ stating that You changed the files; and
96
+
97
+ (c) You must retain, in the Source form of any Derivative Works
98
+ that You distribute, all copyright, patent, trademark, and
99
+ attribution notices from the Source form of the Work,
100
+ excluding those notices that do not pertain to any part of
101
+ the Derivative Works; and
102
+
103
+ (d) If the Work includes a "NOTICE" text file as part of its
104
+ distribution, then any Derivative Works that You distribute must
105
+ include a readable copy of the attribution notices contained
106
+ within such NOTICE file, excluding those notices that do not
107
+ pertain to any part of the Derivative Works, in at least one
108
+ of the following places: within a NOTICE text file distributed
109
+ as part of the Derivative Works; within the Source form or
110
+ documentation, if provided along with the Derivative Works; or,
111
+ within a display generated by the Derivative Works, if and
112
+ wherever such third-party notices normally appear. The contents
113
+ of the NOTICE file are for informational purposes only and
114
+ do not modify the License. You may add Your own attribution
115
+ notices within Derivative Works that You distribute, alongside
116
+ or as an addendum to the NOTICE text from the Work, provided
117
+ that such additional attribution notices cannot be construed
118
+ as modifying the License.
119
+
120
+ You may add Your own copyright statement to Your modifications and
121
+ may provide additional or different license terms and conditions
122
+ for use, reproduction, or distribution of Your modifications, or
123
+ for any such Derivative Works as a whole, provided Your use,
124
+ reproduction, and distribution of the Work otherwise complies with
125
+ the conditions stated in this License.
126
+
127
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
128
+ any Contribution intentionally submitted for inclusion in the Work
129
+ by You to the Licensor shall be under the terms and conditions of
130
+ this License, without any additional terms or conditions.
131
+ Notwithstanding the above, nothing herein shall supersede or modify
132
+ the terms of any separate license agreement you may have executed
133
+ with Licensor regarding such Contributions.
134
+
135
+ 6. Trademarks. This License does not grant permission to use the trade
136
+ names, trademarks, service marks, or product names of the Licensor,
137
+ except as required for reasonable and customary use in describing the
138
+ origin of the Work and reproducing the content of the NOTICE file.
139
+
140
+ 7. Disclaimer of Warranty. Unless required by applicable law or
141
+ agreed to in writing, Licensor provides the Work on an "AS IS" BASIS,
142
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
143
+ implied, including, without limitation, any warranties or conditions
144
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
145
+ PARTICULAR PURPOSE. You are solely responsible for determining the
146
+ appropriateness of using or redistributing the Work and assume any
147
+ risks associated with Your exercise of permissions under this License.
148
+
149
+ 8. Limitation of Liability. In no event and under no legal theory,
150
+ whether in tort (including negligence), contract, or otherwise,
151
+ unless required by applicable law (such as deliberate and grossly
152
+ negligent acts) or agreed to in writing, shall any Contributor be
153
+ liable to You for damages, including any direct, indirect, special,
154
+ incidental, or consequential damages of any character arising as a
155
+ result of this License or out of the use or inability to use the
156
+ Work (including but not limited to damages for loss of goodwill,
157
+ work stoppage, computer failure or malfunction, or any and all
158
+ other commercial damages or losses), even if such Contributor
159
+ has been advised of the possibility of such damages.
160
+
161
+ 9. Accepting Warranty or Additional Liability. While redistributing
162
+ the Work or Derivative Works thereof, You may choose to offer,
163
+ and charge a fee for, acceptance of support, warranty, indemnity,
164
+ or other liability obligations and/or rights consistent with this
165
+ License. However, in accepting such obligations, You may act only
166
+ on Your own behalf and on Your sole responsibility, not on behalf
167
+ of any other Contributor, and only if You agree to indemnify,
168
+ defend, and hold each Contributor harmless for any liability
169
+ incurred by, or claims asserted against, such Contributor by reason
170
+ of your accepting any such warranty or additional liability.
171
+
172
+ END OF TERMS AND CONDITIONS
@@ -0,0 +1,220 @@
1
+ Metadata-Version: 2.4
2
+ Name: risk-bridge
3
+ Version: 1.0.1
4
+ Summary: Risk Bridging through Constrained MLE
5
+ Author: Risk Bridge contributors
6
+ License-Expression: Apache-2.0
7
+ Project-URL: Homepage, https://github.com/SaehwanPark/risk-bridge
8
+ Project-URL: Repository, https://github.com/SaehwanPark/risk-bridge
9
+ Project-URL: Issues, https://github.com/SaehwanPark/risk-bridge/issues
10
+ Keywords: risk-modeling,calibration,constrained-optimization,maximum-likelihood,biostatistics
11
+ Classifier: Development Status :: 5 - Production/Stable
12
+ Classifier: Intended Audience :: Science/Research
13
+ Classifier: Programming Language :: Python :: 3.11
14
+ Classifier: Programming Language :: Python :: 3.12
15
+ Classifier: Programming Language :: Python :: 3.13
16
+ Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
17
+ Classifier: Topic :: Scientific/Engineering :: Mathematics
18
+ Requires-Python: >=3.11
19
+ Description-Content-Type: text/markdown
20
+ License-File: LICENSE
21
+ Requires-Dist: comp-builders>=1.0.0
22
+ Requires-Dist: numpy>=2.4.2
23
+ Requires-Dist: pandas>=3.0.1
24
+ Requires-Dist: polars>=1.38.1
25
+ Requires-Dist: rdata>=1.0.0
26
+ Requires-Dist: scikit-learn>=1.8.0
27
+ Requires-Dist: scipy>=1.17.1
28
+ Dynamic: license-file
29
+
30
+ <p align="center">
31
+ <img src="assets/risk-bridge-banner.png" alt="Risk Bridge banner" width="100%">
32
+ </p>
33
+
34
+ # Risk Bridge
35
+
36
+ Risk Bridge is a Python package for estimating transportable binary-risk models when the available cohorts do not all contain the same information. It combines propensity-score sampling, reference-cohort calibration, maximum likelihood estimation, and constrained maximum likelihood estimation (cMLE) into reproducible simulation and user-data workflows.
37
+
38
+ Package title: **Risk Bridging through Constrained MLE**.
39
+
40
+ ## Motivation
41
+
42
+ Risk models often need to be evaluated or adapted across related populations: a target cohort, a source cohort, and a reference cohort. Standard model fitting can drift when covariate distributions, calibration strata, or observed risk markers differ across those cohorts. Risk Bridge provides a repeatable way to compare ordinary ML estimates with calibration-constrained estimates while preserving diagnostics, thresholds, and run metadata.
43
+
44
+ ## Foundation Papers
45
+
46
+ - > Cao, Y., Ma, W., Zhao, G., McCarthy, A. M., & Chen, J. (2024). A constrained maximum likelihood approach to developing well-calibrated models for predicting binary outcomes. Lifetime Data Analysis, 30(3), 624-648.
47
+ - > Wang, Le., Chen, J. (2026). Developing Accurate Risk Prediction Using Biased Electronic Health Record Data. Manuscript in preparation.
48
+
49
+ ## Key features
50
+
51
+ - Simulated Scenario 1-3 workflows for reproducible method evaluation.
52
+ - User-data workflow for prepared target, source, and reference CSV datasets.
53
+ - Propensity-score matched and random-sampled source paths.
54
+ - Constrained MLE solver ladder with calibration-violation diagnostics.
55
+ - CSV-first output contract with optional parquet mirrors.
56
+ - Public Python API and `risk-bridge` command-line interface.
57
+ - Unit tests covering preprocessing, calibration, likelihoods, constraints, optimization, metrics, sampling, and pipeline behavior.
58
+
59
+ ## Installation
60
+
61
+ ### From the package index (standard path after publication)
62
+
63
+ Once the `risk-bridge` package is published:
64
+
65
+ ```bash
66
+ uv add risk-bridge
67
+ # or: pip install risk-bridge
68
+ ```
69
+
70
+ Until the first public upload completes, install from this repository checkout instead.
71
+
72
+ ### From a repository checkout
73
+
74
+ Risk Bridge is packaged with `uv` and a checked-in lock file. To install `uv`, read [this](https://docs.astral.sh/uv/getting-started/installation/).
75
+
76
+ ```bash
77
+ git clone git@github.com/SaehwanPark/risk-bridge.git
78
+ cd risk-bridge
79
+ uv sync --locked
80
+ ```
81
+
82
+ Run the test suite:
83
+
84
+ ```bash
85
+ uv run pytest
86
+ uv run basedpyright
87
+ ```
88
+
89
+ The orchestration layer uses [`comp-builders`](https://pypi.org/project/comp-builders/) for explicit `Result` composition in recoverable validation paths. `uv sync --locked` installs it from the package index as recorded in `uv.lock`.
90
+
91
+ ## Quick start
92
+
93
+ Run a small simulated scenario:
94
+
95
+ ```bash
96
+ uv run risk-bridge \
97
+ --mode simulated \
98
+ --scenario 2 \
99
+ --nsim 5 \
100
+ --n-target 5000 \
101
+ --n-source 2000 \
102
+ --n-reference 5000 \
103
+ --sample-size 500 \
104
+ --output-root data \
105
+ --run-label quickstart
106
+ ```
107
+
108
+ Run on prepared CSV datasets:
109
+
110
+ ```bash
111
+ uv run risk-bridge \
112
+ --mode user-data \
113
+ --target-csv /path/to/target.csv \
114
+ --source-csv /path/to/source.csv \
115
+ --reference-csv /path/to/reference.csv \
116
+ --y-col label \
117
+ --z-origin-col z_cont \
118
+ --z-cat-col z_cat \
119
+ --x-cols X1,X2,X3,X4 \
120
+ --sample-size 500 \
121
+ --nsim 1 \
122
+ --output-root data \
123
+ --run-label user_data
124
+ ```
125
+
126
+ For a five-minute setup path, see [QUICKSTART.md](QUICKSTART.md).
127
+
128
+ ## Architecture
129
+
130
+ ```text
131
+ Input cohorts
132
+ target, source, reference
133
+ ⬇️
134
+ Preprocessing and schema validation
135
+ ⬇️
136
+ Calibration artifacts from reference cohort
137
+ risk strata, external prevalence, X-support
138
+ ⬇️
139
+ Sampling paths
140
+ propensity-score matched source + random source
141
+ ⬇️
142
+ Model fitting
143
+ ML baseline + cMLE with calibration constraints
144
+ ⬇️
145
+ Evaluation and exports
146
+ estimates, ROC metrics, accuracy metrics, diagnostics, metadata
147
+ ```
148
+
149
+ The public CLI delegates to typed configuration objects in `risk_bridge.config`, orchestration in `risk_bridge.runs`, reusable pipeline helpers in `risk_bridge.pipeline`, and numerical components in `risk_bridge.likelihood`, `risk_bridge.constraints`, `risk_bridge.optimize`, and `risk_bridge.metrics`.
150
+
151
+ ## Library usage
152
+
153
+ ```python
154
+ from risk_bridge import UserDataRunConfig, UserDataSchema, run_user_data
155
+
156
+ run_dir = run_user_data(
157
+ UserDataRunConfig(
158
+ target_df=target_df,
159
+ source_df=source_df,
160
+ reference_df=reference_df,
161
+ schema=UserDataSchema(
162
+ x_cols=("X1", "X2", "X3", "X4"),
163
+ y_col="label",
164
+ z_origin_col="z_cont",
165
+ ),
166
+ sample_size=500,
167
+ output_root="data",
168
+ run_label="hospital_a",
169
+ )
170
+ )
171
+ print(run_dir)
172
+ ```
173
+
174
+ ## Outputs
175
+
176
+ Each run writes a timestamped directory under `output_root` with `intermediate/` and `final/` folders. Start with these final outputs:
177
+
178
+ - `final/run_metadata.csv` (includes `schema_version`, currently `1.1.0`)
179
+ - `final/fit_diagnostics.csv`
180
+ - `final/est_cml_psm.csv`
181
+ - `final/calibration_metrics.csv`
182
+ - `final/calibration_residuals.csv`
183
+ - `final/roc_metrics.csv`
184
+ - `final/accuracy_metrics.csv`
185
+
186
+ ## Reproduction
187
+
188
+ End-to-end regeneration commands for Scenario 2, numerical validation, and the
189
+ synthetic transport second example are in [REPRODUCTION.md](REPRODUCTION.md).
190
+ Cite this software with [CITATION.cff](CITATION.cff); add an archival DOI after
191
+ the Zenodo (or equivalent) deposit.
192
+
193
+ ## Repository layout
194
+
195
+ ```text
196
+ src/risk_bridge/ Python package source
197
+ tests/ Unit tests
198
+ cases/ Privacy-safe replication harnesses
199
+ examples/ Minimal runnable examples
200
+ docs/ Supplementary documentation
201
+ assets/ README visual assets
202
+ ```
203
+
204
+ ## Documentation
205
+
206
+ - [Quickstart](QUICKSTART.md)
207
+ - [Reproduction runbook](REPRODUCTION.md)
208
+ - [User guide](USER_GUIDE.md)
209
+ - [API reference](API_REFERENCE.md)
210
+ - [Architecture overview](ARCHITECTURE.md)
211
+ - [Pipeline architecture](docs/architecture/python_pipeline_analysis.md)
212
+ - [Solver strategy](docs/architecture/python_solver_strategy.md)
213
+ - [Replication cases](cases/README.md)
214
+ - [Changelog](CHANGELOG.md)
215
+ - [Citation](CITATION.cff)
216
+ - [License](LICENSE)
217
+
218
+ ## License
219
+
220
+ Risk Bridge is released under the Apache License 2.0.
@@ -0,0 +1,191 @@
1
+ <p align="center">
2
+ <img src="assets/risk-bridge-banner.png" alt="Risk Bridge banner" width="100%">
3
+ </p>
4
+
5
+ # Risk Bridge
6
+
7
+ Risk Bridge is a Python package for estimating transportable binary-risk models when the available cohorts do not all contain the same information. It combines propensity-score sampling, reference-cohort calibration, maximum likelihood estimation, and constrained maximum likelihood estimation (cMLE) into reproducible simulation and user-data workflows.
8
+
9
+ Package title: **Risk Bridging through Constrained MLE**.
10
+
11
+ ## Motivation
12
+
13
+ Risk models often need to be evaluated or adapted across related populations: a target cohort, a source cohort, and a reference cohort. Standard model fitting can drift when covariate distributions, calibration strata, or observed risk markers differ across those cohorts. Risk Bridge provides a repeatable way to compare ordinary ML estimates with calibration-constrained estimates while preserving diagnostics, thresholds, and run metadata.
14
+
15
+ ## Foundation Papers
16
+
17
+ - > Cao, Y., Ma, W., Zhao, G., McCarthy, A. M., & Chen, J. (2024). A constrained maximum likelihood approach to developing well-calibrated models for predicting binary outcomes. Lifetime Data Analysis, 30(3), 624-648.
18
+ - > Wang, Le., Chen, J. (2026). Developing Accurate Risk Prediction Using Biased Electronic Health Record Data. Manuscript in preparation.
19
+
20
+ ## Key features
21
+
22
+ - Simulated Scenario 1-3 workflows for reproducible method evaluation.
23
+ - User-data workflow for prepared target, source, and reference CSV datasets.
24
+ - Propensity-score matched and random-sampled source paths.
25
+ - Constrained MLE solver ladder with calibration-violation diagnostics.
26
+ - CSV-first output contract with optional parquet mirrors.
27
+ - Public Python API and `risk-bridge` command-line interface.
28
+ - Unit tests covering preprocessing, calibration, likelihoods, constraints, optimization, metrics, sampling, and pipeline behavior.
29
+
30
+ ## Installation
31
+
32
+ ### From the package index (standard path after publication)
33
+
34
+ Once the `risk-bridge` package is published:
35
+
36
+ ```bash
37
+ uv add risk-bridge
38
+ # or: pip install risk-bridge
39
+ ```
40
+
41
+ Until the first public upload completes, install from this repository checkout instead.
42
+
43
+ ### From a repository checkout
44
+
45
+ Risk Bridge is packaged with `uv` and a checked-in lock file. To install `uv`, read [this](https://docs.astral.sh/uv/getting-started/installation/).
46
+
47
+ ```bash
48
+ git clone git@github.com/SaehwanPark/risk-bridge.git
49
+ cd risk-bridge
50
+ uv sync --locked
51
+ ```
52
+
53
+ Run the test suite:
54
+
55
+ ```bash
56
+ uv run pytest
57
+ uv run basedpyright
58
+ ```
59
+
60
+ The orchestration layer uses [`comp-builders`](https://pypi.org/project/comp-builders/) for explicit `Result` composition in recoverable validation paths. `uv sync --locked` installs it from the package index as recorded in `uv.lock`.
61
+
62
+ ## Quick start
63
+
64
+ Run a small simulated scenario:
65
+
66
+ ```bash
67
+ uv run risk-bridge \
68
+ --mode simulated \
69
+ --scenario 2 \
70
+ --nsim 5 \
71
+ --n-target 5000 \
72
+ --n-source 2000 \
73
+ --n-reference 5000 \
74
+ --sample-size 500 \
75
+ --output-root data \
76
+ --run-label quickstart
77
+ ```
78
+
79
+ Run on prepared CSV datasets:
80
+
81
+ ```bash
82
+ uv run risk-bridge \
83
+ --mode user-data \
84
+ --target-csv /path/to/target.csv \
85
+ --source-csv /path/to/source.csv \
86
+ --reference-csv /path/to/reference.csv \
87
+ --y-col label \
88
+ --z-origin-col z_cont \
89
+ --z-cat-col z_cat \
90
+ --x-cols X1,X2,X3,X4 \
91
+ --sample-size 500 \
92
+ --nsim 1 \
93
+ --output-root data \
94
+ --run-label user_data
95
+ ```
96
+
97
+ For a five-minute setup path, see [QUICKSTART.md](QUICKSTART.md).
98
+
99
+ ## Architecture
100
+
101
+ ```text
102
+ Input cohorts
103
+ target, source, reference
104
+ ⬇️
105
+ Preprocessing and schema validation
106
+ ⬇️
107
+ Calibration artifacts from reference cohort
108
+ risk strata, external prevalence, X-support
109
+ ⬇️
110
+ Sampling paths
111
+ propensity-score matched source + random source
112
+ ⬇️
113
+ Model fitting
114
+ ML baseline + cMLE with calibration constraints
115
+ ⬇️
116
+ Evaluation and exports
117
+ estimates, ROC metrics, accuracy metrics, diagnostics, metadata
118
+ ```
119
+
120
+ The public CLI delegates to typed configuration objects in `risk_bridge.config`, orchestration in `risk_bridge.runs`, reusable pipeline helpers in `risk_bridge.pipeline`, and numerical components in `risk_bridge.likelihood`, `risk_bridge.constraints`, `risk_bridge.optimize`, and `risk_bridge.metrics`.
121
+
122
+ ## Library usage
123
+
124
+ ```python
125
+ from risk_bridge import UserDataRunConfig, UserDataSchema, run_user_data
126
+
127
+ run_dir = run_user_data(
128
+ UserDataRunConfig(
129
+ target_df=target_df,
130
+ source_df=source_df,
131
+ reference_df=reference_df,
132
+ schema=UserDataSchema(
133
+ x_cols=("X1", "X2", "X3", "X4"),
134
+ y_col="label",
135
+ z_origin_col="z_cont",
136
+ ),
137
+ sample_size=500,
138
+ output_root="data",
139
+ run_label="hospital_a",
140
+ )
141
+ )
142
+ print(run_dir)
143
+ ```
144
+
145
+ ## Outputs
146
+
147
+ Each run writes a timestamped directory under `output_root` with `intermediate/` and `final/` folders. Start with these final outputs:
148
+
149
+ - `final/run_metadata.csv` (includes `schema_version`, currently `1.1.0`)
150
+ - `final/fit_diagnostics.csv`
151
+ - `final/est_cml_psm.csv`
152
+ - `final/calibration_metrics.csv`
153
+ - `final/calibration_residuals.csv`
154
+ - `final/roc_metrics.csv`
155
+ - `final/accuracy_metrics.csv`
156
+
157
+ ## Reproduction
158
+
159
+ End-to-end regeneration commands for Scenario 2, numerical validation, and the
160
+ synthetic transport second example are in [REPRODUCTION.md](REPRODUCTION.md).
161
+ Cite this software with [CITATION.cff](CITATION.cff); add an archival DOI after
162
+ the Zenodo (or equivalent) deposit.
163
+
164
+ ## Repository layout
165
+
166
+ ```text
167
+ src/risk_bridge/ Python package source
168
+ tests/ Unit tests
169
+ cases/ Privacy-safe replication harnesses
170
+ examples/ Minimal runnable examples
171
+ docs/ Supplementary documentation
172
+ assets/ README visual assets
173
+ ```
174
+
175
+ ## Documentation
176
+
177
+ - [Quickstart](QUICKSTART.md)
178
+ - [Reproduction runbook](REPRODUCTION.md)
179
+ - [User guide](USER_GUIDE.md)
180
+ - [API reference](API_REFERENCE.md)
181
+ - [Architecture overview](ARCHITECTURE.md)
182
+ - [Pipeline architecture](docs/architecture/python_pipeline_analysis.md)
183
+ - [Solver strategy](docs/architecture/python_solver_strategy.md)
184
+ - [Replication cases](cases/README.md)
185
+ - [Changelog](CHANGELOG.md)
186
+ - [Citation](CITATION.cff)
187
+ - [License](LICENSE)
188
+
189
+ ## License
190
+
191
+ Risk Bridge is released under the Apache License 2.0.
@@ -0,0 +1,69 @@
1
+ [project]
2
+ name = "risk-bridge"
3
+ version = "1.0.1"
4
+ description = "Risk Bridging through Constrained MLE"
5
+ readme = "README.md"
6
+ requires-python = ">=3.11"
7
+ license = "Apache-2.0"
8
+ authors = [
9
+ { name = "Risk Bridge contributors" },
10
+ ]
11
+ keywords = ["risk-modeling", "calibration", "constrained-optimization", "maximum-likelihood", "biostatistics"]
12
+ classifiers = [
13
+ "Development Status :: 5 - Production/Stable",
14
+ "Intended Audience :: Science/Research",
15
+ "Programming Language :: Python :: 3.11",
16
+ "Programming Language :: Python :: 3.12",
17
+ "Programming Language :: Python :: 3.13",
18
+ "Topic :: Scientific/Engineering :: Medical Science Apps.",
19
+ "Topic :: Scientific/Engineering :: Mathematics",
20
+ ]
21
+ dependencies = [
22
+ "comp-builders>=1.0.0",
23
+ "numpy>=2.4.2",
24
+ "pandas>=3.0.1",
25
+ "polars>=1.38.1",
26
+ "rdata>=1.0.0",
27
+ "scikit-learn>=1.8.0",
28
+ "scipy>=1.17.1",
29
+ ]
30
+
31
+ [project.urls]
32
+ Homepage = "https://github.com/SaehwanPark/risk-bridge"
33
+ Repository = "https://github.com/SaehwanPark/risk-bridge"
34
+ Issues = "https://github.com/SaehwanPark/risk-bridge/issues"
35
+
36
+ [project.scripts]
37
+ risk-bridge = "risk_bridge.cli:main"
38
+
39
+ [build-system]
40
+ requires = ["setuptools>=80"]
41
+ build-backend = "setuptools.build_meta"
42
+
43
+ [tool.setuptools.packages.find]
44
+ where = ["src"]
45
+
46
+ [dependency-groups]
47
+ dev = [
48
+ "basedpyright>=1.39.6",
49
+ "matplotlib>=3.11.0",
50
+ "pytest>=9.0.2",
51
+ ]
52
+
53
+ [tool.basedpyright]
54
+ pythonVersion = "3.11"
55
+ typeCheckingMode = "standard"
56
+ include = [
57
+ "src/risk_bridge/api.py",
58
+ "src/risk_bridge/config.py",
59
+ "src/risk_bridge/pipeline.py",
60
+ "src/risk_bridge/cli.py",
61
+ "src/risk_bridge/types.py",
62
+ ]
63
+ reportMissingTypeStubs = false
64
+
65
+ [tool.pytest.ini_options]
66
+ testpaths = ["tests"]
67
+
68
+ [tool.uv]
69
+ package = true
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+