### Install SuShiE from Source

Source: https://github.com/mancusolab/sushie/blob/main/README.md

After setting up the environment and handling potential compatibility issues, clone the SuShiE repository and install the package using pip. This command installs the latest version from the cloned repository.

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

--------------------------------

### Clone Repository and Install Dependencies

Source: https://github.com/mancusolab/sushie/blob/main/docs/contributing.md

Clone the sushie repository from your fork and install the project in editable mode with necessary development tools. This command also allows running 'putup --help'.

```bash
git clone git@github.com:YourLogin/sushie.git
cd sushie
pip install -U pip setuptools -e .
```

--------------------------------

### Install and Configure pre-commit Hooks

Source: https://github.com/mancusolab/sushie/blob/main/docs/contributing.md

Install the pre-commit package and configure it to run automatically. This helps maintain code quality by checking code before commits.

```bash
pip install pre-commit
pre-commit install
```

--------------------------------

### Compile Documentation with Tox

Source: https://github.com/mancusolab/sushie/blob/main/docs/contributing.md

Use tox to compile documentation. Ensure you have tox installed.

```bash
tox -e docs
```

--------------------------------

### Troubleshooting JAX Installation on Apple Silicon

Source: https://github.com/mancusolab/sushie/blob/main/README.md

If JAX installation fails on Apple M1/M2/M3 chips, this command provides a workaround by installing 'cbgen' from conda-forge first, followed by the standard pip installation of SuShiE.

```bash
# Use miniforge and install cbgen from conda-forge first
conda install -c conda-forge cbgen
pip install .
```

--------------------------------

### Create and Activate Virtual Environment for Tox

Source: https://github.com/mancusolab/sushie/blob/main/docs/contributing.md

If facing persistent tox errors, create a dedicated virtual environment, install tox within it, and then run tox commands. This ensures a clean and isolated environment for testing.

```bash
virtualenv .venv
source .venv/bin/activate
.venv/bin/pip install tox
.venv/bin/tox -e all
```

--------------------------------

### Run Project Tests with Tox

Source: https://github.com/mancusolab/sushie/blob/main/docs/contributing.md

Verify that your changes do not break any existing unit tests by running the tox command. Ensure tox is installed via pip or pipx.

```bash
tox
```

--------------------------------

### Create and Activate Conda Environment

Source: https://github.com/mancusolab/sushie/blob/main/README.md

Before installing SuShiE, it is highly recommended to create a new conda environment to avoid conflicts with other projects. This ensures a clean environment for the package.

```bash
conda create -n env-sushie python=3.10
conda activate env-sushie
```

--------------------------------

### Check Tox Version and Path

Source: https://github.com/mancusolab/sushie/blob/main/docs/contributing.md

Verify your tox installation and ensure it is using the correct Python version. This can help diagnose issues related to incorrect environments or outdated tox binaries.

```bash
tox --version
# OR
which tox
```

--------------------------------

### Create Virtual Environment with Conda

Source: https://github.com/mancusolab/sushie/blob/main/docs/contributing.md

Create and activate a virtual environment named 'sushie' using Conda, installing Python, six, virtualenv, pytest, and pytest-cov.

```bash
conda create -n sushie python=6 virtualenv pytest pytest-cov
conda activate sushie
```

--------------------------------

### Troubleshooting JAX Import Errors

Source: https://github.com/mancusolab/sushie/blob/main/README.md

To resolve import errors related to JAX, ensure that you have compatible versions of 'jax' and 'jaxlib' installed. This command upgrades them to the latest compatible versions.

```bash
# Ensure you have compatible versions
pip install --upgrade jax jaxlib
```

--------------------------------

### Install cbgen for Apple M1/M2/M3 Chips

Source: https://github.com/mancusolab/sushie/blob/main/README.md

For users with Mac computers featuring Apple M1, M2, or M3 chips, installing the 'cbgen' package from conda-forge is recommended to ensure compatibility with JAX. This step may not be necessary on most HPC systems.

```bash
conda install -c conda-forge cbgen
```

--------------------------------

### Run Tests with Pytest and Drop to PDB

Source: https://github.com/mancusolab/sushie/blob/main/docs/contributing.md

To debug failing tests, use the --pdb option with tox to drop into an interactive Python debugger (PDB) at the start of a test. This allows for in-depth inspection of test failures.

```bash
tox -- -k <NAME OF THE FALLING TEST> --pdb
```

--------------------------------

### Preview Documentation Locally

Source: https://github.com/mancusolab/sushie/blob/main/docs/contributing.md

Serve the compiled documentation locally using Python's http.server. The documentation will be available at http://localhost:8000.

```bash
python3 -m http.server --directory 'docs/_build/html'
```

--------------------------------

### Sushie CLI Configuration Parameters

Source: https://github.com/mancusolab/sushie/blob/main/docs/manual.md

A list of available command-line arguments for configuring the Sushie analysis pipeline.

```APIDOC
## CLI Parameters

### Parameters

#### --max-select
- **Type**: Integer
- **Default**: 250
- **Description**: The maximum selected number of SNPs to calculate the purity. Must be a positive integer. A larger number can unnecessarily consume memory.

#### --min-snps
- **Type**: Integer
- **Default**: 100
- **Description**: The minimum number of SNPs to fine-map. Must be a positive integer. A smaller number may produce unreliable results.

#### --maf
- **Type**: float
- **Default**: 0.01
- **Description**: Threshold for minor allele frequency (MAF) to filter out SNPs for each ancestry. Must be a float between 0 (exclusive) and 0.5 (inclusive).

#### --rint
- **Type**: Boolean
- **Default**: False
- **Description**: Indicator to perform rank inverse normalization transformation (rint) for each phenotype data. Specifying this flag sets the value to True.
```

