biopipen 0.21.0__py3-none-any.whl → 0.34.26__py3-none-any.whl

biopipen/ns/gsea.py

@@ -1,8 +1,10 @@
 """Gene set enrichment analysis"""
+from pipen.utils import mark
 from ..core.proc import Proc
 from ..core.config import config
 
 
+@mark(deprecated='[{proc.name}] is deprecated, use `FGSEA` instead.')
 class GSEA(Proc):
     """Gene set enrichment analysis
 
@@ -51,6 +53,7 @@ class GSEA(Proc):
     plugin_opts = {"report": "file://../reports/gsea/GSEA.svelte"}
 
 
+@mark(deprecated='[{proc.name}] is deprecated, use `FGSEA` directly.')
 class PreRank(Proc):
     """PreRank the genes for GSEA analysis
 
@@ -100,59 +103,82 @@ class PreRank(Proc):
 class FGSEA(Proc):
     """Gene set enrichment analysis using `fgsea`
 
-    Need `devtools::install_github("ctlab/fgsea")`
-
     Input:
-        infile: The expression file.
-            Either a tab-delimited matrix or an RDS file (on envs.inopts)
+        infile: The expression file (genes x samples).
+            Either a tab-delimited file.
         metafile: The meta data file, determining the class of the samples
-            Two columns are required
-            Sample: The unique sample id for each sample
-            `[Group]`: The groups/classes of the samples
-        gmtfile: The GMT file of reference gene sets
-        configfile: The configuration file in TOML format to specify some envs.
-            `clscol`: If not provided, will use `envs.clscol`
-            `classes`: Defines pos and neg labels. If not provided, use will
-            `envs.classes`.
+            Two columns are required. If column `Sample` is found, it will be used
+            as the samples; otherwise the first column should be the samples.
+            The other column should be the group/class of the samples, whose
+            name is specified by `envs.clscol`.
 
     Output:
-        outdir: The output directory
+        outdir: The output directory containing the results, including
+            the table and plots.
 
     Envs:
-        inopts: The options for `read.table()` to read the input file
-            If `rds` will use `readRDS()`
-        metaopts: The options for `read.table()` to read the meta file
-        method: The method to do the preranking.
-            Supported: `s2n(signal_to_noise)`, `abs_s2n(abs_signal_to_noise)`,
-            `t_test`, `ratio_of_classes`, `diff_of_classes` and
-            `log2_ratio_of_classes`.
+        ncores (type=int): Number of cores for parallelization
+            Passed to `nproc` of `fgseaMultilevel()`.
+        case: The case label for the positive class.
+        control: The control label for the negative class.
+            When there are only two classes in `in.metafile` at column `envs.clscol`,
+            either `case` or `control` can be specified and the other will be
+            automatically set to the other class.
+        gmtfile: The pathways in GMT format, with the gene names/ids in the same format as the seurat object.
+            One could also use a URL to a GMT file. For example, from <https://download.baderlab.org/EM_Genesets/current_release/Human/symbol/Pathways/>.
+        method (choice): The method to do the preranking.
+            - signal_to_noise: Signal to noise.
+                The larger the differences of the means (scaled by the standard deviations);
+                that is, the more distinct the gene expression is in each phenotype and the more the gene
+                acts as a "class marker".
+            - s2n: Alias of signal_to_noise.
+            - abs_signal_to_noise: The absolute value of signal_to_noise.
+            - abs_s2n: Alias of abs_signal_to_noise.
+            - t_test: T test.
+                Uses the difference of means scaled by the standard deviation and number of samples.
+            - ratio_of_classes: Also referred to as fold change.
+                Uses the ratio of class means to calculate fold change for natural scale data.
+            - diff_of_classes: Difference of class means.
+                Uses the difference of class means to calculate fold change for nature scale data
+            - log2_ratio_of_classes: Log2 ratio of class means.
+                Uses the log2 ratio of class means to calculate fold change for natural scale data.
+                This is the recommended statistic for calculating fold change for log scale data.
         clscol: The column of metafile specifying the classes of the samples
-        classes: The classes to specify the pos and neg labels.
-            It could be a pair of labels (e.g. `["CASE", "CNTRL"]`), where
-            the first one is pos and second is neg. Or you can have multiple
-            pairs of labels (e.g. `[["CASE1", "CNTRL"], ["CASE2", "CNTRL"]]`)
-        top: Do gsea table and enrich plot for top N pathways. If it is < 1,
-            will apply it to `padj`
-        `<rest>`: Rest arguments for `fgsea()`
+            When `in.metafile` is not specified, it can also be specified as a list of
+            classes, in the same order as the samples in `in.infile`.
+        top (type=auto): Do gsea table and enrich plot for top N pathways.
+            If it is < 1, will apply it to `padj`, selecting pathways with `padj` < `top`.
+        eps (type=float): This parameter sets the boundary for calculating the p value.
+            See <https://rdrr.io/bioc/fgsea/man/fgseaMultilevel.html>
+        minsize (type=int): Minimal size of a gene set to test. All pathways below the threshold are excluded.
+        maxsize (type=int): Maximal size of a gene set to test. All pathways above the threshold are excluded.
+        rest (type=json;order=98): Rest arguments for [`fgsea()`](https://rdrr.io/bioc/fgsea/man/fgsea.html)
+            See also <https://rdrr.io/bioc/fgsea/man/fgseaMultilevel.html>
+        cases (type=json;order=99): If you have multiple cases, you can specify them here.
+            The keys are the names of the cases and the values are the above options except `mutaters`.
+            If some options are not specified, the default values specified above will be used.
+            If no cases are specified, the default case will be added with the name `GSEA`.
 
     Requires:
         bioconductor-fgsea:
             - check: {{proc.lang}} -e "library(fgsea)"
-    """
-    input = "infile:file, metafile:file, gmtfile:file, configfile:file"
+    """  # noqa: E501
+    input = "infile:file, metafile:file"
     output = "outdir:dir:{{in.infile | stem}}.fgsea"
     lang = config.lang.rscript
     envs = {
-        "inopts": {"header": True, "row.names": -1},
-        "metaopts": {"header": True, "row.names": -1},
-        "method": "s2n",
-        "clscol": None,
-        "classes": None,
-        "top": 20,
         "ncores": config.misc.ncores,
-        "minSize": 10,
-        "maxSize": 100,
+        "case": None,
+        "control": None,
+        "gmtfile": None,
+        "method": "signal_to_noise",
+        "clscol": None,
+        "top": 10,
         "eps": 0,
+        "minsize": 10,
+        "maxsize": 100,
+        "rest": {},
+        "cases": {},
     }
     script = "file://../scripts/gsea/FGSEA.R"
     plugin_opts = {"report": "file://../reports/gsea/FGSEA.svelte"}

biopipen/ns/misc.py

@@ -80,7 +80,7 @@ class Str2File(Proc):
         name: The name of the output file
     """
     input = "str, name"
