Second round global PCA projection

MODULE STATUS

Developer: DEEP developer team

Scripts status: Run when requested by the DEEP coordinating team.

Prerequisites:

• post01b mode: Completed Module 01, with cleaned GRCh38 genotype files available.
• genetic_only mode: Prior pipeline completion is not required. Imputed genotype data in PLINK BED/BIM/FAM format, an imputation quality-score file, and a sample list are required. This mode prepares data specifically for global PCA projection and does not replace the standard pipeline QC.

Script: 01b_PCAplot.sh on the global_pca_v2 branch.

Data upload method: Upload to upload/global_pca on the Bristol SFTP server.

Issue report to: Haotian Tang haotian.tang@bristol.ac.uk and Prachand Issarapu prachand.issarapu@lshtm.ac.uk

Second-round global PCA projection

The first-round global PCA projections used a reference SNP set that was not fully represented in every cohort. Differences in SNP coverage could affect the projected PC scores.

For the second round, the DEEP coordinating team has rebuilt the reference PCA using SNPs shared across participating cohorts and the HGDP + 1000 Genomes reference. Each cohort projects its cleaned genotype data onto this updated reference.

The reference PCA excludes long-range LD regions and strand-ambiguous A/T and C/G SNPs, applies SNP call rate ≥ 0.99 and MAF ≥ 0.001, and performs LD pruning with an r² threshold of 0.1 within a 10 Mb window.

Before running

These instructions use the default post01b mode, which requires the cleaned GRCh38 genotype files produced by 01b-process_genetic_data.sh.

By default, these files are located at:

<home_directory>/processed_data/genetic_data/data.bed
<home_directory>/processed_data/genetic_data/data.bim
<home_directory>/processed_data/genetic_data/data.fam

Please ensure these files are still available.

Download the second-round PCA scripts

Clone the global_pca_v2 branch into a separate directory:

git clone -b global_pca_v2 https://github.com/MRCIEU/DEEP_mqtls DEEP_mqtls_globalpca
cd DEEP_mqtls_globalpca

Use the software environment configured for your DEEP pipeline analysis.

Prepare your configuration file

Copy the config used for your original QC analysis into the new directory. For example:

cp /path/to/your/original/config ./config_study_gpca

Replace config_study_gpca with your preferred filename.

In the copied config, update scripts_directory to the full path of the new checkout:

scripts_directory="/full/path/to/DEEP_mqtls_globalpca"

Keep home_directory pointing to your original analysis directory, so the script can find the cleaned genotype files from 01b.

Important

scripts_directory identifies the new code directory. home_directory identifies your existing analysis directory. You do not need to copy the genotype files into the new code directory.

The following settings may be added to the config. These are also the defaults when omitted:

pca_mode="post01b"
pca_share_level="individual"

Sharing options

Choose the sharing mode appropriate for your cohort:

Setting	Outputs prepared for submission
pca_share_level="individual"	Individual PC1–PC10 scores with sample IDs removed and rows shuffled, together with binned counts, summaries and plots.
pca_share_level="aggregate"	Binned counts, summaries and density plots, without an individual PC score file.

Both modes retain the PC scores with sample IDs locally.

For the binned outputs, counts of 1–4 are reported as <5. Density plot cells containing fewer than five samples are hidden.

Run the projection

From the DEEP_mqtls_globalpca directory, run:

./01b_PCAplot.sh -c ./config_study_gpca

The script will:

1. Read the cleaned GRCh38 genotypes from 01b.
2. Extract variants at the updated reference SNP positions.
3. Match alleles to the reference and recode genotype counts where allele order is reversed. This does not perform strand flipping.
4. Exclude allele mismatches and positions with multiple matching variants.
5. Project samples using Hail, with the reference allele frequencies and SNP loadings.
6. Report SNP coverage and genotype call rates.
7. Generate plots and check the output files.

The post01b mode does not repeat liftover or the full genetic QC workflow. The PCA axes are defined by the updated reference; PCA is not recalculated within your cohort.

Check the results

Results for submission are written to:

<home_directory>/results/01b_pca/

File	Contents
<study_name>_globalPCA_v2_scores.tsv.gz	PC1–PC10 without sample IDs, with rows shuffled. Generated only in individual sharing mode.
<study_name>_globalPCA_v2_bins.tsv	Sample counts in fixed reference bins.
<study_name>_globalPCA_v2_coverage.tsv	SNP matching, coverage and genotype call-rate statistics.
<study_name>_globalPCA_v2_summary.tsv	Sample size, run information, and PC means and standard deviations.
<study_name>_globalPCA_v2.png	Cohort projections plotted against the reference.
logs/	Run logs.

SNP coverage and genotype call rate

These describe different aspects of the data:

• SNP coverage: The proportion of reference SNPs matched and retained for projection.
• Genotype call rate: For each retained SNP, the proportion of cohort samples with a non-missing genotype. The report includes the mean, minimum, and number of SNPs with call rate below 95%.

The script stops if SNP coverage is below 95% and issues a warning if coverage is below 100%. Missing SNPs and missing genotype calls contribute zero after reference-based centring.

If coverage is below 95%, please contact the coordinating team before proceeding.

PCA plots

Please inspect:

<study_name>_globalPCA_v2.png

The figure compares your cohort with the reference using:

• PC1 versus PC2;
• PC1 versus PC3;
• PC2 versus PC4.

Individual sharing mode includes scatter and density plots. Aggregate sharing mode includes density plots only.

Please contact the coordinating team if you observe unexpected patterns or warnings.

Files retained locally

Scores containing FID, IID and PC1–PC20 are saved under:

<home_directory>/processed_data/genetic_data/global_pca_v2/

Important

Files containing sample IDs must remain local. Do not copy the scores with IDs, genotype files or projected_ids.txt into results/01b_pca.

Check and upload the encrypted results

To check that the script completed successfully and the expected outputs are present, run:

./check_upload.sh -c ./config_study_gpca 01b_pca check

After reviewing the plots and reports, encrypt and upload the results:

./check_upload.sh -c ./config_study_gpca 01b_pca upload

By default, this uses SFTP and is equivalent to:

./check_upload.sh -c ./config_study_gpca 01b_pca upload sftp

The results archive, separate PCA configuration archive, and checksum files are uploaded to:

upload/global_pca

Important

Second-round PCA results are submitted separately from the original QC stage 01 results. The standard 01 upload command only packages results/01 and does not upload results/01b_pca.

When prompted, enter the encryption password assigned during your DEEP pipeline registration.