Merge pull request #97 from learningMalanya/dev

Updated NEWS.md for version 1.2.0

NEWS.md

@@ -1,3 +1,13 @@
+## Version 1.2.0 (Aug 17, 2023)
+- Help documentation added: to view the help documentation for functions `scan()`, and `bulkscan()`, type `?` in front of the functions.
+- New features:
+    - Added the wrapper function `bulkscan()` for the three algorithms of multiple-trait scans previously named as `bulkscan_null()`, `bulkscan_null_grid()`, `bulkscan_alt_grid()`. Now, the user can simply call the common interface `bulkscan(...; method = )` by supplying with the method by the user's specific favor of computational speed or precision. Allowable inputs are string types, named as "null-exact", "null-grid", "alt-grid". The default option is "null-grid" with a loose grid of h2-step of size 0.1 (a grid of 10 values from 0.0, 0.10, ..., 0.90).
+    - Added the option for SVD decomposition of the kinship matrix. To use this feature, supply the option `decomp_scheme = svd`.
+    - Added the option in both `scan()` and `bulkscan()` functions for returning the $-log_{10}(p)$ result, where $p$ is the likelihood ratio test p-value: To use this feature, supply the option `output_pvals = true`. For more details, check the help instruction by `?scan()`, `?bulkscan()`.
+- Fixed bugs: 
+    - Fixed a bug causing compilation error in `bulkscan()` "null-grid" algorithm with REML due to a typo.
+    - Fixed a bug causing output dimension mismatch when using the function `scan()` for permutation testing with adjusted covariates.
+
 ## Version 1.1.1 (July 11, 2023)
 - Fixed bugs:  
     - REML option in multiple trait scan functions ("bulkscan"'s) used to lead to compilation errors.

README.md

@@ -316,7 +316,7 @@ detailed description of the function.
 Here, we started a 16-threaded *julia* session in julia version 1.9.2. Specific session info 
 is as follows:
 ```julia
-	versioninfo()
+versioninfo()
 ```
 
 	Julia Version 1.9.2

src/BulkLMM.jl

@@ -6,7 +6,7 @@ module BulkLMM
     using Random, Distributions
 
     include("./util.jl");
-    export p2lod, lod2p
+    export p2lod, lod2p, lod2log10p
 
     include("./kinship.jl");
     export calcKinship

src/analysis_helpers/single_trait_analysis.jl

@@ -28,7 +28,9 @@ end
 ## Outputs: the logliks (null, alt mean model) under the given h2
 function getLL(y0::Array{Float64, 2}, X0::Array{Float64, 2}, lambda0::Array{Float64, 1},
                num_of_covar::Int64, 
-               markerID::Int64, h2::Float64; prior::Array{Float64, 1} = [0.0, 0.0])
+               markerID::Int64, h2::Float64; 
+               prior::Array{Float64, 1} = [0.0, 0.0],
+               reml::Bool = false)
 
     n = size(y0, 1);
     w = makeweights(h2, lambda0);
