========================================================================
       Process 8: GWAS & eQTL Colocalization Pipeline User Guide
========================================================================

1. Module Overview

This module integrates GCTA-COJO conditional analysis with the COLOC Bayesian statistical framework to perform colocalization analysis between core GWAS signals for complex traits and conventional bulk eQTL signals.

The complete workflow uses the project root directory (PROJECT_DIR) parameter to fully decouple all file paths from hard-coded locations.


2. Directory and File Structure

8.GWAS and eQTL/
├── 1.Prepare_eQTL.R              # Extract eQTL BED files for colocalization analysis
├── 2.Prepare_GWAS.R              # Extract GWAS candidate windows within ±1 Mb
├── 3.run_coloc.R                 # Core Bayesian colocalization analysis
├── GCTA-COJO.R                   # R script for converting MLMA results to COJO format
├── run_gwas_coloc_pipeline.sh    # Master Bash script for unified pipeline execution
└── README.txt                    # Pipeline documentation


3. Command-Line Usage Guide

[Step 1] Grant execution permission to the master script

Run the following command in the current directory:

chmod +x run_gwas_coloc_pipeline.sh


[Step 2] Run the complete pipeline

Launch the master Bash script and specify the global project root directory using the `--project_dir` long option:

bash run_gwas_coloc_pipeline.sh --project_dir "/faststorage/project/cattle_gtexs"


[Step 3] Monitor runtime logs and quality-control output

Once the pipeline starts, the `./gwas_coloc_logs/` directory will be automatically created in the current working directory.

Runtime information from the GCTA conditional signal scan and chromosome 1–29 QTL merging process will be displayed in real time in the terminal and simultaneously written to the following log files:

- COJO format conversion log:
  ./gwas_coloc_logs/8.1.GCTA_Cojo_Format.log

- eQTL preparation log:
  ./gwas_coloc_logs/8.2.Prepare_eQTL.log

- GWAS preparation log:
  ./gwas_coloc_logs/8.3.Prepare_GWAS.log

- Bayesian colocalization log:
  ./gwas_coloc_logs/8.4.Run_Coloc.log


4. Manual Execution of Individual Components

For step-by-step debugging of a specific trait, population, or problematic data block, each component can be executed independently.

1. Prepare eQTL input blocks for colocalization analysis:

Rscript 1.Prepare_eQTL.R \
  --input_dir "/faststorage/project/cattle_gtexs/CattleGTEx/OmiGA/eQTL" \
  --output_dir "./output_eQTL"

2. Prepare GWAS candidate windows:

Rscript 2.Prepare_GWAS.R \
  --gwas_dir "/faststorage/project/cattle_gtexs/Downstream_analysis/complextraits/GWAS" \
  --cojo_dir "/faststorage/project/cattle_gtexs/Downstream_analysis/complextraits/GWAS" \
  --output_dir "./output_GWAS"


5. Pipeline Data Flow and Integration Points

The master script uses standardized inputs and outputs to ensure seamless data transfer between modules. The key integration points are summarized below:

1. [Integration of format conversion and conditional signal detection]

   After `GCTA-COJO.R` is completed, the `*_cojo.txt` files generated in each trait directory are directly used as inputs for the `gcta64 --cojo-file` conditional analysis performed by the Bash loop. This step identifies independent significant association signals.

2. [Integration of eQTL signals and GWAS candidate windows]

   The tissue-specific `*_coloc.bed` files generated by `1.Prepare_eQTL.R` and the GWAS candidate regions extracted by `2.Prepare_GWAS.R` are used as parallel inputs for `3.run_coloc.R` through the `--bulk_dir` and `--gwas_dir` options, respectively. The two datasets are precisely aligned by genomic variants using `merge(..., by = "variant_id")`.

3. [Foundation for downstream Process 10]

   The trait-specific colocalization results generated by this module are directly used as core inputs for the downstream GWAS enrichment analysis in Process 10.


6. Runtime Safety and Fail-Fast Termination

The master pipeline script uses PIPESTATUS[0] to capture the actual exit code of each step. If any R script encounters an unrecoverable error during format conversion, chromosome-wise eQTL merging, or GWAS candidate-window extraction, the master script immediately terminates the workflow.

This fail-fast mechanism prevents incomplete, empty, or invalid intermediate data from propagating into downstream Bayesian colocalization analyses.

========================================================================
