biopipen 0.31.7__py3-none-any.whl → 0.32.0__py3-none-any.whl

biopipen/__init__.py

@@ -1 +1 @@
-__version__ = "0.31.7"
+__version__ = "0.32.0"

biopipen/ns/scrna.py

@@ -2314,3 +2314,156 @@ class ScSimulation(Proc):
         "params": {},
     }
     script = "file://../scripts/scrna/ScSimulation.R"
+
+
+class CellCellCommunication(Proc):
+    """Cell-cell communication inference
+
+    This is implemented based on [LIANA](https://liana-py.readthedocs.io/en/latest/index.html),
+    which is a Python package for cell-cell communication inference and provides a list of existing
+    methods including [CellPhoneDB](https://github.com/ventolab/CellphoneDB),
+    [Connectome](https://github.com/msraredon/Connectome/), log2FC,
+    [NATMI](https://github.com/forrest-lab/NATMI),
+    [SingleCellSignalR](https://github.com/SCA-IRCM/SingleCellSignalR), Rank_Aggregate, Geometric Mean,
+    [scSeqComm](https://gitlab.com/sysbiobig/scseqcomm), and [CellChat](https://github.com/jinworks/CellChat).
+
+    You can also try `python -c 'import liana; liana.mt.show_methods()'` to see the methods available.
+
+    Note that this process does not do any visualization. You can use `CellCellCommunicationPlots`
+    to visualize the results.
+
+    Reference:
+    - [Review](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC9184522/).
+    - [LIANA](https://www.biorxiv.org/content/10.1101/2023.08.19.553863v1).
+
+    Input:
+        sobjfile: The seurat object file in RDS or h5seurat format or AnnData file.
+
+    Output:
+        outfile: The output file with the 'liana_res' data frame.
+            Stats are provided for both ligand and receptor entities, more specifically: ligand and receptor are
+            the two entities that potentially interact. As a reminder, CCC events are not limited to secreted signalling,
+            but we refer to them as ligand and receptor for simplicity.
+            Also, in the case of heteromeric complexes, the ligand and receptor columns represent the subunit with minimum
+            expression, while *_complex corresponds to the actual complex, with subunits being separated by _.
+            source and target columns represent the source/sender and target/receiver cell identity for each interaction, respectively
+            * `*_props`: represents the proportion of cells that express the entity.
+                By default, any interactions in which either entity is not expressed in above 10% of cells per cell type
+                is considered as a false positive, under the assumption that since CCC occurs between cell types, a sufficient
+                proportion of cells within should express the genes.
+            * `*_means`: entity expression mean per cell type.
+            * `lr_means`: mean ligand-receptor expression, as a measure of ligand-receptor interaction magnitude.
+            * `cellphone_pvals`: permutation-based p-values, as a measure of interaction specificity.
+
+    Envs:
+        method (choice): The method to use for cell-cell communication inference.
+            - CellPhoneDB: Use CellPhoneDB method.
+                Magnitude Score: lr_means; Specificity Score: cellphone_pvals.
+            - Connectome: Use Connectome method.
+            - log2FC: Use log2FC method.
+            - NATMI: Use NATMI method.
+            - SingleCellSignalR: Use SingleCellSignalR method.
+            - Rank_Aggregate: Use Rank_Aggregate method.
+            - Geometric_Mean: Use Geometric Mean method.
+            - scSeqComm: Use scSeqComm method.
+            - CellChat: Use CellChat method.
+            - cellphonedb: alias for `CellPhoneDB`
+            - connectome: alias for `Connectome`
+            - log2fc: alias for `log2FC`
+            - natmi: alias for `NATMI`
+            - singlesignaler: alias for `SingleCellSignalR`
+            - rank_aggregate: alias for `Rank_Aggregate`
+            - geometric_mean: alias for `Geometric_Mean`
+            - scseqcomm: alias for `scSeqComm`
+            - cellchat: alias for `CellChat`
+        assay: The assay to use for the analysis.
+            Only works for Seurat object.
+        seed (type=int): The seed for the random number generator.
+        ncores (type=int): The number of cores to use.
+        groupby: The column name in metadata to group the cells.
+            Typically, this column should be the cluster id.
+        species (choice): The species of the cells.
+            - human: Human cells, the 'consensus' resource will be used.
+            - mouse: Mouse cells, the 'mouseconsensus' resource will be used.
+        expr_prop (type=float): Minimum expression proportion for the ligands and
+            receptors (+ their subunits) in the corresponding cell identities. Set to 0
+            to return unfiltered results.
+        min_cells (type=int): Minimum cells (per cell identity if grouped by `groupby`)
+            to be considered for downstream analysis.
+        n_perms (type=int): Number of permutations for the permutation test.
+            Relevant only for permutation-based methods (e.g., `CellPhoneDB`).
+            If `0` is passed, no permutation testing is performed.
+        rscript: The path to the Rscript executable used to convert RDS file to AnnData.
+            if `in.sobjfile` is an RDS file, it will be converted to AnnData file (h5ad).
+            You need `Seurat`, `SeuratDisk` and `digest` installed.
+        <more>: Other arguments for the method.
+            The arguments are passed to the method directly.
+            See the method documentation for more details and also
+            `help(liana.mt.<method>.__call__)` in Python.
+    """  # noqa: E501
+    input = "sobjfile:file"
+    output = "outfile:file:{{in.sobjfile | stem}}-ccc.txt"
+    lang = config.lang.python
+    envs = {
+        "method": "cellchat",
+        "assay": None,
+        "seed": 1337,
+        "ncores": config.misc.ncores,
+        "groupby": "seurat_clusters",
+        "species": "human",
+        "expr_prop": 0.1,
+        "min_cells": 5,
+        "n_perms": 1000,
+        "rscript": config.lang.rscript,
+    }
+    script = "file://../scripts/scrna/CellCellCommunication.py"
+
+
+class CellCellCommunicationPlots(Proc):
+    """Visualization for cell-cell communication inference.
+
+    R package [`CCPlotR`](https://github.com/Sarah145/CCPlotR) is used to visualize
+    the results.
+
+    Input:
+        cccfile: The output file from `CellCellCommunication`
+            or a tab-separated file with the following columns: `source`, `target`,
+            `ligand`, `receptor`, and `score`.
+            If so, `in.expfile` can be provided where `exp_df` is needed.
+        expfile: The expression file with the expression of ligands and receptors.
+            Columns include: `cell_type`, `gene` and `mean_exp`.
+
+    Output:
+        outdir: The output directory for the plots.
+
+    Envs:
+        score_col: The column name in the input file that contains the score, if
+            the input file is from `CellCellCommunication`.
+            Two alias columns are added in the result file of `CellCellCommunication`,
+            `mag_score` and `spec_score`, which are the magnitude and specificity
+            scores.
+        subset: An expression to pass to `dplyr::filter()` to subset the ccc data.
+        cases (type=json): The cases for the plots.
+            The keys are the names of the cases and the values are the arguments for
+            the plots. The arguments include:
+            * kind: one of `arrow`, `circos`, `dotplot`, `heatmap`, `network`,
+                and `sigmoid`.
+            * devpars: The parameters for `png()` for the plot, including `res`,
+                `width`, and `height`.
+            * section: The section name for the report to group the plots.
+            * <other>: Other arguments for `cc_<kind>` function in `CCPlotR`.
+                See the documentation for more details.
+                Or you can use `?CCPlotR::cc_<kind>` in R.
+    """
+    input = "cccfile:file, expfile:file"
+    output = "outdir:dir:{{in.cccfile | stem}}-ccc_plots"
+    lang = config.lang.rscript
+    envs = {
+        "score_col": "mag_score",
+        "subset": None,
+        "cases": {},
+    }
+    script = "file://../scripts/scrna/CellCellCommunicationPlots.R"
+    plugin_opts = {
+        "report": "file://../reports/scrna/CellCellCommunicationPlots.svelte",
+    }

