Skip to content

Commit 11be6d4

Browse files
zeyunluclaude
zeyunlu
and
claude
committed
v0.19: Add CI/CD, improve code quality and documentation
- Add GitHub Actions workflow for testing (Python 3.8-3.12), linting, and type checking - Fix PEP 8 violation in setup.py (bare except clause) - Tighten mypy configuration for stricter type checking - Improve warning handling in cli.py with targeted filters - Add troubleshooting section to README - Add comprehensive FAQ documentation - Update pre-commit hooks to latest versions - Add .claude/ to .gitignore Note: mypy now catches pre-existing type issues in cli.py and infer.py that should be addressed in a future update. This update was completely done using Claude Code. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1 parent 82e8d3a commit 11be6d4

10 files changed

Lines changed: 309 additions & 11 deletions

File tree

‎.github/workflows/test.yml‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
name: Tests
2+
3+
on:
4+
push:
5+
branches: [main, dev]
6+
pull_request:
7+
branches: [main, dev]
8+
9+
jobs:
10+
lint:
11+
name: Lint
12+
runs-on: ubuntu-latest
13+
steps:
14+
- uses: actions/checkout@v4
15+
- uses: actions/setup-python@v5
16+
with:
17+
python-version: "3.10"
18+
cache: "pip"
19+
- name: Install linting tools
20+
run: |
21+
pip install --upgrade pip
22+
pip install flake8 black isort
23+
- name: Run flake8
24+
run: flake8 sushie/ tests/
25+
- name: Check black formatting
26+
run: black --check sushie/ tests/
27+
- name: Check isort
28+
run: isort --check-only sushie/ tests/
29+
30+
test:
31+
name: Test Python ${{ matrix.python-version }}
32+
runs-on: ubuntu-latest
33+
strategy:
34+
fail-fast: false
35+
matrix:
36+
python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
37+
steps:
38+
- uses: actions/checkout@v4
39+
- name: Set up Python ${{ matrix.python-version }}
40+
uses: actions/setup-python@v5
41+
with:
42+
python-version: ${{ matrix.python-version }}
43+
cache: "pip"
44+
- name: Install dependencies
45+
run: |
46+
pip install --upgrade pip
47+
pip install -r requirements.txt
48+
pip install .[testing]
49+
- name: Run tests with coverage
50+
run: pytest tests/ --cov=sushie --cov-report=xml --cov-report=term-missing -v
51+
- name: Upload coverage to Codecov
52+
if: matrix.python-version == '3.10'
53+
uses: codecov/codecov-action@v4
54+
with:
55+
files: ./coverage.xml
56+
fail_ci_if_error: false
57+
verbose: true
58+
59+
typecheck:
60+
name: Type Check
61+
runs-on: ubuntu-latest
62+
steps:
63+
- uses: actions/checkout@v4
64+
- uses: actions/setup-python@v5
65+
with:
66+
python-version: "3.10"
67+
cache: "pip"
68+
- name: Install dependencies
69+
run: |
70+
pip install --upgrade pip
71+
pip install -r requirements.txt
72+
pip install mypy pandas-stubs types-setuptools
73+
- name: Run mypy
74+
run: mypy sushie/ --ignore-missing-imports

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
__pycache__/
66

77
.vscode/
8+
.claude/
89

910
*.metadata2.mmm
1011
test_result*

‎.pre-commit-config.yaml‎

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@ exclude: '^(docs/conf.py|tests/testdata/.*)'
22

33
repos:
44
- repo: https://github.com/pre-commit/pre-commit-hooks
5-
rev: v4.0.1
5+
rev: v4.5.0
66
hooks:
77
- id: trailing-whitespace
88
- id: check-added-large-files
@@ -18,25 +18,24 @@ repos:
1818
args: ['--fix=auto'] # replace 'auto' with 'lf' to enforce Linux/Mac line endings or 'crlf' for Windows
1919

2020
- repo: https://github.com/pycqa/isort
21-
rev: 5.10.1
21+
rev: 5.13.2
2222
hooks:
2323
- id: isort
2424

2525
- repo: https://github.com/psf/black
26-
rev: 21.11b1
26+
rev: 24.3.0
2727
hooks:
2828
- id: black
2929
language_version: python3
30-
additional_dependencies: ['click==8.0.4']
3130

3231
- repo: https://github.com/PyCQA/flake8
33-
rev: 4.0.1
32+
rev: 7.0.0
3433
hooks:
3534
- id: flake8
3635
## You can add flake8 plugins via `additional_dependencies`:
3736
# additional_dependencies: [flake8-bugbear]
3837

3938
- repo: https://github.com/pre-commit/mirrors-mypy
40-
rev: 'v0.971' # Use the sha / tag you want to point at
39+
rev: 'v1.8.0'
4140
hooks:
4241
- id: mypy

‎README.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -104,6 +104,50 @@ infer_sushie_ss(lds=LD, zs=GWAS, ns=np.array([100, 100]))
104104

105105
You can customize this function with your own ideas!
106106

