biopipen 0.33.0__py3-none-any.whl → 0.34.0__py3-none-any.whl

biopipen/scripts/tcr/TESSA.R

@@ -1,27 +1,28 @@
-{{ biopipen_dir | joinpaths: "utils", "misc.R" | source_r }}
-{{ biopipen_dir | joinpaths: "utils", "single_cell.R" | source_r }}
-
 library(glue)
 library(dplyr)
 library(tidyr)
 library(tibble)
-library(immunarch)
 library(Seurat)
-library(ggplot2)
-library(ggprism)
+library(biopipen.utils)
 
-immfile <- {{in.immdata | r}}
-exprfile <- {{in.srtobj | r}}
+screpdata <- {{in.screpdata | r}}
 outfile <- {{out.outfile | r}}
 joboutdir <- {{job.outdir | r}}
 python <- {{envs.python | r}}
-prefix <- {{envs.prefix | r}}
 within_sample <- {{envs.within_sample | r}}
 assay <- {{envs.assay | r}}
 predefined_b <- {{envs.predefined_b | r}}
 max_iter <- {{envs.max_iter | int}}
 save_tessa <- {{envs.save_tessa | r}}
-tessa_srcdir <- "{{biopipen_dir}}/scripts/tcr/TESSA_source"
+
+log <- get_logger()
+reporter <- get_reporter()
+
+# In case this script is running in the cloud and <biopipen_dir> can not be found in there
+# In stead, we use the python command, which is associated with the cloud environment,
+# to get the biopipen directory
+biopipen_dir <- get_biopipen_dir(python)
+tessa_srcdir <- file.path(biopipen_dir, "scripts", "tcr", "TESSA_source")
 
 outdir <- dirname(outfile)
 result_dir <- file.path(outdir, "result")
@@ -31,88 +32,49 @@ if (!dir.exists(tessa_dir)) dir.create(tessa_dir)
 
 ### Start preparing input files for TESSA
 # Prepare input files
-log_info("Preparing TCR input file ...")
-# If immfile endswith .rds, then it is an immunarch object
-if (endsWith(tolower(immfile), ".rds")) {
-    immdata <- readRDS(immfile)
-    if (is.null(prefix)) { prefix = immdata$prefix }
-    if (is.null(prefix)) { prefix = "" }
-    tcrdata <- expand_immdata(immdata) %>%
-        mutate(Barcode = glue(paste0(prefix, "{Barcode}")))
-    rm(immdata)
-} else {
-    tcrdata <- read.table(immfile, sep="\t", header=TRUE, row.names=1) %>%
-        rownames_to_column("Barcode")
-}
-
-has_VJ <- "V.name" %in% colnames(tcrdata) && "J.name" %in% colnames(tcrdata)
-
-if (has_VJ) {
-    tcrdata <- tcrdata %>% dplyr::mutate(
-        v_gene = sub("-\\d+$", "", V.name),
-        j_gene = sub("-\\d+$", "", J.name)
-    ) %>% dplyr::select(
-        contig_id = Barcode,
-        cdr3 = CDR3.aa,
-        v_gene,
-        j_gene,
-        sample = Sample
-    )
-} else {
-    tcrdata <- tcrdata %>% dplyr::select(
-        contig_id = Barcode,
-        cdr3 = CDR3.aa,
-        sample = Sample
-    )
-}
-
-
-log_info("Preparing expression input file ...")
-is_seurat <- endsWith(tolower(exprfile), ".rds")
-is_gz <- endsWith(tolower(exprfile), ".gz")
-
-if (is_seurat) {
-    sobj <- readRDS(exprfile)
-    expr <- GetAssayData(sobj, layer = "data")
-} else if (is_gz) {
-    expr <- read.table(gzfile(exprfile), sep="\t", header=TRUE, row.names=1)
-} else {
-    expr <- read.table(exprfile, sep="\t", header=TRUE, row.names=1)
-}
+log$info("Reading input file ...")
+sobj <- read_obj(screpdata)
 
