TorchGWAS

https://github.com/zhigroup/torchgwas
Admin
TorchGWAS is a software companion for Genome-Wide Association Studies, providing command-line...
Tokens:7,711
Snippets:102
Trust Score:8
License:MIT
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install TorchGWAS

Source: https://github.com/zhigroup/torchgwas/blob/main/README.md

Installs TorchGWAS in editable mode. Use the alternative command if editable installation is restricted.

```bash
cd TorchGWAS
python -m pip install -e .
```

```bash
PYTHONPATH=src python -m torchgwas ...
```

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

### Minimal Reproducible Example for Linear Workflow

Source: https://github.com/zhigroup/torchgwas/blob/main/docs/tutorial-linear.md

Run the linear workflow with a toy dataset to reproduce the full analysis pipeline. Ensure all required input files and columns are specified.

```bash
torchgwas linear \
  --genotype examples/toy/genotype.npy \
  --phenotype-table examples/toy/pheno.tsv \
  --covariates-table examples/toy/covar.tsv \
  --trait-columns trait_0,trait_1,trait_2 \
  --covariate-columns covar_0,covar_1,covar_2,covar_3 \
  --marker-ids examples/toy/markers.tsv \
  --sample-ids examples/toy/samples.tsv \
  --output-dir linear_out
```

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

### TorchGWAS Prep and Linear Workflow Example

Source: https://github.com/zhigroup/torchgwas/blob/main/README.md

Illustrates the command-line pattern for preparing genotype and phenotype data using `torchgwas prep` and then running a linear GWAS analysis with `torchgwas linear` using PLINK format.

```bash
torchgwas prep \
  --genotype /path/to/study.bed \
  --genotype-format plink \
  --phenotype-table /path/to/pheno.tsv \
  --covariates-table /path/to/covar.tsv \
  --output-dir prep_out
```

```bash
torchgwas linear \
  --genotype /path/to/study.bed \
  --genotype-format plink \
  --phenotype-table /path/to/pheno.tsv \
  --covariates-table /path/to/covar.tsv \
  --output-dir linear_out
```

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

### Editable Install TorchGWAS

Source: https://github.com/zhigroup/torchgwas/blob/main/docs/install.md

Install TorchGWAS in editable mode from the project's root directory. This is useful for development.

```bash
cd TorchGWAS
python -m pip install -e .
```

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

### Minimal Reproducible Example for Multivariate GWAS

Source: https://github.com/zhigroup/torchgwas/blob/main/docs/tutorial-multivariate.md

This command demonstrates the basic usage of the `torchgwas multi` command with toy data. Ensure all specified files and columns exist.

```bash
torchgwas multi \
  --genotype examples/toy/genotype.npy \
  --phenotype-table examples/toy/pheno.tsv \
  --covariates-table examples/toy/covar.tsv \
  --trait-columns trait_0,trait_1,trait_2 \
  --covariate-columns covar_0,covar_1,covar_2,covar_3 \
  --marker-ids examples/toy/markers.tsv \
  --output-dir multi_out
```

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

### TorchGWAS Linear Workflow for Large BGEN Files

Source: https://github.com/zhigroup/torchgwas/blob/main/README.md

Demonstrates running a linear GWAS with large BGEN files, including specifying a sample file, a persistent cache directory, and the compute data type. This setup is optimized for disk-backed genotype streaming.

```bash
torchgwas linear \
  --genotype /path/to/study.bgen \
  --genotype-format bgen \
  --sample-file /path/to/study.sample \
  --genotype-cache-dir /path/to/torchgwas_cache \
  --compute-dtype float32 \
  --phenotype-table /path/to/pheno.tsv \
  --covariates-table /path/to/covar.tsv \
  --output-dir linear_out
```

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

### Run Toy Multivariate Case Benchmark

Source: https://github.com/zhigroup/torchgwas/blob/main/docs/reproduce-benchmarks.md

Executes a benchmark for a toy multivariate case, intended for exploratory analysis. The output is saved to a specified TSV file.

```bash
python benchmarks/run_multivariate_case.py \
  --output results/benchmarks/multivariate_case.tsv
```

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

### Write Real Case Commands

Source: https://github.com/zhigroup/torchgwas/blob/main/docs/application-note-assets.md

Generates the command files for executing the T1 real-case scenario. The output directory should be specified.

```bash
python scripts/write_real_case_commands.py --output-dir real_case/t1_128
```

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

### TorchGWAS Demo Run

Source: https://github.com/zhigroup/torchgwas/blob/main/docs/tutorial-linear.md

Execute a quick repository-level smoke test using the tracked toy dataset. This command is useful for validating the basic functionality of TorchGWAS.

```bash
torchgwas demo --output-dir demo_run
```

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

### Prepare Real Case Data

Source: https://github.com/zhigroup/torchgwas/blob/main/docs/application-note-assets.md

Prepares the necessary data for the T1 real-case execution. Specify the output directory for the prepared data.

```bash
python scripts/prepare_t1_real_case.py --output-dir real_case/t1_128
```

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

### Illustrative Large-Scale Linear GWAS Command

