biopipen 0.21.1__py3-none-any.whl → 0.22.0__py3-none-any.whl

biopipen/scripts/tcr/Immunarch-diversity.R

@@ -1,6 +1,11 @@
 # Diversity estimation
 # https://immunarch.com/articles/web_only/v6_diversity.html
 
+log_info("")
+log_info("#####################################")
+log_info("# Diversity estimation              #")
+log_info("#####################################")
+
 # Other variables are loaded in the parent template
 # immdata is already loaded, meta is mutated
 div_method = {{envs.divs.method | r}}
@@ -22,10 +27,9 @@ div_ymax = {{envs.divs.ymax | r}}
 div_dir = file.path(outdir, "diversity")
 dir.create(div_dir, showWarnings = FALSE)
 
-print("- Diversity estimation ...")
-
 # Fill up the cases
 update_case = function(case) {
+    log_info("Filling up cases ...")
     if (is.null(case$subset)) {
         case$subset = div_subset
     }
@@ -161,7 +165,7 @@ filter_div = function(div, samples) {
 #   case: the case with argument to be run
 #   ddir: the directory to save the results
 #   value_col: the column name of the value
-run_general = function(d, case, ddir, value_col = "Value") {
+run_general = function(casename, d, case, ddir, value_col = "Value") {
     args = case$args
     args$.data = d$data
     args$.method = case$method
@@ -278,6 +282,63 @@ run_general = function(d, case, ddir, value_col = "Value") {
     print(p)
     dev.off()
 
+    add_report(
+        list(
+            kind = "descr",
+            content = paste0(
+                "Diversity estimation using ",
+                "<code>",
+                case$method,
+                "</code>: ",
+                switch(case$method,
+                    chao1 = paste0(
+                        "a nonparameteric asymptotic estimator of species richness ",
+                        "(number of species in a population)."),
+                    hill = paste0(
+                        "Hill numbers are a mathematically unified family of ",
+                        "diversity indices (differing only by an exponent q)."),
+                    div = paste0(
+                        "true diversity, or the effective number of types, ",
+                        "refers to the number of equally abundant types needed for ",
+                        "the average proportional abundance of the types to equal that ",
+                        "observed in the dataset of interest where all types may ",
+                        "not be equally abundant."),
+                    gini.simp = paste0(
+                        "the Gini-Simpson index is the probability of interspecific ",
+                        "encounter, i.e., probability that two entities represent different types."),
+                    inv.simp = paste0(
+                        "Inverse Simpson index is the effective number of types ",
+                        "that is obtained when the weighted arithmetic mean is used ",
+                        "to quantify average proportional abundance of types in ",
+                        "the dataset of interest."),
+                    gini = paste0(
+                        "the Gini coefficient measures the inequality among ",
+                        "values of a frequency distribution (for example levels of income). ",
+                        "A Gini coefficient of zero expresses perfect equality, ",
+                        "where all values are the same (for example, where everyone has ",
+                        "the same income). A Gini coefficient of one (or 100 percents ) ",
+                        "expresses maximal inequality among values (for example where only ",
+                        "one person has all the income).")
+                )
+            )
+        ),
+        h1 = "Diversity Estimation",
+        h2 = casename
+    )
+    add_report(
+        list(
+            name = "Diversity Plot",
+            contents = list(list(kind = "image", src = file.path(ddir, "diversity.png")))
+        ),
+        list(
+            name = "Diversity Table",
+            contents = list(list(kind = "table", src = file.path(ddir, "diversity.txt")))
+        ),
+        h1 = "Diversity Estimation",
+        h2 = casename,
+        ui = "tabs"
+    )
+
     # Test
     if (!is.null(case$test) && case$test$method != "none") {
         # Use pairwise.t.test or pairwise.wilcox.test
@@ -340,6 +401,19 @@ run_general = function(d, case, ddir, value_col = "Value") {
             row.names = FALSE,
             col.names = TRUE
         )
+
+        add_report(
+            list(
+                name = paste0("Test (", case$test$method, ")"),
+                contents = list(list(
+                    kind = "table",
+                    src = file.path(ddir, paste0("diversity.test.", case$test$method, ".txt"))
+                ))
+            ),
+            h1 = "Diversity Estimation",
+            h2 = casename,
+            ui = "tabs"
+        )
     }
 }
 
@@ -421,7 +495,8 @@ run_raref_multi = function(d, case, ddir) {
     widths = list()
     plots = list()
     for (sepvar in sepvars) {
-        print(paste0("  ", case$separate_by, ": ", sepvar))
+        # print(paste0("  ", case$separate_by, ": ", sepvar))
+        log_info("  {case$separate_by}: {sepvar}")
         q = list(include(sepvar))
         names(q) = case$separate_by
         single_run = run_raref_single(
@@ -466,19 +541,24 @@ run_raref_multi = function(d, case, ddir) {
     } else {
         height = case$devpars$height
     }
-    png(file.path(ddir, paste0("raref-", case$separate_by, ".png")), width = width, height = height, res = res)
+    png(
+        file.path(ddir, paste0("raref-", slugify(case$separate_by), ".png")),
+        width = width,
+        height = height,
+        res = res
+    )
     print(p)
     dev.off()
 }
 
 # Run the diversity estimation for one case
 run_div_case = function(casename) {
-    print(paste0("  Case: ", casename))
+    log_info("Processing case: {casename} ...")
     case = div_cases[[casename]]
     if (case$method == "raref") {
-        ddir = file.path(outdir, "rarefraction", casename)
+        ddir = file.path(outdir, "rarefraction", slugify(casename, tolower = FALSE))
     } else {
-        ddir = file.path(div_dir, casename)
+        ddir = file.path(div_dir, slugify(casename, tolower = FALSE))
     }
     dir.create(ddir, recursive = TRUE, showWarnings = FALSE)
 
@@ -490,26 +570,56 @@ run_div_case = function(casename) {
     }
 
     # Run repDiversity
-    if (case$method == "chao1") {
-        run_general(d, case, ddir, "Estimator")
-    } else if (case$method == "hill") {
-        run_general(d, case, ddir)
-    } else if (case$method == "div") {
-        run_general(d, case, ddir)
-    } else if (case$method == "gini.simp") {
-        run_general(d, case, ddir)
-    } else if (case$method == "inv.simp") {
-        run_general(d, case, ddir)
-    } else if (case$method == "gini") {
-        run_general(d, case, ddir, "V1")
-    } else if (case$method == "raref") {
+    if (case$method == "raref") {
+        add_report(
+            list(
+                kind = "descr",
+                content = paste0(
+                    "Rarefaction is a technique to assess species richness from the ",
+                    "results of sampling through extrapolation. "
+                )
+            ),
+            h1 = "Rarefraction",
+            h2 = casename
+        )
+
         if (!is.null(case$separate_by)) {
             run_raref_multi(d, case, ddir)
+            add_report(
+                list(
+                    kind = "image",
+                    src = file.path(ddir, paste0("raref-", slugify(case$separate_by), ".png"))
+                ),
+                h1 = "Rarefraction",
+                h2 = casename
+            )
         } else {
             run_raref_single(d, case, ddir)
+            add_report(
+                list(
+                    kind = "image",
+                    src = file.path(ddir, "raref.png")
+                ),
+                h1 = "Rarefraction",
+                h2 = casename
+            )
         }
     } else {
-        stop(paste0("Unknown diversity method: ", case$method))
+        if (case$method == "chao1") {
+            run_general(casename, d, case, ddir, "Estimator")
+        } else if (case$method == "hill") {
+            run_general(casename, d, case, ddir)
+        } else if (case$method == "div") {
+            run_general(casename, d, case, ddir)
+        } else if (case$method == "gini.simp") {
+            run_general(casename, d, case, ddir)
+        } else if (case$method == "inv.simp") {
+            run_general(casename, d, case, ddir)
+        } else if (case$method == "gini") {
+            run_general(casename, d, case, ddir, "V1")
+        } else {
+            stop(paste0("Unknown diversity method: ", case$method))
+        }
     }
 }
 

biopipen/scripts/tcr/Immunarch-geneusage.R

@@ -1,9 +1,15 @@
 # loaded variables
 # immfile, outdir, mutaters, immdata, n_samples
 
+log_info("")
+log_info("#####################################")
+log_info("# Gene usage analysis               #")
+log_info("#####################################")
+
 gene_usages = {{ envs.gene_usages | r: todot="-" }}
 
 # Fill up cases
+log_info("Filling up cases ...")
 cases = gene_usages$cases
 if (is.null(cases) || length(cases) == 0) {
     cases$DEFAULT = list(
@@ -92,7 +98,8 @@ for (name in names(cases)) {
 }
 
 do_one_case_geneusage = function(name, case, gu_dir) {
-    print(paste0("  Case: ", name))
+    # print(paste0("  Case: ", name))
+    log_info("Processing case: {name} ...")
     odir = file.path(gu_dir, name)
     dir.create(odir, showWarnings = FALSE)
 
@@ -119,15 +126,30 @@ do_one_case_geneusage = function(name, case, gu_dir) {
 
     ofig = file.path(odir, paste0(name, ".png"))
     png(ofig, width = case$devpars$width, height = case$devpars$height, res = case$devpars$res)
-    print(p)
+    print(p + scale_fill_biopipen())
     dev.off()
 
+    add_report(
+        list(
+            kind = "table_image",
+            src = ofig,
+            descr = paste0(
+                 "Distribution of known gene segments following the ",
+                 '<a href="http://www.imgt.org/IMGTrepertoire/LocusGenes/" target="_blank">IMGT</a> ',
+                 "nomenclature."
+            )
+        ),
+        h1 = "Gene Usage",
+        h2 = ifelse(name == "DEFAULT", "#", name)
+    )
+
     if (!is.null(case$analyses$cases) && length(case$analyses$cases) > 0) {
         for (aname in names(case$analyses$cases)) {
             if (case$analyses$cases[[aname]]$method == "none") {
                 next
             }
-            print(paste0("    Analysis: ", aname))
+            # print(paste0("    Analysis: ", aname))
+            log_info("- Processing analysis: {aname} ...")
             tryCatch({
                 imm_gua = geneUsageAnalysis(imm_gu, .method = case$analyses$cases[[aname]]$method)
             }, error = function(e) {
@@ -152,6 +174,14 @@ do_one_case_geneusage = function(name, case, gu_dir) {
             png(aofig, width = case$analyses$cases[[aname]]$devpars$width, height = case$analyses$cases[[aname]]$devpars$height, res = case$analyses$cases[[aname]]$devpars$res)
             print(ap)
             dev.off()
+
+            add_report(
+                list(src = aofig, name = aname),
+                h1 = "Gene Usage",
+                h2 = ifelse(name == "DEFAULT", "#", name),
+                h3 = "Gene Usage Analysis",
+                ui = "table_of_images"
+            )
         }
     }
 }
@@ -159,7 +189,6 @@ do_one_case_geneusage = function(name, case, gu_dir) {
 gu_dir = file.path(outdir, "gene_usage")
 dir.create(gu_dir, showWarnings = FALSE)
 
-print("- Gene usage")
 for (name in names(cases)) {
     do_one_case_geneusage(name, cases[[name]], gu_dir)
 }

biopipen/scripts/tcr/Immunarch-kmer.R

@@ -1,9 +1,15 @@
 # loaded variables
 # immfile, outdir, mutaters, immdata, n_samples
 
+log_info("")
+log_info("#####################################")
+log_info("# K-mer analysis                    #")
+log_info("#####################################")
+
 kmers = {{ envs.kmers | r: todot="-" }}
 
 # Fill up cases
+log_info("Filling up cases ...")
 cases = kmers$cases
 if (is.null(cases) || length(cases) == 0) {
     cases$DEFAULT = list(
@@ -80,8 +86,9 @@ for (name in names(cases)) {
 }
 
 do_one_case_kmer = function(name, case, kmer_dir) {
-    print(paste0("  Case: ", name))
-    odir = file.path(kmer_dir, name)
+    # print(paste0("  Case: ", name))
+    log_info("Processing case: {name} ...")
+    odir = file.path(kmer_dir, slugify(name, tolower = FALSE))
     dir.create(odir, showWarnings = FALSE)
 
     if (!is.null(case$subset)) {
@@ -101,34 +108,77 @@ do_one_case_kmer = function(name, case, kmer_dir) {
     print(p)
     dev.off()
 
+    add_report(
+        list(
+            kind = "descr",
+            content = "K-mer sequence occurrences and motif analysis of CDR3 amino acid sequences"
+        ),
+        h1 = "Kmer and sequence motif analysis",
+        h2 = ifelse(name == "DEFAULT", "#", name),
+        h3 = "Kmer sequence occurrences"
+    )
+
+    add_report(
+        list(kind = "image", src = ofig),
+        h1 = "Kmer and sequence motif analysis",
+        h2 = ifelse(name == "DEFAULT", "#", name),
+        h3 = "Kmer sequence occurrences"
+    )
+
+    add_report(
+        h1 = "Kmer and sequence motif analysis",
+        h2 = ifelse(name == "DEFAULT", "#", name),
+        h3 = "Motif analysis"
+    )
+
     for (sample in names(d$data)) {
-        print(paste0("    Sample: ", sample))
+        # print(paste0("    Sample: ", sample))
+        log_info("- Sample: {sample} ...")
         imm_kmer = getKmers(d$data[[sample]], case$k)
 
         if (!is.null(case$profiles$cases) && length(case$profiles$cases) > 0) {
             for (aname in names(case$profiles$cases)) {
-                print(paste0("    Profiling: ", aname))
+                # print(paste0("    Profiling: ", aname))
+                log_info("  Profiling: {aname} ...")
                 imm_kmera = kmer_profile(imm_kmer, case$profiles$cases[[aname]]$method)
                 avis_args = case$profiles$cases[[aname]]$vis_args
                 avis_args$.data = imm_kmera
                 ap = do_call(vis, avis_args)
                 if (aname == "DEFAULT") {
-                    aofig = file.path(odir, paste0(sample, "-profile.png"))
+                    aofig = file.path(odir, paste0(slugify(sample), "-profile.png"))
                 } else {
-                    aofig = file.path(odir, paste0(sample, "-", aname, "-profile.png"))
+                    aofig = file.path(odir, paste0(slugify(sample), "-", slugify(aname), "-profile.png"))
                 }
                 png(aofig, width = case$profiles$cases[[aname]]$devpars$width, height = case$profiles$cases[[aname]]$devpars$height, res = case$profiles$cases[[aname]]$devpars$res)
                 print(ap)
                 dev.off()
+
+                add_report(
+                    list(
+                        src = aofig,
+                        name = paste0(sample, ifelse(aname == "DEFAULT", "", paste0(" - ", aname)))
+                    ),
+                    h1 = "Kmer and sequence motif analysis",
+                    h2 = ifelse(name == "DEFAULT", "#", name),
+                    h3 = "Motif analysis",
+                    ui = "table_of_images"
+                )
             }
         }
     }
 }
 
+add_report(
+    list(
+        kind = "descr",
+        content = "Counting k-mer occurrences"
+    ),
+    h1 = "Kmer and sequence motif analysis"
+)
+
 kmer_dir = file.path(outdir, "kmer")
 dir.create(kmer_dir, showWarnings = FALSE)
 
-print("- K-mer analysis")
 for (name in names(cases)) {
     do_one_case_kmer(name, cases[[name]], kmer_dir)
 }

biopipen/scripts/tcr/Immunarch-overlap.R

@@ -1,6 +1,11 @@
 # loaded variables
 # immfile, outdir, mutaters, immdata, n_samples
 
+log_info("")
+log_info("#####################################")
+log_info("# Overlap analysis                  #")
+log_info("#####################################")
+
 overlaps = {{ envs.overlaps | r: todot="-" }}
 
 # Fill up cases
@@ -75,8 +80,48 @@ for (name in names(cases)) {
     cases[[name]]$analyses = analyses
 }
 
+get_method_descr <- function(method) {
+    descr <- switch(method,
+        public = paste0(
+            "number of public (shared) clonotypes, ",
+            "a classic measure of overlap similarity"
+        ),
+        overlap = paste0(
+            "overlap coefficient, a normalised measure of overlap similarity. ",
+            "It is defined as the size of the intersection divided by the smaller of ",
+            "the size of the two sets."
+        ),
+        jaccard = paste0(
+            "Jaccard index, measures the similarity between finite sample sets, ",
+            "and is defined as the size of the intersection divided by the size of ",
+            "the union of the sample sets."
+        ),
+        tversky = paste0(
+            "Tversky index, an asymmetric similarity measure on sets that compares ",
+            "a variant to a prototype. ",
+            "If using default arguments, it’s similar to Dice’s coefficient."
+        ),
+        cosine = "cosine similarity, a measure of similarity between two non-zero vectors",
+        morisita = paste0(
+            "Morisita's overlap index, a statistical measure of dispersion of ",
+            "individuals in a population. ",
+            "It is used to compare overlap among samples."
+        )
+    )
+
+    if (!is.null(descr)) {
+        return(descr)
+    }
+
+    return(paste0(
+        "incremental overlap, ",
+        "overlaps of the N most abundant clonotypes with incrementally growing N"
+    ))
+}
+
 do_one_case_overlap = function(name, case, ov_dir) {
-    print(paste0("  Case: ", name))
+    # print(paste0("  Case: ", name))
+    log_info("Processing case: {name} ...")
     odir = file.path(ov_dir, name)
     dir.create(odir, showWarnings = FALSE)
 
@@ -96,11 +141,26 @@ do_one_case_overlap = function(name, case, ov_dir) {
     print(p)
     dev.off()
 
+    add_report(
+        list(
+            kind = "table_image",
+            src = ofig,
+            descr = paste0(
+                "Repertoire overlap is the most common approach to measure repertoire similarity, ",
+                "using method <code>", case$method, "</code>, ",
+                get_method_descr(case$method)
+            )
+        ),
+        h1 = "Repertoire Overlaps",
+        h2 = ifelse(name == "DEFAULT", "#", name)
+    )
+
     if (!is.null(case$analyses$cases) && length(case$analyses$cases) > 0) {
         for (aname in names(case$analyses$cases)) {
             if (case$analyses$cases[[aname]]$method == "none") next
 
-            print(paste0("    Analysis: ", aname))
+            # print(paste0("    Analysis: ", aname))
+            log_info("- Processing analysis: {aname} ...")
             k = min(n_samples - 1, 2)
             tryCatch({
                 imm_ova = repOverlapAnalysis(
@@ -128,6 +188,15 @@ do_one_case_overlap = function(name, case, ov_dir) {
             png(aofig, width = case$analyses$cases[[aname]]$devpars$width, height = case$analyses$cases[[aname]]$devpars$height, res = case$analyses$cases[[aname]]$devpars$res)
             print(ap)
             dev.off()
+
+            add_report(
+                list(src = aofig, name = aname),
+                h1 = "Repertoire Overlaps",
+                h2 = ifelse(name == "DEFAULT", "#", name),
+                h3 = "Repertoire Overlap Analysis",
+                ui = "table_of_images"
+            )
+
         }
     }
 }
@@ -135,7 +204,7 @@ do_one_case_overlap = function(name, case, ov_dir) {
 ov_dir = file.path(outdir, "overlap")
 dir.create(ov_dir, showWarnings = FALSE)
 
-print("- Overlap")
+# print("- Overlap")
 for (name in names(cases)) {
     do_one_case_overlap(name, cases[[name]], ov_dir)
 }

biopipen/scripts/tcr/Immunarch-spectratyping.R

@@ -1,9 +1,15 @@
 # loaded variables
 # immfile, outdir, mutaters, immdata, n_samples
 
+log_info("")
+log_info("#####################################")
+log_info("# Spectratyping analysis            #")
+log_info("#####################################")
+
 spects = {{ envs.spects | r }}
 
 # Fill up cases
+log_info("Filling up cases ...")
 if (is.null(spects$cases) || length(spects$cases) == 0) {
     spects$cases$DEFAULT = list(
         quant = spects$quant,
@@ -37,8 +43,9 @@ if (is.null(spects$cases) || length(spects$cases) == 0) {
 }
 
 do_one_case_spectratyping = function(name, case, spect_dir) {
-    print(paste0("  Case: ", name))
-    odir = file.path(spect_dir, name)
+    # print(paste0("  Case: ", name))
+    log_info("- Processing case: {name} ...")
+    odir = file.path(spect_dir, slugify(name, tolower = FALSE))
     dir.create(odir, showWarnings = FALSE)
 
     if (!is.null(case$subset)) {
@@ -48,24 +55,40 @@ do_one_case_spectratyping = function(name, case, spect_dir) {
     }
 
     for (sample in names(d$data)) {
-        print(paste0("    Sample: ", sample))
+        # print(paste0("    Sample: ", sample))
+        log_info("  Sample: {sample} ...")
         spec_obj = spectratype(
             d$data[[sample]],
             .quant = case$quant,
             .col = case$col
         )
+        spectfile = file.path(odir, paste0(slugify(sample, tolower = FALSE), ".spect"))
         png(
-            file.path(odir, paste0(sample, ".png")),
+            spectfile,
             res = case$devpars$res,
             width = case$devpars$width,
             height = case$devpars$height
         )
         print(vis(spec_obj))
         dev.off()
+
+        add_report(
+            list(src = spectfile, name = sample),
+            h1 = "Spectratyping",
+            h2 = name,
+            ui = "table_of_images"
+        )
     }
 }
 
-print("- Spectratyping")
+add_report(
+    list(
+        kind = "descr",
+        content = "Spectratype is a useful way to represent distributions of genes per sequence length."
+    ),
+    h1 = "Spectratyping"
+)
+
 spect_dir = file.path(outdir, "spectratyping")
 dir.create(spect_dir, showWarnings = FALSE)
 

biopipen/scripts/tcr/Immunarch-tracking.R

@@ -1,7 +1,11 @@
-print("- Clonotype tracking")
+log_info("")
+log_info("#####################################")
+log_info("# Clonotype tracking                #")
+log_info("#####################################")
 
 trackings = {{ envs.trackings | r }}
 
+log_info("Filling up cases ...")
 if (is.null(trackings$subjects)) {
     trackings$subjects = c()
 }
@@ -41,9 +45,11 @@ run_tracking_case = function(casename) {
     }
 
     if (is.null(case$targets)) {
-        print(paste0("  ", casename, ", skip, no targets"))
+        # print(paste0("  ", casename, ", skip, no targets"))
+        log_info("- Case: {casename}, skip, no targets")
     } else {
-        print(paste0("  ", casename))
+        # print(paste0("  ", casename))
+        log_info("- Case: {casename}")
         allsubjects = d$meta %>% pull(case$subject_col) %>% unlist() %>% unique() %>% na.omit()
         if (is.null(case$subjects) || length(case$subjects) == 0) {
             subjects = allsubjects
@@ -80,10 +86,33 @@ run_tracking_case = function(casename) {
             imm_tracking = trackClonotypes(newdata, targets, .col = "aa")
         }
 
-        tracking_png = file.path(tracking_dir, paste0(casename, ".png"))
+        tracking_png = file.path(tracking_dir, paste0(slugify(casename), ".png"))
         png(tracking_png, res=100, height=1000, width=600 + 150 * length(subjects))
         print(vis(imm_tracking))
         dev.off()
+
+        add_report(
+            list(
+                kind = "descr",
+                content = paste0(
+                    "Clonotype tracking is a popular approach to monitor changes in the frequency of ",
+                    "clonotypes of interest in vaccination and cancer immunology. ",
+                    "For example, a researcher can track a clonotype across different time points ",
+                    "in pre- and post-vaccination repertoires, or analyse the growth of ",
+                    "malignant clonotypes in a tumor sample."
+                )
+            ),
+            h1 = "Tracking of clonotypes"
+        )
+
+        add_report(
+            list(
+                src = tracking_png,
+                name = if (casename == "DEFAULT") NULL else casename
+            ),
+            h1 = "Tracking of clonotypes",
+            ui = "table_of_images"
+        )
     }
 }