SuShiE

https://mancusolab.github.io/sushie
Admin
SuShiE is a Python package for multiancestry SNP fine-mapping that estimates effect size...
Tokens:124,130
Snippets:590
Trust Score:9.7
Update:6 months ago
Show doc for...
Tokens:
Raw
### Build API Documentation Locally

Source: https://mancusolab.github.io/sushie/contributing.html?q=

To build API documentation, ensure the sushie package and its dependencies are installed. This example shows setting up a conda environment and installing necessary packages.

```bash
# Create and activate a conda environment with dependencies
conda create -n sushie-docs python=3.10
conda activate sushie-docs

# Install sushie and all dependencies
pip install -r requirements.txt -r requirements_dev.txt
pip install -e .

# Now build the docs
make -C docs html

```

```bash
tox -r -e docs

```

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

### Install SuShiE via Pip

Source: https://mancusolab.github.io/sushie/manual.html

Clone the repository and install the package using pip.

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

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

### Main CLI execution logic

Source: https://mancusolab.github.io/sushie/_modules/sushie/cli.html

Handles argument parsing, logging setup, and execution of the fine-mapping process.

```python
def _main(argsv):
    version = metadata.version("sushie")

    # setup main parser
    argp = argparse.ArgumentParser(
        formatter_class=argparse.ArgumentDefaultsHelpFormatter
    )
    argp.add_argument("--version", action="version", version=version)
    subp = argp.add_subparsers(
        help="Subcommands: finemap to perform gene expression fine-mapping using SuShiE"
    )

    finemap = build_finemap_parser(subp)
    finemap.set_defaults(func=run_finemap)

    # parse arguments
    args = argp.parse_args(argsv)

    cmd_str = _get_command_string(argsv)

    version = metadata.version("sushie")

    masthead = "===================================" + os.linesep
    masthead += f"             SuShiE v{version}             " + os.linesep
    masthead += "===================================" + os.linesep

    # setup logging
    log_format = "[%(asctime)s - %(levelname)s] %(message)s"
    date_format = "%Y-%m-%d %H:%M:%S"

    if args.verbose:
        log.logger.setLevel(logging.DEBUG)
    else:
        log.logger.setLevel(logging.INFO)
    fmt = logging.Formatter(fmt=log_format, datefmt=date_format)
    log.logger.propagate = False

    # write to stdout unless quiet is set
    if not args.quiet:
        sys.stdout.write(masthead)
        sys.stdout.write(cmd_str)
        sys.stdout.write("Starting log..." + os.linesep)
        stdout_handler = logging.StreamHandler(sys.stdout)
        stdout_handler.setFormatter(fmt)
        log.logger.addHandler(stdout_handler)

    # setup log file, but write PLINK-style command first
    disk_log_stream = open(f"{args.output}.log", "w")
    disk_log_stream.write(masthead)
    disk_log_stream.write(cmd_str)
    disk_log_stream.write("Starting log..." + os.linesep)

    disk_handler = logging.StreamHandler(disk_log_stream)
    disk_handler.setFormatter(fmt)
    log.logger.addHandler(disk_handler)

    # launch finemap
    args.func(args)

    return 0
```

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

### Run all project tests with tox

Source: https://mancusolab.github.io/sushie/contributing.html?q=

Execute all pre-configured tasks and unit tests for the project using tox. Ensure tox is installed.

```bash
tox
```

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

### Clone and Set Up Repository

Source: https://mancusolab.github.io/sushie/contributing.html?q=

Clone the forked sushie repository to your local disk. Install the project in editable mode and set up pre-commit hooks for code quality checks.

```bash
git clone git@github.com:YourLogin/sushie.git
cd sushie

```

```bash
pip install -U pip setuptools -e .

```

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

```

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

### Run SuShiE fine-mapping

Source: https://mancusolab.github.io/sushie/_modules/sushie/infer.html

Basic usage example demonstrating how to run SuShiE with two-ancestry data and access the resulting PIPs and credible sets.

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

# Generate example data for 2 ancestries
# Ancestry 1: 100 samples, 500 SNPs
X1 = np.random.randn(100, 500)
y1 = np.random.randn(100)

# Ancestry 2: 150 samples, 500 SNPs
X2 = np.random.randn(150, 500)
y2 = np.random.randn(150)

# Run SuShiE fine-mapping
result = infer_sushie(Xs=[X1, X2], ys=[y1, y2], L=5)

# Access results
print(result.pip)       # Posterior inclusion probabilities
print(result.cs)        # Credible sets
```

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

### Install SuShiE using pip

Source: https://mancusolab.github.io/sushie/manual.html?q=

Clone the SuShiE repository and install it using pip. Ensure you are in the desired conda environment before running these commands.

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