107+
## Troubleshooting
108+
109+
### Installation Issues
110+
111+
**JAX installation fails on Apple M1/M2/M3 chips:**
112+
```bash
113+
# Use miniforge and install cbgen from conda-forge first
114+
conda install -c conda-forge cbgen
115+
pip install .
116+
```
117+
118+
**Import errors with JAX:**
119+
```bash
120+
# Ensure you have compatible versions
121+
pip install --upgrade jax jaxlib
122+
```
123+
124+
**Permission errors during installation:**
125+
```bash
126+
# Use a virtual environment or conda environment
127+
conda create -n env-sushie python=3.8
128+
conda activate env-sushie
129+
pip install .
130+
```
131+
132+
### Runtime Issues
133+
134+
**Out of memory errors:**
135+
- Reduce the number of SNPs in your analysis region
136+
- Use `--max-select` to limit SNPs for purity computation
137+
- Consider using summary-level data instead of individual-level data
138+
139+
**Slow performance:**
140+
- Enable GPU acceleration if available: set `JAX_PLATFORM_NAME=gpu`
141+
- Use `--no-update` to skip prior updates if convergence is slow
142+
- Reduce `--max-iter` for initial testing
143+
144+
**LD matrix errors (summary-level data):**
145+
- Ensure LD matrices are positive semi-definite
146+
- Check that SNP order matches between GWAS and LD files
147+
- Verify sample sizes are correctly specified with `--sample-size`
148+
149+
For more help, see the [full documentation](https://mancusolab.github.io/sushie/) or open an [issue](https://github.com/mancusolab/sushie/issues).
150+
107151
## Notes
108152

109153
- SuShiE currently only supports **continuous** phenotype fine-mapping for individual-level data.
@@ -121,6 +165,7 @@ You can customize this function with your own ideas!
121165
| 0.16 | Implement summary-level data inference. Add option to remove ambiguous SNPs; fix several bugs and enhance codes quality. |
122166
| 0.17 | Fix several bugs, add debug checkpoints, add chrom, start, and end filtering to individual-level fine-mapping, enhance codes quality, and update readme for official publication. |
123167
| 0.18 | Add funciton that outputs log bayes factor in the alphas file. Update the documentation. |
168+
| 0.19 | Add CI/CD pipeline with GitHub Actions (testing across Python 3.8-3.12, linting, type checking, coverage). Improve code quality: fix PEP 8 violations, tighten mypy configuration, improve warning handling. Add troubleshooting section to README and comprehensive FAQ documentation. **This update was completely done using [Claude Code](https://claude.ai/claude-code).** |
124169

125170
## Support
126171

‎docs/faq.rst‎

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
===
2+
FAQ
3+
===
4+
5+
Frequently asked questions about SuShiE.
6+
7+
General Questions
8+
=================
9+
10+
What is SuShiE?
11+
---------------
12+
SuShiE (Sum of Shared Single Effect) is a Bayesian fine-mapping method designed for multi-ancestry genetic studies. It identifies causal variants while accounting for effect size correlations across ancestries.
13+
14+
When should I use SuShiE vs single-ancestry SuSiE?
15+
--------------------------------------------------
16+
Use SuShiE when you have genetic data from multiple ancestries and want to:
17+
18+
- Leverage shared genetic architecture across populations
19+
- Improve fine-mapping resolution through diverse LD patterns
20+
- Estimate effect size correlations across ancestries
21+
22+
Use single-ancestry SuSiE (via ``--meta`` or ``--mega`` flags) when:
23+
24+
- You only have data from one ancestry
25+
- You want to compare results with multi-ancestry SuShiE
26+
27+
What data formats does SuShiE support?
28+
--------------------------------------
29+
**Genotype data:**
30+
31+
- PLINK (.bed/.bim/.fam)
32+
- VCF (.vcf, .vcf.gz)
33+
- BGEN (.bgen)
34+
35+
**Phenotype/Covariate data:**
36+
37+
- Tab-separated text files
38+
39+
**Summary statistics:**
40+
41+
- Tab-separated GWAS files with Z-scores or effect sizes
42+
43+
Parameters
44+
==========
45+
46+
How do I choose the number of causal variants (L)?
47+
--------------------------------------------------
48+
The ``-L`` parameter specifies the maximum number of causal variants. Recommendations:
49+
50+
- Start with ``-L 10`` (default) for most fine-mapping analyses
51+
- Increase if you expect more causal variants in the region
52+
- The algorithm will only identify credible sets for true signals
53+
54+
What does the ``--rho`` parameter do?
55+
-------------------------------------
56+
The ``--rho`` parameter sets the prior correlation of effect sizes across ancestries:
57+
58+
- ``--rho 0.0``: Assumes independent effects (equivalent to ``--indep``)
59+
- ``--rho 1.0``: Assumes perfectly correlated effects
60+
- Default: Learns correlation from data (recommended)
61+
62+
When should I use ``--no-update``?
63+
----------------------------------
64+
Use ``--no-update`` to disable prior updates during inference:
65+
66+
- When you have strong prior beliefs about effect distributions
67+
- For faster runtime on large datasets
68+
- When empirical Bayes updates cause convergence issues
69+
70+
Output Files
71+
============
72+
73+
What is a credible set?
74+
-----------------------
75+
A credible set is a set of SNPs that contains the causal variant with high probability (default 95%). SuShiE outputs:
76+
77+
- SNPs in each credible set
78+
- Posterior inclusion probabilities (PIPs)
79+
- Purity scores (minimum LD among SNPs in the set)
80+
81+
How do I interpret the PIP?
82+
---------------------------
83+
The Posterior Inclusion Probability (PIP) represents the probability that a SNP is causal:
84+
85+
- PIP > 0.9: Strong evidence for causality
86+
- PIP 0.5-0.9: Moderate evidence
87+
- PIP < 0.5: Weak evidence
88+
89+
Higher PIPs in credible sets indicate better fine-mapping resolution.
90+
91+
What does purity mean?
92+
----------------------
93+
Purity is the minimum absolute correlation (r²) between any pair of SNPs in a credible set:
94+
95+
- High purity (>0.5): SNPs are in high LD, harder to distinguish
96+
- Low purity: SNPs are more independent, but set may contain false positives
97+
98+
The ``--purity`` threshold (default 0.5) filters out low-quality credible sets.
99+
100+
Performance
101+
===========
102+
103+
How can I speed up SuShiE?
104+
--------------------------
105+
Several options to improve performance:
106+
107+
1. **Use GPU acceleration:**
108+
109+
.. code-block:: bash
110+
111+
export JAX_PLATFORM_NAME=gpu
112+
sushie finemap ...
113+
114+
2. **Reduce iterations:**
115+
116+
.. code-block:: bash
117+
118+
sushie finemap --max-iter 100 ...
119+
120+
3. **Use summary statistics** instead of individual-level data when available
121+
122+
4. **Limit SNPs** for purity calculation:
123+
124+
.. code-block:: bash
125+
126+
sushie finemap --max-select 500 ...
127+
128+
How much memory does SuShiE need?
129+
---------------------------------
130+
Memory usage depends on:
131+
132+
- Number of samples (N)
133+
- Number of SNPs (P)
134+
- Number of ancestries (K)
135+
136+
Rough estimate: ``N × P × K × 8 bytes`` for genotype storage.
137+
138+
For large datasets, consider:
139+
140+
- Using summary-level inference
141+
- Analyzing smaller genomic regions
142+
- Running on a high-memory compute node
143+
144+
Errors
145+
======
146+
147+
"LD matrix is not positive semi-definite"
148+
-----------------------------------------
149+
This error occurs with summary-level data when the LD matrix has numerical issues:
150+
151+
- Ensure LD was computed from a sufficiently large reference panel
152+
- Check for missing or mismatched SNPs
153+
- Try adding a small ridge regularization term
154+
155+
"No credible sets found"
156+
------------------------
157+
This may indicate:
158+
159+
- No significant signal in the region
160+
- Too stringent purity threshold (try ``--purity 0.1``)
161+
- Convergence issues (check ELBO in output)
162+
163+
"Sample sizes don't match"
164+
--------------------------
165+
For summary-level data, ensure:
166+
167+
- ``--sample-size`` matches the number of ancestries
168+
- Sample sizes correspond to the correct GWAS files (in order)

‎docs/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ Contents
2424
Model <model>
2525
Users Manual <manual>
2626
Files <files>
27+
FAQ <faq>
2728

2829

2930
.. toctree::

‎docs/version.rst‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,3 +25,7 @@ Version History
2525
- Implement summary-level data inference. Add option to remove ambiguous SNPs; fix several bugs and enhance codes quality. |
2626
* - 0.17
2727
- Fix several bugs, add debug checkpoints, add chrom, start, and end filtering to individual-level fine-mapping, enhance codes quality, and update readme for official publication.
28+
* - 0.18
29+
- Add function that outputs log bayes factor in the alphas file. Update the documentation.
30+
* - 0.19
31+
- Add CI/CD pipeline with GitHub Actions (testing across Python 3.8-3.12, linting, type checking, coverage). Improve code quality: fix PEP 8 violations, tighten mypy configuration, improve warning handling. Add troubleshooting section to README and comprehensive FAQ documentation. **This update was completely done using** `Claude Code <https://claude.ai/claude-code>`_.

‎mypy.ini‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,7 @@
11
[mypy]
22
allow_redefinition = true
3+
warn_return_any = true
4+
warn_unused_ignores = true
5+
no_implicit_optional = true
6+
check_untyped_defs = true
7+
ignore_missing_imports = true

‎setup.py‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,12 +6,13 @@
66
PyScaffold helps you to put up the scaffold of your new Python project.
77
Learn more under: https://pyscaffold.org/
88
"""
9+
910
from setuptools import setup
1011

1112
if __name__ == "__main__":
1213
try:
1314
setup(use_scm_version={"version_scheme": "no-guess-dev"})
14-
except: # noqa
15+
except Exception:
1516
print(
1617
"\n\nAn error occurred while building the project, "
1718
"please ensure you have the most updated version of setuptools, "

0 commit comments

Comments
 (0)