--------------------------------

### CLI Configuration Parameters

Source: https://github.com/mancusolab/sushie/blob/main/docs/manual.md

List of available command-line flags for configuring the Sushie execution environment.

```APIDOC
## CLI Configuration Parameters

### Description
Configuration flags used to control the behavior of the Sushie CLI tool.

### Parameters
- **--verbose** (Boolean) - Optional - Default: False. Indicator to include debug information in the log.
- **--compress** (Boolean) - Optional - Default: False. Indicator to compress all output tsv files in ‘tsv.gz’ to save disk space.
- **--platform** (String) - Optional - Default: cpu. Indicator for the JAX platform. Choices: ["cpu", "gpu", "tpu"].
- **--jax-precision** (Integer) - Optional - Default: 64. Indicator for the JAX precision. Choices: [32, 64].
```

--------------------------------

### Create Virtual Environment with virtualenv

Source: https://github.com/mancusolab/sushie/blob/main/docs/contributing.md

Create and activate a virtual environment using virtualenv. Replace <PATH TO VENV> with your desired path.

```bash
virtualenv <PATH TO VENV>
source <PATH TO VENV>/bin/activate
```

--------------------------------

### Recreate Tox Environment

Source: https://github.com/mancusolab/sushie/blob/main/docs/contributing.md

If you encounter issues with missing dependencies when running tox, try recreating the tox environment using the -r flag. This is particularly useful after updating dependencies in setup.cfg or requirements.txt.

```bash
tox -r -e docs
```

--------------------------------

### Build Release Artifacts with Tox

Source: https://github.com/mancusolab/sushie/blob/main/docs/contributing.md

Run tox to build the release artifacts. Verify that the version in dist is correct and that no unwanted files are included.

```bash
tox -e build
```

--------------------------------

### Sushie CLI Options

Source: https://github.com/mancusolab/sushie/blob/main/docs/manual.md

This section describes the available command-line options for the Sushie tool.

```APIDOC
## Sushie CLI Options

### Description
This section describes the available command-line options for the Sushie tool.

### Parameters
#### Query Parameters
- **--alphas** (Boolean) - Optional - Indicator to output all the credible set results before pruning for purity including PIPs, $\alpha$ (in Model Description), whether in cs, across all $L$. Default is False. Specify –alphas will store ‘True’ value and increase running time.
- **--numpy** (Boolean) - Optional - Indicator to output all the results in \*.npy file. Specify `--numpy` will store `True` and increase running time. \*.npy file contains all the inference results including SNP information, credible sets, pips, priors, posteriors, and sample size for users’ own post-hoc analysis. Default is False.
- **--trait** (String) - Optional - Trait, tissue, gene name of the phenotype for better indexing in post-hoc analysis. Default is “Trait”.
- **--quiet** (Boolean) - Optional - Indicator to not print message to console. Specify `--quiet` will store `True` value. Default is False.

### Request Example
```json
{
  "example": "--trait GENE_ABC --alphas --numpy"
}
```

### Response
#### Success Response (200)
- **Output** (Various) - The output format depends on the flags used. For example, `--alphas` will output credible sets, and `--numpy` will generate a \*.npy file.

#### Response Example
```json
{
  "example": "(Output varies based on flags. For --alphas, it might be a list of credible sets. For --numpy, it's a .npy file.)"
}
```
```

--------------------------------

### Sushie Fine-Mapping Configuration Options

Source: https://github.com/mancusolab/sushie/blob/main/docs/manual.md

This section details the various command-line arguments available for configuring the Sushie fine-mapping process, including input data files, covariates, LD information, and chromosomal filtering.

```APIDOC
## Sushie Fine-Mapping Command-Line Arguments

### Description
This section describes the command-line arguments used to configure the Sushie fine-mapping tool. These arguments control the input data, filtering criteria, and analysis parameters.

### Arguments

#### `--keep`
- **Type**: String
- **Default**: None
- **Description**: Specifies a single file containing subject IDs to filter all phenotype, genotype, and covariate data. The file must be a TSV (or compressed TSV.gz) with at least one column for subject IDs. No headers are expected. This ensures analysis is restricted to the specified subjects.
- **Example**: `--keep keep.subject`

#### `--covar`
- **Type**: String
- **Default**: None
- **Description**: Provides covariate files for the fine-mapping analysis. Each file must be a TSV (or compressed TSV.gz) with at least two columns: subject ID and covariate values. No headers are expected. Multiple ancestry covariate files can be specified, separated by spaces, maintaining the same order as the phenotype data. Categorical covariates must be pre-converted into dummy variables (n-1 columns for n levels).
- **Example**: `--covar EUR.covar AFR.covar`

#### `--ld`
- **Type**: String
- **Default**: None
- **Description**: Specifies Linkage Disequilibrium (LD) files for fine-mapping. Files must be TSV or compressed TSV.gz format and should have SNP names in the header matching the GWAS data. The tool will find overlapping SNPs between LD and GWAS data. Users must ensure that LD and GWAS z-statistics are computed using the same counting alleles.
- **Example**: `--ld EUR.ld AFR.ld`

#### `--chrom`
- **Type**: Integer
- **Default**: None
- **Description**: Filters GWAS SNPs for fine-mapping to a specific chromosome. The value must be an integer between 1 and 22. SNP position information from the first ancestry will be used for filtering. If this flag is used, `--start` and `--end` must also be provided.
- **Example**: `--chrom 6`
```