```

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

### Create and activate a virtual environment for tox

Source: https://mancusolab.github.io/sushie/contributing.html?q=

When facing issues with tox, create a dedicated virtual environment, install tox, and then run tox commands within it.

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

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

### Check tox version and location

Source: https://mancusolab.github.io/sushie/contributing.html?q=

Verify your tox installation and its location. This helps in troubleshooting tox-related issues.

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

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

### SuShiE with Combined Participants and Ancestry Index

Source: https://mancusolab.github.io/sushie/manual.html?q=

Run SuShiE when all subjects are in single files. Use '--ancestry-index' to specify subject ID and ancestry index (starting from 1). Ensure data is in the 'data/' directory.

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

```

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

### Install cbgen Dependency

Source: https://mancusolab.github.io/sushie/manual.html

Install the cbgen package from conda-forge, which is required for JAX compatibility on Mac M1 chips.

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

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

### Configure Output and Execution Options

Source: https://mancusolab.github.io/sushie/_modules/sushie/cli.html

These arguments control output formats, logging verbosity, and hardware acceleration settings.

```python
    finemap.add_argument(
        "--alphas",
        default=False,
        action="store_true",
        help=(
            "Indicator to output all the cs (alphas) results before pruning for purity",
            " including PIPs, alphas, whether in cs, across all L.",
            " Default is False. Specify --alphas will store 'True' value and increase running time.",
        ),
    )

    finemap.add_argument(
        "--numpy",
        default=False,
        action="store_true",
        help=(
            "Indicator to output all the results in *.npy file.",
            " Default is False. Specify --numpy will store 'True' value and increase running time.",
            " *.npy file contains all the inference results including credible sets, pips, priors and posteriors",
            " for your own post-hoc analysis.",
        ),
    )

    finemap.add_argument(
        "--trait",
        default="Trait",
        help=(
            "Trait, tissue, gene name of the phenotype for better indexing in post-hoc analysis. Default is 'Trait'.",
        ),
    )

    # misc options
    finemap.add_argument(
        "--quiet",
        default=False,
        action="store_true",
        help="Indicator to not print message to console. Default is False. Specify --quiet will store 'True' value.",
    )

    finemap.add_argument(
        "--verbose",
        default=False,
        action="store_true",
        help=(
            "Indicator to include debug information in the log. Default is False.",
            " Specify --verbose will store 'True' value.",
        ),
    )

    finemap.add_argument(
        "--compress",
        default=False,
        action="store_true",
        help=(
            "Indicator to compress all output tsv files in tsv.gz.",
            " Default is False. Specify --compress will store 'True' value to save disk space.",
            " This command will not compress *.npy files.",
        ),
    )

    finemap.add_argument(
        "--platform",
        default="cpu",
        type=str,
        choices=["cpu", "gpu", "tpu"],
        help=(
            "Indicator for the JAX platform. It has to be 'cpu', 'gpu', or 'tpu'. Default is cpu.",
        ),
    )

    finemap.add_argument(
        "--jax-precision",
        default=64,
        type=int,
        choices=[32, 64],
        help=(
            "Indicator for the JAX precision: 64-bit or 32-bit.",
            " Default is 64-bit. Choose 32-bit may cause 'elbo decreases' warning.",
        ),
    )
```

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

### Validate Fine-Mapping Region Coordinates

Source: https://mancusolab.github.io/sushie/_modules/sushie/cli.html

Ensures start and end positions are positive and that the end position is greater than the start position when a region is specified.

```python
elif args.chrom is not None and args.start is not None and args.end is not None:
        if args.start <= 0:
            raise ValueError(
                "The start position for the region must be greater than 0. Update with --start."
            )

        if args.end <= 0:
            raise ValueError(
                "The end position for the region must be greater than 0. Update with --end."
            )

        if args.end <= args.start:
            raise ValueError(
                "The end position for the region must be greater than --start. Update with"
                + " --start or --end."
            )

        log.logger.info(
            f"Detect region (chrom{args.chrom}:{args.start}:{args.end}) to be fine-mapped."
            + " Will only use SNPs within the region."
        )
```

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

### Build distributions with tox

Source: https://mancusolab.github.io/sushie/contributing.html?q=

Use tox to build the distribution files for the new release. Verify that the files in 'dist' have the correct version and are not excessively large.

```bash
tox -e build
```

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

### Estimate Cis-Heritability

Source: https://mancusolab.github.io/sushie/_modules/sushie/utils.html

Calculates the proportion of expression variation explained by genotypes. Includes an example usage snippet.