-    output = "outfile:file:{{in.name}}"
+    output = "outfile:file:{{in.name | default: 'unnamed.txt'}}"
     lang = config.lang.python
     envs = {"name": None}
     script = "file://../scripts/misc/Str2File.py"
@@ -105,17 +105,42 @@ class Shell(Proc):
     output = "outfile:file:{{in.infile | basename}}"
     envs = {"cmd": "", "outdir": False}
     lang = config.lang.bash
-    script = """
-        infile={{in.infile | quote}}
-        outfile={{out.outfile | quote}}
-        is_outdir={{envs.outdir | int}}
-        cmd={{envs.cmd | quote}}
-        if [[ -z "$cmd" ]]; then
-            echo "No command given." 1>&2
-            exit 1
-        fi
-        if [[ $is_outdir -eq 1 ]]; then
-            mkdir -p "$outfile"
-        fi
-        eval "$cmd"
+    script = "file://../scripts/misc/Shell.sh"
+
+
+class Plot(Proc):
+    """Plot given data using plotthis package in R
+
+    Input:
+        datafile: The input data file in RDS or qs/qs2 format.
+            If it is not in RDS nor qs/qs2 format, read.table will be used
+            to read the data file with the options provided by `envs.read_opts`.
+
+    Output:
+        plotfile: The output plot file in PNG format
+
+    envs:
+        fn: The plot function to use. Required.
+        devpars (ns): The device parameters for the plot.
+            - width: The width of the plot in pixels.
+            - height: The height of the plot in pixels.
+            - res: The resolution of the plot in DPI.
+        more_formats: The additional formats to save the plot in other than PNG.
+            The file will be saved in the same directory as the plotfile.
+        save_code: Whether to save the R code used for plotting.
+        read_opts: Options to read the data file.
+            If the data file is not in RDS nor qs/qs2 format, these options
+            will be passed to `read.table`.
+        <more>: Additional parameters to the plot function.
     """
+    input = "datafile:file"
+    output = "plotfile:file:{{in.datafile | stem}}.png"
+    envs = {
+        "fn": None,
+        "devpars": {"res": 100},
+        "more_formats": [],
+        "save_code": False,
+        "read_opts": {},
+    }
+    lang = config.lang.rscript
+    script = "file://../scripts/misc/Plot.R"

biopipen/ns/plot.py

@@ -1,8 +1,16 @@
 """Plotting data"""
 
+import warnings
+
 from ..core.proc import Proc
 from ..core.config import config
 
+warnings.warn(
+    "The `biopipen.ns.plot` module is deprecated and will be removed in the future. "
+    "Please use `biopipen.ns.misc.Plot` process instead.",
+    DeprecationWarning,
+)
+
 
 class VennDiagram(Proc):
     """Plot Venn diagram