--------------------------------

### Sushie CLI Parameters

Source: https://github.com/mancusolab/sushie/blob/main/docs/manual.md

Configuration parameters for controlling fine-mapping behavior in Sushie.

```APIDOC
## CLI Parameters

### Parameters
#### Query Parameters
- **--gwas-sig** (Float) - Optional - The significance threshold for SNPs to be included in the fine-mapping. Default is 1.0. Only SNPs with P value less than this threshold will be included. Must be a float between 0 and 1.
- **--gwas-sig-type** (String) - Optional - Logic for including significant SNPs across ancestries. Options: 'at-least' (default) or 'all'.
- **--L** (Integer) - Optional - Integer number of shared effects pre-specified. Default is 10.
- **--pi** (String) - Optional - Prior probability for each SNP to be causal. Default is 'uniform'. Can also be a file path to a TSV file containing SNP IDs and prior weights.
```

--------------------------------

### Reading SuShiE Output Files with Pandas

Source: https://context7.com/mancusolab/sushie/llms.txt

Demonstrates how to read and inspect the main output files generated by SuShiE (credible sets, weights, correlations) using the pandas library.

```python
# After running:
# sushie finemap --pheno EUR.pheno AFR.pheno --plink EUR AFR --output ./results

# Main output files:
# - results.sushie.cs.tsv        - Credible sets after purity filtering
# - results.sushie.weights.tsv   - SNP weights and PIPs
# - results.sushie.corr.tsv      - Effect size correlations across ancestries

# Optional outputs (with flags):
# - results.sushie.alphas.tsv    - Full alphas before pruning (--alphas)
# - results.sushie.her.tsv       - Heritability estimates (--her)
# - results.sushie.cv.tsv        - Cross-validation results (--cv)
# - results.sushie.all.results.npy - All results in numpy (--numpy)

import pandas as pd

# Read credible sets
cs = pd.read_csv("results.sushie.cs.tsv", sep="\t")
print(cs.columns.tolist())
# ['SNPIndex', 'chrom', 'snp', 'pos', 'a0', 'a1', 'CSIndex',
#  'alpha', 'c_alpha', 'pip_all', 'pip_cs', 'trait', 'ancestry']

# Read weights for TWAS
weights = pd.read_csv("results.sushie.weights.tsv", sep="\t")
print(weights.columns.tolist())
# ['SNPIndex', 'chrom', 'snp', 'pos', 'a0', 'a1', 'trait', 'n_snps',
#  'ancestry1_sushie_weight', 'ancestry2_sushie_weight',
#  'sushie_pip_all', 'sushie_pip_cs', 'sushie_cs_index']

# Read correlation estimates
corr = pd.read_csv("results.sushie.corr.tsv", sep="\t")
print(corr.head())
# Shows effect size variance and correlation per credible set
```

--------------------------------

### Publish Release to PyPI with Tox

Source: https://github.com/mancusolab/sushie/blob/main/docs/contributing.md

Use tox to publish the built release artifacts to PyPI. Ensure that the upload is successful and all files are correctly published.

```bash
tox -e publish -- --repository pypi
```

--------------------------------

### Sushie Parameters

Source: https://github.com/mancusolab/sushie/blob/main/docs/manual.md

This section details the command-line parameters for the Sushie tool, including options for running fine-mapping on summary statistics or phenotype data, and specifying genetic data sources.

```APIDOC
## Sushie Tool Parameters

### Description
This section details the command-line parameters for the Sushie tool, including options for running fine-mapping on summary statistics or phenotype data, and specifying genetic data sources.

### Parameters

#### Query Parameters

- **--summary** (Boolean) - Optional - Indicator whether to run fine-mapping on summary statistics. Default is False. If True, the software will need GWAS files as input data by specifying –gwas and need LD matrix by specifying either –ld or one of the –plink, –vcf, or –bgen. If False, the software will need phenotype data by specifying –pheno and genotype data by specifying either –plink, –vcf, or –bgen.
- **--pheno** (String) - Required - Phenotype data. It has to be a tsv file that contains at least two columns where the first column is subject ID and the second column is the continuous phenotypic value. It can be a compressed file (e.g., tsv.gz). It is okay to have additional columns, but only the first two columns will be used. **No headers**. Use `space` to separate ancestries if more than two. SuShiE currently only fine-maps on **continuous** data.

### Request Example
```bash
--summary # will store as True
--pheno EUR.pheno AFR.pheno
```

### Response

#### Success Response (200)

This section is not applicable as the tool operates via command-line arguments and does not return a standard API response.

#### Response Example

N/A
```

--------------------------------

### Initialize Hyperparameters for Fine-Mapping

Source: https://github.com/mancusolab/sushie/blob/main/docs/manual.md

Specify custom initial values for residual variance (`--resid-var`), effect variance (`--effect-var`), and ancestral correlation (`--rho`). Ensure the ancestry order matches the phenotype file order.

```bash
cd ./data/
sushie finemap --pheno EUR.pheno AFR.pheno --vcf vcf/EUR.vcf vcf/AFR.vcf --resid-var 2.2 2.2 --effect-var 1.2 3.4 --rho 0.2 --output ./test_result
```

--------------------------------

### Meta SuShiE Analysis

Source: https://github.com/mancusolab/sushie/blob/main/docs/manual.md

Run meta SuShiE by performing single-ancestry SuShiE followed by meta-analysis of the PIPs.