```python
def estimate_her(
    X: ArrayLike,
    y: ArrayLike,
    covar: ArrayLike = None,
    normalize: bool = True,
) -> Tuple[float, Array, float, float]:
    """Calculate proportion of expression variation explained by genotypes (cis-heritability; :math:`h_g^2`).

    Args:
        X: :math:`n \times p` matrix for independent variables with no intercept vector.
        y: :math:`n \times 1` vector for gene expression.
        covar: :math:`n \times m` matrix for covariates.
        normalize: Boolean value to indicate whether normalize X and y

    Returns:
        :py:obj:`Tuple[float, Array, float, float]`: A tuple of
            #. genetic variance (:py:obj:`float`) of the complex trait,
            #. :math:`h_g^2` (:py:obj:`Array`) from `limix <https://github.com/limix/limix>`_ definition,
            #. LRT test statistics (:py:obj:`float`) for :math:`h_g^2`,
            #. LRT :math:`p` value (:py:obj:`float`) for :math:`h_g^2`.

    Example:
        Estimate cis-heritability for a gene::

            import numpy as np
            from sushie.utils import estimate_her

            # Genotype matrix (100 samples, 500 SNPs)
            X = np.random.randn(100, 500)
            # Gene expression
            y = np.random.randn(100)

            # Estimate heritability
            g, h2g, lrt_stat, p_value = estimate_her(X, y)
            print(f"Heritability: {h2g:.3f}, p-value: {p_value:.4f}")

    """
    n, p = X.shape

    if normalize:
        X -= jnp.mean(X, axis=0)
        X /= jnp.std(X, axis=0)
        y -= jnp.mean(y)
        y /= jnp.std(y)

    if covar is None:
        covar = jnp.ones(n)

    GRM = jnp.dot(X, X.T) / p
```

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

### Enable GPU Acceleration

Source: https://mancusolab.github.io/sushie/manual.html?q=

Utilize JAX-based GPU or TPU acceleration for faster computation.

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

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

### GET /io/read_ld

Source: https://mancusolab.github.io/sushie/_modules/sushie/io.html?q=

Reads an LD correlation matrix from a TSV file, performing automatic cleaning of infinite or NaN values.

```APIDOC
## GET /io/read_ld

### Description
Reads an LD (linkage disequilibrium) matrix from a TSV file. The matrix is expected to be a symmetric correlation matrix where rows and columns represent SNPs.

### Method
GET

### Parameters
#### Query Parameters
- **path** (string) - Required - The file system path to the tab-separated LD matrix file.

### Response
#### Success Response (200)
- **ld** (pd.DataFrame) - A cleaned LD correlation matrix with SNP IDs as both index and columns.

### Response Example
{
  "ld": "pd.DataFrame object with shape (n_snps, n_snps)"
}
```

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

### CLI entry point

Source: https://mancusolab.github.io/sushie/_modules/sushie/cli.html

Standard entry point functions for the CLI.

```python
def run_cli():
    return _main(sys.argv[1:])


if __name__ == "__main__":
    sys.exit(_main(sys.argv[1:]))
```

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

### Handle No Region Specification

Source: https://mancusolab.github.io/sushie/_modules/sushie/cli.html

Logs a debug message if no specific region (chrom, start, end) is provided, indicating all available SNPs will be used.

```python
if args.chrom is None and args.start is None and args.end is None:
        log.logger.debug(
            "No region is specified. Will use all SNPs available in the data."
        )
```

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

### Run SuShiE with Summary-Level Data

Source: https://mancusolab.github.io/sushie/_modules/sushie/cli.html?q=

Initiates SuShiE fine-mapping using summary statistics. Requires pre-processed summary data and configuration parameters.

```python
            log.logger.info(f"Start fine-mapping using SuShiE with {args.L} effects.")
            tmp_result = infer_ss.infer_sushie_ss(
                lds=data.lds,
                ns=data.ns,
                zs=data.zs,
                L=args.L,
                no_update=args.no_update,
                pi=data.pi,
                resid_var=args.resid_var,
                effect_var=args.effect_var,
                rho=args.rho,
                max_iter=args.max_iter,
                min_tol=args.min_tol,
                threshold=args.threshold,
                purity=args.purity,
                purity_method=args.purity_method,
                max_select=args.max_select,
                min_snps=args.min_snps,
                no_reorder=args.no_reorder,
                seed=args.seed,
            )
            result.append(tmp_result)
```

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

### Recreate tox environment with missing dependencies

Source: https://mancusolab.github.io/sushie/contributing.html?q=

If tox encounters missing dependencies, try recreating the environment using the -r flag. This is useful when dependencies are updated in setup.cfg or requirements.txt.

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

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

### Subset analysis by genomic region

Source: https://mancusolab.github.io/sushie/manual.html

Specify the chromosome, start position, and end position to limit the fine-mapping analysis to a particular genomic window.

```bash
cd ./data/
sushie finemap --summary --gwas EUR.gwas AFR.gwas --vcf vcf/EUR.vcf vcf/AFR.vcf --sample-size 489 639 --chrom 1 --start 34886700 --end 35128637 --output ./test_result
```

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

### Read GWAS Data

Source: https://mancusolab.github.io/sushie/api/io/read_gwas.html?q=

Reads GWAS data from a specified TSV file path. Supports filtering by chromosome, start, and end positions.

```APIDOC
## POST /websites/mancusolab_github_io_sushie/read_gwas

### Description
Reads GWAS data from a TSV file. Allows specifying the file path, header information, and optionally filtering by chromosome, start, and end positions.

### Method
POST

### Endpoint
/websites/mancusolab_github_io_sushie/read_gwas

### Parameters
#### Query Parameters
- **path** (str) - Required - The path for GWAS data (full file name).
- **header** (List[str]) - Required - The header for GWAS data.
- **chrom** (int | None) - Optional - The chromosome number.
- **start** (int | None) - Optional - The start position.
- **end** (int | None) - Optional - The end position.

### Request Example
```json
{
  "path": "/path/to/your/gwas_data.tsv",
  "header": ["SNP", "CHR", "BP", "P"],
  "chrom": 1,
  "start": 1000000,
  "end": 2000000
}
```

### Response
#### Success Response (200)
- **DataFrame** (pd.DataFrame) - A pandas DataFrame containing the GWAS data.

#### Response Example
```json
{
  "SNP": ["rs123", "rs456"],
  "CHR": [1, 1],
  "BP": [1000001, 1000002],
  "P": [1.2e-5, 3.4e-6]
}
```
```

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

### Sushie CLI Configuration Parameters

Source: https://mancusolab.github.io/sushie/manual.html

A list of available command-line arguments for configuring the Sushie execution environment.

```APIDOC
## CLI Configuration Parameters

### Description
Configuration flags for controlling the execution, logging, and output behavior of the Sushie tool.

### Parameters
- **--quiet** (Boolean) - Optional - Default: False. If specified, suppresses console messages.
- **--verbose** (Boolean) - Optional - Default: False. If specified, includes debug information in the log.
- **--compress** (Boolean) - Optional - Default: False. If specified, compresses output tsv files into 'tsv.gz' to save disk space (does not affect npy files).
- **--platform** (String) - Optional - Default: cpu. Choices: ["cpu", "gpu", "tpu"]. Sets the JAX platform.
- **--jax-precision** (Integer) - Optional - Default: 64. Choices: [32, 64]. Sets the JAX precision; note that 32-bit may trigger 'elbo decreases' warnings.
- **--output** (String) - Optional - Default: sushie_finemap. Sets the prefix for output files.
```

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

### Publish to PyPI with tox

Source: https://mancusolab.github.io/sushie/contributing.html?q=

Upload the built distributions to PyPI using tox. Confirm that the upload was successful.

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

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

### SuShiE CLI Configuration Arguments

Source: https://mancusolab.github.io/sushie/_modules/sushie/cli.html

A comprehensive list of command-line arguments used to configure the SuShiE fine-mapping process.

```APIDOC
## CLI Arguments

### Description
Configuration options for the SuShiE fine-mapping pipeline.

### Parameters
- **--mega** (boolean) - Optional - Perform mega SuShiE by row-wise stacking genotype and phenotype data across ancestries.
- **--her** (boolean) - Optional - Perform heritability (h2g) analysis using limix.
- **--cv** (boolean) - Optional - Perform cross validation and output results for FUSION pipeline.
- **--cv-num** (integer) - Optional - Number of folds for cross validation. Default: 5.
- **--seed** (integer) - Optional - Randomization seed for CV and purity calculation. Default: 12345.
- **--alphas** (boolean) - Optional - Output all cs (alphas) results before pruning.
- **--numpy** (boolean) - Optional - Output all results in *.npy file format.
- **--trait** (string) - Optional - Trait, tissue, or gene name for indexing. Default: 'Trait'.
- **--quiet** (boolean) - Optional - Suppress console messages.
- **--verbose** (boolean) - Optional - Include debug information in logs.
- **--compress** (boolean) - Optional - Compress output tsv files to tsv.gz.
- **--platform** (string) - Optional - JAX platform: 'cpu', 'gpu', or 'tpu'. Default: 'cpu'.
- **--jax-precision** (integer) - Optional - JAX precision: 32 or 64. Default: 64.
```

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

### Get the latest release tag

Source: https://mancusolab.github.io/sushie/contributing.html?q=

Fetch all tags from the upstream repository to ensure you have the latest release information. This command should return the expected version tag.

```bash
git describe --abbrev=0 --tags
```

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

### Filter SNPs by Chromosomal Region

Source: https://mancusolab.github.io/sushie/manual.html?q=

This command allows you to focus on SNPs within a specific chromosomal range. Provide the chromosome number, start, and end positions.

```bash
cd ./data/
sushie finemap --summary --gwas EUR.gwas AFR.gwas --vcf vcf/EUR.vcf vcf/AFR.vcf --sample-size 489 639 --chrom 1 --start 34886700 --end 35128637 --output ./test_result

```

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

### Initialize Conda Environment

Source: https://mancusolab.github.io/sushie/manual.html

Create and activate a dedicated conda environment for SuShiE using Python 3.10.

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

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

### Sushie CLI Configuration Parameters

Source: https://mancusolab.github.io/sushie/manual.html

A comprehensive list of command-line arguments for configuring GWAS data processing, statistical priors, and optimization parameters in Sushie.

```APIDOC
## CLI Configuration Parameters

### Parameters
- **--sample-size** (Integer) - Optional - GWAS sample size of each ancestry. Default is None. Values must be positive integers.
- **--gwas-header** (String) - Optional - GWAS file header names. Default is ['chrom', 'snp', 'pos', 'a1', 'a0', 'z'].
- **--gwas-sig** (Float) - Optional - Significance threshold for SNPs to be included in fine-mapping. Default is 1.0.
- **--gwas-sig-type** (String) - Optional - Strategy for including significant SNPs ('at-least' or 'all'). Default is 'at-least'.
- **--L** (Integer) - Optional - Number of shared effects pre-specified. Default is 10.
- **--pi** (String) - Optional - Prior probability for each SNP to be causal. Default is 'uniform'.
- **--resid-var** (Float) - Optional - Prior for the residual variance for ancestries.
- **--effect-var** (Float) - Optional - Prior for the causal effect size variance for ancestries.
- **--rho** (Float) - Optional - Prior for the effect correlation for ancestries. Default is 0.1.
- **--no-scale** (Boolean) - Optional - If present, disables scaling of genotype and phenotype data by standard deviation.
- **--no-regress** (Boolean) - Optional - If present, disables regression of covariates on each SNP.
- **--no-update** (Boolean) - Optional - If present, disables updating of effect covariance prior.
- **--max-iter** (Integer) - Optional - Maximum iterations for the optimization. Default is 500.
```

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

### Handle Incorrect Region Specification

Source: https://mancusolab.github.io/sushie/_modules/sushie/cli.html

Raises a ValueError if the region is not specified correctly, requiring --chrom, --start, and --end to be provided together or omitted entirely.

```python
else:
        raise ValueError(
            "The region is not specified correctly. Please provide --chrom, --start, and --end together,"
            + " or omit all of them."
        )
```

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

### SuShiE CLI Execution Parameters

Source: https://mancusolab.github.io/sushie/manual.html

Configuration parameters for running the SuShiE fine-mapping software via command line.

```APIDOC
## CLI Parameters

### Parameters
#### Options
- **--summary** (Boolean) - Optional - Indicator whether to run fine-mapping on summary statistics. Default is False.
- **--pheno** (String) - Required - Phenotype data (tsv or tsv.gz). First column: subject ID, second column: continuous phenotypic value. No headers.
- **--plink** (String) - Optional - Genotype data in plink 1 format (triplet bed, bim, fam).
- **--vcf** (String) - Optional - Genotype data in vcf format.
- **--bgen** (String) - Optional - Genotype data in bgen 1.3 format.
- **--ancestry-index** (String) - Optional - File containing subject ID and ancestry index (tsv or tsv.gz). No headers.
- **--keep** (String) - Optional - File containing subject IDs to include in fine-mapping (tsv or tsv.gz). No headers.
- **--covar** (String) - Optional - Covariates file (tsv or tsv.gz). First column: subject ID. No headers.
- **--ld** (String) - Optional - LD files (tsv or tsv.gz). Header must match SNP names in GWAS data.
- **--chrom** (Integer) - Optional - Chromosome number (1-22) to subset GWAS SNPs. Requires --start and --end.
- **--start** (Integer) - Optional - Base-pair start position. Requires --chrom and --end.
- **--end** (Integer) - Optional - Base-pair end position. Requires --chrom and --start.
```

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

### Filter SNPs by Chromosome and Position

Source: https://mancusolab.github.io/sushie/_modules/sushie/cli.html

Filters SNPs based on chromosome, start position, and end position. Raises a ValueError if no SNPs remain after filtering on a specific chromosome or position range.

```python
log.logger.debug(
        "Filter SNPs based on Chrom, Start, and End using coordinates of first ancestry."
    )
    snps["chrom"] = snps["chrom"].astype("int64")

    if chrom is not None:
        old_num = snps.shape[0]
        snps = snps[snps.chrom == chrom]
        del_num = old_num - snps.shape[0]

        if snps.shape[0] == 0:
            raise ValueError(f"No SNPs remain after filtering on chromosome {chrom}.")

        if del_num != 0:
            log.logger.debug(f"Drop {del_num} SNPs that are not on chromosome {chrom}.")

        old_num = snps.shape[0]
        snps = snps[snps.pos_1 >= start]
        del_num = old_num - snps.shape[0]

        if snps.shape[0] == 0:
            raise ValueError(
                f"No SNPs are located after position {start} on chromosome {chrom}."
            )

        if del_num != 0:
            log.logger.debug(
                f"Drop {del_num} SNPs that are located before position {start} on chromosome {chrom}."
            )

        old_num = snps.shape[0]
        snps = snps[snps.pos_1 <= end]
        del_num = old_num - snps.shape[0]

        if snps.shape[0] == 0:
            raise ValueError(
                f"No SNPs are located before position {end} on chromosome {chrom}."
            )

        if del_num != 0:
            log.logger.debug(
                f"Drop {del_num} SNPs that are located after position {end} on chromosome {chrom}."
            )

        snps = snps.reset_index(drop=True)
```

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

### Sushie Fine-Mapping Tool Parameters

Source: https://mancusolab.github.io/sushie/manual.html?q=

This section details the command-line arguments for the Sushie fine-mapping tool.

```APIDOC
## Sushie Fine-Mapping Tool Parameters

### Description
This section details the command-line arguments for the Sushie fine-mapping tool, covering data input, significance thresholds, prior settings, and optimization controls.

### Parameters

#### GWAS Data Input

- **`--sample-size`** (Integer) - Optional - GWAS sample size of each ancestry. Default is None. Values have to be positive integers. 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.

#### Significance Thresholds

- **`--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. It has to be a float number between 0 and 1.
- **`--gwas-sig-type`** (String) - Optional - The cases how to include significant SNPs in the fine-mapping across ancestries. If it is 'at-least', the software will include SNPs that are significant in at least one ancestry. If it is 'all', the software will include SNPs that are significant in all ancestries. Default is 'at-least'. The significant threshold is specified by `--gwas-sig`.

#### Prior Settings

- **`--L`** (Integer) - Optional - Integer number of shared effects pre-specified. Default is 10. Larger number may cause slow inference.
- **`--pi`** (String) - Optional - Prior probability for each SNP to be causal (π in Model Description). Default is uniform (i.e., 1/p where p is the number of SNPs in the region). It is fixed across all ancestries. Alternatively, users can specify the file path that contains the prior weights for each SNP. The weights have to be positive values. The weights will be normalized to sum to 1 before inference. The file has to be a tsv file that contains two columns where the first column is the SNP ID and the second column is the prior weights. Additional columns will be ignored. For SNPs do not have prior weights in the file, it will be assigned the average value of the rest. It can be a compressed file (e.g., tsv.gz). No headers.
- **`--resid-var`** (Float) - Optional - Specify the prior for the residual variance (σe2 in Model Description) for ancestries. Default is 1e-3. Values have to be positive. Use space to separate ancestries if more than two.
- **`--effect-var`** (Float) - Optional - Specify the prior for the causal effect size variance (σi,b2 in Model Description) for ancestries. Default is 1e-3. Values have to be positive. Use space to separate ancestries if more than two. If `--no-update` is specified and `--rho` is not, specifying this parameter will only fix `effect-var` as prior through optimizations and update `rho`. If `--effect-var`, `--rho`, and `--no-update` all three are specified, both `--effect-var` and `--rho` will be fixed as prior through optimizations. If `--no-update` is specified, but neither `--effect-var` nor `--rho`, both `--effect-var` and `--rho` will be fixed as default prior value through optimizations.
- **`--rho`** (Float) - Optional - Specify the prior for the effect correlation (ρ in Model Description) for ancestries. Default is 0.1 for each pair of ancestries. Use space to separate ancestries if more than two. Each rho has to be a float number between -1 and 1. If there are N > 2 ancestries, X = choose(N, 2) is required. The rho order has to be `rho(1,2)`, …, `rho(1, N)`, `rho(2,3)`, …, `rho(N-1. N)`. If `--no-update` is specified and `--effect-var` is not, specifying this parameter will only fix `rho` as prior through optimizations and update `effect-covar`. If `--effect-var`, `--rho`, and `--no-update` all three are specified, both `--effect-var` and `--rho` will be fixed as prior through optimizations. If `--no-update` is specified, but neither `--effect-var` nor `--rho`, both `--effect-var` and `--rho` will be fixed as default prior value through optimizations.

#### Optimization and Scaling

- **`--no-scale`** (Boolean) - Optional - Indicator to scale the genotype and phenotype data by standard deviation. Default is to scale (False). Specify `--no-scale` will store `True` value, and may cause different inference.
- **`--no-regress`** (Boolean) - Optional - Indicator to regress the covariates on each SNP. Default is to regress (False). Specify `--no-regress` will store `True` value. It may slightly slow the inference, but can be more accurate.
- **`--no-update`** (Boolean) - Optional - Indicator to update effect covariance prior before running single effect regression. Default is to update (False). Specify `--no-update` will store `True` value. The updating algorithm is similar to EM algorithm or Empirical Bayes method that computes the prior covariance conditioned on other parameters. See the manuscript for more information.
- **`--max-iter`** (Integer) - Optional - Maximum iterations for the optimization. Default is 500. Larger number may slow the inference while smaller may cause different inference.

### Request Example
```bash
sushie --gwas gwas1.tsv gwas2.tsv --sample-size 1000 2000 --gwas-sig 5e-8 --pi uniform --resid-var 1e-3 1e-3 --effect-var 0.1 0.1 --rho 0.5
```

### Response
This tool typically outputs fine-mapping results, which are not detailed here. The parameters above control the input and behavior of the tool.
```

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

### SuShiE CLI - run_finemap

Source: https://mancusolab.github.io/sushie/api/cli/run_finemap.html?q=

The umbrella function to run SuShiE's finemapping analysis.

```APIDOC
## run_finemap

### Description
The umbrella function to run SuShiE finemapping.

### Method
CLI Command

### Endpoint
N/A (CLI Function)

### Parameters
#### Arguments
- **args** (object) - Required - The command line parameter input for the finemapping process.

### Request Example
```bash
sushie run_finemap --input data.txt --output results.txt
```

### Response
#### Success Response (0)
- **Output**: Finemapping results are typically written to a specified output file or standard output.

#### Response Example
```
# Example output format (may vary based on SuShiE version and parameters)
Chrom	Start	End	P-value	Locus	Credible Set
1	10000	20000	1.23e-05	1	SNP1,SNP2,SNP3
```
```

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

### Filter and Prepare GWAS Data

Source: https://mancusolab.github.io/sushie/_modules/sushie/io.html

Filters and prepares GWAS data by selecting specified columns, renaming them, handling infinite and NaN values, converting types, and filtering by chromosome, start, and end positions. Raises ValueError if essential columns are missing or if no SNPs remain after filtering.

```python
if not all(col in df_gwas.columns for col in header):
        raise ValueError("The specified GWAS columns are not in the GWAS data.")

    df_gwas = (
        df_gwas[header]
        .rename(
            columns={
                header[0]: "chrom",
                header[1]: "snp",
                header[2]: "pos",
                header[3]: "a1",
                header[4]: "a0",
                header[5]: "z",
            }
        )
        .replace([jnp.inf, -jnp.inf], jnp.nan, inplace=False)
        .dropna(inplace=False)
    )

    df_gwas[["chrom"]] = df_gwas[["chrom"]].astype(int)
    df_gwas[["pos"]] = df_gwas[["pos"]].astype(int)

    log.logger.debug("Filter GWAS data based on Chrom, Start, and End.")
    if chrom is not None:
        old_num = df_gwas.shape[0]
        df_gwas = df_gwas[df_gwas.chrom == chrom]
        del_num = old_num - df_gwas.shape[0]

        if df_gwas.shape[0] == 0:
            raise ValueError(
                f"No SNPs remain after filtering on chromosome {chrom} for GWAS data from {path}."
            )

        if del_num != 0:
            log.logger.debug(
                f"Drop {del_num} SNPs that are not on chromosome {chrom} for GWAS data from {path}."
            )

        old_num = df_gwas.shape[0]
        df_gwas = df_gwas[df_gwas.pos >= start]
        del_num = old_num - df_gwas.shape[0]

        if df_gwas.shape[0] == 0:
            raise ValueError(
                f"No SNPs are located after position {start} on chromosome {chrom} for GWAS data from {path}."
            )

        if del_num != 0:
            log.logger.debug(
                f"Drop {del_num} SNPs that are located before position {start} on chromosome {chrom}."
                + " for GWAS data from {path}."
            )

        old_num = df_gwas.shape[0]
        df_gwas = df_gwas[df_gwas.pos <= end]
        del_num = old_num - df_gwas.shape[0]

        if df_gwas.shape[0] == 0:
            raise ValueError(
                f"No SNPs are located before position {end} on chromosome {chrom} for GWAS data from {path}."
            )

        if del_num != 0:
            log.logger.debug(
                f"Drop {del_num} SNPs that are located after position {end} on chromosome {chrom}."
                + " for GWAS data from {path}."
            )

    df_gwas = df_gwas.copy().reset_index(drop=True)

    return df_gwas
```

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

### Initialize Prior Variances and Correlations

Source: https://mancusolab.github.io/sushie/_modules/sushie/infer.html?q=

Sets up residual variance, effect size variance, and correlation parameters for the SuShiE model.

```python
    if resid_var is None:
        resid_var = []
        for idx in range(n_pop):
            resid_var.append(jnp.var(ys[idx], ddof=1))
    else:
        if len(resid_var) != n_pop:
            raise ValueError(
                f"Number of specified residual prior ({len(resid_var)}) does not match ancestry number ({n_pop})."
            )
        resid_var = [float(i) for i in resid_var]
        if jnp.any(jnp.array(resid_var) <= 0):
            raise ValueError(
                f"The input of residual prior ({resid_var}) is invalid (<0). Check your input."
            )

    if min_snps < L:
        raise ValueError(
            f"The number of minimum common SNPs across ancestries ({min_snps}) is less than inferred L ({L})."
            + " Specify a larger value using '--min-snps' for command-line usage"
            + " or 'min_snps=' for in-Python function calls."
        )

    if n_snps < min_snps:
        raise ValueError(
            f"The number of common SNPs across ancestries ({n_snps}) is less than minimum common"
            + " number of SNPs (100) specified."
            + " Users can specify a smaller value using '--min-snps' for command-line usage"
            + " or 'min_snps=' for in-Python function calls."
        )

    param_effect_var = effect_var
    if effect_var is None:
        effect_var = [1e-3] * n_pop
    else:
        if len(effect_var) != n_pop:
            raise ValueError(
                f"Number of specified effect prior ({len(effect_var)}) does not match ancestry number ({n_pop})."
            )
        effect_var = [float(i) for i in effect_var]
        if jnp.any(jnp.array(effect_var) <= 0):
            raise ValueError(
                f"The effect size prior variance ({effect_var}) must be positive."
            )

    exp_num_rho = math.comb(n_pop, 2)
    param_rho = rho
    if rho is None:
        rho = [0.1] * exp_num_rho
    else:
        if n_pop == 1:
            log.logger.debug(
                "Running single-ancestry SuShiE. The '--rho' parameter is specified but will be ignored."
            )

        if (len(rho) != exp_num_rho) and n_pop != 1:
            raise ValueError(
                f"Number of specified rho ({len(rho)}) does not match expected"
                + f" number {exp_num_rho}.",
            )
        rho = [float(i) for i in rho]
        # double-check the if it's invalid rho
        if jnp.any(jnp.abs(jnp.array(rho)) >= 1):
            raise ValueError(
                f"Effect size prior correlation ({rho}) must be between -1 and 1 (inclusive)."
            )

    effect_covar = jnp.diag(jnp.array(effect_var))
    ct = 0
    for col in range(n_pop):
        for row in range(1, n_pop):
            if col < row:
                _two_sd = jnp.sqrt(effect_var[row] * effect_var[col])
                effect_covar = effect_covar.at[row, col].set(rho[ct] * _two_sd)
                effect_covar = effect_covar.at[col, row].set(rho[ct] * _two_sd)
                ct += 1
```

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

### Configure Prior Probability for Causal SNPs

Source: https://mancusolab.github.io/sushie/_modules/sushie/cli.html?q=

Sets the prior probability for each SNP to be causal. The default is 'uniform' (1/p, where p is the number of SNPs). This can also be a file path to custom prior weights (TSV format, two columns: SNP ID and weight). Weights are normalized to sum to 1. SNPs not in the file get the average weight.

```python
finemap.add_argument(
        "--pi",
        default="uniform",
        type=str,
        help=(
            "Prior probability for each SNP to be causal.",
            " Default is uniform (i.e., 1/p where p is the number of SNPs in the region.",
            " It is the fixed across all ancestries.",
            " Alternatively, users can specify the file path that contains the prior weights for each SNP.",
            " The weights have to be positive value.",
            " The weights will be normalized to sum to 1 before inference.",
            " The file has to be a tsv file that contains two columns where the",
            " first column is the SNP ID and the second column is the prior weights.",
            " Additional columns will be ignored.",
            " For SNPs do not have prior weights in the file, it will be assigned the average value of the rest.",
            " It can be a compressed file (e.g., tsv.gz). No headers.",
        ),
    )
```

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

### CLI Entry Point

Source: https://mancusolab.github.io/sushie/_modules/sushie/cli.html?q=

Provides the main entry point for the SuShiE command-line interface, calling the internal _main function with command-line arguments.

```python
def run_cli():
    return _main(sys.argv[1:])
```
Tokens:
Raw