seminal 0.0.0a1__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.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Leonid Shpaner
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,168 @@
1
+ Metadata-Version: 2.4
2
+ Name: seminal
3
+ Version: 0.0.0a1
4
+ Summary: Published risk equations in andrology and male reproductive health: azoospermia probability from FSH and clinical inputs (Tradewell et al., World J Mens Health 2022)
5
+ Author-email: Leonid Shpaner <lshpaner@ucla.edu>
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/lshpaner/seminal
8
+ Project-URL: Documentation, https://lshpaner.github.io/seminal
9
+ Project-URL: Issues, https://github.com/lshpaner/seminal/issues
10
+ Keywords: andrology,urology,male infertility,azoospermia,fsh,semen analysis,risk prediction
11
+ Classifier: Programming Language :: Python :: 3
12
+ Classifier: Programming Language :: Python :: 3.8
13
+ Classifier: Programming Language :: Python :: 3.9
14
+ Classifier: Programming Language :: Python :: 3.10
15
+ Classifier: Programming Language :: Python :: 3.11
16
+ Classifier: Programming Language :: Python :: 3.12
17
+ Classifier: Programming Language :: Python :: 3.13
18
+ Classifier: Operating System :: OS Independent
19
+ Classifier: Intended Audience :: Science/Research
20
+ Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
21
+ Requires-Python: >=3.8
22
+ Description-Content-Type: text/markdown
23
+ License-File: LICENSE
24
+ Requires-Dist: numpy>=1.20
25
+ Requires-Dist: pandas>=1.3
26
+ Provides-Extra: dev
27
+ Requires-Dist: pytest>=7; extra == "dev"
28
+ Requires-Dist: pytest-cov; extra == "dev"
29
+ Requires-Dist: build; extra == "dev"
30
+ Requires-Dist: twine; extra == "dev"
31
+ Requires-Dist: nbstripout; extra == "dev"
32
+ Provides-Extra: data
33
+ Requires-Dist: requests; extra == "data"
34
+ Requires-Dist: typer; extra == "data"
35
+ Requires-Dist: pyarrow; extra == "data"
36
+ Requires-Dist: openpyxl; extra == "data"
37
+ Requires-Dist: ipykernel; extra == "data"
38
+ Requires-Dist: matplotlib; extra == "data"
39
+ Requires-Dist: model_metrics; extra == "data"
40
+ Requires-Dist: eda_toolkit; extra == "data"
41
+ Requires-Dist: statsmodels; extra == "data"
42
+ Requires-Dist: scikit-learn; extra == "data"
43
+ Requires-Dist: dcurves; extra == "data"
44
+ Provides-Extra: docs
45
+ Requires-Dist: sphinx; extra == "docs"
46
+ Requires-Dist: sphinx-rtd-theme; extra == "docs"
47
+ Requires-Dist: sphinx-copybutton; extra == "docs"
48
+ Requires-Dist: myst-nb; extra == "docs"
49
+ Requires-Dist: ipykernel; extra == "docs"
50
+ Dynamic: license-file
51
+
52
+ <img src="https://raw.githubusercontent.com/lshpaner/seminal/main/assets/seminal_logo.svg" width="300" style="border: none; outline: none; box-shadow: none;" oncontextmenu="return false;">
53
+
54
+ <br>
55
+
56
+ [![PyPI](https://img.shields.io/pypi/v/seminal.svg)](https://pypi.org/project/seminal/)
57
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/lshpaner/seminal/tree/main?tab=MIT-1-ov-file)
58
+
59
+ `seminal` is a Python library of published risk equations in andrology and male reproductive health, implemented with the coefficients exactly as printed in the source papers and checked against the authors' own validation data.
60
+
61
+ The first release implements the two azoospermia prediction models of Tradewell et al. (World J Mens Health 2022): a quadratic in serum FSH alone, and a logistic regression on age, FSH, LH, total testosterone and mean testis volume. Both estimate the probability that a man presenting for infertility evaluation has no sperm in the ejaculate, without a semen analysis.
62
+
63
+ > **Not affiliated with the original authors.** This is an independent implementation of published equations, intended for research use. It is not a medical device and should not be used to make clinical decisions.
64
+
65
+ ## Installation
66
+
67
+ ```bash
68
+ pip install seminal
69
+ ```
70
+
71
+ Requires Python 3.8+, numpy 1.20+ and pandas 1.3+.
72
+
73
+ ## Usage
74
+
75
+ ### FSH alone
76
+
77
+ ```python
78
+ from seminal import azoospermia_fsh
79
+
80
+ azoospermia_fsh(20)
81
+ # 0.439
82
+ ```
83
+
84
+ The published curve is U-shaped: 10.1% at undetectable FSH, a minimum of about 8.4% at FSH 3.6 IU/L, and 100% from about 30 IU/L. Output is clipped to [0, 1]; pass `clip=False` to reproduce the paper's unbounded quadratic.
85
+
86
+ ### Full logistic model
87
+
88
+ ```python
89
+ from seminal import azoospermia_lr
90
+
91
+ azoospermia_lr(age=36, fsh=5.7, lh=4.5, testosterone=429, testis_volume=15)
92
+ # 0.086
93
+ ```
94
+
95
+ Pass `explain=True` to also get the linear predictor and each input's contribution to the log-odds, largest first.
96
+
97
+ ### A whole cohort
98
+
99
+ ```python
100
+ from seminal import add_azoospermia_risk_cols
101
+
102
+ scored = add_azoospermia_risk_cols(
103
+ df, age_col="age", fsh_col="fsh", lh_col="lh",
104
+ testosterone_col="testosterone", testis_volume_col="testis_volume",
105
+ )
106
+ scored[["azoo_fsh", "azoo_lr"]]
107
+ ```
108
+
109
+ Rows missing any logistic-model input get `NaN` in `azoo_lr`; `azoo_fsh` needs only FSH.
110
+
111
+ ## The equations
112
+
113
+ **FSH-only quadratic** (Fig. 1): `p(%) = 0.133·FSH² − 0.965·FSH + 10.1`, fit to binned Miami probabilities, R² = 0.95.
114
+
115
+ **Logistic regression** (Table 3): `p = 1 / (1 + exp(−η))` where
116
+
117
+ | Term | Units | Coefficient |
118
+ |---|---|---|
119
+ | Intercept | | −1.9 |
120
+ | Age | years | 0.02 |
121
+ | FSH | IU/L | 0.13 |
122
+ | LH | IU/L | 0.03 |
123
+ | Total testosterone | ng/dL | −0.002 |
124
+ | Mean testis volume | cm³ (Prader orchidometer) | −0.08 |
125
+
126
+ The paper prints the model form as `1/exp[−(b₀ + bᵢXᵢ)]`, which is a typesetting error (it exceeds 1); the standard logistic form is used here.
127
+
128
+ ## Validation against the authors' data
129
+
130
+ The study data are public under CC0 on [Harvard Dataverse](https://doi.org/10.7910/DVN/EQFMCM). `make data_gen preprocess` downloads them into `data/` (gitignored) and the test suite then checks the implementation against the paper's external validation:
131
+
132
+ | Site | n | AUC, logistic (paper) | AUC, FSH-only (paper) |
133
+ |---|---|---|---|
134
+ | Milan | 1,955 | 0.786 (0.79) | 0.786 (0.78) |
135
+ | Chicago | 614 | 0.723 (0.72) | 0.708 (0.71) |
136
+
137
+ ### Things to know about the data
138
+
139
+ - The deposit contains all three sites as separate sheets. Miami (1,070 rows) and Chicago (643) are pre-exclusion; applying the paper's stated exclusions (prior vasectomy, Y microdeletion, solitary testis, testosterone or steroid use) gives 943 and 614 versus the paper's 946 and 596. Milan (1,955) matches exactly.
140
+ - Chicago testis volumes are ultrasound long-axis measurements in cm (median 4.5), not orchidometer volumes in mL (median 14 to 15 at Miami and Milan). The paper does not address this; `preprocessing.py` labels the measurement method per site.
141
+ - The logistic coefficients are printed to one or two significant figures. At the extremes of testosterone and age this rounding alone can move the log-odds by several tenths. A refit on the Miami data recovers full-precision values; that is planned for a later release and kept separate from the as-published model.
142
+ - Azoospermia was confirmed on at least two semen analyses. The outcome in the Miami and Chicago sheets is sperm concentration = 0; Milan carries an explicit flag plus obstructive/non-obstructive type.
143
+
144
+ ## Repository layout
145
+
146
+ ```
147
+ seminal/
148
+ ├── src/seminal/ the package (equations only; no data)
149
+ ├── tests/ unit tests plus optional validation against data/
150
+ ├── data_gen.py download the Dataverse file into data/raw
151
+ ├── preprocessing.py harmonize sites into data/processed
152
+ ├── notebooks/ worked examples
153
+ └── Makefile venv, install, test, data_gen, preprocess, build
154
+ ```
155
+
156
+ ## Citation
157
+
158
+ If you use `seminal`, please cite the software (see `CITATION.cff`) and the original paper:
159
+
160
+ Tradewell MB, Cazzaniga W, Pagani RL, et al. Algorithms for Predicting the Probability of Azoospermia from Follicle Stimulating Hormone: Design and Multi-Institutional External Validation. *World J Mens Health*. 2022;40(4):600-607. doi:10.5534/wjmh.210138
161
+
162
+ ## License
163
+
164
+ MIT. The study data on Dataverse are CC0.
165
+
166
+ ## Author
167
+
168
+ Leonid Shpaner, Health Analytics Data Scientist, UCLA Health CTSI. [leonshpaner.com](https://www.leonshpaner.com)
@@ -0,0 +1,117 @@
1
+ <img src="https://raw.githubusercontent.com/lshpaner/seminal/main/assets/seminal_logo.svg" width="300" style="border: none; outline: none; box-shadow: none;" oncontextmenu="return false;">
2
+
3
+ <br>
4
+
5
+ [![PyPI](https://img.shields.io/pypi/v/seminal.svg)](https://pypi.org/project/seminal/)
6
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/lshpaner/seminal/tree/main?tab=MIT-1-ov-file)
7
+
8
+ `seminal` is a Python library of published risk equations in andrology and male reproductive health, implemented with the coefficients exactly as printed in the source papers and checked against the authors' own validation data.
9
+
10
+ The first release implements the two azoospermia prediction models of Tradewell et al. (World J Mens Health 2022): a quadratic in serum FSH alone, and a logistic regression on age, FSH, LH, total testosterone and mean testis volume. Both estimate the probability that a man presenting for infertility evaluation has no sperm in the ejaculate, without a semen analysis.
11
+
12
+ > **Not affiliated with the original authors.** This is an independent implementation of published equations, intended for research use. It is not a medical device and should not be used to make clinical decisions.
13
+
14
+ ## Installation
15
+
16
+ ```bash
17
+ pip install seminal
18
+ ```
19
+
20
+ Requires Python 3.8+, numpy 1.20+ and pandas 1.3+.
21
+
22
+ ## Usage
23
+
24
+ ### FSH alone
25
+
26
+ ```python
27
+ from seminal import azoospermia_fsh
28
+
29
+ azoospermia_fsh(20)
30
+ # 0.439
31
+ ```
32
+
33
+ The published curve is U-shaped: 10.1% at undetectable FSH, a minimum of about 8.4% at FSH 3.6 IU/L, and 100% from about 30 IU/L. Output is clipped to [0, 1]; pass `clip=False` to reproduce the paper's unbounded quadratic.
34
+
35
+ ### Full logistic model
36
+
37
+ ```python
38
+ from seminal import azoospermia_lr
39
+
40
+ azoospermia_lr(age=36, fsh=5.7, lh=4.5, testosterone=429, testis_volume=15)
41
+ # 0.086
42
+ ```
43
+
44
+ Pass `explain=True` to also get the linear predictor and each input's contribution to the log-odds, largest first.
45
+
46
+ ### A whole cohort
47
+
48
+ ```python
49
+ from seminal import add_azoospermia_risk_cols
50
+
51
+ scored = add_azoospermia_risk_cols(
52
+ df, age_col="age", fsh_col="fsh", lh_col="lh",
53
+ testosterone_col="testosterone", testis_volume_col="testis_volume",
54
+ )
55
+ scored[["azoo_fsh", "azoo_lr"]]
56
+ ```
57
+
58
+ Rows missing any logistic-model input get `NaN` in `azoo_lr`; `azoo_fsh` needs only FSH.
59
+
60
+ ## The equations
61
+
62
+ **FSH-only quadratic** (Fig. 1): `p(%) = 0.133·FSH² − 0.965·FSH + 10.1`, fit to binned Miami probabilities, R² = 0.95.
63
+
64
+ **Logistic regression** (Table 3): `p = 1 / (1 + exp(−η))` where
65
+
66
+ | Term | Units | Coefficient |
67
+ |---|---|---|
68
+ | Intercept | | −1.9 |
69
+ | Age | years | 0.02 |
70
+ | FSH | IU/L | 0.13 |
71
+ | LH | IU/L | 0.03 |
72
+ | Total testosterone | ng/dL | −0.002 |
73
+ | Mean testis volume | cm³ (Prader orchidometer) | −0.08 |
74
+
75
+ The paper prints the model form as `1/exp[−(b₀ + bᵢXᵢ)]`, which is a typesetting error (it exceeds 1); the standard logistic form is used here.
76
+
77
+ ## Validation against the authors' data
78
+
79
+ The study data are public under CC0 on [Harvard Dataverse](https://doi.org/10.7910/DVN/EQFMCM). `make data_gen preprocess` downloads them into `data/` (gitignored) and the test suite then checks the implementation against the paper's external validation:
80
+
81
+ | Site | n | AUC, logistic (paper) | AUC, FSH-only (paper) |
82
+ |---|---|---|---|
83
+ | Milan | 1,955 | 0.786 (0.79) | 0.786 (0.78) |
84
+ | Chicago | 614 | 0.723 (0.72) | 0.708 (0.71) |
85
+
86
+ ### Things to know about the data
87
+
88
+ - The deposit contains all three sites as separate sheets. Miami (1,070 rows) and Chicago (643) are pre-exclusion; applying the paper's stated exclusions (prior vasectomy, Y microdeletion, solitary testis, testosterone or steroid use) gives 943 and 614 versus the paper's 946 and 596. Milan (1,955) matches exactly.
89
+ - Chicago testis volumes are ultrasound long-axis measurements in cm (median 4.5), not orchidometer volumes in mL (median 14 to 15 at Miami and Milan). The paper does not address this; `preprocessing.py` labels the measurement method per site.
90
+ - The logistic coefficients are printed to one or two significant figures. At the extremes of testosterone and age this rounding alone can move the log-odds by several tenths. A refit on the Miami data recovers full-precision values; that is planned for a later release and kept separate from the as-published model.
91
+ - Azoospermia was confirmed on at least two semen analyses. The outcome in the Miami and Chicago sheets is sperm concentration = 0; Milan carries an explicit flag plus obstructive/non-obstructive type.
92
+
93
+ ## Repository layout
94
+
95
+ ```
96
+ seminal/
97
+ ├── src/seminal/ the package (equations only; no data)
98
+ ├── tests/ unit tests plus optional validation against data/
99
+ ├── data_gen.py download the Dataverse file into data/raw
100
+ ├── preprocessing.py harmonize sites into data/processed
101
+ ├── notebooks/ worked examples
102
+ └── Makefile venv, install, test, data_gen, preprocess, build
103
+ ```
104
+
105
+ ## Citation
106
+
107
+ If you use `seminal`, please cite the software (see `CITATION.cff`) and the original paper:
108
+
109
+ Tradewell MB, Cazzaniga W, Pagani RL, et al. Algorithms for Predicting the Probability of Azoospermia from Follicle Stimulating Hormone: Design and Multi-Institutional External Validation. *World J Mens Health*. 2022;40(4):600-607. doi:10.5534/wjmh.210138
110
+
111
+ ## License
112
+
113
+ MIT. The study data on Dataverse are CC0.
114
+
115
+ ## Author
116
+
117
+ Leonid Shpaner, Health Analytics Data Scientist, UCLA Health CTSI. [leonshpaner.com](https://www.leonshpaner.com)
@@ -0,0 +1,48 @@
1
+ [build-system]
2
+ requires = ["setuptools>=77.0"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "seminal"
7
+ version = "0.0.0a1"
8
+ description = "Published risk equations in andrology and male reproductive health: azoospermia probability from FSH and clinical inputs (Tradewell et al., World J Mens Health 2022)"
9
+ readme = "README.md"
10
+ license = "MIT"
11
+ license-files = ["LICENSE"]
12
+ authors = [{ name = "Leonid Shpaner", email = "lshpaner@ucla.edu" }]
13
+ requires-python = ">=3.8"
14
+ dependencies = ["numpy>=1.20", "pandas>=1.3"]
15
+ keywords = ["andrology", "urology", "male infertility", "azoospermia", "fsh", "semen analysis", "risk prediction"]
16
+ classifiers = [
17
+ "Programming Language :: Python :: 3",
18
+ "Programming Language :: Python :: 3.8",
19
+ "Programming Language :: Python :: 3.9",
20
+ "Programming Language :: Python :: 3.10",
21
+ "Programming Language :: Python :: 3.11",
22
+ "Programming Language :: Python :: 3.12",
23
+ "Programming Language :: Python :: 3.13",
24
+ "Operating System :: OS Independent",
25
+ "Intended Audience :: Science/Research",
26
+ "Topic :: Scientific/Engineering :: Medical Science Apps.",
27
+ ]
28
+
29
+ [project.optional-dependencies]
30
+ dev = ["pytest>=7", "pytest-cov", "build", "twine", "nbstripout"]
31
+ data = ["requests", "typer", "pyarrow", "openpyxl", "ipykernel", "matplotlib", "model_metrics", "eda_toolkit", "statsmodels", "scikit-learn", "dcurves"]
32
+ docs = ["sphinx", "sphinx-rtd-theme", "sphinx-copybutton", "myst-nb", "ipykernel"]
33
+
34
+ [project.urls]
35
+ Homepage = "https://github.com/lshpaner/seminal"
36
+ Documentation = "https://lshpaner.github.io/seminal"
37
+ Issues = "https://github.com/lshpaner/seminal/issues"
38
+
39
+ [tool.setuptools.packages.find]
40
+ where = ["src"]
41
+
42
+ [tool.pytest.ini_options]
43
+ testpaths = ["tests"]
44
+ pythonpath = ["src"]
45
+
46
+ [tool.coverage.run]
47
+ source = ["src/seminal"]
48
+ branch = false
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,44 @@
1
+ import sys
2
+ import builtins
3
+ from .logo import *
4
+
5
+ from .azoospermia import *
6
+
7
+ detailed_doc = """
8
+ seminal: Male Reproductive Risk Equations in Python
9
+ ========================================================================================
10
+
11
+ `seminal` implements published risk equations in andrology and male reproductive health,
12
+ with coefficients taken exactly as printed in the source papers.
13
+
14
+ Currently included (Tradewell et al., World J Mens Health 2022):
15
+ * azoospermia_fsh probability of azoospermia from serum FSH alone (quadratic)
16
+ * azoospermia_lr probability of azoospermia from age, FSH, LH, testosterone
17
+ and mean testis volume (logistic regression)
18
+ * add_azoospermia_risk_cols score a whole cohort in a DataFrame
19
+
20
+ Not affiliated with the original authors. For research use only.
21
+
22
+ PyPI: https://pypi.org/project/seminal/
23
+ GitHub: https://github.com/lshpaner/seminal
24
+
25
+ Version: 0.0.0a1
26
+
27
+ """
28
+
29
+ __author__ = "Leonid Shpaner"
30
+ __email__ = "lshpaner@ucla.edu"
31
+ __version__ = "0.0.0a1"
32
+
33
+
34
+ def custom_help(obj=None):
35
+ """Custom help function to include the ASCII logo in help() output."""
36
+ if obj is None or obj is sys.modules[__name__]:
37
+ print(seminal_logo)
38
+ print(detailed_doc)
39
+ else:
40
+ original_help(obj)
41
+
42
+
43
+ original_help = builtins.help
44
+ builtins.help = custom_help
@@ -0,0 +1,222 @@
1
+ """Probability of azoospermia from serum FSH and clinical inputs.
2
+
3
+ Implements the two models of Tradewell et al., World J Mens Health
4
+ 2022;40(4):600-607 (doi:10.5534/wjmh.210138), developed on 946 men from
5
+ the University of Miami infertility clinic and externally validated on
6
+ Milan (n=1,955) and Chicago (n=596):
7
+
8
+ * ``azoospermia_fsh``: a quadratic in serum FSH alone (Fig. 1 of the paper).
9
+ * ``azoospermia_lr``: a logistic regression on age, FSH, LH, total
10
+ testosterone and mean testis volume (Table 3 of the paper).
11
+
12
+ Both coefficients sets are used exactly as printed. The paper rounds the
13
+ logistic coefficients to one or two significant figures; see the README
14
+ for what that implies.
15
+ """
16
+
17
+ import math
18
+
19
+ import numpy as np
20
+ import pandas as pd
21
+
22
+ # ---------------------------------------------------------------------------
23
+ # Published coefficients
24
+ # ---------------------------------------------------------------------------
25
+
26
+ # Table 3. Logistic regression model coefficients (log-odds scale).
27
+ # Fit on Miami data (n=946). Units: age in years, FSH and LH in IU/L,
28
+ # total testosterone in ng/dL, mean testis volume in cm^3 (Prader orchidometer).
29
+ LR_COEFS = {
30
+ "intercept": -1.9,
31
+ "age": 0.02,
32
+ "fsh": 0.13,
33
+ "lh": 0.03,
34
+ "testosterone": -0.002,
35
+ "testis_volume": -0.08,
36
+ }
37
+
38
+ # Fig. 1. Quadratic fit to binned Miami probabilities, output in percent:
39
+ # p(%) = 0.133 * FSH^2 - 0.965 * FSH + 10.1 (R^2 = 0.95)
40
+ FSH_QUAD = {"a": 0.133, "b": -0.965, "c": 10.1}
41
+
42
+ # Reference limits quoted in the paper (Methods), used only for input warnings.
43
+ REFERENCE_RANGES = {
44
+ "fsh": (1.5, 7.6), # IU/L
45
+ "lh": (1.8, 8.6), # IU/L
46
+ "testosterone": (264, 916), # ng/dL
47
+ "testis_volume": (12.5, 19), # cm^3, mean of both testes
48
+ }
49
+
50
+
51
+ # ---------------------------------------------------------------------------
52
+ # FSH-only quadratic model
53
+ # ---------------------------------------------------------------------------
54
+
55
+ def azoospermia_fsh(fsh, clip=True):
56
+ """Probability of azoospermia from serum FSH alone (quadratic model).
57
+
58
+ Parameters
59
+ ----------
60
+ fsh : float or array-like
61
+ Serum follicle-stimulating hormone in IU/L.
62
+ clip : bool, default True
63
+ Clip the result to [0, 1]. The published quadratic exceeds 100%
64
+ above roughly 30 IU/L and is unbounded; the paper's own validation
65
+ tables carry unclipped values above 1. Set ``clip=False`` to
66
+ reproduce that behaviour exactly.
67
+
68
+ Returns
69
+ -------
70
+ float or numpy.ndarray
71
+ Probability between 0 and 1 (a fraction, not a percent).
72
+
73
+ Notes
74
+ -----
75
+ The curve is U-shaped: 10.1% at undetectable FSH, a minimum of about
76
+ 8.4% at FSH 3.6 IU/L, and 100% at about 29.9 IU/L.
77
+
78
+ Examples
79
+ --------
80
+ >>> round(azoospermia_fsh(0), 3)
81
+ 0.101
82
+ >>> round(azoospermia_fsh(20), 3)
83
+ 0.439
84
+ """
85
+ x = np.asarray(fsh, dtype=float)
86
+ pct = FSH_QUAD["a"] * x**2 + FSH_QUAD["b"] * x + FSH_QUAD["c"]
87
+ p = pct / 100.0
88
+ if clip:
89
+ p = np.clip(p, 0.0, 1.0)
90
+ return float(p) if p.ndim == 0 else p
91
+
92
+
93
+ # ---------------------------------------------------------------------------
94
+ # Logistic regression model
95
+ # ---------------------------------------------------------------------------
96
+
97
+ def _lr_terms(age, fsh, lh, testosterone, testis_volume):
98
+ b = LR_COEFS
99
+ return {
100
+ "age": b["age"] * age,
101
+ "fsh": b["fsh"] * fsh,
102
+ "lh": b["lh"] * lh,
103
+ "testosterone": b["testosterone"] * testosterone,
104
+ "testis_volume": b["testis_volume"] * testis_volume,
105
+ }
106
+
107
+
108
+ def azoospermia_lr(age, fsh, lh, testosterone, testis_volume, explain=False):
109
+ """Probability of azoospermia from the logistic regression model.
110
+
111
+ Parameters
112
+ ----------
113
+ age : float
114
+ Age in years.
115
+ fsh : float
116
+ Serum FSH in IU/L.
117
+ lh : float
118
+ Serum luteinizing hormone in IU/L.
119
+ testosterone : float
120
+ Total testosterone in ng/dL. (Divide nmol/L by 0.03467 to convert.)
121
+ testis_volume : float
122
+ Mean of left and right testis volume in cm^3 (mL), as estimated by
123
+ Prader orchidometer in the development cohort.
124
+ explain : bool, default False
125
+ Return a breakdown instead of just the probability.
126
+
127
+ Returns
128
+ -------
129
+ float or dict
130
+ Probability between 0 and 1. With ``explain=True``, a dict with
131
+ ``risk``, ``intercept``, ``linear_predictor`` (log-odds) and
132
+ ``contributions`` (each predictor's log-odds term, largest first).
133
+
134
+ Notes
135
+ -----
136
+ The paper prints the model form as ``1/exp[-(b0 + bi*Xi)]``, which is a
137
+ typesetting error (it would exceed 1). The standard logistic form
138
+ ``1/(1 + exp(-(b0 + sum(bi*Xi))))`` is used here.
139
+
140
+ Examples
141
+ --------
142
+ >>> round(azoospermia_lr(age=36, fsh=5.7, lh=4.5, testosterone=429,
143
+ ... testis_volume=15), 3)
144
+ 0.086
145
+ """
146
+ terms = _lr_terms(age, fsh, lh, testosterone, testis_volume)
147
+ lp = LR_COEFS["intercept"] + sum(terms.values())
148
+ risk = 1.0 / (1.0 + math.exp(-lp))
149
+ if not explain:
150
+ return risk
151
+ return {
152
+ "risk": risk,
153
+ "intercept": LR_COEFS["intercept"],
154
+ "linear_predictor": lp,
155
+ "contributions": dict(sorted(terms.items(), key=lambda kv: -abs(kv[1]))),
156
+ }
157
+
158
+
159
+ # ---------------------------------------------------------------------------
160
+ # Cohort scoring
161
+ # ---------------------------------------------------------------------------
162
+
163
+ def add_azoospermia_risk_cols(
164
+ df,
165
+ age_col="age",
166
+ fsh_col="fsh",
167
+ lh_col="lh",
168
+ testosterone_col="testosterone",
169
+ testis_volume_col="testis_volume",
170
+ lr_col="azoo_lr",
171
+ fsh_model_col="azoo_fsh",
172
+ copy=True,
173
+ ):
174
+ """Add both azoospermia probabilities to every row of a DataFrame.
175
+
176
+ Parameters
177
+ ----------
178
+ df : pandas.DataFrame
179
+ One row per semen analysis / hormone panel.
180
+ age_col, fsh_col, lh_col, testosterone_col, testis_volume_col : str
181
+ Column names for the five logistic-model inputs. Only ``fsh_col``
182
+ is needed for the FSH-only model.
183
+ lr_col : str, default "azoo_lr"
184
+ Name of the logistic regression probability column.
185
+ fsh_model_col : str, default "azoo_fsh"
186
+ Name of the FSH-only quadratic probability column.
187
+ copy : bool, default True
188
+ Work on a copy and leave ``df`` unchanged.
189
+
190
+ Returns
191
+ -------
192
+ pandas.DataFrame
193
+ ``df`` (or a copy) with the two probability columns added. A row
194
+ with any logistic-model input missing gets ``NaN`` in ``lr_col``;
195
+ the FSH-only column needs only FSH.
196
+ """
197
+ out = df.copy() if copy else df
198
+ b = LR_COEFS
199
+
200
+ fsh = pd.to_numeric(out[fsh_col], errors="coerce")
201
+ out[fsh_model_col] = azoospermia_fsh(fsh.to_numpy())
202
+
203
+ lp = (
204
+ b["intercept"]
205
+ + b["age"] * pd.to_numeric(out[age_col], errors="coerce")
206
+ + b["fsh"] * fsh
207
+ + b["lh"] * pd.to_numeric(out[lh_col], errors="coerce")
208
+ + b["testosterone"] * pd.to_numeric(out[testosterone_col], errors="coerce")
209
+ + b["testis_volume"] * pd.to_numeric(out[testis_volume_col], errors="coerce")
210
+ )
211
+ out[lr_col] = 1.0 / (1.0 + np.exp(-lp))
212
+ return out
213
+
214
+
215
+ __all__ = [
216
+ "LR_COEFS",
217
+ "FSH_QUAD",
218
+ "REFERENCE_RANGES",
219
+ "azoospermia_fsh",
220
+ "azoospermia_lr",
221
+ "add_azoospermia_risk_cols",
222
+ ]
@@ -0,0 +1,13 @@
1
+ """ASCII logo shown by help(seminal)."""
2
+
3
+ seminal_logo = r"""
4
+ ███████╗███████╗███╗ ███╗██╗███╗ ██╗ █████╗ ██╗
5
+ ██╔════╝██╔════╝████╗ ████║██║████╗ ██║██╔══██╗██║
6
+ ███████╗█████╗ ██╔████╔██║██║██╔██╗ ██║███████║██║
7
+ ╚════██║██╔══╝ ██║╚██╔╝██║██║██║╚██╗██║██╔══██║██║
8
+ ███████║███████╗██║ ╚═╝ ██║██║██║ ╚████║██║ ██║███████╗
9
+ ╚══════╝╚══════╝╚═╝ ╚═╝╚═╝╚═╝ ╚═══╝╚═╝ ╚═╝╚══════╝
10
+
11
+ """
12
+
13
+ __all__ = ["seminal_logo"]
@@ -0,0 +1,168 @@
1
+ Metadata-Version: 2.4
2
+ Name: seminal
3
+ Version: 0.0.0a1
4
+ Summary: Published risk equations in andrology and male reproductive health: azoospermia probability from FSH and clinical inputs (Tradewell et al., World J Mens Health 2022)
5
+ Author-email: Leonid Shpaner <lshpaner@ucla.edu>
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/lshpaner/seminal
8
+ Project-URL: Documentation, https://lshpaner.github.io/seminal
9
+ Project-URL: Issues, https://github.com/lshpaner/seminal/issues
10
+ Keywords: andrology,urology,male infertility,azoospermia,fsh,semen analysis,risk prediction
11
+ Classifier: Programming Language :: Python :: 3
12
+ Classifier: Programming Language :: Python :: 3.8
13
+ Classifier: Programming Language :: Python :: 3.9
14
+ Classifier: Programming Language :: Python :: 3.10
15
+ Classifier: Programming Language :: Python :: 3.11
16
+ Classifier: Programming Language :: Python :: 3.12
17
+ Classifier: Programming Language :: Python :: 3.13
18
+ Classifier: Operating System :: OS Independent
19
+ Classifier: Intended Audience :: Science/Research
20
+ Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
21
+ Requires-Python: >=3.8
22
+ Description-Content-Type: text/markdown
23
+ License-File: LICENSE
24
+ Requires-Dist: numpy>=1.20
25
+ Requires-Dist: pandas>=1.3
26
+ Provides-Extra: dev
27
+ Requires-Dist: pytest>=7; extra == "dev"
28
+ Requires-Dist: pytest-cov; extra == "dev"
29
+ Requires-Dist: build; extra == "dev"
30
+ Requires-Dist: twine; extra == "dev"
31
+ Requires-Dist: nbstripout; extra == "dev"
32
+ Provides-Extra: data
33
+ Requires-Dist: requests; extra == "data"
34
+ Requires-Dist: typer; extra == "data"
35
+ Requires-Dist: pyarrow; extra == "data"
36
+ Requires-Dist: openpyxl; extra == "data"
37
+ Requires-Dist: ipykernel; extra == "data"
38
+ Requires-Dist: matplotlib; extra == "data"
39
+ Requires-Dist: model_metrics; extra == "data"
40
+ Requires-Dist: eda_toolkit; extra == "data"
41
+ Requires-Dist: statsmodels; extra == "data"
42
+ Requires-Dist: scikit-learn; extra == "data"
43
+ Requires-Dist: dcurves; extra == "data"
44
+ Provides-Extra: docs
45
+ Requires-Dist: sphinx; extra == "docs"
46
+ Requires-Dist: sphinx-rtd-theme; extra == "docs"
47
+ Requires-Dist: sphinx-copybutton; extra == "docs"
48
+ Requires-Dist: myst-nb; extra == "docs"
49
+ Requires-Dist: ipykernel; extra == "docs"
50
+ Dynamic: license-file
51
+
52
+ <img src="https://raw.githubusercontent.com/lshpaner/seminal/main/assets/seminal_logo.svg" width="300" style="border: none; outline: none; box-shadow: none;" oncontextmenu="return false;">
53
+
54
+ <br>
55
+
56
+ [![PyPI](https://img.shields.io/pypi/v/seminal.svg)](https://pypi.org/project/seminal/)
57
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/lshpaner/seminal/tree/main?tab=MIT-1-ov-file)
58
+
59
+ `seminal` is a Python library of published risk equations in andrology and male reproductive health, implemented with the coefficients exactly as printed in the source papers and checked against the authors' own validation data.
60
+
61
+ The first release implements the two azoospermia prediction models of Tradewell et al. (World J Mens Health 2022): a quadratic in serum FSH alone, and a logistic regression on age, FSH, LH, total testosterone and mean testis volume. Both estimate the probability that a man presenting for infertility evaluation has no sperm in the ejaculate, without a semen analysis.
62
+
63
+ > **Not affiliated with the original authors.** This is an independent implementation of published equations, intended for research use. It is not a medical device and should not be used to make clinical decisions.
64
+
65
+ ## Installation
66
+
67
+ ```bash
68
+ pip install seminal
69
+ ```
70
+
71
+ Requires Python 3.8+, numpy 1.20+ and pandas 1.3+.
72
+
73
+ ## Usage
74
+
75
+ ### FSH alone
76
+
77
+ ```python
78
+ from seminal import azoospermia_fsh
79
+
80
+ azoospermia_fsh(20)
81
+ # 0.439
82
+ ```
83
+
84
+ The published curve is U-shaped: 10.1% at undetectable FSH, a minimum of about 8.4% at FSH 3.6 IU/L, and 100% from about 30 IU/L. Output is clipped to [0, 1]; pass `clip=False` to reproduce the paper's unbounded quadratic.
85
+
86
+ ### Full logistic model
87
+
88
+ ```python
89
+ from seminal import azoospermia_lr
90
+
91
+ azoospermia_lr(age=36, fsh=5.7, lh=4.5, testosterone=429, testis_volume=15)
92
+ # 0.086
93
+ ```
94
+
95
+ Pass `explain=True` to also get the linear predictor and each input's contribution to the log-odds, largest first.
96
+
97
+ ### A whole cohort
98
+
99
+ ```python
100
+ from seminal import add_azoospermia_risk_cols
101
+
102
+ scored = add_azoospermia_risk_cols(
103
+ df, age_col="age", fsh_col="fsh", lh_col="lh",
104
+ testosterone_col="testosterone", testis_volume_col="testis_volume",
105
+ )
106
+ scored[["azoo_fsh", "azoo_lr"]]
107
+ ```
108
+
109
+ Rows missing any logistic-model input get `NaN` in `azoo_lr`; `azoo_fsh` needs only FSH.
110
+
111
+ ## The equations
112
+
113
+ **FSH-only quadratic** (Fig. 1): `p(%) = 0.133·FSH² − 0.965·FSH + 10.1`, fit to binned Miami probabilities, R² = 0.95.
114
+
115
+ **Logistic regression** (Table 3): `p = 1 / (1 + exp(−η))` where
116
+
117
+ | Term | Units | Coefficient |
118
+ |---|---|---|
119
+ | Intercept | | −1.9 |
120
+ | Age | years | 0.02 |
121
+ | FSH | IU/L | 0.13 |
122
+ | LH | IU/L | 0.03 |
123
+ | Total testosterone | ng/dL | −0.002 |
124
+ | Mean testis volume | cm³ (Prader orchidometer) | −0.08 |
125
+
126
+ The paper prints the model form as `1/exp[−(b₀ + bᵢXᵢ)]`, which is a typesetting error (it exceeds 1); the standard logistic form is used here.
127
+
128
+ ## Validation against the authors' data
129
+
130
+ The study data are public under CC0 on [Harvard Dataverse](https://doi.org/10.7910/DVN/EQFMCM). `make data_gen preprocess` downloads them into `data/` (gitignored) and the test suite then checks the implementation against the paper's external validation:
131
+
132
+ | Site | n | AUC, logistic (paper) | AUC, FSH-only (paper) |
133
+ |---|---|---|---|
134
+ | Milan | 1,955 | 0.786 (0.79) | 0.786 (0.78) |
135
+ | Chicago | 614 | 0.723 (0.72) | 0.708 (0.71) |
136
+
137
+ ### Things to know about the data
138
+
139
+ - The deposit contains all three sites as separate sheets. Miami (1,070 rows) and Chicago (643) are pre-exclusion; applying the paper's stated exclusions (prior vasectomy, Y microdeletion, solitary testis, testosterone or steroid use) gives 943 and 614 versus the paper's 946 and 596. Milan (1,955) matches exactly.
140
+ - Chicago testis volumes are ultrasound long-axis measurements in cm (median 4.5), not orchidometer volumes in mL (median 14 to 15 at Miami and Milan). The paper does not address this; `preprocessing.py` labels the measurement method per site.
141
+ - The logistic coefficients are printed to one or two significant figures. At the extremes of testosterone and age this rounding alone can move the log-odds by several tenths. A refit on the Miami data recovers full-precision values; that is planned for a later release and kept separate from the as-published model.
142
+ - Azoospermia was confirmed on at least two semen analyses. The outcome in the Miami and Chicago sheets is sperm concentration = 0; Milan carries an explicit flag plus obstructive/non-obstructive type.
143
+
144
+ ## Repository layout
145
+
146
+ ```
147
+ seminal/
148
+ ├── src/seminal/ the package (equations only; no data)
149
+ ├── tests/ unit tests plus optional validation against data/
150
+ ├── data_gen.py download the Dataverse file into data/raw
151
+ ├── preprocessing.py harmonize sites into data/processed
152
+ ├── notebooks/ worked examples
153
+ └── Makefile venv, install, test, data_gen, preprocess, build
154
+ ```
155
+
156
+ ## Citation
157
+
158
+ If you use `seminal`, please cite the software (see `CITATION.cff`) and the original paper:
159
+
160
+ Tradewell MB, Cazzaniga W, Pagani RL, et al. Algorithms for Predicting the Probability of Azoospermia from Follicle Stimulating Hormone: Design and Multi-Institutional External Validation. *World J Mens Health*. 2022;40(4):600-607. doi:10.5534/wjmh.210138
161
+
162
+ ## License
163
+
164
+ MIT. The study data on Dataverse are CC0.
165
+
166
+ ## Author
167
+
168
+ Leonid Shpaner, Health Analytics Data Scientist, UCLA Health CTSI. [leonshpaner.com](https://www.leonshpaner.com)
@@ -0,0 +1,12 @@
1
+ LICENSE
2
+ README.md
3
+ pyproject.toml
4
+ src/seminal/__init__.py
5
+ src/seminal/azoospermia.py
6
+ src/seminal/logo.py
7
+ src/seminal.egg-info/PKG-INFO
8
+ src/seminal.egg-info/SOURCES.txt
9
+ src/seminal.egg-info/dependency_links.txt
10
+ src/seminal.egg-info/requires.txt
11
+ src/seminal.egg-info/top_level.txt
12
+ tests/test_azoospermia.py
@@ -0,0 +1,29 @@
1
+ numpy>=1.20
2
+ pandas>=1.3
3
+
4
+ [data]
5
+ requests
6
+ typer
7
+ pyarrow
8
+ openpyxl
9
+ ipykernel
10
+ matplotlib
11
+ model_metrics
12
+ eda_toolkit
13
+ statsmodels
14
+ scikit-learn
15
+ dcurves
16
+
17
+ [dev]
18
+ pytest>=7
19
+ pytest-cov
20
+ build
21
+ twine
22
+ nbstripout
23
+
24
+ [docs]
25
+ sphinx
26
+ sphinx-rtd-theme
27
+ sphinx-copybutton
28
+ myst-nb
29
+ ipykernel
@@ -0,0 +1 @@
1
+ seminal
@@ -0,0 +1,135 @@
1
+ import math
2
+ from pathlib import Path
3
+
4
+ import numpy as np
5
+ import pandas as pd
6
+ import pytest
7
+
8
+ from seminal import (
9
+ FSH_QUAD,
10
+ LR_COEFS,
11
+ add_azoospermia_risk_cols,
12
+ azoospermia_fsh,
13
+ azoospermia_lr,
14
+ )
15
+
16
+ # Tradewell et al. 2022, Table 3, exactly as printed
17
+ PAPER_TABLE_3 = {
18
+ "intercept": -1.9,
19
+ "age": 0.02,
20
+ "fsh": 0.13,
21
+ "lh": 0.03,
22
+ "testosterone": -0.002,
23
+ "testis_volume": -0.08,
24
+ }
25
+
26
+
27
+ def test_lr_coefficients_match_table_3():
28
+ assert LR_COEFS == PAPER_TABLE_3
29
+
30
+
31
+ def test_fsh_quadratic_matches_fig_1():
32
+ assert FSH_QUAD == {"a": 0.133, "b": -0.965, "c": 10.1}
33
+
34
+
35
+ # ---- FSH-only model: anchors quoted in the paper's Results and Discussion ----
36
+
37
+ def test_fsh_undetectable_is_10_percent():
38
+ # "at undetectable FSH there is a 10.1% chance of being azoospermic"
39
+ assert azoospermia_fsh(0) == pytest.approx(0.101)
40
+
41
+
42
+ def test_fsh_nadir_at_3_6():
43
+ # "the probability of azoospermia is lowest in men with FSH values of 3.6 IU/L"
44
+ nadir = -FSH_QUAD["b"] / (2 * FSH_QUAD["a"])
45
+ assert nadir == pytest.approx(3.6, abs=0.05)
46
+ grid = np.arange(0, 20, 0.01)
47
+ assert grid[np.argmin(azoospermia_fsh(grid))] == pytest.approx(3.63, abs=0.01)
48
+
49
+
50
+ def test_fsh_reaches_certainty_near_30():
51
+ # "after an FSH of 30 IU/L the majority of men will be azoospermic"
52
+ assert azoospermia_fsh(29) < 1.0
53
+ assert azoospermia_fsh(30) == 1.0
54
+ assert azoospermia_fsh(30, clip=False) > 1.0
55
+
56
+
57
+ def test_fsh_vectorized_and_clipped():
58
+ out = azoospermia_fsh([0, 3.6, 20, 80])
59
+ assert isinstance(out, np.ndarray)
60
+ assert out.min() >= 0 and out.max() <= 1
61
+ assert out[-1] == 1.0
62
+
63
+
64
+ # ---- Logistic model ----
65
+
66
+ def test_lr_hand_computed_median_patient():
67
+ # Median Miami-ish patient from Table 1
68
+ lp = -1.9 + 0.02 * 36 + 0.13 * 5.7 + 0.03 * 4.5 - 0.002 * 429 - 0.08 * 15
69
+ expected = 1 / (1 + math.exp(-lp))
70
+ got = azoospermia_lr(age=36, fsh=5.7, lh=4.5, testosterone=429, testis_volume=15)
71
+ assert got == pytest.approx(expected)
72
+ assert round(got, 3) == 0.086
73
+
74
+
75
+ def test_lr_monotone_in_fsh():
76
+ base = dict(age=36, lh=4.5, testosterone=429, testis_volume=15)
77
+ assert azoospermia_lr(fsh=5, **base) < azoospermia_lr(fsh=15, **base) < azoospermia_lr(fsh=30, **base)
78
+
79
+
80
+ def test_lr_explain_breakdown_sums_to_linear_predictor():
81
+ out = azoospermia_lr(age=40, fsh=12, lh=6, testosterone=300, testis_volume=10, explain=True)
82
+ assert set(out) == {"risk", "intercept", "linear_predictor", "contributions"}
83
+ assert out["intercept"] + sum(out["contributions"].values()) == pytest.approx(out["linear_predictor"])
84
+ assert out["risk"] == pytest.approx(1 / (1 + math.exp(-out["linear_predictor"])))
85
+ # largest absolute contribution first
86
+ vals = [abs(v) for v in out["contributions"].values()]
87
+ assert vals == sorted(vals, reverse=True)
88
+
89
+
90
+ # ---- Cohort scoring ----
91
+
92
+ def test_add_cols_matches_scalar_functions_and_handles_missing():
93
+ df = pd.DataFrame({
94
+ "age": [36, 50, 30],
95
+ "fsh": [5.7, 25.0, 2.0],
96
+ "lh": [4.5, 10.0, np.nan],
97
+ "testosterone": [429, 250, 600],
98
+ "testis_volume": [15, 8, 20],
99
+ })
100
+ out = add_azoospermia_risk_cols(df)
101
+ assert "azoo_lr" in out and "azoo_fsh" in out
102
+ assert out.loc[0, "azoo_lr"] == pytest.approx(
103
+ azoospermia_lr(age=36, fsh=5.7, lh=4.5, testosterone=429, testis_volume=15))
104
+ assert out.loc[1, "azoo_fsh"] == pytest.approx(azoospermia_fsh(25.0))
105
+ assert np.isnan(out.loc[2, "azoo_lr"]) # LH missing -> NaN
106
+ assert not np.isnan(out.loc[2, "azoo_fsh"]) # FSH-only model still scores
107
+ assert "azoo_lr" not in df # copy=True leaves input alone
108
+
109
+
110
+ # ---- External validation against the CC0 Dataverse file (optional) ----
111
+
112
+ PROCESSED = Path(__file__).resolve().parents[1] / "data" / "processed" / "tradewell_2022.parquet"
113
+
114
+
115
+ def _auc(y, p):
116
+ """Rank-based AUC without sklearn."""
117
+ y = np.asarray(y, bool)
118
+ p = np.asarray(p, float)
119
+ r = pd.Series(p).rank().to_numpy()
120
+ n_pos, n_neg = y.sum(), (~y).sum()
121
+ return (r[y].sum() - n_pos * (n_pos + 1) / 2) / (n_pos * n_neg)
122
+
123
+
124
+ @pytest.mark.skipif(not PROCESSED.exists(), reason="run `make data_gen preprocess` first")
125
+ @pytest.mark.parametrize("site,paper_lr,paper_fsh", [
126
+ ("milan", 0.79, 0.78),
127
+ ("chicago", 0.72, 0.71),
128
+ ])
129
+ def test_external_validation_auc_matches_paper(site, paper_lr, paper_fsh):
130
+ df = pd.read_parquet(PROCESSED)
131
+ df = df[(df["site"] == site) & df["included"]]
132
+ df = add_azoospermia_risk_cols(df)
133
+ ok = df["azoo_lr"].notna()
134
+ assert _auc(df.loc[ok, "azoospermia"], df.loc[ok, "azoo_lr"]) == pytest.approx(paper_lr, abs=0.03)
135
+ assert _auc(df["azoospermia"], df["azoo_fsh"]) == pytest.approx(paper_fsh, abs=0.03)