```bash
cd ./data/
sushie finemap --pheno EUR.pheno AFR.pheno --vcf vcf/EUR.vcf vcf/AFR.vcf --meta --output ./test_result
```

--------------------------------

### Fine-mapping with Summary-Level Data via CLI

Source: https://context7.com/mancusolab/sushie/llms.txt

Use GWAS summary statistics and LD matrices for fine-mapping. Requires sample size information and specific header mapping for GWAS files.

```bash
sushie finemap \
    --summary \
    --gwas EUR.gwas AFR.gwas \
    --vcf EUR.vcf AFR.vcf \
    --sample-size 489 639 \
    --gwas-header chrom snp pos a1 a0 z \
    --output ./results/gene1
```

```bash
sushie finemap \
    --summary \
    --gwas EUR.gwas AFR.gwas \
    --ld EUR.ld AFR.ld \
    --sample-size 1000 1500 \
    --L 10 \
    --ld-adjust 0.01 \
    --output ./results/gene1
```

```bash
sushie finemap \
    --summary \
    --gwas EUR.gwas AFR.gwas \
    --plink EUR AFR \
    --sample-size 489 639 \
    --gwas-sig 5e-8 \
    --gwas-sig-type at-least \
    --output ./results/gene1
```

--------------------------------

### Fine-mapping with Summary-Level Data

Source: https://github.com/mancusolab/sushie/blob/main/README.md

This command illustrates fine-mapping using summary-level GWAS data. It requires specifying summary statistics files, VCF files, sample sizes, GWAS header information, and the output directory.

```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
```

--------------------------------

### Fine-mapping with Individual-Level Data

Source: https://github.com/mancusolab/sushie/blob/main/README.md

This command demonstrates how to perform fine-mapping using individual-level genotype and phenotype data. It specifies the phenotype files, VCF files, covariate files, and the output directory.

```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
```

--------------------------------

### Sushie CLI Configuration Parameters

Source: https://github.com/mancusolab/sushie/blob/main/docs/manual.md

Configuration parameters for controlling the Sushie model priors and data processing behavior.

```APIDOC
## CLI Parameters

### Description
Parameters used to configure the Sushie model priors and data scaling behavior.

### Parameters
- **--resid-var** (Float) - Optional - Specify the prior for the residual variance for ancestries. Values must be positive. Use space to separate ancestries if more than two.
- **--effect-var** (Float) - Optional - Specify the prior for the causal effect size variance for ancestries. Values must be positive. Use space to separate ancestries if more than two.
- **--rho** (Float) - Optional - Specify the prior for the effect correlation for ancestries. Must be a float between -1 and 1. If N > 2 ancestries, choose(N, 2) values are required in specific order.
- **--no-scale** (Boolean) - Optional - Indicator to scale the genotype and phenotype data by standard deviation. Default is to scale. Specifying this flag sets the value to True.
```

--------------------------------

### Stage and Commit Changes

Source: https://github.com/mancusolab/sushie/blob/main/docs/contributing.md

After implementing your changes, stage the modified files and commit them to record your progress. Ensure you have added docstrings to new code elements.

```bash
git add <MODIFIED FILES>
git commit
```

--------------------------------

### Clean Build Artifacts with Tox

Source: https://github.com/mancusolab/sushie/blob/main/docs/contributing.md

Use tox to clean the dist and build folders before creating a new release. This ensures no old build artifacts interfere with the new release.

```bash
tox -e clean
```

--------------------------------

### Utilize GPU for Faster Inference

Source: https://github.com/mancusolab/sushie/blob/main/docs/manual.md

To leverage GPU acceleration for faster computation, add the `--platform gpu` flag to the command. SuShiE uses JAX with JIT compilation, which supports GPU and TPU.

```bash
cd ./data/
sushie finemap --pheno EUR.pheno AFR.pheno --vcf vcf/EUR.vcf vcf/AFR.vcf --platform gpu --output ./test_result
```

--------------------------------

### Meta and Mega Analysis via CLI

Source: https://context7.com/mancusolab/sushie/llms.txt

Execute meta-analysis or mega-analysis strategies for multi-ancestry data. Supports cross-validation and heritability estimation.

```bash
sushie finemap \
    --pheno EUR.pheno AFR.pheno \
    --plink EUR AFR \
    --meta \
    --output ./results/gene1
```

```bash
sushie finemap \
    --pheno EUR.pheno AFR.pheno \
    --plink EUR AFR \
    --mega \
    --output ./results/gene1
```

```bash
sushie finemap \
    --pheno EUR.pheno AFR.pheno \
    --plink EUR AFR \
    --meta \
    --mega \
    --cv \
    --cv-num 5 \
    --her \
    --output ./results/gene1
```

--------------------------------

### CLI: sushie finemap (Summary-Level)

Source: https://context7.com/mancusolab/sushie/llms.txt

Performs fine-mapping using GWAS summary statistics and LD matrices.

```APIDOC
## CLI: sushie finemap --summary

### Description
Performs fine-mapping using GWAS summary statistics and LD matrices.

### Parameters
- **--summary** (flag) - Required - Enables summary-level mode.
- **--gwas** (list) - Required - Path to GWAS summary statistics files.
- **--ld** (list) - Optional - Path to pre-computed LD matrices.
- **--sample-size** (list) - Required - Sample sizes for each ancestry.
- **--gwas-header** (list) - Optional - Column names for GWAS files.
- **--gwas-sig** (float) - Optional - Significance threshold for filtering.
- **--ld-adjust** (float) - Optional - LD matrix adjustment factor.
```