@@ -35,7 +43,7 @@ class VennDiagram(Proc):
     envs = {
         "inopts": {"row.names": -1, "header": False},
         "intype": "raw",
-        "devpars": {"res": 100, "width": 1000, "height": 1000},
+        "devpars": {"res": 100, "width": 800, "height": 600},
         "args": {},
         "ggs": None,
     }
@@ -114,3 +122,298 @@ class Heatmap(Proc):
         "globals": "",
     }
     script = "file://../scripts/plot/Heatmap.R"
+
+
+class ROC(Proc):
+    """Plot ROC curve using [`plotROC`](https://cran.r-project.org/web/packages/plotROC/vignettes/examples.html).
+
+    Input:
+        infile: The input file for data, tab-separated.
+            The first column should be ids of the records (this is optional if `envs.noids` is True).
+            The second column should be the labels of the records (1 for positive, 0 for negative).
+            If they are not binary, you can specify the positive label by `envs.pos_label`.
+            From the third column, it should be the scores of the different models.
+
+    Output:
+        outfile: The output figure file
+
+    Envs:
+        noids: Whether the input file has ids (first column) or not.
+        pos_label: The positive label.
+        ci: Whether to use `geom_rocci()` instead of `geom_roc()`.
+        devpars: The parameters for `png()`
+        args: Additional arguments for `geom_roc()` or `geom_rocci()` if `envs.ci` is True.
+        style_roc: Arguments for `style_roc()`
+    """  # noqa: E501
+    input = "infile:file"
+    output = "outfile:file:{{in.infile | stem}}.roc.png"
+    lang = config.lang.rscript
+    envs = {
+        "noids": False,
+        "pos_label": 1,
+        "ci": False,
+        "devpars": {"res": 100, "width": 750, "height": 600},
+        "args": {"labels": False},
+        "style_roc": {},
+        "show_auc": True,
+    }
+    script = "file://../scripts/plot/ROC.R"
+
+
+class Manhattan(Proc):
+    """Plot Manhattan plot.
+
+    Using the [`ggmanh`](https://bioconductor.org/packages/devel/bioc/vignettes/ggmanh/inst/doc/ggmanh.html) package.
+    Requires `ggmanh` v1.9.6 or later.
+
+    Input:
+        infile: The input file for data
+            It should contain at least three columns, the chromosome, the position
+            and the p-value of the SNPs.
+            Header is required.
+
+    Output:
+        outfile: The output figure file
+
+    Envs:
+        chrom_col: The column for chromosome
+            An integer (1-based) or a string indicating the column name.
+        pos_col: The column for position
+            An integer (1-based) or a string indicating the column name.
+        pval_col: The column for p-value
+            An integer (1-based) or a string indicating the column name.
+        label_col: The column for label.
+            Once specified, the significant SNPs will be labeled on the plot.
+        devpars (ns): The parameters for `png()`
+            - res (type=int): The resolution
+            - width (type=int): The width
+            - height (type=int): The height
+        title: The title of the plot
+        ylabel: The y-axis label
+        rescale (flag): Whether to rescale the p-values
+        rescale_ratio_threshold (type=float): Threshold of that triggers the rescale
+        signif (auto): A single value or a list of values to indicate the significance levels
+            Multiple values should be also separated by comma (`,`).
+            The minimum value will be used as the cutoff to determine if the SNPs are significant.
+        hicolors (auto): The colors for significant and non-significant SNPs
+            If a single color is given, the non-significant SNPs will be in grey.
+            Set it to None to disable the highlighting.
+        thin_n (type=int): Number of max points per horizontal partitions of the plot.
+            `0` or `None` to disable thinning.
+        thin_bins (type=int): Number of bins to partition the data.
+        zoom (auto): Chromosomes to zoom in
+            Each chromosome should be separated by comma (`,`) or in a list. Single chromosome is also accepted.
+            Ranges are also accepted, see `envs.chroms`.
+            Each chromosome will be saved in a separate file.
+        zoom_devpars (ns): The parameters for the zoomed plot
+            - width (type=int): The width
+            - height (type=int): The height, inherited from `devpars` by default
+            - res (type=int): The resolution, inherited from `devpars` by default
+        chroms (auto): The chromosomes and order to plot
+            A hyphen (`-`) can be used to indicate a range.
+            For example `chr1-22,chrX,chrY,chrM` will plot all autosomes, X, Y and M.
+            if `auto`, only the chromosomes in the data will be plotted in the order
+            they appear in the data.
+        args (ns): Additional arguments for `manhattan_plot()`.
+            See <https://rdrr.io/github/leejs-abv/ggmanh/man/manhattan_plot.html>.
+            Note that `-` will be replaced by `.` in the argument names.
+            - <more>: Additional arguments for `manhattan_plot()`
+    """  # noqa: E501
+    input = "infile:file"
+    output = "outfile:file:{{in.infile | stem0}}.manhattan.png"
+    lang = config.lang.rscript
+    envs = {
+        "chrom_col": 1,
+        "pos_col": 2,
+        "pval_col": 3,
+        "label_col": None,
+        "devpars": {"res": 100, "width": 1000, "height": 500},
+        "zoom_devpars": {"width": 500, "height": None, "res": None},
+        "title": None,
+        "ylabel": "-log10(p-value)",
+        "rescale": True,
+        "rescale_ratio_threshold": 5,
+        "signif": [5e-8, 1e-5],
+        "hicolors": None,
+        "thin_n": None,
+        "thin_bins": 200,
+        "zoom": None,
+        "chroms": "auto",
+        "args": {},
+    }
+    script = "file://../scripts/plot/Manhattan.R"
+
+
+class QQPlot(Proc):
+    """Generate QQ-plot or PP-plot using qqplotr.
+
+    See <https://cran.r-project.org/web/packages/qqplotr/vignettes/introduction.html>.
+
+    Input:
+        infile: The input file for data
+            It should contain at least one column of p-values or the values to be
+            plotted. Header is required.
+        theorfile: The file for theoretical values (optional)
+            This file should contain at least one column of theoretical values.
+            The values will be passed to `envs.theor_qfunc` to calculate the theoretical
+            quantiles.
+            Header is required.
+
+    Output:
+        outfile: The output figure file
+
+    Envs:
+        val_col: The column for values to be plotted
+            An integer (1-based) or a string indicating the column name.
+        devpars (ns): The parameters for `png()`
+            - res (type=int): The resolution
+            - width (type=int): The width
+            - height (type=int): The height
+        xlabel: The x-axis label
+        ylabel: The y-axis label
+        title: The title of the plot
+        trans: The transformation of the values
+            You can use `-log10` to transform the values to `-log10(values)`.
+            Otherwise you can a direct R function or a custom R function.
+            For example `function(x) -log10(x)`.
+        kind (choice): The kind of the plot, `qq` or `pp`
+            - qq: QQ-plot
+            - pp: PP-plot
+        theor_col: The column for theoretical values in `in.theorfile` if provided,
+            otherwise in `in.infile`.
+            An integer (1-based) or a string indicating the column name.
+            If `distribution` of `band`, `line`, or `point` is `custom`, this column
+            must be provided.
+        theor_trans: The transformation of the theoretical values.
+            The `theor_funs` have default functions to take the theoretical values.
+            This transformation will be applied to the theoretical values before
+            passing to the `theor_funs`.
+        theor_funs (ns): The R functions to generate density, quantile and deviates
+            of the theoretical distribution base on the theoretical values
+            if `distribution` of `band`, `line`, or `point` is `custom`.
+            - dcustom: The density function, used by band
+            - qcustom: The quantile function, used by point
+            - rcustom: The deviates function, used by line
+        args (ns): The common arguments for `envs.band`, `envs.line` and `envs.point`.
+            - distribution: The distribution of the theoretical quantiles
+                When `custom` is used, the `envs.theor_col` should be provided and
+                `values` will be added to `dparams` automatically.
+            - dparams (type=json): The parameters for the distribution
+            - <more>: Other shared arguments between `stat_*_band`, `stat_*_line`
+                and `stat_*_point`.
+        band (ns): The arguments for `stat_qq_band()` or `stat_pp_band()`.
+            See <https://rdrr.io/cran/qqplotr/man/stat_qq_band.html> and
+            <https://rdrr.io/cran/qqplotr/man/stat_pp_band.html>.
+            Set to `None` or `band.disabled` to True to disable the band.
+            - disabled (flag): Disable the band
+            - distribution: The distribution of the theoretical quantiles
+                When `custom` is used, the `envs.theor_col` should be provided and
+                `values` will be added to `dparams` automatically.
+            - dparams (type=json): The parameters for the distribution
+            - <more>: Additional arguments for `stat_qq_band()` or `stat_pp_band()`
+        line (ns): The arguments for `stat_qq_line()` or `stat_pp_line()`.
+            See <https://rdrr.io/cran/qqplot/man/stat_qq_line.html> and
+            <https://rdrr.io/cran/qqplot/man/stat_pp_line.html>.
+            Set to `None` or `line.disabled` to True to disable the line.
+            - disabled (flag): Disable the line
+            - distribution: The distribution of the theoretical quantiles
+                When `custom` is used, the `envs.theor_col` should be provided and
+                `values` will be added to `dparams` automatically.
+            - dparams (type=json): The parameters for the distribution
+            - <more>: Additional arguments for `stat_qq_line()` or `stat_pp_line()`
+        point (ns): The arguments for `geom_qq_point()` or `geom_pp_point()`.
+            See <https://rdrr.io/cran/qqplot/man/stat_qq_point.html> and
+            <https://rdrr.io/cran/qqplot/man/stat_pp_point.html>.
+            Set to `None` or `point.disabled` to True to disable the point.
+            - disabled (flag): Disable the point
+            - distribution: The distribution of the theoretical quantiles
+                When `custom` is used, the `envs.theor_col` should be provided and
+                `values` will be added to `dparams` automatically.
+            - dparams (type=json): The parameters for the distribution
+            - <more>: Additional arguments for `geom_qq_point()` or `geom_pp_point()`
+        ggs (list): Additional ggplot expression to adjust the plot.
+    """
+    input = "infile:file, theorfile:file"
+    output = "outfile:file:{{in.infile | stem}}.{{envs.kind}}.png"
+    lang = config.lang.rscript
+    envs = {
+        "val_col": 1,
+        "theor_col": None,
+        "theor_trans": None,
+        "theor_funs": {
+            "dcustom": """
+              function(x, values, ...) {
+                density(values, from = min(values), to = max(values), n = length(x))$y
+              }
+            """,
+            "qcustom": "function(p, values, ...) {quantile(values, probs = p)}",
+            "rcustom": "function(n, values, ...) { sample(values, n, replace = TRUE) }",
+        },
+        "args": {"distribution": "norm", "dparams": {}},
+        "devpars": {"res": 100, "width": 1000, "height": 1000},
+        "xlabel": "Theoretical Quantiles",
+        "ylabel": "Observed Quantiles",
+        "title": "QQ-plot",
+        "trans": None,
+        "kind": "qq",
+        "band": {"disabled": False, "distribution": None, "dparams": None},
+        "line": {"disabled": False, "distribution": None, "dparams": None},
+        "point": {"disabled": False, "distribution": None, "dparams": None},
+        "ggs": None,
+    }
+    script = "file://../scripts/plot/QQPlot.R"
+
+
+class Scatter(Proc):
+    """Generate scatter plot using ggplot2.
+
+    [`ggpmisc`](https://cran.r-project.org/web/packages/ggpmisc/index.html) is used
+    for the stats and labels.
+    See also https://cran.r-project.org/web/packages/ggpmisc/vignettes/model-based-annotations.html
+
+    Input:
+        infile: The input file for data
+            It should contain at least two columns for x and y values.
+            Header is required.
+
+    Output:
+        outfile: The output figure file
+
+    Envs:
+        x_col: The column for x values
+            An integer (1-based) or a string indicating the column name.
+        y_col: The column for y values
+            An integer (1-based) or a string indicating the column name.
+        devpars (ns): The parameters for `png()`
+            - res (type=int): The resolution
+            - width (type=int): The width
+            - height (type=int): The height
+        args (ns): Additional arguments for `geom_point()`
+            See <https://ggplot2.tidyverse.org/reference/geom_point.html>.
+            - <more>: Additional arguments for `geom_point()`
+        mapping: Extra mapping for all geoms, including `stats`.
+            Should be `aes(color = group)` but all these are valid: `color = group` or
+            `(color = group)`.
+        ggs (list): Additional ggplot expression to adjust the plot.
+        formula: The formula for the model
+        stats (type=json): The stats to add to the plot.
+            A dict with keys available stats in `ggpmisc` (without `stat_`).
+            See <https://cran.r-project.org/web/packages/ggpmisc/vignettes/model-based-annotations.html#statistics>.
+            The values should be the arguments for the stats.
+            If you want a stat to be added multiple times, add a suffix `#x` to the key.
+            For example, `poly_line#1` and `poly_line#2` will add two polynomial lines.
+    """  # noqa: E501
+    input = "infile:file"
+    output = "outfile:file:{{in.infile | stem}}.scatter.png"
+    lang = config.lang.rscript
+    envs = {
+        "x_col": 1,
+        "y_col": 2,
+        "devpars": {"res": 100, "width": 1000, "height": 800},
+        "args": {},
+        "mapping": None,
+        "ggs": [],
+        "formula": "y ~ x",
+        "stats": {},
+    }
+    script = "file://../scripts/plot/Scatter.R"