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.
- seminal-0.0.0a1/LICENSE +21 -0
- seminal-0.0.0a1/PKG-INFO +168 -0
- seminal-0.0.0a1/README.md +117 -0
- seminal-0.0.0a1/pyproject.toml +48 -0
- seminal-0.0.0a1/setup.cfg +4 -0
- seminal-0.0.0a1/src/seminal/__init__.py +44 -0
- seminal-0.0.0a1/src/seminal/azoospermia.py +222 -0
- seminal-0.0.0a1/src/seminal/logo.py +13 -0
- seminal-0.0.0a1/src/seminal.egg-info/PKG-INFO +168 -0
- seminal-0.0.0a1/src/seminal.egg-info/SOURCES.txt +12 -0
- seminal-0.0.0a1/src/seminal.egg-info/dependency_links.txt +1 -0
- seminal-0.0.0a1/src/seminal.egg-info/requires.txt +29 -0
- seminal-0.0.0a1/src/seminal.egg-info/top_level.txt +1 -0
- seminal-0.0.0a1/tests/test_azoospermia.py +135 -0
seminal-0.0.0a1/LICENSE
ADDED
|
@@ -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.
|
seminal-0.0.0a1/PKG-INFO
ADDED
|
@@ -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
|
+
[](https://pypi.org/project/seminal/)
|
|
57
|
+
[](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
|
+
[](https://pypi.org/project/seminal/)
|
|
6
|
+
[](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,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
|
+
[](https://pypi.org/project/seminal/)
|
|
57
|
+
[](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 @@
|
|
|
1
|
+
|
|
@@ -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)
|