--------------------------------

### Fine-mapping with individual-level reference panels

Source: https://github.com/mancusolab/sushie/blob/main/docs/manual.md

Perform fine-mapping using summary-level GWAS data and individual-level VCF files for LD estimation.

```bash
cd ./data/
sushie finemap --summary --gwas EUR.gwas AFR.gwas --vcf vcf/EUR.vcf vcf/AFR.vcf --sample-size 489 639 --output ./test_result
```

--------------------------------

### Fine-mapping with Individual-Level Data via CLI

Source: https://context7.com/mancusolab/sushie/llms.txt

Perform multi-ancestry fine-mapping using genotype and phenotype files. Supports various input formats like PLINK and VCF, with options for genomic region filtering.

```bash
sushie finemap \
    --pheno EUR.pheno AFR.pheno \
    --plink EUR AFR \
    --covar EUR.covar AFR.covar \
    --output ./results/gene1
```

```bash
sushie finemap \
    --pheno EUR.pheno AFR.pheno EAS.pheno \
    --vcf EUR.vcf AFR.vcf EAS.vcf \
    --covar EUR.covar AFR.covar EAS.covar \
    --L 5 \
    --threshold 0.95 \
    --purity 0.5 \
    --maf 0.01 \
    --output ./results/gene1 \
    --compress
```

```bash
sushie finemap \
    --pheno EUR.pheno AFR.pheno \
    --plink EUR AFR \
    --chrom 1 \
    --start 100000 \
    --end 200000 \
    --output ./results/chr1_region
```

--------------------------------

### Read PLINK Files

Source: https://context7.com/mancusolab/sushie/llms.txt

Load genotype data from PLINK 1 bed/bim/fam files.

```python
from sushie.io import read_triplet

# Read plink files (provide prefix without extension)
bim, fam, bed = read_triplet("path/to/data/EUR")

print(f"SNP info (bim): {bim.shape}")
print(bim.head())
# Columns: chrom, snp, pos, a0, a1

print(f"\nSample info (fam): {fam.shape}")
print(fam.head())
# Columns: iid

print(f"\nGenotype matrix (bed): {bed.shape}")
# Shape: (n_samples, n_snps), values 0/1/2 or NaN
```

--------------------------------

### CLI: sushie finemap (Individual-Level)

Source: https://context7.com/mancusolab/sushie/llms.txt

Performs fine-mapping using individual genotype and phenotype data across multiple ancestries.

```APIDOC
## CLI: sushie finemap (Individual-Level)

### Description
Performs fine-mapping using individual genotype and phenotype data across multiple ancestries.

### Parameters
- **--pheno** (list) - Required - Path to phenotype files for each ancestry.
- **--plink** (list) - Optional - Path to PLINK genotype files.
- **--vcf** (list) - Optional - Path to VCF files.
- **--covar** (list) - Optional - Path to covariate files.
- **--L** (int) - Optional - Number of effects to infer.
- **--threshold** (float) - Optional - Credible set PIP threshold.
- **--purity** (float) - Optional - Minimum purity for credible sets.
- **--maf** (float) - Optional - Minor allele frequency threshold.
- **--output** (string) - Required - Output directory path.
- **--chrom/start/end** (int) - Optional - Genomic region filtering.
```

--------------------------------

### SuShiE with Combined Ancestry Data

Source: https://github.com/mancusolab/sushie/blob/main/docs/manual.md

Run SuShiE when all participants are in single phenotype, genotype, and covariate files. Use --ancestry-index to specify ancestry.

```bash
cd ./data/
sushie finemap --pheno all.pheno --plink plink/all --ancestry-index all.ancestry.index --output ./test_result
```

--------------------------------

### Single-Ancestry SuShiE

Source: https://github.com/mancusolab/sushie/blob/main/docs/manual.md

Perform single-ancestry SuShiE, equivalent to the SuSiE model.

```bash
cd ./data/
sushie finemap --pheno EUR.pheno --vcf vcf/EUR.vcf --covar EUR.covar --output ./test_result
```

--------------------------------

### SuShiE with BGEN Genotypes

Source: https://github.com/mancusolab/sushie/blob/main/docs/manual.md

Use SuShiE with BGEN genotype data. Ensure the latter allele in 'allele ids' is the reference allele.

```bash
cd ./data/
sushie finemap --pheno EUR.pheno AFR.pheno --bgen bgen/EUR.bgen bgen/AFR.bgen --output ./test_result
```

--------------------------------

### Perform Summary-Level Fine-Mapping

Source: https://context7.com/mancusolab/sushie/llms.txt

Run SuShiE fine-mapping using GWAS summary statistics and LD matrices.

```python
import numpy as np
from sushie.infer_ss import infer_sushie_ss

# Generate example summary statistics for 2 ancestries, 500 SNPs
np.random.seed(42)
n_snps = 500
n1, n2 = 1000, 1500  # Sample sizes

# Create LD matrices (using identity for simplicity)
LD1 = np.eye(n_snps)
LD2 = np.eye(n_snps)

# Add some LD structure
for i in range(n_snps - 1):
    LD1[i, i+1] = LD1[i+1, i] = 0.3
    LD2[i, i+1] = LD2[i+1, i] = 0.25

# Generate Z-scores with true causal signals
z1 = np.random.randn(n_snps) * 0.5
z2 = np.random.randn(n_snps) * 0.5
z1[10] = 5.0  # Causal signal
z2[10] = 4.5
z1[50] = 3.5
z2[50] = 4.0

# Run SuShiE with summary statistics
result = infer_sushie_ss(
    lds=[LD1, LD2],
    zs=[z1, z2],
    ns=np.array([[n1], [n2]]),  # Sample sizes as column array
    L=5,
    threshold=0.95,
    purity=0.5,
    max_iter=500,
    seed=12345
)

# Access results
print("Top 10 SNPs by PIP:")
top_snps = np.argsort(-result.pip_all)[:10]
for snp in top_snps:
    print(f"  SNP {snp}: PIP = {result.pip_all[snp]:.4f}")

print("\nCredible Sets:")
print(result.cs)

# Check if ELBO converged properly
print(f"\nConverged: {result.elbo_increase}")
print(f"Final ELBO: {result.elbo[-1]:.2f}")
```