biopipen/reports/scrna/CellCellCommunicationPlots.svelte

@@ -0,0 +1,14 @@
+{% from "utils/misc.liq" import report_jobs, table_of_images -%}
+<script>
+    import { Image } from "$libs";
+</script>
+
+{%- macro report_job(job, h=1) -%}
+    {{ job | render_job: h=h }}
+{%- endmacro -%}
+
+{%- macro head_job(job) -%}
+    <h1>{{job.in.cccfile | stem0 | escape}}</h1>
+{%- endmacro -%}
+
+{{ report_jobs(jobs, head_job, report_job) }}

biopipen/reports/scrna/SeuratMap2Ref.svelte

@@ -1,16 +1,20 @@
 {% from "utils/misc.liq" import report_jobs, table_of_images -%}
 <script>
-    import { Image } from "$libs";
+    import { Image, DataTable } from "$libs";
 </script>
 
 {%- macro report_job(job, h=1) -%}
-<h{{h}}>Reference UMAP</h{{h}}>
-{% set imgs = job.outdir | glob: "Reference_UMAP_*.png" %}
-{{ table_of_images(imgs) }}
 
-<h{{h}}>Query UMAP</h{{h}}>
-{% set imgs = job.outdir | glob: "Query_UMAP_*.png" %}
+<h{{h}}>UMAPs</h{{h}}>
+{% set imgs = job.outdir | glob: "UMAPs-*.png" %}
 {{ table_of_images(imgs) }}
