Metadata-Version: 2.4
Name: sushie
Version: 0.20
Summary: SNP fine-mapping of molecular data across ancestries using SuShiE
Project-URL: Homepage, https://github.com/mancusolab/sushie
Project-URL: Source, https://github.com/mancusolab/sushie
Project-URL: Tracker, https://github.com/mancusolab/sushie/issues
Author-email: Zeyun Lu <zeyun_lu@dfci.harvard.edu>, Nicholas Mancuso <Nicholas.Mancuso@med.usc.edu>
License-Expression: MIT
License-File: LICENSE.txt
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.11
Requires-Dist: equinox<0.14,>=0.13
Requires-Dist: genoio<0.3,>=0.2
Requires-Dist: glimix-core<4,>=3.1
Requires-Dist: jax<0.11,>=0.10
Requires-Dist: jaxlib<0.11,>=0.10
Requires-Dist: polars<2,>=1.42
Requires-Dist: scipy<2,>=1.17
Provides-Extra: dev
Requires-Dist: mkdocstrings-python==2.0.5; extra == 'dev'
Requires-Dist: pre-commit; extra == 'dev'
Requires-Dist: pytest-accept; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: ruff>=0.0.243; extra == 'dev'
Requires-Dist: ty>=0.0.44; extra == 'dev'
Requires-Dist: zensical==0.0.53; extra == 'dev'
Provides-Extra: testing
Requires-Dist: pytest; extra == 'testing'
Requires-Dist: pytest-cov; extra == 'testing'
Requires-Dist: setuptools; extra == 'testing'
Description-Content-Type: text/markdown