--------------------------------

### Fine-mapping with pre-computed LD matrix

Source: https://github.com/mancusolab/sushie/blob/main/docs/manual.md

Perform fine-mapping using summary-level GWAS data and pre-computed LD matrices.

```bash
cd ./data/
sushie finemap --summary --gwas EUR.gwas AFR.gwas --ld EUR.ld AFR.ld --sample-size 489 639 --output ./test_result
```

--------------------------------

### Genotype and Ancestry Configuration Arguments

Source: https://github.com/mancusolab/sushie/blob/main/docs/manual.md

Configuration options for providing genotype data in various formats and mapping subject ancestry indices.

```APIDOC
## CLI Arguments

### Description
These arguments define the input genotype data formats and ancestry mapping for SuShiE analysis.

### Parameters
#### Command Line Arguments
- **--plink** (String) - Optional - Genotype data in plink 1 format. Requires bed, bim, and fam files with the same prefix. Use space to separate multiple ancestries.
- **--vcf** (String) - Optional - Genotype data in vcf format. Use space to separate multiple ancestries.
- **--bgen** (String) - Optional - Genotype data in bgen 1.3 format. Use space to separate multiple ancestries.
- **--ancestry-index** (String) - Optional - Path to a TSV file containing subject ID and ancestry index. The file must have no headers, with the first column as subject ID and the second as ancestry index (starting from 1).
```

--------------------------------

### Use 32-bit Precision for Inference

Source: https://github.com/mancusolab/sushie/blob/main/docs/manual.md

To switch from the default 64-bit precision to 32-bit precision, use the `--precision 32` flag. Note that 32-bit precision may lead to less accurate inference and potential issues like non-positive semi-definite covariance priors or premature ELBO convergence.

```bash
cd ./data/
sushie finemap --pheno EUR.pheno AFR.pheno --vcf vcf/EUR.vcf vcf/AFR.vcf --precision 32 --output ./test_result
```

--------------------------------

### Three-Ancestry SuShiE

Source: https://github.com/mancusolab/sushie/blob/main/docs/manual.md

Perform three-ancestry SuShiE with specified phenotypes, VCF files, and covariates.

```bash
cd ./data/
sushie finemap --pheno EUR.pheno AFR.pheno EAS.pheno --vcf vcf/EUR.vcf vcf/AFR.vcf vcf/EAS.vcf --covar EUR.covar AFR.covar EAS.covar --output ./test_result
```

--------------------------------

### Run Fine-Mapping on Specific Subjects

Source: https://github.com/mancusolab/sushie/blob/main/docs/manual.md

To restrict fine-mapping inference to a specific set of subjects, provide a file containing subject IDs using the `--keep` command.

```bash
cd ./data/
sushie finemap --pheno EUR.pheno AFR.pheno --vcf vcf/EUR.vcf vcf/AFR.vcf --keep keep.subject --output ./test_result
```

--------------------------------

### Mega SuShiE Analysis

Source: https://github.com/mancusolab/sushie/blob/main/docs/manual.md

Run mega SuShiE by performing single-ancestry SuShiE on row-wise stacked genotype and phenotype data across ancestries.

```bash
cd ./data/
sushie finemap --pheno EUR.pheno AFR.pheno --vcf vcf/EUR.vcf vcf/AFR.vcf --mega --output ./test_result
```

--------------------------------

### Read VCF Files

Source: https://context7.com/mancusolab/sushie/llms.txt

Load genotype data from VCF format using cyvcf2.

```python
from sushie.io import read_vcf

# Read VCF file
bim, fam, bed = read_vcf("path/to/data/EUR.vcf")

print(f"Loaded {bed.shape[0]} samples, {bed.shape[1]} variants")
print(f"Alleles: REF is counted (0=hom ref, 1=het, 2=hom alt)")
```

--------------------------------

### Create a New Branch for Changes

Source: https://github.com/mancusolab/sushie/blob/main/docs/contributing.md

Before making any modifications, create a new branch to isolate your work from the main codebase. Avoid working directly on the master branch.

```bash
git checkout -b my-feature
```

--------------------------------

### Sushie Fine-Mapping Configuration

Source: https://github.com/mancusolab/sushie/blob/main/docs/manual.md

Configuration options for fine-mapping with Sushie, including subsetting by genomic position and specifying GWAS details.