+log$info("Preparing TCR input file ...")
+# If immfile endswith .rds, then it is an immunarch object
+tcrdata <- sobj@meta.data %>%
+    rownames_to_column("contig_id") %>%
+    filter(!is.na(CTaa) & !is.na(CTgene)) %>%
+    separate(CTaa, into = c(NA, "cdr3"), sep = "_", remove = FALSE) %>%
+    separate(CTgene, into = c(NA, "vjgene"), sep = "_", remove = FALSE) %>%
+    separate(vjgene, into = c("v_gene", NA, "j_gene", NA), sep = "\\.", remove = TRUE) %>%
+    mutate(v_gene = sub("-\\d+$", "", v_gene), j_gene = sub("-\\d+$", "", j_gene))
+
+log$info("Preparing expression input file ...")
+expr <- GetAssayData(sobj, layer = "data")
 cell_ids <- intersect(tcrdata$contig_id, colnames(expr))
 # Warning about unused cells
-unused_tcr_cells <- setdiff(tcrdata$contig_id, cell_ids)
 unused_expr_cells <- setdiff(colnames(expr), cell_ids)
-if (length(unused_tcr_cells) > 0) {
-    log_warn(glue("{length(unused_tcr_cells)}/{nrow(tcrdata)} TCR cells are not used."))
-}
 if (length(unused_expr_cells) > 0) {
-    log_warn(glue("{length(unused_expr_cells)}/{ncol(expr)} expression cells are not used."))
+    log$warn(glue("{length(unused_expr_cells)}/{ncol(expr)} cells without TCR data are not used."))
 }
 if (length(cell_ids) == 0) {
-    stop(paste0(
-        "No common cells between TCR and expression data. ",
-        "Are you using the correct `envs.prefix` here or in `ImmunarchLoading`?"
-    ))
+    stop(
+        "No TCR data found in the Seurat object. ",
+        "Please use scRepertiore::combineExpression() to generate the Seurat object with TCR data."
+    )
 }
-tcrdata <- tcrdata[tcrdata$contig_id %in% cell_ids, , drop=FALSE]
 expr <- as.matrix(expr)[, tcrdata$contig_id, drop=FALSE]
 
 # Write input files
-log_info("Writing input files ...")
+log$info("Writing input files ...")
 write.table(tcrdata, file.path(tessa_dir, "tcrdata.txt"), sep=",", quote=FALSE, row.names=FALSE)
 write.table(expr, file.path(tessa_dir, "exprdata.txt"), sep=",", quote=FALSE, row.names=TRUE, col.names=TRUE)
 
 ### End preparing input files for TESSA
 
 ### Start running TESSA
-log_info("Running TESSA ...")
+log$info("Running TESSA ...")
 
 # The original TESSA uses a python wrapper to run the encoder and tessa model
 # here we run those two steps directly here
 
