update doc: clatify raw p-val; procedure to increase MC samples in gr…

…oup analysis; faq for increasing MC samples in group analysis

docs/faq.rst

@@ -66,6 +66,12 @@ scDRS detected few significant cells (FDR<0.2)?
 scDRS may be underpowered for certain GWAS/scRNA-seq data sets. In these cases, the ensuing scDRS group analyses may still have sufficient power, because scDRS group analyses aggregate results of individual cells and hence have higher power than the scDRS individual cell-level analyses. To assess if scDRS has sufficient power, we suggest performing the `scDRS group analyses <https://martinjzhang.github.io/scDRS/reference_cli.html#perform-downstream>`_ to assess significance at an aggregated level. In addition, it is helpful to visually inspect the scDRS normalized disease score on the UMAP plot. Localized enrichments of high scDRS disease scores on the UMAP usually indicate that scDRS have detected interesting biological signals.
 
 
+MC z-scores much more significant than MC p-values in group analysis due to the MC limit? 
+===========================================================================================
+
+Increasing :code:`--n-ctrl` in `compute-score` will produce more control scores, which will be later used in the group analysis to increase the number of MC samples for MC tests. Alternatively, you can compute a p-value from assoc_mcz when assoc_mcp is reasonably small. As mentioned in the Methods section: "We recommend using MC P values to determine statistical significance and using MC z-scores to further prioritize associations whose MC P values have reached the MC limit. "
+
+
 Use scDRS for other types of single-cell data?
 ====================================================
 

docs/file_format.rst

@@ -86,8 +86,8 @@ scDRS score file for a give trait. :code:`.tsv.gz` file.
 - First column: cell names, should be the same as :code:`adata.obs_names`.
 - raw_score: raw disease score.
 - norm_score: normalized disease score.
-- mc_pval: cell-level MC p-value.
-- pval: cell-level scDRS p-value.
+- mc_pval: cell-level MC p-value. Raw p-value without multiple testing adjustment.
+- pval: cell-level scDRS p-value. Raw p-value without multiple testing adjustment.
 - nlog10_pval: -log10(pval).
 - zscore: z-score converted from pval.
 
@@ -118,9 +118,9 @@ Results for scDRS group-level analysis for a give trait and a given cell-group a
 - First column: different cell groups in :code:`adata.obs[<annot>]`.
 - n_cell: number of cells from the cell group.
 - n_ctrl: number of control gene sets.
-- assoc_mcp: MC p-value for cell group-disease association.
+- assoc_mcp: MC p-value for cell group-disease association. Raw p-value without multiple testing adjustment.
 - assoc_mcz: MC z-score for cell group-disease association.
-- hetero_mcp:  MC p-value for within-cell group heterogeneity in association with disease.
+- hetero_mcp:  MC p-value for within-cell group heterogeneity in association with disease. Raw p-value without multiple testing adjustment.
 - hetero_mcz:  MC z-score for within-cell group heterogeneity in association with disease.
 
 .. csv-table:: Example <trait>.scdrs_group.<annot> file
@@ -138,7 +138,7 @@ Results for scDRS cell-level correlation analysis for a given trait. :code:`.tsv
 - <trait> : trait name consistent with :code:`<trait>.full_score.gz` file.
 - First column: all cell-level variables, specified by specified by :code:`corr_analysis` in CLI.
 - n_ctrl: number of control gene sets.
-- corr_mcp: MC p-value for cell-level variable association with disease.
+- corr_mcp: MC p-value for cell-level variable association with disease. Raw p-value without multiple testing adjustment.
 - corr_mcz: MC z-score for cell-level variable association with disease.
 
 .. csv-table:: Example <trait>.scdrs_cell_corr file

docs/reference_cli.rst

@@ -138,7 +138,7 @@ flag_return_ctrl_norm_score : bool, optional
 perform-downstream
 ~~~~~~~~~~~~~~~~~~
 
-Perform scDRS downstream analyses based on precomputed scDRS :code:`.full_score.gz` files.
+Perform scDRS downstream analyses based on precomputed scDRS :code:`.full_score.gz` files. The number of MC samples in MC tests depends on the number of control scores in the :code:`.full_score.gz` file; to increase this number, specify a larger :code:`--n_ctrl` when calling :code:`scdrs compute-score` in the previous step. 
 
 --group-analysis  For a given cell group-level annotation (e.g., tissue or cell type), assess cell 
     group-disease association (control-score-based MC tests using 5% quantile) and within-cell