```APIDOC
## Sushie Fine-Mapping Parameters

### Description
This section details the command-line parameters used to configure the Sushie fine-mapping tool, focusing on subsetting GWAS data by genomic position, sample size, and header information.

### Parameters

#### Command-Line Flags

- `--start` (Integer) - Optional - Base-pair start position to subset GWAS SNPs in the fine-mapping. Default is None. Value has to be a positive integer number. The SNP position information from the first ancestry will be used for filtering. If this flag is specified, –chrom and –end must also be provided.
- `--end` (Integer) - Optional - Base-pair end position to subset GWAS SNPs in the fine-mapping. Default is None. Value has to be a positive integer number. The SNP position information from the first ancestry will be used for filtering. If this flag is specified, –chrom and –start must also be provided.
- `--sample-size` (Integer) - Optional - GWAS sample size of each ancestry. Default is None. Values have to be positive integer. Use ‘space’ to separate ancestries if more than two. The order has to be the same as the GWAS data in –gwas.
- `--gwas-header` (String) - Optional - GWAS file header names. Default is [‘chrom’, ‘snp’, ‘pos’, ‘a1’, ‘a0’, ‘z’]. Users can specify the header names for the GWAS data in this order.

### Examples

#### Subset by genomic position:
`--chrom 1 --start 10000 --end 50000`

#### Specify sample sizes for two ancestries:
`--sample-size 489 639`

#### Specify custom GWAS headers:
`--gwas-header CHR SNP BP A1 A2 Z`
```

--------------------------------

### Pushing Release Tag

Source: https://github.com/mancusolab/sushie/blob/main/docs/contributing.md

Push the newly created release tag to the upstream repository. This makes the tag available to others.

```bash
git push upstream v1.2.3
```

--------------------------------

### Push Local Branch to GitHub

Source: https://github.com/mancusolab/sushie/blob/main/docs/contributing.md

Once your changes are complete and tests pass, push your local feature branch to the remote GitHub repository to prepare for a pull request.

```bash
git push -u origin my-feature
```

--------------------------------

### Heritability Estimation, CV, and FUSION Files

Source: https://github.com/mancusolab/sushie/blob/main/docs/manual.md

Estimate heritability, perform cross-validation (CV), and generate FUSION files using SuShiE. Requires Rscript for FUSION file generation.

```bash
cd ./data/
sushie finemap --pheno EUR.pheno AFR.pheno --vcf vcf/EUR.vcf vcf/AFR.vcf --cv --her --output ./test_result
Rscript ./misc/make_FUSION.R ./test_result ~
```

--------------------------------

### SuShiE with PLINK 1 Genotypes

Source: https://github.com/mancusolab/sushie/blob/main/docs/manual.md

Use SuShiE with PLINK 1 genotype data, providing the triplet (bed, bim, fam) prefix for each ancestry.

```bash
cd ./data/
sushie finemap --pheno EUR.pheno AFR.pheno --plink plink/EUR plink/AFR --output ./test_result
```

--------------------------------

### Tagging a Release Commit

Source: https://github.com/mancusolab/sushie/blob/main/docs/contributing.md

Tag the current commit on the main branch with a release tag. This is a crucial step before pushing the release.

```bash
git tag v1.2.3
```

--------------------------------

### Save All Inference Results as NumPy Files

Source: https://github.com/mancusolab/sushie/blob/main/docs/manual.md

To save all inference results, including SNP information, prior and posterior estimators, credible sets, PIPs, and sample size, in `*.npy` files, specify the `--numpy` option.

```bash
cd ./data/
sushie finemap --pheno EUR.pheno AFR.pheno --vcf vcf/EUR.vcf vcf/AFR.vcf --numpy --output ./test_result
```

--------------------------------

### Fine-mapping with custom GWAS column headers

Source: https://github.com/mancusolab/sushie/blob/main/docs/manual.md

Specify custom column names for GWAS summary statistics files.

```bash
cd ./data/
sushie finemap --summary --gwas EUR.gwas AFR.gwas --vcf vcf/EUR.vcf vcf/AFR.vcf --sample-size 489 639 --gwas-header CHR SNP BP A1 A2 STAT --output ./test_result
```

--------------------------------

### Fine-mapping with LD matrix adjustment

Source: https://github.com/mancusolab/sushie/blob/main/docs/manual.md

Adjust the LD matrix by adding a small value to the diagonal to ensure it is positive definite.

```bash
cd ./data/
sushie finemap --summary --gwas EUR.gwas AFR.gwas --ld EUR.ld AFR.ld --sample-size 489 639 --ld-adjust 1e-3 --output ./test_result
```

--------------------------------

### Individual-Level Fine-Mapping with Python API

Source: https://context7.com/mancusolab/sushie/llms.txt

Use the infer_sushie function to perform Bayesian fine-mapping on numpy arrays. Requires centered and standardized genotype matrices.

```python
import numpy as np
from sushie.infer import infer_sushie

# Generate example data for 2 ancestries
# Ancestry 1: 200 samples, 500 SNPs
np.random.seed(42)
n1, n2, p = 200, 300, 500

# Create genotype matrices (centered, standardized)
X1 = np.random.randn(n1, p)
X2 = np.random.randn(n2, p)

# Create phenotypes with causal SNPs at indices 10 and 50
beta_true = np.zeros(p)
beta_true[10] = 0.5
beta_true[50] = 0.3
y1 = X1 @ beta_true + np.random.randn(n1) * 0.5
y2 = X2 @ beta_true + np.random.randn(n2) * 0.5

# Run SuShiE fine-mapping
result = infer_sushie(
    Xs=[X1, X2],
    ys=[y1, y2],
    L=5,                    # Number of effects to infer
    threshold=0.95,         # Credible set PIP threshold
    purity=0.5,             # Minimum purity for credible sets
    max_iter=500,           # Maximum optimization iterations
    min_tol=1e-4,           # Convergence tolerance
    seed=12345
)

# Access results
print("Posterior Inclusion Probabilities (all effects):")
print(f"  Top 5 SNPs: {np.argsort(-result.pip_all)[:5]}")
print(f"  Max PIP: {result.pip_all.max():.4f}")

print("\nCredible Sets:")
print(result.cs[['CSIndex', 'SNPIndex', 'alpha', 'pip_all']])

# Get effect size estimates per ancestry
weights = np.sum(result.posteriors.post_mean, axis=0)  # L x p x k -> p x k
print(f"\nEffect weights shape: {weights.shape}")  # (500, 2) for 2 ancestries
```

