cellink.tl.external.run_saigeqtl

cellink.tl.external.run_saigeqtl(dd, gene_col, prefix='saigeqtl_temp', steps=[1, 2], mode='cis', analysis_type='single_variant', n_pcs=50, use_sparse_grm_to_fit_null=False, use_grm_to_fit_null=True, skip_variance_ratio=False, overwrite_variance_ratio_file=False, tol=0.02, maxiter=20, tol_pcg=1e-05, maxiter_pcg=500, n_threads=1, spa_cutoff=2, num_random_marker_variance_ratio=30, skip_model_fitting=False, memory_chunk=2, tau_init='0,0', loco_step1=True, is_low_mem_loco=False, trace_cv_cutoff=0.0025, nrun=30, ratio_cv_cutoff=0.001, output_prefix_var_ratio='', sparse_grm_file='', sparse_grm_sample_id_file='', is_cate_variance_ratio=False, relatedness_cutoff=0, cate_var_ratio_min_mac_vec_exclude='10,20.5', cate_var_ratio_max_mac_vec_include='20.5', is_covariate_transform=True, is_diag_of_kin_set_as_one=False, use_sparse_grm_for_var_ratio=False, min_maf_for_grm=0.01, max_missing_rate_for_grm=0.15, min_covariate_count=-1, include_nonauto_markers_for_var_ratio=False, female_only=False, male_only=False, sex_col='', female_code='1', male_code='0', is_covariate_offset=True, sample_id_include_file='', allele_order='alt-first', ids_to_include_file='', ranges_to_include_file='', window=500000, chrom=None, is_imputed_data=False, min_maf=0, min_mac=20, min_info=0, max_missing=0.15, impute_method='best_guess', loco_step2=False, gmmat_model_file='', variance_ratio_file='', saige_output_file='', markers_per_chunk=10000, is_output_more_details=False, is_overwrite_output=True, group_file=None, max_maf_in_group_test='0.0001,0.001,0.01', min_maf_in_group_test_exclude=None, max_mac_in_group_test='0', min_mac_in_group_test_exclude=None, annotation_in_group_test='lof,missense;lof,missense;lof;synonymous', mac_cutoff_to_collapse_ultra_rare=10, min_group_mac_in_burden_test=5, weights_beta='1;25', r_corr=0, markers_per_chunk_in_group_test=100, groups_per_chunk=100, condition='', weights_for_condition=None, dosage_zerod_cutoff=0.2, dosage_zerod_mac_cutoff=10, is_single_in_group_test=False, is_skato=False, is_equal_weight_in_group_test=False, is_output_marker_list_in_group_test=False, is_firth_beta=False, p_cutoff_for_firth=0.01, is_fast_test=False, is_noadj_cov=True, is_sparse_grm=False, pval_cutoff_for_fast_test=0.05, max_mac_for_er=4, is_emp_spa=False, weight_file='', gene_name='', sample_covariates=None, cell_covariates=None, encode_sex=True, encode_age=True, dtype='float32', run=True, read_results=True, save_cmd_file=None, plink_export_kwargs=None, remove_intermediate_files=True, runner=None)

Run eQTL mapping using SAIGE-QTL with flexible step execution.

This function can run Step 1 (null model fitting), Step 2 (association testing), and/or Step 3 (gene-level p-values) independently or in combination.

Parameters:

• dd (DonorData) – DonorData object with genotype and expression data

• gene_col (str) – Gene/phenotype column name

• prefix (str, default="saigeqtl_temp") – Output file prefix

• steps (list[int], default=[1, 2]) – Which steps to run: [1], [2], [3], [1,2], [1,2,3], [2,3], etc.

• mode ({'cis', 'genome_wide'}, default='cis') – Analysis mode

• analysis_type ({'single_variant', 'set_based'}, default='single_variant') – Type of analysis in Step 2

• n_pcs (int, default=50) – Number of PCs to compute

