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:
- 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”)