Source: https://github.com/zhigroup/torchgwas/blob/main/README.md

This command pattern demonstrates how to run a large-scale linear GWAS using TorchGWAS, emphasizing options for memory efficiency and result filtering.

```bash
torchgwas linear \
  --genotype /path/to/study.bgen \
  --genotype-format bgen \
  --sample-file /path/to/study.sample \
  --genotype-cache-dir /path/to/torchgwas_cache \
  --phenotype-table /path/to/pheno.tsv \
  --covariates-table /path/to/covar.tsv \
  --compute-dtype float32 \
  --topk-per-trait 100 \
  --output-dir linear_out
```

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

### Run Linear Workflow with BGEN Input and Cache

Source: https://github.com/zhigroup/torchgwas/blob/main/docs/tutorial-linear.md

Perform linear association tests with BGEN format genotypes, utilizing a genotype cache directory for efficiency. Specify `--sample-file` and `--genotype-cache-dir` for large cohorts.

```bash
torchgwas linear \
  --genotype /path/to/study.bgen \
  --genotype-format bgen \
  --sample-file /path/to/study.sample \
  --genotype-cache-dir /path/to/torchgwas_cache \
  --phenotype-table /path/to/pheno.tsv \
  --covariates-table /path/to/covar.tsv \
  --sample-id-column IID \
  --trait-columns trait1,trait2,trait3 \
  --covariate-columns SEX,AGE,PC1,PC2,PC3 \
  --compute-dtype float32 \
  --output-dir linear_out
```

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

### Prepare Data for Multivariate GWAS

Source: https://github.com/zhigroup/torchgwas/blob/main/docs/tutorial-multivariate.md

This command prepares genotype, phenotype, and covariate data for the multivariate analysis. It aligns samples by IID and specifies trait and covariate columns. Add `--sample-file` for BGEN input.

```bash
torchgwas prep \
  --genotype /path/to/study.bed \
  --genotype-format plink \
  --phenotype-table /path/to/pheno.tsv \
  --covariates-table /path/to/covar.tsv \
  --sample-id-column IID \
  --trait-columns QT0,QT1,QT2,QT3 \
  --covariate-columns SEX,AGE,PC1,PC2,PC3 \
  --output-dir prep_out
```

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

### Materialize Historical Runtime Table

Source: https://github.com/zhigroup/torchgwas/blob/main/docs/reproduce-benchmarks.md

Creates a table of historical runtime points from the original notebook. This script is used to generate runtime scaling benchmarks.

```bash
python benchmarks/materialize_runtime_table.py \
  --output results/benchmarks/runtime_scaling.tsv
```

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

### Run Multivariate GWAS with Prepared Data

Source: https://github.com/zhigroup/torchgwas/blob/main/docs/tutorial-multivariate.md

This command runs the multivariate GWAS analysis using prepared data. It requires specifying genotype, phenotype, covariate tables, sample ID column, and trait/covariate columns.

```bash
torchgwas multi \
  --genotype /path/to/study.bed \
  --genotype-format plink \
  --phenotype-table /path/to/pheno.tsv \
  --covariates-table /path/to/covar.tsv \
  --sample-id-column IID \
  --trait-columns QT0,QT1,QT2,QT3 \
  --covariate-columns SEX,AGE,PC1,PC2,PC3 \
  --output-dir multi_out
```

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

### Prepare Data for Linear Workflow

Source: https://github.com/zhigroup/torchgwas/blob/main/docs/tutorial-linear.md

Use `torchgwas prep` to verify sample alignment and preprocess data before running the linear association test. This is recommended for cohort-scale analyses.

```bash
torchgwas prep \
  --genotype /path/to/study.bed \
  --genotype-format plink \
  --phenotype-table /path/to/pheno.tsv \
  --covariates-table /path/to/covar.tsv \
  --sample-id-column IID \
  --trait-columns trait1,trait2,trait3 \
  --covariate-columns SEX,AGE,PC1,PC2,PC3 \
  --output-dir prep_out
```

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

### Run Linear Workflow with PLINK BED Input

Source: https://github.com/zhigroup/torchgwas/blob/main/docs/tutorial-linear.md

Execute the linear association test using PLINK BED format for genotypes. Specify input tables, sample ID column, trait columns, and covariate columns.

```bash
torchgwas linear \
  --genotype /path/to/study.bed \
  --genotype-format plink \
  --phenotype-table /path/to/pheno.tsv \
  --covariates-table /path/to/covar.tsv \
  --sample-id-column IID \
  --trait-columns trait1,trait2,trait3 \
  --covariate-columns SEX,AGE,PC1,PC2,PC3 \
  --output-dir linear_out
```

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

### Profile Large-Scale Linear Streaming Memory

Source: https://github.com/zhigroup/torchgwas/blob/main/docs/reproduce-benchmarks.md

Benchmarks large-scale linear TorchGWAS memory usage in streaming mode with simulated large datasets. Measures peak steady-state memory and extrapolates runtime without materializing the full result table.