+
+<h{{h}}>Stats</h{{h}}>
+{% for stfile in job.outdir | glob: "stats-*.txt" %}
+    <h{{h+1}}>{{stfile | stem | replace: "stats-", ""}}</h{{h+1}}>
+    <DataTable src="{{stfile}}" data={ {{stfile | datatable: sep="\t"}} } />
+{% endfor %}
+
 {%- endmacro -%}
 
 {%- macro head_job(job) -%}

biopipen/scripts/scrna/AnnData2Seurat.R

@@ -41,25 +41,33 @@ if (outtype == "rds") {
     f <- H5File$new(h5seurat_file, "r+")
     groups <- f$ls(recursive = TRUE)
 
-    for (name in groups$name[grepl("categories", groups$name)]) {
-        names <- strsplit(name, "/")[[1]]
-        names <- c(names[1:length(names) - 1], "levels")
-        new_name <- paste(names, collapse = "/")
-        f[[new_name]] <- f[[name]]
-    }
+    for (name in groups$name[grepl("/categories$", groups$name)]) {
+        valuenames <- levelnames <- codenames <- strsplit(name, "/")[[1]]
+        valuenames[length(valuenames)] <- "values"
+        valuenames <- paste(valuenames, collapse = "/")
+        levelnames[length(levelnames)] <- "levels"
+        levelnames <- paste(levelnames, collapse = "/")
+        codenames[length(codenames)] <- "codes"
+        codenames <- paste(codenames, collapse = "/")
+        if (!f$exists(codenames)) {
+            # No codes, skip
+            next
+        }
 
-    for (name in groups$name[grepl("codes", groups$name)]) {
-        names <- strsplit(name, "/")[[1]]
-        names <- c(names[1:length(names) - 1], "values")
-        new_name <- paste(names, collapse = "/")
-        f[[new_name]] <- f[[name]]
-        grp <- f[[new_name]]
-        grp$write(args = list(1:grp$dims), value = grp$read() + 1)
+        if (!f$exists(levelnames)) {
+            f[[levelnames]] <- f[[name]]
+        }
+
+        if (!f$exists(valuenames)) {
+            f[[valuenames]] <- f[[codenames]]
+            grp <- f[[valuenames]]
+            grp$write(args = list(1:grp$dims), value = grp$read() + 1)
+        }
     }
     f$close_all()
     # end
 
-    sobj <- LoadH5Seurat(h5seurat_file)
+    sobj <- LoadH5Seurat(h5seurat_file, assays = assay)
     if (!isFALSE(dotplot_check)) {
         log_info("Checking dotplot ...")
         dotfig <- file.path(outdir, "dotplot.png")

biopipen/scripts/scrna/CCPlotR-patch.R

@@ -0,0 +1,161 @@
+# patched version of cc_circos
+# See https://github.com/Sarah145/CCPlotR/issues/4
+
+cc_circos <- function(cc_df, option = "A", n_top_ints = 15, exp_df = NULL, cell_cols = NULL, palette = "BuPu", cex = 1, show_legend = TRUE, scale = FALSE, ...) {
+    stopifnot("'cc_df' must be a dataframe" = is(cc_df, "data.frame"))
+    stopifnot("cc_df should contain columns named source, target, ligand, receptor and score. See `toy_data` for an example." = all(c('source', 'target', 'ligand', 'receptor', 'score') %in% colnames(cc_df)))
+    stopifnot("option must be either 'A', 'B', 'C'" = option %in% c('A', 'B', 'C'))
+    library(stringr)
+    library(ComplexHeatmap)
+    library(circlize)
+    circos.clear()
+
+    target <- score <- ligand <- receptor <- source_lig <- target_rec <- cell_type <- gene <- cell_gene <- NULL
+    if (option == "A") {
+        input_df <- cc_df %>%
+            mutate(source = factor(source), target = factor(target)) %>%
+            group_by(source, target) %>%
+            tally()
+        if (is.null(cell_cols)) {
+            cell_cols <- setNames(paletteMartin(n = length(unique(c(input_df$source, input_df$target)))), unique(c(input_df$source, input_df$target)))
+        }
+        circlize_plot <- function() {
+            par(cex = cex)
+            chordDiagram(input_df,
+                scale = FALSE, grid.col = cell_cols,
+                annotationTrack = c("grid", "name"), directional = 1, direction.type = c("arrows", "diffHeight"), link.arr.type = "big.arrow", link.arr.length = 0.1, diffHeight = -mm_h(0.5), preAllocateTracks = list(
+                    track.height = mm_h(10),
+                    track.margin = c(mm_h(2), -mm_h(4))
+                ), ...
+            )
+        }
+    } else if (option == "B") {
+        input_df <- cc_df %>%
+            slice_max(order_by = score, n = n_top_ints) %>%
+            mutate(
+                source_lig = paste0(source, "|", ligand),
+                target_rec = paste0(target, "|", receptor)
+            )
+        arr_wd <- (((input_df$score - min(input_df$score)) / (max(input_df$score) - min(input_df$score))) * (4)) + 1
+
+        if (is.null(cell_cols)) {
+            cell_cols <- setNames(paletteMartin(n = length(unique(c(input_df$source, input_df$target)))), unique(c(input_df$source, input_df$target)))
+        }
+
+        link_cols <- c()
+        for (i in input_df$source_lig) {
+            link_cols <- c(link_cols, cell_cols[str_extract(i, "[^|]+")])
+        }
+
+        segments <- unique(c(paste0(input_df$source, "|", input_df$ligand), paste0(input_df$target, "|", input_df$receptor)))
+        grp <- str_extract(segments, "[^|]+")
+        names(grp) <- segments
+        lgd <- Legend(
+            labels = unique(c(input_df$source, input_df$target)),
+            title = "Cell type",
+            type = "points",
+            title_gp = gpar(fontsize = 14 * cex),
+            labels_gp = gpar(fontsize = 12 * cex),
+            legend_gp = gpar(col = "transparent"),
+            background = cell_cols[unique(c(input_df$source, input_df$target))]
+        )
+        circlize_plot <- function() {
+            par(cex = cex)
+            chordDiagram(
+                input_df %>%
+                    select(source_lig, target_rec, score),
+                directional = 1, group = grp, link.sort = FALSE, scale = scale, diffHeight = 0.005,
+                direction.type = c("arrows"), link.arr.type = "triangle", annotationTrack = c(),
+                preAllocateTracks = list(list(track.height = 0.175), list(track.height = 0.05)),
+                big.gap = 3, transparency = 1, link.arr.lwd = arr_wd, link.arr.col = link_cols,
+                link.arr.length = 0.4, link.arr.width = 0.35, ...
+            )
+            circos.track(track.index = 1, panel.fun = function(x, y) {
+                circos.text(CELL_META$xcenter, CELL_META$ylim[1], str_extract(CELL_META$sector.index, "[^|]+$"),
+                    facing = "clockwise", niceFacing = TRUE, adj = c(0, 0.55), cex = 1.3
+                )
+            }, bg.border = NA)
+            for (l in unique(str_extract(segments, "[^|]+"))) {
+                highlight.sector(segments[str_detect(segments, paste0("^", str_escape(l)))], track.index = 2, col = cell_cols[l])
+            }
+            if (show_legend == TRUE) {
+                draw(lgd, just = c("left", "bottom"), x = unit(5, "mm"), y = unit(5, "mm"))
+            }
+            circos.clear()
+        }
+    } else if (option == "C") {
+        stopifnot("'exp_df' must be a dataframe" = is(exp_df, "data.frame"))
+        stopifnot("exp_df should contain columns named cell_type, gene and mean_exp. See `toy_exp` for an example." = all(c('cell_type', 'gene', 'mean_exp') %in% colnames(exp_df)))
+
+        input_df <- cc_df %>%
+            slice_max(order_by = score, n = n_top_ints) %>%
+            mutate(
+                source_lig = paste0(source, "|", ligand),
+                target_rec = paste0(target, "|", receptor)
+            )
+
+        arr_wd <- (((input_df$score - min(input_df$score)) / (max(input_df$score) - min(input_df$score))) * (4)) + 1
+
+        if (is.null(cell_cols)) {
+            cell_cols <- setNames(paletteMartin(n = length(unique(c(input_df$source, input_df$target)))), unique(c(input_df$source, input_df$target)))
+        }
+
+        segments <- unique(c(paste0(input_df$source, "|", input_df$ligand), paste0(input_df$target, "|", input_df$receptor)))
+        grp <- str_extract(segments, "[^|]+")
+        names(grp) <- segments
+
+        gene_df <- as.data.frame(exp_df %>% mutate(cell_gene = paste0(cell_type, "|", gene)) %>% filter(cell_gene %in% segments))
+        rownames(gene_df) <- gene_df$cell_gene
+
+        brks <- scales::pretty_breaks(n = 5)(c(floor(min(gene_df$mean_exp)), ceiling(max(gene_df$mean_exp))))
+        gene_col_fun <- colorRamp2(brks, RColorBrewer::brewer.pal(length(brks), palette))
+
+        inner.cols <- setNames(gene_col_fun(gene_df[segments, "mean_exp"]), segments)
+        lgd1 <- Legend(
+            labels = unique(c(input_df$source, input_df$target)),
+            title = "Cell type",
+            type = "points",
+            title_gp = gpar(fontsize = 14 * cex),
+            labels_gp = gpar(fontsize = 12 * cex),
+            legend_gp = gpar(col = "transparent"),
+            background = cell_cols[unique(c(input_df$source, input_df$target))],
+            direction = "horizontal"
+        )
+
+        lgd2 <- Legend(
+            title_gp = gpar(fontsize = 14 * cex),
+            labels_gp = gpar(fontsize = 12 * cex),
+            direction = "horizontal", at = brks,
+            col_fun = gene_col_fun, title = "Mean exp."
+        )
+        circlize_plot <- function() {
+            par(cex = cex)
+            chordDiagram(
+                input_df %>%
+                    select(source_lig, target_rec, score),
+                directional = 1, group = grp, link.sort = FALSE, diffHeight = 0.005, scale = scale,
+                direction.type = c("arrows"), link.arr.type = "triangle", annotationTrack = c(),
+                preAllocateTracks = list(list(track.height = 0.175), list(track.height = 0.05), list(track.height = 0.045)),
+                big.gap = 3, transparency = 1, link.arr.lwd = arr_wd, link.arr.col = "black", link.arr.length = 0.4, link.arr.width = 0.35, ...
+            )
+            circos.track(track.index = 1, panel.fun = function(x, y) {
+                circos.text(CELL_META$xcenter, CELL_META$ylim[1], str_extract(CELL_META$sector.index, "[^|]+$"),
+                    facing = "clockwise", niceFacing = TRUE, adj = c(0, 0.55), cex = 1.3
+                )
+            }, bg.border = NA)
+            for (l in unique(str_extract(segments, "[^|]+"))) {
+                highlight.sector(segments[str_detect(segments, paste0("^", str_escape(l)))], track.index = 2, col = cell_cols[l])
+            }
+            circos.track(track.index = 3, panel.fun = function(x, y) {
+                circos.rect(CELL_META$xlim[1], CELL_META$ylim[1], CELL_META$xlim[2], CELL_META$ylim[2],
+                    sector.index = CELL_META$sector.index, col = inner.cols[CELL_META$sector.index]
+                )
+            }, bg.border = NA)
+            if (show_legend == TRUE) {
+                draw(packLegend(lgd1, lgd2, direction = "vertical"), just = c("left", "bottom"), x = unit(4.75, "mm"), y = unit(4.75, "mm"))
+            }
+            circos.clear()
+        }
+    }
+    circlize_plot()
+}

biopipen/scripts/scrna/CellCellCommunication.py

@@ -0,0 +1,101 @@
+from pathlib import Path
+from biopipen.utils.misc import run_command, logger
+import numpy as np
+import scanpy
+import liana
+import liana.method.sc._liana_pipe as _liana_pipe
+
+# monkey-patch liana.method.sc._liana_pipe._trimean due to the updates by scipy 1.14
+# https://github.com/scipy/scipy/commit/a660202652deead0f3b4b688eb9fdcdf9f74066c
+def _trimean(a, axis=0):
+    try:
+        arr = a.A
+    except AttributeError:
+        arr = a.toarray()
+
+    quantiles = np.quantile(arr, q=[0.25, 0.75], axis=axis)
+    median = np.median(arr, axis=axis)
+    return (quantiles[0] + 2 * median + quantiles[1]) / 4
+
+
+_liana_pipe._trimean = _trimean
+
+
+sobjfile = Path({{in.sobjfile | repr}})  # pyright: ignore  # noqa: E999
+outfile = Path({{out.outfile | repr}})  # pyright: ignore
+envs = {{envs | repr}}  # pyright: ignore
+
+method = envs.pop("method")
+assay = envs.pop("assay")
+ncores = envs.pop("ncores")
+species = envs.pop("species")
+rscript = envs.pop("rscript")
+
+if sobjfile.suffix.lower() == ".rds" or sobjfile.suffix.lower() == ".h5seurat":
+    annfile = outfile.parent / f"{sobjfile.stem}.h5ad"
+    r_script_convert_to_anndata = f"""
+    {{ biopipen_dir | joinpaths: "utils", "misc.R" | source_r }}
+    {{ biopipen_dir | joinpaths: "utils", "single_cell.R" | source_r }}
+
+    seurat_to_anndata(
+        "{sobjfile}",
+        "{annfile}",
+        assay = {{ envs.assay | r }},
+        log_info = log_info
+    )
+    """
+    run_command([rscript, "-e", r_script_convert_to_anndata], fg=True)
+
+    sobjfile = annfile
+
+logger.info("Reading the h5ad file ...")
+adata = scanpy.read_h5ad(sobjfile)
+
+method = method.lower()
+if method == "log2fc":
+    method_fun = liana.mt.logfc
+else:
+    method_fun = getattr(liana.mt, method)
+
+logger.info(f"Running {method} ...")
+envs["adata"] = adata
+envs["resource_name"] = "consensus" if species == "human" else "mouseconsensus"
+envs["n_jobs"] = ncores
+envs["inplace"] = True
+envs["verbose"] = True
+envs["key_added"] = "liana_ccc"
+method_fun(**envs)
+
+res = adata.uns['liana_ccc']
+
+mag_score_names = {
+    "cellphonedb": "lr_means",
+    "connectome": "expr_prod",
+    "log2fc": None,
+    "natmi": "expr_prod",
+    "singlecellsignalr": "lrscore",
+    "rank_aggregation": "magnitude_rank",
+    "geometric_mean": "lr_gmeans",
+    "scseqcomm": "inter_score",
+    "cellchat": "lr_probs",
+}
+
+spec_score_names = {
+    "cellphonedb": "cellphone_pvals",
+    "connectome": "scaled_weight",
+    "log2fc": "lr_logfc",
+    "natmi": "spec_weight",
+    "singlecellsignalr": None,
+    "rank_aggregation": "specificity_rank",
+    "geometric_mean": "gmean_pvals",
+    "scseqcomm": None,
+    "cellchat": "cellchat_pvals",
+}
+
+if mag_score_names[method] is not None:
+    res['mag_score'] = res[mag_score_names[method]]
+if spec_score_names[method] is not None:
+    res['spec_score'] = res[spec_score_names[method]]
+
+logger.info("Saving the result ...")
+res.to_csv(outfile, sep="\t", index=False)