--------------------------------

### Assign Prior Weights for Each SNP

Source: https://github.com/mancusolab/sushie/blob/main/docs/manual.md

To assign custom prior weights for each SNP, specify a TSV file containing SNP IDs and their weights using the `--pi` command. The weights will be normalized to sum to 1 before inference.

```bash
cd ./data/
sushie finemap --pheno EUR.pheno AFR.pheno --vcf vcf/EUR.vcf vcf/AFR.vcf --pi prior_weights --output ./test_result
```

--------------------------------

### Heritability Estimation Output (*.her.tsv)

Source: https://github.com/mancusolab/sushie/blob/main/docs/files.md

Describes the structure of the heritability estimation output file generated when the --her flag is used.

```APIDOC
## Heritability Estimation Output (*.her.tsv)

### Description
This file tracks the heritability analysis results for each ancestry, performing two rounds of estimation: one using all SNPs and one using SNPs in the credible set.

### Columns
- **ancestry** (Integer) - The ancestry index.
- **genetic_var** (Float) - The variance of genetic components contributing to the complex traits. Includes s_genetic_var if credible sets are non-empty.
- **h2g** (Float) - The narrow-sense cis-heritability of the traits based on limix definition.
- **lrt_stats** (Float) - The likelihood ratio test statistics comparing the linear mixed effects model to the fixed effects model. Includes s_lrt_stats if credible sets are non-empty.
- **p_value** (Float) - The p-value for the likelihood ratio test statistics. Includes s_p_value if credible sets are non-empty.
- **trait** (String) - The trait, tissue, or gene name.
```

--------------------------------

### Python API for SuShiE Inference (Individual-Level Data)

Source: https://github.com/mancusolab/sushie/blob/main/README.md

This Python code snippet shows how to use the `infer_sushie` function from the `sushie.infer` module for fine-mapping with individual-level genotype (Xs) and phenotype (ys) data. Ensure Xs and ys are lists of numpy arrays corresponding to each ancestry.

```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)
```

--------------------------------

### Python API for SuShiE Inference (Summary-Level Data)

Source: https://github.com/mancusolab/sushie/blob/main/README.md

This Python code demonstrates the use of `infer_sushie_ss` for fine-mapping with summary-level data. It requires LD data (lds) and GWAS summary statistics (zs) as lists of numpy arrays, along with sample sizes (ns).

```python
# 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]))
```

--------------------------------

### SuShiE Output Data Fields

Source: https://github.com/mancusolab/sushie/blob/main/docs/files.md

Definition of columns and data types found in SuShiE output files such as *.meta.weights.tsv and *.cs.tsv.

```APIDOC
## SuShiE Output Fields

### Description
This table defines the fields present in SuShiE output files, providing the data type and description for each metric.

### Fields
- **trait** (String) - The trait, tissue, or gene name.
- **ancestry1_sushie_weight** (Float) - The ancestry-specific SNP prediction weights inferred by SuShiE. For *.meta.weights.tsv, it includes ancestry-specific weights; for --mega, it includes mega_weight.
- **sushie_pip_all** (Float) - The posterior inclusion probability for all SNPs calculated across L credible sets.
- **sushie_pip_cs** (Float) - The posterior inclusion probability for SNPs calculated across credible sets kept after pruning based on purity.
- **sushie_cs_index** (Integer) - The credible set index where the SNPs fall into. 0 indicates no credible sets contain the SNP.
- **n_snps** (Integer) - The number of total SNPs in the inference.
```

--------------------------------

### Python API: infer_sushie

Source: https://context7.com/mancusolab/sushie/llms.txt

Performs Bayesian fine-mapping using individual-level genotype and phenotype data from multiple ancestries.

```APIDOC
## Python API: infer_sushie

### Description
Performs Bayesian fine-mapping using individual-level genotype and phenotype data from multiple ancestries.

### Parameters
- **Xs** (list of arrays) - Required - List of genotype matrices (centered, standardized).
- **ys** (list of arrays) - Required - List of phenotype vectors.
- **L** (int) - Optional - Number of effects to infer.
- **threshold** (float) - Optional - Credible set PIP threshold.
- **purity** (float) - Optional - Minimum purity for credible sets.
- **max_iter** (int) - Optional - Maximum optimization iterations.
- **min_tol** (float) - Optional - Convergence tolerance.
- **seed** (int) - Optional - Random seed for reproducibility.

### Response
- **result** (object) - Contains posterior inclusion probabilities (pip_all) and credible sets (cs).
```

--------------------------------

### Read LD Matrix

Source: https://context7.com/mancusolab/sushie/llms.txt

Load a pre-computed LD correlation matrix from a TSV file.

```python
from sushie.io import read_ld

# Read LD matrix (SNP IDs as column headers)
ld = read_ld("path/to/EUR.ld")

print(f"LD matrix shape: {ld.shape}")
print(f"SNPs: {ld.columns[:5].tolist()}")
# Returns DataFrame with SNP IDs as index and columns
```