• Fitting) (Step 1 Parameters (Null Model)

• ---------------------------------------

• use_sparse_grm_to_fit_null (bool, default=False) – Use sparse GRM for null model

• use_grm_to_fit_null (bool, default=True) – Use full GRM for null model

• skip_variance_ratio (bool, default=False) – Skip variance ratio estimation

• overwrite_variance_ratio_file (bool, default=False) – Overwrite existing variance ratio file

• tol (float, default=0.02) – Convergence tolerance

• maxiter (int, default=20) – Maximum iterations

• tol_pcg (float, default=1e-5) – PCG tolerance

• maxiter_pcg (int, default=500) – Maximum PCG iterations

• n_threads (int, default=1) – Number of threads

• spa_cutoff (float, default=2) – SPA cutoff in SD units

• num_random_marker_variance_ratio (int, default=30) – Number of random markers for variance ratio

• skip_model_fitting (bool, default=False) – Skip model fitting (requires existing .rda)

• memory_chunk (float, default=2) – Memory chunk size in Gb

• tau_init (str, default="0,0") – Initial tau values

• loco_step1 (bool, default=True) – Use LOCO in Step 1

• is_low_mem_loco (bool, default=False) – Low memory LOCO mode

• trace_cv_cutoff (float, default=0.0025) – Trace CV cutoff

• nrun (int, default=30) – Number of trace estimation runs

• ratio_cv_cutoff (float, default=0.001) – Ratio CV cutoff

• output_prefix_var_ratio (str, default="") – Variance ratio file prefix

• sparse_grm_file (str, default="") – Pre-calculated sparse GRM file

• sparse_grm_sample_id_file (str, default="") – Sample IDs for sparse GRM

• is_cate_variance_ratio (bool, default=False) – Estimate categorical variance ratios

• relatedness_cutoff (float, default=0) – Kinship threshold for sparse GRM

• cate_var_ratio_min_mac_vec_exclude (str, default="10,20.5") – Lower MAC bounds for categories

• cate_var_ratio_max_mac_vec_include (str, default="20.5") – Upper MAC bounds for categories

• is_covariate_transform (bool, default=True) – Apply QR transformation to covariates

• is_diag_of_kin_set_as_one (bool, default=False) – Set GRM diagonal to 1

• use_sparse_grm_for_var_ratio (bool, default=False) – Use sparse GRM for variance ratio

• min_maf_for_grm (float, default=0.01) – Minimum MAF for GRM markers

• max_missing_rate_for_grm (float, default=0.15) – Maximum missing rate for GRM markers

• min_covariate_count (int, default=-1) – Minimum count for binary covariates

• include_nonauto_markers_for_var_ratio (bool, default=False) – Include non-autosomal markers

• female_only (bool, default=False) – Run for females only

• male_only (bool, default=False) – Run for males only

• sex_col (str, default="") – Sex column name

• female_code (str, default="1") – Female code in sex column

• male_code (str, default="0") – Male code in sex column

• is_covariate_offset (bool, default=True) – Estimate fixed effect coefficients

• sample_id_include_file (str, default="") – File with sample IDs to include

• Testing) (Step 2 Parameters (Association)

• ---------------------------------------

• allele_order (str, default="alt-first") – Allele order for PLINK/BGEN

• ids_to_include_file (str, default="") – File with variant IDs to include

• ranges_to_include_file (str, default="") – File with genomic ranges

• window (int, default=500000) – Cis-window size in bp

• chrom (str, optional) – Chromosome

• is_imputed_data (bool, default=False) – Whether data is imputed

• min_maf (float, default=0) – Minimum MAF

• min_mac (float, default=20) – Minimum MAC

• min_info (float, default=0) – Minimum imputation INFO

• max_missing (float, default=0.15) – Maximum missing rate

• impute_method (str, default="best_guess") – Imputation method

• loco_step2 (bool, default=False) – Use LOCO in Step 2

• gmmat_model_file (str, default="") – Pre-computed model file

• variance_ratio_file (str, default="") – Pre-computed variance ratio file

• saige_output_file (str, default="") – Custom output file name

• markers_per_chunk (int, default=10000) – Markers per chunk

• is_output_more_details (bool, default=False) – Output additional details

• is_overwrite_output (bool, default=True) – Overwrite existing output

• Parameters (Execution)

• -------------------------

• group_file (str, optional) – Group file for set-based tests

• max_maf_in_group_test (str, default="0.0001,0.001,0.01") – Maximum MAF for masks

• min_maf_in_group_test_exclude (str, optional) – Minimum MAF to exclude

• max_mac_in_group_test (str, default="0") – Maximum MAC for masks

• min_mac_in_group_test_exclude (str, optional) – Minimum MAC to exclude

• annotation_in_group_test (str, default="lof,missense;lof,missense;lof;synonymous") – Annotation categories

• mac_cutoff_to_collapse_ultra_rare (int, default=10) – MAC cutoff for collapsing

• min_group_mac_in_burden_test (float, default=5) – Minimum MAC for burden test

• weights_beta (str, default="1;25") – Beta distribution parameters

• r_corr (float, default=0) – Correlation for SKAT-O (0=SKAT-O, 1=burden)

• markers_per_chunk_in_group_test (int, default=100) – Markers per chunk in group test

• groups_per_chunk (int, default=100) – Groups per chunk

• condition (str, default="") – Conditioning markers

• weights_for_condition (str, optional) – Weights for conditioning

• dosage_zerod_cutoff (float, default=0.2) – Dosage zeroing cutoff

• dosage_zerod_mac_cutoff (int, default=10) – MAC cutoff for dosage zeroing

• is_single_in_group_test (bool, default=False) – Output single-variant results

• is_skato (bool, default=False) – Perform SKAT-O test

• is_equal_weight_in_group_test (bool, default=False) – Use equal weights

• is_output_marker_list_in_group_test (bool, default=False) – Output marker lists

• is_firth_beta (bool, default=False) – Use Firth correction

• p_cutoff_for_firth (float, default=0.01) – P-value cutoff for Firth

• is_fast_test (bool, default=False) – Use fast test mode

• is_noadj_cov (bool, default=True) – Don’t adjust for covariates in genotypes

• is_sparse_grm (bool, default=False) – Use sparse GRM in Step 2

• pval_cutoff_for_fast_test (float, default=0.05) – P-value cutoff for fast test

• max_mac_for_er (int, default=4) – Maximum MAC for efficient resampling

• is_emp_spa (bool, default=False) – Use empirical SPA

• P-values) (Step 3 Parameters (Gene-Level)

• ---------------------------------------

• weight_file (str, default="") – File with variant weights for ACAT

• gene_name (str, default="") – Gene name for output

• Parameters

• -------------------

• sample_covariates (list[str], optional) – Individual-level covariates

• cell_covariates (list[str], optional) – Cell-level covariates

• encode_sex (bool, default=True) – Include sex covariate

• encode_age (bool, default=True) – Include age covariate

• dtype (str, default="float32") – Data type for covariates

• Parameters

• -------------------

• run (bool, default=True) – Execute commands

• read_results (bool, default=True) – Read and return results

• save_cmd_file (str, optional) – Save commands to file

• plink_export_kwargs (dict, optional) – Additional kwargs for to_plink

• remove_intermediate_files (bool, default=True) – Remove intermediate files

• runner (SAIGEQTLRunner, optional) – Runner instance

Return type:

DataFrame | dict | str

Returns:

pd.DataFrame, dict, or str Results or commands depending on execution mode

Examples

# Run only Step 1 >>> run_saigeqtl(dd, gene_col=”GENE1”, steps=[1], prefix=”step1_only”)

# Run Steps 1 and 2 >>> run_saigeqtl(dd, gene_col=”GENE1”, steps=[1, 2], prefix=”full_analysis”)

# Run only Step 3 (requires existing Step 2 results) >>> run_saigeqtl(dd, gene_col=”GENE1”, steps=[3], prefix=”existing_results”)

# Run all steps including gene-level p-values >>> run_saigeqtl(dd, gene_col=”GENE1”, steps=[1, 2, 3], prefix=”complete”)