|
| 1 | +# markeR Python Bridge |
| 2 | + |
| 3 | +This workspace provides two simple Python helpers for using the |
| 4 | +Bioconductor R package **markeR** via `rpy2`. |
| 5 | + |
| 6 | +- `markeR_to_python.py` provides a minimal example workflow |
| 7 | + demonstrating how to load the example data and call a specific |
| 8 | + function, serving as a template for users who wish to structure |
| 9 | + their own analysis script in Python. |
| 10 | +- `run_marker_function.py` is a generic command‑line wrapper that can |
| 11 | + invoke *any* function exported by the markeR package. |
| 12 | + |
| 13 | +## Prerequisites |
| 14 | + |
| 15 | +* R (>=.4.5) installed and on your `PATH`. |
| 16 | +* A Python virtual environment. Install dependencies with: |
| 17 | + |
| 18 | +```bash |
| 19 | +python -m venv .venv |
| 20 | +source .venv/bin/activate |
| 21 | +pip install -r requirements.txt |
| 22 | +``` |
| 23 | + |
| 24 | +## Quick start |
| 25 | + |
| 26 | +### 1. Run the tutorial workflow |
| 27 | + |
| 28 | +```bash |
| 29 | +python markeR_to_python.py --tutorial --output tutorial.png |
| 30 | +open tutorial.png |
| 31 | +``` |
| 32 | + |
| 33 | +This executes an example from the markeR vignette; consult the |
| 34 | +original R tutorial (link below) for a step‑by‑step description of each |
| 35 | +analysis step. |
| 36 | + |
| 37 | +### 2. Call any markeR function |
| 38 | + |
| 39 | +```bash |
| 40 | +python run_marker_function.py PlotScores \ |
| 41 | + --data counts_example \ |
| 42 | + --metadata metadata_example \ |
| 43 | + --gene_sets genesets_example \ |
| 44 | + --Variable "Condition" \ |
| 45 | + --method logmedian \ |
| 46 | + --nrow 1 \ |
| 47 | + --output my_plot.png |
| 48 | +``` |
| 49 | + |
| 50 | +All parameters are passed as `--name value` pairs. Use `--help-function` or |
| 51 | +refer to the online reference manual for argument names. The two scripts |
| 52 | +are described briefly below. |
| 53 | + |
| 54 | +--- |
| 55 | + |
| 56 | +## Tutorial script (`markeR_to_python.py`) |
| 57 | + |
| 58 | +A minimal Python example illustrating how to call markeR from within a Python |
| 59 | +environment. It loads the example datasets, runs a selected function, and |
| 60 | +generates a corresponding plot. The script is intended as a template for users |
| 61 | +who wish to structure and extend their own analysis workflows in Python. |
| 62 | + |
| 63 | +```bash |
| 64 | +python markeR_to_python.py --tutorial [--output file.png] |
| 65 | +``` |
| 66 | + |
| 67 | +--- |
| 68 | + |
| 69 | +## Flexible CLI caller (`run_marker_function.py`) |
| 70 | + |
| 71 | +This wrapper constructs and executes R code on the fly, so you can run any |
| 72 | +markeR function without _writing_ R. It handles type conversion, data |
| 73 | +loading and optional PNG output. |
| 74 | + |
| 75 | +Basic syntax: |
| 76 | + |
| 77 | +```bash |
| 78 | +python run_marker_function.py FUNCTION_NAME [OPTIONS] |
| 79 | +``` |
| 80 | + |
| 81 | +Useful options: |
| 82 | + |
| 83 | +* `--param value` – named argument for the R function |
| 84 | +* `--output filename.png` – capture plot output |
| 85 | +* `--width` / `--height` – PNG dimensions (pixels; default 800×600) |
| 86 | +* `--help-function` – show documentation link/usage hint |
| 87 | +* `--verbose` – display generated R code prior to execution |
| 88 | + |
| 89 | +Example (scores only, no plot): |
| 90 | + |
| 91 | +```bash |
| 92 | +python run_marker_function.py CalculateScores \ |
| 93 | + --data counts_example \ |
| 94 | + --metadata metadata_example \ |
| 95 | + --gene_sets genesets_example \ |
| 96 | + --method logmedian |
| 97 | +``` |
| 98 | + |
| 99 | +Example saving a plot to PNG (with custom dimensions): |
| 100 | + |
| 101 | +```bash |
| 102 | +python run_marker_function.py PlotScores \ |
| 103 | + --data counts_example \ |
| 104 | + --metadata metadata_example \ |
| 105 | + --gene_sets genesets_example \ |
| 106 | + --Variable "Condition" \ |
| 107 | + --method logmedian \ |
| 108 | + --nrow 1 \ |
| 109 | + --width 800 \ |
| 110 | + --height 400 \ |
| 111 | + --output my_plot.png |
| 112 | +``` |
| 113 | +--- |
| 114 | + |
| 115 | +## Built‑in example data |
| 116 | + |
| 117 | +`counts_example`, `metadata_example` and `genesets_example` are loaded |
| 118 | +automatically and mirror the objects used in the tutorial. They let you |
| 119 | +try commands without supplying your own datasets. |
| 120 | + |
| 121 | +--- |
| 122 | + |
| 123 | +## Tips & troubleshooting |
| 124 | + |
| 125 | +* Add `--verbose` to see the exact R code being run – handy when a |
| 126 | + parameter doesn’t behave as expected. |
| 127 | +* If `--output` fails, check write permissions and ensure the directory |
| 128 | + exists. |
| 129 | +* Installation problems usually indicate R is missing; make sure `R` is |
| 130 | + on your path before installing Python dependencies. |
| 131 | + |
| 132 | +--- |
| 133 | + |
| 134 | +## References |
| 135 | + |
| 136 | +* [markeR on Bioconductor](https://bioconductor.org/packages/markeR) |
| 137 | +* [Official R tutorial](https://diseasetranscriptomicslab.github.io/markeR/articles/Article_BenchmarkingMode.html) |
| 138 | +* [Reference manual](https://diseasetranscriptomicslab.github.io/markeR/reference/) |
| 139 | +* Paper: https://www.biorxiv.org/content/10.64898/2025.12.05.692517 |
| 140 | + |
| 141 | +--- |
| 142 | + |
| 143 | +*Notes:* scripts install markeR via BiocManager if it’s not already present. |
| 144 | +Warnings from `ggplot2` (e.g. about `aes_string()`) are harmless and come |
| 145 | +from the package itself. |
0 commit comments