```bash
python benchmarks/profile_linear_streaming_large.py \
  --n-samples 20000 \
  --n-markers-total 1000000 \
  --n-traits 2000 \
  --chunk-size 4096 \
  --devices cpu cuda \
  --output results/benchmarks/linear_streaming_profile_large.tsv
```

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

### Run Linear GWAS with Tracked Inputs

Source: https://github.com/zhigroup/torchgwas/blob/main/README.md

Invoke the linear GWAS workflow directly using specified input files. Ensure all input paths are correct.

```bash
torchgwas linear \
  --genotype examples/toy/genotype.npy \
  --phenotype-table examples/toy/pheno.tsv \
  --covariates-table examples/toy/covar.tsv \
  --marker-ids examples/toy/markers.tsv \
  --sample-ids examples/toy/samples.tsv \
  --output-dir linear_out
```

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

### Reproduce Small-to-Medium Linear GWAS Profile

Source: https://github.com/zhigroup/torchgwas/blob/main/results/benchmarks/BENCHMARK_REPORT.md

Command to run the profiling script for small-to-medium sized linear GWAS workloads. It specifies the shapes of the data, devices to use (CPU and CUDA), chunk size, and output file.

```bash
CUDA_VISIBLE_DEVICES=5 PYTHONPATH=src python benchmarks/profile_linear_memory.py \
  --shapes 1024x4096x8 2048x8192x8 4096x16384x16 \
  --devices cpu cuda \
  --chunk-size 1024 \
  --output results/benchmarks/linear_memory_profile.tsv
```

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

### Reproduce Large-Scale Streaming GWAS Profile

Source: https://github.com/zhigroup/torchgwas/blob/main/results/benchmarks/BENCHMARK_REPORT.md

Command to run the profiling script for large-scale streaming linear GWAS workloads. It defines the number of samples, total markers, traits, chunk size, data type, devices, and output file.

```bash
CUDA_VISIBLE_DEVICES=5 PYTHONPATH=src python benchmarks/profile_linear_streaming_large.py \
  --n-samples 20000 \
  --n-markers-total 1000000 \
  --n-traits 2000 \
  --chunk-size 4096 \
  --dtype float32 \
  --devices cpu cuda \
  --output results/benchmarks/linear_streaming_profile_large.tsv
```

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

### Summarize PLINK Concordance

Source: https://github.com/zhigroup/torchgwas/blob/main/docs/reproduce-benchmarks.md

Generates a PLINK concordance accuracy table by comparing TorchGWAS results against an external baseline. Requires specifying the root path to TorchGWAS and trait indices.

```bash
python benchmarks/summarize_plink_accuracy.py \
  --fast-gwas-root /path/to/fast_GWAS \
  --trait-indices 0,17,63,127 \
  --output results/benchmarks/accuracy_plink.tsv
```

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

### Profile Linear GWAS Memory Usage

Source: https://github.com/zhigroup/torchgwas/blob/main/docs/reproduce-benchmarks.md

Simulates and profiles memory usage for linear TorchGWAS on CPU and GPU. Records peak CPU resident set size, peak GPU memory, and runtime for various matrix shapes and chunk sizes.

```bash
python benchmarks/profile_linear_memory.py \
  --shapes 1024x4096x8 2048x8192x8 \
  --devices cpu cuda \
  --chunk-size 1024 \
  --output results/benchmarks/linear_memory_profile.tsv
```

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

### TorchGWAS Linear: Top K Associations per Trait

Source: https://github.com/zhigroup/torchgwas/blob/main/docs/tutorial-linear.md

Use this command to retain only the strongest K associations for each phenotype in large GWAS runs. Ensure all required input files and columns are specified.

```bash
torchgwas linear \
  --genotype /path/to/study.bgen \
  --genotype-format bgen \
  --sample-file /path/to/study.sample \
  --genotype-cache-dir /path/to/torchgwas_cache \
  --phenotype-table /path/to/pheno.tsv \
  --covariates-table /path/to/covar.tsv \
  --sample-id-column IID \
  --trait-columns trait1,trait2,trait3 \
  --covariate-columns SEX,AGE,PC1,PC2,PC3 \
  --compute-dtype float32 \
  --topk-per-trait 100 \
  --output-dir linear_out
```

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

### Run Linear GWAS Excluding Related Individuals

Source: https://github.com/zhigroup/torchgwas/blob/main/docs/tutorial-linear.md

Execute the script to perform a linear GWAS, filtering for unrelated individuals using a specified kinship cutoff. Ensure the PYTHONPATH is set correctly and provide paths to genotype, sample, phenotype, and covariate files.

```bash
PYTHONPATH=src python scripts/run_linear_unrelated.py \
  --genotype /path/to/study.bgen \
  --genotype-format bgen \
  --sample-file /path/to/study.sample \
  --phenotype-table /path/to/pheno.tsv \
  --covariates-table /path/to/covar.tsv \
  --sample-id-column IID \
  --trait-columns trait1,trait2,trait3 \
  --covariate-columns SEX,AGE,PC1,PC2,PC3 \
  --output-dir unrelated_linear_run
```
Tokens:
Raw