-log_info("- Running encoder ...")
+log$info("- Running encoder ...")
 cmd_encoder <- paste(
     python,
     file.path(tessa_srcdir, "BriseisEncoder.py"),
@@ -127,23 +89,22 @@ cmd_encoder <- paste(
     "-output_log",
     file.path(tessa_dir, "tcr_encoder.log")
 )
-if (has_VJ) {
-    cmd_encoder <- paste(
-        cmd_encoder,
-        "-output_VJ",
-        file.path(tessa_dir, "tcr_vj.txt")
-    )
-}
+cmd_encoder <- paste(
+    cmd_encoder,
+    "-output_VJ",
+    file.path(tessa_dir, "tcr_vj.txt")
+)
+
 print("Running:")
 print(cmd_encoder)
-log_debug(paste("- ", cmd_encoder))
+log$debug(paste("- ", cmd_encoder))
 
 rc <- system(cmd_encoder)
 if (rc != 0) {
     stop("Error: Failed to run encoder.")
 }
 
-log_info("- Running TESSA model ...")
+log$info("- Running TESSA model ...")
 source(file.path(tessa_srcdir, "real_data.R"))
 
 tessa <- run_tessa(
@@ -158,51 +119,40 @@ tessa <- run_tessa(
 )
 
 # Save TESSA results
-log_info("Saving TESSA results ...")
-if (is_seurat) {
-    cells <- rownames(sobj@meta.data)
-    sobj@meta.data <- sobj@meta.data %>%
-        mutate(
-            TESSA_Cluster = tessa$meta[
-                match(cells, tessa$meta$barcode),
-                "cluster_number"
-            ]
-        ) %>%
-        add_count(TESSA_Cluster, name = "TESSA_Cluster_Size")
-    rownames(sobj@meta.data) <- cells
-
-    if (save_tessa) {
-        sobj@misc$tessa <- tessa
-    }
-    saveRDS(sobj, outfile)
-} else {
-    out <- tessa$meta %>%
-        dplyr::select(barcode, TESSA_Cluster = cluster_number) %>%
-        add_count(TESSA_Cluster, name = "TESSA_Cluster_Size")
-    write.table(out, outfile, sep="\t", quote=FALSE, row.names=FALSE, col.names=TRUE)
+log$info("Saving TESSA results ...")
+cells <- rownames(sobj@meta.data)
+sobj@meta.data <- sobj@meta.data %>%
+    mutate(
+        TESSA_Cluster = tessa$meta[
+            match(cells, tessa$meta$barcode),
+            "cluster_number"
+        ]
+    ) %>%
+    add_count(TESSA_Cluster, name = "TESSA_Cluster_Size")
+rownames(sobj@meta.data) <- cells
+
+if (save_tessa) {
+    sobj@misc$tessa <- tessa
 }
+save_obj(sobj, outfile)
 
 # Post analysis
-log_info("Post analysis ...")
+log$info("Post analysis ...")
 plot_tessa(tessa, result_dir)
 plot_Tessa_clusters(tessa, result_dir)
 
 p <- tessa$meta %>%
     dplyr::select(barcode, TESSA_Cluster = cluster_number) %>%
     add_count(TESSA_Cluster, name = "TESSA_Cluster_Size") %>%
-    ggplot(aes(x = TESSA_Cluster_Size)) +
-    geom_histogram(binwidth = 1) +
-    theme_prism()
-
-png(file.path(result_dir, "Cluster_size_dist.png"), width=8, height=8, units="in", res=100)
-print(p)
-dev.off()
+    plotthis::Histogram(x = "TESSA_Cluster_Size")
 
-pdf(file.path(result_dir, "Cluster_size_dist.pdf"), width=8, height=8)
-print(p)
-dev.off()
+res <- 100
+height <- attr(p, "height") * res
+width <- attr(p, "width") * res
+prefix <- file.path(result_dir, "Cluster_size_dist")
+save_plot(p, prefix, devpars = list(width = width, height = height, res = res))
 
-add_report(
+reporter$add(
     list(
         src = file.path(result_dir, "Cluster_size_dist.png"),
         descr = "Histogram of cluster size distribution",
@@ -232,4 +182,4 @@ add_report(
     ui = "table_of_images"
 )
 
-save_report(joboutdir)
+reporter$save(joboutdir)

biopipen/scripts/tcr/VJUsage.R

@@ -1,9 +1,9 @@
 
-infile = {{in.infile | quote}}
-outprefix = {{out.outfile | prefix | replace: ".fancyvj.wt", "" | quote}}
-vdjtools = {{ envs.vdjtools | quote }}
-vdjtools_patch = {{ envs.vdjtools_patch | quote }}
-joboutdir = {{job.outdir | quote}}
+infile = {{in.infile | r}}
+outprefix = {{out.outfile | prefix | replace: ".fancyvj.wt", "" | r}}
+vdjtools = {{ envs.vdjtools | r }}
+vdjtools_patch = {{ envs.vdjtools_patch | r }}
+joboutdir = {{job.outdir | r}}
 
 command = sprintf(
     "cd %s && bash %s %s PlotFancyVJUsage --plot-type png %s %s",

biopipen/scripts/vcf/TruvariBenchSummary.R

@@ -1,11 +1,7 @@
-{{ biopipen_dir | joinpaths: "utils", "misc.R" | source_r }}
-{{ biopipen_dir | joinpaths: "utils", "plot.R" | source_r }}
-
-library(ggprism)
 library(rjson)
+library(rlang)
 library(dplyr)
-
-theme_set(theme_prism(axis_text_angle = 90))
+library(plotthis)
 
 indirs = {{in.indirs | r}}
 outdir = {{out.outdir | r}}
@@ -39,13 +35,21 @@ get_devpars = function() {
 
 plot_summary = function(col) {
     outfile = file.path(outdir, paste0(col, ".png"))
-    plotGG(
+    p <- plotthis::BarPlot(
         summaries,
-        "col",
-        list(mapping = aes_string(x = "Sample", y = bQuote(col), fill = "Sample")),
-        devpars = get_devpars(),
-        outfile = outfile
+        x = "Sample",
+        y = col,
+        x_text_angle = 90
+    )
+    devpars <- get_devpars()
+    png(
+        filename = outfile,
+        width = devpars$width,
+        height = devpars$height,
+        res = devpars$res
     )
+    print(p)
+    dev.off()
 }
 
 main = function() {

biopipen/utils/common_docstrs.py

@@ -27,74 +27,77 @@ def format_placeholder(**kwargs) -> Callable[[type], type]:
     """
 
     def decorator(klass: type) -> type:
+        if not klass.__doc__:
+            return klass
+
         klass.__doc__ = klass.__doc__ % kwargs
         return klass
 
     return decorator
 
 
-MUTATE_HELPERS_CLONESIZE = """
-There are also also 4 helper functions, `expanded`, `collapsed`, `emerged` and `vanished`,
-which can be used to identify the expanded/collpased/emerged/vanished groups (i.e. TCR clones).
-See also <https://pwwang.github.io/immunopipe/configurations/#mutater-helpers>.
-For example, you can use
-`{"Patient1_Tumor_Collapsed_Clones": "expanded(., Source, 'Tumor', subset = Patent == 'Patient1', uniq = FALSE)"}`
-to create a new column in metadata named `Patient1_Tumor_Collapsed_Clones`
-with the collapsed clones in the tumor sample (compared to the normal sample) of patient 1.
-The values in this columns for other clones will be `NA`.
-Those functions take following arguments:
-* `df`: The metadata data frame. You can use the `.` to refer to it.
-* `group.by`: The column name in metadata to group the cells.
-* `idents`: The first group or both groups of cells to compare (value in `group.by` column). If only the first group is given, the rest of the cells (with non-NA in `group.by` column) will be used as the second group.
-* `subset`: An expression to subset the cells, will be passed to `dplyr::filter()`. Default is `TRUE` (no filtering).
-* `each`: A column name (without quotes) in metadata to split the cells.
-    Each comparison will be done for each value in this column (typically each patient or subject).
-* `id`: The column name in metadata for the group ids (i.e. `CDR3.aa`).
-* `compare`: Either a (numeric) column name (i.e. `Clones`) in metadata to compare between groups, or `.n` to compare the number of cells in each group.
-    If numeric column is given, the values should be the same for all cells in the same group.
-    This will not be checked (only the first value is used).
-    It is helpful to use `Clones` to use the raw clone size from TCR data, in case the cells are not completely mapped to RNA data.
-    Also if you have `subset` set or `NA`s in `group.by` column, you should use `.n` to compare the number of cells in each group.
-* `uniq`: Whether to return unique ids or not. Default is `TRUE`. If `FALSE`, you can mutate the meta data frame with the returned ids. For example, `df |> mutate(expanded = expanded(...))`.
-* `debug`: Return the data frame with intermediate columns instead of the ids. Default is `FALSE`.
-* `order`: The expression passed to `dplyr::arrange()` to order intermediate dataframe and get the ids in order accordingly.
-    The intermediate dataframe includes the following columns:
-    * `<id>`: The ids of clones (i.e. `CDR3.aa`).
-    * `<each>`: The values in `each` column.
-    * `ident_1`: The size of clones in the first group.
-    * `ident_2`: The size of clones in the second group.
-    * `.diff`: The difference between the sizes of clones in the first and second groups.
-    * `.sum`: The sum of the sizes of clones in the first and second groups.
-    * `.predicate`: Showing whether the clone is expanded/collapsed/emerged/vanished.
-* `include_emerged`: Whether to include the emerged group for `expanded` (only works for `expanded`). Default is `FALSE`.
-* `include_vanished`: Whether to include the vanished group for `collapsed` (only works for `collapsed`). Default is `FALSE`.
+# MUTATE_HELPERS_CLONESIZE = """
+# There are also also 4 helper functions, `expanded`, `collapsed`, `emerged` and `vanished`,
+# which can be used to identify the expanded/collpased/emerged/vanished groups (i.e. TCR clones).
+# See also <https://pwwang.github.io/immunopipe/configurations/#mutater-helpers>.
+# For example, you can use
+# `{"Patient1_Tumor_Collapsed_Clones": "expanded(., Source, 'Tumor', subset = Patent == 'Patient1', uniq = FALSE)"}`
+# to create a new column in metadata named `Patient1_Tumor_Collapsed_Clones`
+# with the collapsed clones in the tumor sample (compared to the normal sample) of patient 1.
+# The values in this columns for other clones will be `NA`.
+# Those functions take following arguments:
+# * `df`: The metadata data frame. You can use the `.` to refer to it.
+# * `group.by`: The column name in metadata to group the cells.
+# * `idents`: The first group or both groups of cells to compare (value in `group.by` column). If only the first group is given, the rest of the cells (with non-NA in `group.by` column) will be used as the second group.
+# * `subset`: An expression to subset the cells, will be passed to `dplyr::filter()`. Default is `TRUE` (no filtering).
+# * `each`: A column name (without quotes) in metadata to split the cells.
+#     Each comparison will be done for each value in this column (typically each patient or subject).
+# * `id`: The column name in metadata for the group ids (i.e. `CDR3.aa`).
+# * `compare`: Either a (numeric) column name (i.e. `Clones`) in metadata to compare between groups, or `.n` to compare the number of cells in each group.
+#     If numeric column is given, the values should be the same for all cells in the same group.
+#     This will not be checked (only the first value is used).
+#     It is helpful to use `Clones` to use the raw clone size from TCR data, in case the cells are not completely mapped to RNA data.
+#     Also if you have `subset` set or `NA`s in `group.by` column, you should use `.n` to compare the number of cells in each group.
+# * `uniq`: Whether to return unique ids or not. Default is `TRUE`. If `FALSE`, you can mutate the meta data frame with the returned ids. For example, `df |> mutate(expanded = expanded(...))`.
+# * `debug`: Return the data frame with intermediate columns instead of the ids. Default is `FALSE`.
+# * `order`: The expression passed to `dplyr::arrange()` to order intermediate dataframe and get the ids in order accordingly.
+#     The intermediate dataframe includes the following columns:
+#     * `<id>`: The ids of clones (i.e. `CDR3.aa`).
+#     * `<each>`: The values in `each` column.
+#     * `ident_1`: The size of clones in the first group.
+#     * `ident_2`: The size of clones in the second group.
+#     * `.diff`: The difference between the sizes of clones in the first and second groups.
+#     * `.sum`: The sum of the sizes of clones in the first and second groups.
+#     * `.predicate`: Showing whether the clone is expanded/collapsed/emerged/vanished.
+# * `include_emerged`: Whether to include the emerged group for `expanded` (only works for `expanded`). Default is `FALSE`.
+# * `include_vanished`: Whether to include the vanished group for `collapsed` (only works for `collapsed`). Default is `FALSE`.
 
-You can also use `top()` to get the top clones (i.e. the clones with the largest size) in each group.
-For example, you can use
-`{"Patient1_Top10_Clones": "top(subset = Patent == 'Patient1', uniq = FALSE)"}`
-to create a new column in metadata named `Patient1_Top10_Clones`.
-The values in this columns for other clones will be `NA`.
-This function takes following arguments:
-* `df`: The metadata data frame. You can use the `.` to refer to it.
-* `id`: The column name in metadata for the group ids (i.e. `CDR3.aa`).
-* `n`: The number of top clones to return. Default is `10`.
-    If n < 1, it will be treated as the percentage of the size of the group.
-    Specify `0` to get all clones.
-* `compare`: Either a (numeric) column name (i.e. `Clones`) in metadata to compare between groups, or `.n` to compare the number of cells in each group.
-    If numeric column is given, the values should be the same for all cells in the same group.
-    This will not be checked (only the first value is used).
-    It is helpful to use `Clones` to use the raw clone size from TCR data, in case the cells are not completely mapped to RNA data.
-    Also if you have `subset` set or `NA`s in `group.by` column, you should use `.n` to compare the number of cells in each group.
-* `subset`: An expression to subset the cells, will be passed to `dplyr::filter()`. Default is `TRUE` (no filtering).
-* `each`: A column name (without quotes) in metadata to split the cells.
-    Each comparison will be done for each value in this column (typically each patient or subject).
-* `uniq`: Whether to return unique ids or not. Default is `TRUE`. If `FALSE`, you can mutate the meta data frame with the returned ids. For example, `df |> mutate(expanded = expanded(...))`.
-* `debug`: Return the data frame with intermediate columns instead of the ids. Default is `FALSE`.
-* `with_ties`: Whether to include ties (i.e. clones with the same size as the last clone) or not. Default is `FALSE`.
-"""
+# You can also use `top()` to get the top clones (i.e. the clones with the largest size) in each group.
+# For example, you can use
+# `{"Patient1_Top10_Clones": "top(subset = Patent == 'Patient1', uniq = FALSE)"}`
+# to create a new column in metadata named `Patient1_Top10_Clones`.
+# The values in this columns for other clones will be `NA`.
+# This function takes following arguments:
+# * `df`: The metadata data frame. You can use the `.` to refer to it.
+# * `id`: The column name in metadata for the group ids (i.e. `CDR3.aa`).
+# * `n`: The number of top clones to return. Default is `10`.
+#     If n < 1, it will be treated as the percentage of the size of the group.
+#     Specify `0` to get all clones.
+# * `compare`: Either a (numeric) column name (i.e. `Clones`) in metadata to compare between groups, or `.n` to compare the number of cells in each group.
+#     If numeric column is given, the values should be the same for all cells in the same group.
+#     This will not be checked (only the first value is used).
+#     It is helpful to use `Clones` to use the raw clone size from TCR data, in case the cells are not completely mapped to RNA data.
+#     Also if you have `subset` set or `NA`s in `group.by` column, you should use `.n` to compare the number of cells in each group.
+# * `subset`: An expression to subset the cells, will be passed to `dplyr::filter()`. Default is `TRUE` (no filtering).
+# * `each`: A column name (without quotes) in metadata to split the cells.
+#     Each comparison will be done for each value in this column (typically each patient or subject).
+# * `uniq`: Whether to return unique ids or not. Default is `TRUE`. If `FALSE`, you can mutate the meta data frame with the returned ids. For example, `df |> mutate(expanded = expanded(...))`.
+# * `debug`: Return the data frame with intermediate columns instead of the ids. Default is `FALSE`.
+# * `with_ties`: Whether to include ties (i.e. clones with the same size as the last clone) or not. Default is `FALSE`.
+# """
 
-ENVS_SECTION_EACH = """
-The `section` is used to collect cases and put the results under the same directory and the same section in report.
-When `each` for a case is specified, the `section` will be ignored and case name will be used as `section`.
-The cases will be the expanded values in `each` column. When `prefix_each` is True, the column name specified by `each` will be prefixed to each value as directory name and expanded case name.
-"""
+# ENVS_SECTION_EACH = """
+# The `section` is used to collect cases and put the results under the same directory and the same section in report.
+# When `each` for a case is specified, the `section` will be ignored and case name will be used as `section`.
+# The cases will be the expanded values in `each` column. When `prefix_each` is True, the column name specified by `each` will be prefixed to each value as directory name and expanded case name.
+# """

biopipen/utils/reporter.py

@@ -0,0 +1,177 @@
+from __future__ import annotations
+from typing import Sequence
+from os import PathLike
+from pathlib import Path
+
+"""An implementation of reporter in python
+"https://pwwang.github.io/biopipen.utils.R/reference/Reporter.html
+
+to generate a json file for pipen-report to build a report for a process.
+"""
+
+import json
+
+
+class Reporter:
+
+    def __init__(self):
+        self.report = {}
+
+    def add(
+        self,
+        *args,
+        h1: str,
+        h2: str = "#",
+        h3: str = "#",
+        ui: str = "flat",
+    ) -> None:
+        """Add a content to the report
+
+        Args:
+            *args: The content of the report
+            h1 (str): The first level header
+            h2 (str): The second level header
+            h3 (str): The third level header
+            ui (str): The user interface of the report
+        """
+
+        self.report.setdefault(h1, {})
+        self.report[h1].setdefault(h2, {})
+        self.report[h1][h2].setdefault(h3, {})
+        self.report[h1][h2][h3][ui] = []
+
+        for arg in args:
+            self.report[h1][h2][h3][ui].append(arg)
+
+    def add2(
+        self,
+        *args,
+        hs: Sequence[str],
+        hs2: Sequence[str] = (),
+        ui: str = "flat",
+        collapse: str = ": ",
+    ) -> None:
+        """Add a content to the report
+
+        Args:
+            *args: The content of the report
+            hs: The headings of the case
+            hs2: The headings that must be shown.
+                When there are more items in `hs`, they will be concatenated.
+                For example, if `hs = c("Section1", "Case1")`, and `hs2 = c("A", "B")`,
+                then headings will be `h1 = "Section1: Case1"` and `h2 = "A"` and
+                `h3 = "B"`.
+            ui: The user interface of the report
+            collapse: The separator to concatenate the headings
+        """
+        if len(hs2) > 2:
+            raise ValueError("hs2 must have 2 or less items")
+
+        if len(hs2) == 2:
+            h1 = collapse.join(hs)
+            h2 = hs2[0]
+            h3 = hs2[1]
+        elif len(hs2) == 1:
+            h1 = hs[0]
+            hs = hs[1:]
+            if hs:
+                h2 = collapse.join(hs)
+                h3 = hs2[0]
+            else:
+                h2 = hs2[0]
+                h3 = "#"
+        else:
+            h1 = hs[0]
+            hs = hs[1:]
+            if hs:
+                h2 = hs[0]
+                hs = hs[1:]
+            else:
+                h2 = "#"
+
+            if hs:
+                h3 = collapse.join(hs)
+            else:
+                h3 = "#"
+
+        self.add(*args, h1=h1, h2=h2, h3=h3, ui=ui)
+
+    def image(
+        self,
+        prefix: str,
+        more_formats: str | Sequence[str],
+        save_code: bool,
+        kind: str = "image",
+        **kwargs,
+    ) -> dict:
+        """Generate a report for an image to be added.
+
+        Args:
+            prefix: The prefix of the image.
+            more_formats: More formats of the image available.
+            save_code: Whether to save the code to reproduce the plot.
+            kind: The kind of the report, default is "image".
+            **kwargs: Other arguments to add to the report.
+
+        Returns:
+            dict: The structured report for the image
+
+        Examples:
+            >>> reporter = Reporter()
+            >>> reporter.add(
+            >>>   {
+            >>>     "name": "Image 1",
+            >>>     "contents": [
+            >>>       reporter.image("/path/to/image1", "pdf", save_code=True)
+            >>>     ]
+            >>>   },
+            >>>   h1="Images",
+            >>>   h2="Image 1",
+            >>> )
+        """
+        out = {
+            "kind": kind,
+            "src": f"{prefix}.png",
+            **kwargs,
+        }
+
+        if more_formats or save_code:
+            out["download"] = []
+
+        if more_formats:
+            for mf in more_formats:
+                out["download"].append(f"{prefix}.{mf}")
+
+        if save_code:
+            out["download"].append(
+                {
+                    "src": f"{prefix}.code.zip",
+                    "tip": "Download the code to reproduce the plot",
+                    "icon": "Code",
+                }
+            )
+
+        return out
+
+    def clear(self):
+        """Clear the report"""
+        self.report = {}
+
+    def save(self, path: str | PathLike, clear: bool = True) -> None:
+        """Save the report to a file
+
+        Args:
+            path: The path to save the report
+                If the path is a directory, the report will be saved as `report.json`
+                in the directory. Otherwise, the report will be saved to the file.
+            clear: Whether to clear the report after saving.
+        """
+        path = Path(path)
+        if path.is_dir():
+            path = path / "report.json"
+
+        with open(path, "w") as f:
+            json.dump(self.report, f, indent=2)
+
+        if clear:
+            self.clear()

{biopipen-0.33.0.dist-info → biopipen-0.34.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: biopipen
-Version: 0.33.0
+Version: 0.34.0
 Summary: Bioinformatics processes/pipelines that can be run from `pipen run`
 License: MIT
 Author: pwwang
@@ -17,6 +17,7 @@ Provides-Extra: runinfo
 Requires-Dist: datar[pandas] (>=0.15.8,<0.16.0)
 Requires-Dist: pipen-board[report] (>=0.17,<0.18)
 Requires-Dist: pipen-cli-run (>=0.15,<0.16)
+Requires-Dist: pipen-deprecated (>=0.0,<0.1)
 Requires-Dist: pipen-filters (>=0.15,<0.16)
 Requires-Dist: pipen-poplog (>=0.3,<0.4)
 Requires-Dist: pipen-runinfo (>=0.9,<0.10) ; extra == "runinfo"