[![Documentation-webpage](https://img.shields.io/badge/Docs-Available-brightgreen)](https://mancusolab.github.io/sushie/)
[![Github](https://img.shields.io/github/stars/mancusolab/sushie?style=social)](https://github.com/mancusolab/sushie)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

# SuShiE🍣

SuShiE (Sum of Shared Single Effect) is a Python package for multiancestry SNP fine-mapping, estimating effect size correlations across ancestries, and computing ancestry-specific prediction weights using either individual-level or summary-level data for molecular or complex traits.

``` diff
- We detest usage of our software or scientific outcome to promote racial discrimination.
```

SuShiE is described in
>  [Improved multiancestry fine-mapping identifies cis-regulatory variants underlying molecular traits and disease risk](https://doi.org/10.1038/s41588-025-02262-7).
>
> Zeyun Lu,  Xinran Wang,  Matthew Carr,  Artem Kim,  Steven Gazal,  Pejman Mohammadi,  Lang Wu,  James Pirruccello,  Linda Kachuri,  Alexander Gusev,  Nicholas Mancuso.
>
> Nature Genetics. July, 2025.

Check [here](https://mancusolab.github.io/sushie/) for full
documentation.

  [**Installation**](#installation)
  | [**Example**](#get-started-with-example)
  | [**Notes**](#notes)
  | [**Version History**](#version-history)
  | [**Support**](#support)
  | [**Other Software**](#other-software)

## Installation

Install the released package from PyPI:

```bash
pip install sushie
# or using uv
uv pip install sushie
```

To install from a source checkout:

```bash
git clone https://github.com/mancusolab/sushie.git
cd sushie
pip install .
```

or with `uv`:

```bash
uv sync
```

## Get Started with Example

SuShiE software is very easy to use:

For fine-mapping using individual-level data:
``` bash
cd ./data/
sushie finemap --pheno EUR.pheno AFR.pheno --vcf vcf/EUR.vcf vcf/AFR.vcf --covar EUR.covar AFR.covar --output ./test_result
```

For fine-mapping using summary-level data:
``` bash
cd ./data/
sushie finemap --summary --gwas EUR.gwas AFR.gwas --vcf vcf/EUR.vcf vcf/AFR.vcf --sample-size 489 639 --gwas-header chrom snp pos a1 a0 z --output ./test_result
```

It can perform:

-   SuShiE: multi-ancestry fine-mapping accounting for ancestral
    correlation
-   Single-ancestry SuSiE (Sum of Single Effect)
-   Independent SuShiE: multi-ancestry SuShiE without accounting for
    correlation
-   Meta-SuSiE: single-ancestry SuSiE followed by meta-analysis
-   Mega-SuSiE: single-ancestry SuSiE on row-wise stacked data across
    ancestries (individual-level data only)
-   *cis*-molQTL effect size correlation estimation
-   *cis*-SNP heritability estimation (individual-level data only)
-   Cross-validation for SuShiE prediction weights (individual-level data only)
-   Convert prediction results to
    [FUSION](http://gusevlab.org/projects/fusion/) format, thus can be
    used in [TWAS](https://www.nature.com/articles/ng.3506)

See [here](https://mancusolab.github.io/sushie/) for more details on how
to use SuShiE.

If you want to use in-software SuShiE inference function, you can use
following Python code as an example:

``` python
from sushie.infer import infer_sushie
# Xs is for genotype data, and it should be a list of numpy array whose length is the number of ancestry.
# ys is for phenotype data, and it should also be a list of numpy array whose length is the number of ancestry.
infer_sushie(Xs=X, ys=y)
# Or summary-level data
# lds is for LD data, and it should be a list of p by p numpy array whose length is the number of ancestry.
# zs is for GWAS data, and it should be a list of numpy array whose length is the number of ancestry/
infer_sushie_ss(lds=LD, zs=GWAS, ns=np.array([100, 100]))
```

You can customize this function with your own ideas!

## Troubleshooting

### Installation Issues

**Import errors with JAX:**
```bash
# Ensure you have compatible versions
pip install --upgrade jax jaxlib
```

### Runtime Issues

**Out of memory errors:**
- Reduce the number of SNPs by shortening your analysis region
- Use `--max-select` to limit SNPs for purity computation

**Slow performance:**
- Use `--no-update` to skip prior updates if convergence is slow
- Reduce `--max-iter` for initial testing

**LD matrix errors (summary-level data):**
- Ensure LD matrices are positive semi-definite
- Check that SNP order matches between GWAS and LD files
- Verify sample sizes are correctly specified with `--sample-size`

For more help, see the [full documentation](https://mancusolab.github.io/sushie/) or open an [issue](https://github.com/mancusolab/sushie/issues).

## Notes

-   SuShiE currently only supports **continuous** phenotype fine-mapping for individual-level data.

## Version History

| Version | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
|---------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 0.20 | VCF input now uses `a0=REF` and `a1=ALT` and counts ALT alleles. Compared with 0.19 and earlier, VCF `a0`/`a1` and signed weights may be reversed while allele-aware results remain equivalent. |
| 0.19 | Improve code quality. Add troubleshooting section to README and comprehensive FAQ documentation. **This update was completely done using [Claude Code](https://claude.ai/claude-code) with human tuning.** |
| 0.18 | Add function that outputs log bayes factor in the alphas file. Update the documentation. |
| 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.  |
| 0.16  | Implement summary-level data inference. Add option to remove ambiguous SNPs; fix several bugs and enhance codes quality.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| 0.15    | Fix several typos; add a sanity check on reading vcf genotype data by assigning gt_types==Unknown as NA; Add preprint information.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| 0.14    | Remove KL-Divergence pruning. Enhance command line appearance and improve the output files contents. Fix small bugs on multivariate KL.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| 0.13    | Add `--keep` command to enable user to specify a file that contains the subjects ID SuShiE will perform on. Add `--ancestry_index` command to enable user to specify a file that contains the ancestry index for fine-mapping. With this, user can input single phenotype, genotype, and covariate file that contains all the subjects across ancestries. Implement padding to increase inference time. Record elbo at each iteration and can access it in the `infer.SuShiEResult` object. The alphas table now outputs the average purity and KL divergence for each `L`. Change `--kl_threshold` to `--divergence`. Add `--maf` command to remove SNPs that less than minor allele frequency threshold within each ancestry. Add `--max_select` command to randomly select maximum number of SNPs to compute purity to avoid unnecessary memory spending. Add a QC function to remove duplicated SNPs. |
| 0.12    | Update io.corr function so that report all the correlation results no matter cs is pruned or not.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| 0.11    | Fix the bug for OLS to compute adjusted r squared.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| 0.1     | Initial Release                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |

## Support

For any questions, comments, bug reporting, and feature requests, please contact Zeyun Lu (<zeyun_lu@dfci.harvard.edu>) and
Nicholas Mancuso (<nmancuso@usc.edu>), and open a new thread in the [Issue
Tracker](https://github.com/mancusolab/sushie/issues).

## Other Software

Feel free to use other software developed by [Mancuso
Lab](https://www.mancusolab.com/):

-   [jaxQTL](https://github.com/mancusolab/jaxqtl): a single-cell eQTL mapping tool using highly efficient count-based model (i.e., negative binomial or Poisson).
-   [MA-FOCUS](https://github.com/mancusolab/ma-focus): a Bayesian
    fine-mapping framework using
    [TWAS](https://www.nature.com/articles/ng.3506) statistics across
    multiple ancestries to identify the causal genes for complex traits.
-   [SuSiE-PCA](https://github.com/mancusolab/susiepca): a scalable
    Bayesian variable selection technique for sparse principal component
    analysis
-   [twas_sim](https://github.com/mancusolab/twas_sim): a Python
    software to simulate [TWAS](https://www.nature.com/articles/ng.3506)
    statistics.
-   [FactorGo](https://github.com/mancusolab/factorgo): a scalable
    variational factor analysis model that learns pleiotropic factors
    from GWAS summary statistics.
-   [HAMSTA](https://github.com/tszfungc/hamsta): a Python software to
    estimate heritability explained by local ancestry data from
    admixture mapping summary statistics.
-   [Traceax](https://github.com/mancusolab/traceax): a Python library to perform stochastic trace estimation for linear operators.