@@ -43,13 +45,14 @@ function getLL(y0::Array{Float64, 2}, X0::Array{Float64, 2}, lambda0::Array{Floa
     X_design[:, 1:num_of_covar] = X0_covar;
     X_design[:, num_of_covar+1] = X0[:, markerID+num_of_covar];
 
-    return (ll_null = wls(y0, X0_covar, w, prior).ell, ll_markerID = wls(y0, X_design, w, prior).ell)
+    return (ll_null = wls(y0, X0_covar, w, prior; reml = reml).ell, 
+            ll_markerID = wls(y0, X_design, w, prior; reml = reml).ell)
 end
 
-function profileLL(y::Array{Float64, 2}, G::Array{Float64, 2}, covar::Array{Float64, 2}, 
+function profile_LL(y::Array{Float64, 2}, G::Array{Float64, 2}, covar::Array{Float64, 2}, 
                    K::Array{Float64, 2}, 
                    h2_grid::Array{Float64, 1}, markerID::Int64;
-                   prior::Array{Float64, 1} = [0.0, 0.0])
+                   prior::Array{Float64, 1} = [0.0, 0.0], reml::Bool = false)
 
     ## Initiate the vector to store the profile likelihood values evaluated under each given parameter value
     ell_null = zeros(length(h2_grid)); # loglikelihood under null
@@ -62,7 +65,7 @@ function profileLL(y::Array{Float64, 2}, G::Array{Float64, 2}, covar::Array{Floa
     ## Loop through the supplied h2 values, evaluate the profile loglik under each h2
     for k in 1:length(h2_grid)
         curr_h2 = h2_grid[k];
-        output = getLL(y0, X0, lambda0, num_of_covar, markerID, curr_h2; prior = prior);
+        output = getLL(y0, X0, lambda0, num_of_covar, markerID, curr_h2; prior = prior, reml = reml);
         ell_null[k] = output.ll_null;
         ell_alt[k] = output.ll_markerID;
     end

src/bulkscan.jl

@@ -74,8 +74,8 @@ The output of the single-trait scan function is an object. Depending on the user
     contains the LOD scores for one trait
 
 ## If the option for reporting p-values is on, the p-values results will be returned as:
-- `MT_out.Pvals_mat::Array{Float64, 2}`: 2-dimensional array (dimension: p*m) consisting of the p-values corresponding
-    to the LOD scores in MT_out.L
+- `MT_out.log10Pvals_mat::Array{Float64, 2}`: 2-dimensional array (dimension: p*m) consisting of the -log10(p-values)
+for each test (of association between each trait and each marker).
 
 """
 function bulkscan(Y::Array{Float64, 2}, G::Array{Float64, 2}, K::Array{Float64, 2};
@@ -152,8 +152,8 @@ function bulkscan(Y::Array{Float64, 2}, G::Array{Float64, 2}, Covar::Array{Float
     end
 
     if output_pvals
-        Pvals_mat = lod2p.(bulkscan_results.L, chisq_df);
-        temp_tuple = (Pvals_mat = Pvals_mat, Chisq_df = chisq_df);
+        log10Pvals_mat = lod2log10p.(bulkscan_results.L, chisq_df);
+        temp_tuple = (log10Pvals_mat = log10Pvals_mat, Chisq_df = chisq_df);
         return merge(bulkscan_results, temp_tuple)
     else
         return bulkscan_results

src/scan.jl

@@ -82,9 +82,9 @@ The output of the single-trait scan function is an object. Depending on the user
     is a vector of length p of p LOD scores for each permuted copy.
 
 ## If the option for reporting p-values is on, the p-values results will be returned as:
-- `out.pvals::Array{Float64, 1}`: 1-dimensional array consisting of the p-values
-- `out.Pvals_mat_perms::Array{Float64, 2}`: 2-dimensional array consisting of the p-values testing all 
-    permuted copies of the original trait
+- `out.log10pvals::Array{Float64, 1}`: 1-dimensional array consisting of the -log10(p-values)
+- `out.log10Pvals_perms::Array{Float64, 2}`: 2-dimensional array consisting of the -log10(p-values) for each test
+(for testing the association between each marker and each permuted trait).
 
 ## Additionally, if the user wants to examine the profile likelihood values under a given set of h2-values:
 - `out.ll_list_null::Array{Float64, 1}`: gives the values under the null model under each h2-value
@@ -260,8 +260,8 @@ function scan(y::Array{Float64,2}, g::Array{Float64,2}, covar::Array{Float64, 2}
         display(p)
         =# 
 
-        results_profileLL = profileLL(y_st, g_st, covar_st, K_st, h2_grid, markerID; 
-                                      prior = [prior_variance, prior_sample_size]);
+        results_profileLL = profile_LL(y_st, g_st, covar_st, K_st, h2_grid, markerID; 
+                                      prior = [prior_variance, prior_sample_size], reml = reml);
 
         return (results, results_profileLL);
     else
@@ -351,8 +351,8 @@ function scan_null(y::Array{Float64, 2}, g::Array{Float64, 2}, covar::Array{Floa
     end
 
     if output_pvals
-        pvals = lod2p.(lod, chisq_df);
-        return (sigma2_e = out00.sigma2, h2_null = out00.h2, lod = lod, pvals = pvals)
+        log10pvals = lod2log10p.(lod, chisq_df);
+        return (sigma2_e = out00.sigma2, h2_null = out00.h2, lod = lod, log10pvals = log10pvals)
     else
         return (sigma2_e = out00.sigma2, h2_null = out00.h2, lod = lod)
     end
@@ -443,8 +443,8 @@ function scan_alt(y::Array{Float64, 2}, g::Array{Float64, 2}, covar::Array{Float
     end
 
     if output_pvals
-        pvals = lod2p.(lod, chisq_df);
-        return (sigma2_e = out00.sigma2, h2_null = out00.h2, h2_each_marker = pve_list, lod = lod, pvals = pvals);
+        log10pvals = lod2log10p.(lod, chisq_df);
+        return (sigma2_e = out00.sigma2, h2_null = out00.h2, h2_each_marker = pve_list, lod = lod, log10pvals = log10pvals);
     else
         return (sigma2_e = out00.sigma2, h2_null = out00.h2, h2_each_marker = pve_list, lod = lod);
     end
@@ -546,10 +546,10 @@ function scan_perms_lite(y::Array{Float64,2}, g::Array{Float64,2}, covar::Array{
     L_perms = L[:, 2:end]; # lod scores for the permuted copies of the original, excluding the lod scores for the original trait
 
     if output_pvals
-        pvals = lod2p.(lod, chisq_df);
-        Pvals_perms = lod2p.(L_perms, chisq_df);
-        return (sigma2_e = sigma2_e, h2_null = h2_null, lod = lod, pvals = pvals,
-                                                        L_perms = L_perms, Pvals_perms = Pvals_perms)
+        log10pvals = lod2log10p.(lod, chisq_df);
+        log10Pvals_perms = lod2log10p.(L_perms, chisq_df);
+        return (sigma2_e = sigma2_e, h2_null = h2_null, lod = lod, log10pvals = pvals,
+                           L_perms = L_perms, log10Pvals_perms = log10Pvals_perms)
     else
         return (sigma2_e = sigma2_e, h2_null = h2_null, lod = lod, L_perms = L_perms)
     end

src/util.jl

@@ -195,3 +195,12 @@ function lod2p(lod::Float64, df::Int64)
     return pval
 
 end
+
+function lod2log10p(lod::Float64, df::Int64)
+
+    lrs = lod*2*log(10);
+    logpval = logccdf(Chisq(df), lrs)
+
+    return -logpval/log(10);
+
+end

test/bulkscan_test.jl

@@ -175,14 +175,6 @@ test_bulkscan_general = quote
 
     @test sum((test_bulkscan.L .- test_bulkscan_alt_grid.L).^2) <= 1e-7;
 
-    # test P-vals output:
-    test_Pvals = BulkLMM.bulkscan(stand_pheno, stand_geno, kinship;
-                                  method = "alt-grid", 
-                                  h2_grid = grid_list, 
-                                  prior_variance = 1.0, prior_sample_size = 0.1,
-                                  output_pvals = true);
-    @test sum((lod2p.(test_bulkscan.L, 1) .- test_Pvals.Pvals_mat).^2) <= 1e-7;
-
 end;
 
 

test/scan_covar_test.jl

@@ -38,11 +38,18 @@ println("Scan with covariates functions test (SVD2): ",
 
 test_scan_covar_pvals = scan(pheno_y, geno, pseudo_covars, kinship; output_pvals = true);
 println("Scan with covariates functions test (p-vals output): ", 
-@test mean(abs.(lod2p.(test_scan_covar.lod, 1) .- test_scan_covar_pvals.pvals)) <= tol
+@test mean(abs.(lod2log10p.(test_scan_covar.lod, 1) .- test_scan_covar_pvals.log10pvals)) <= tol
+)
+
+test_bulkscan_covar_Pvals = bulkscan(hcat(pheno[:, 2000], pheno_y), geno, pseudo_covars, kinship; 
+                                    h2_grid = vcat(collect(0.0:0.05:0.95), 
+                                                   test_scan_covar.h2_null),
+                                    output_pvals = true).log10Pvals_mat;
+println("Bulkscan with covariates functions test (p-vals output): ", 
+@test mean(abs.(test_bulkscan_covar_Pvals[:, 2] .- test_scan_covar_pvals.log10pvals)) <= tol
 )
 
 test_scan_covar_vec = scan(pheno[:, pheno_id], geno, pseudo_covars, kinship);
 println("Scan with covariates functions test (vector trait input): ", 
-@test mean(abs.(test_scan_covar.lod .- test_scan_covar_vec.lod)) <= tol
-)
+@test mean(abs.(test_scan_covar.lod .- test_scan_covar_vec.lod)) <= tol)