-
Notifications
You must be signed in to change notification settings - Fork 0
/
lsf.Rmd
158 lines (106 loc) · 4.74 KB
/
lsf.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
---
title: "LSF array jobs with easypar"
author: "Giulio Caravagna"
date: "15 September 2019"
institute: "Institute for Cancer Research"
email: "giulio.caravagna@icr.ac.uk"
output: rmarkdown::html_vignette
vignette: >
%\VignetteEngine{knitr::knitr}
%\VignetteIndexEntry{LSF array jobs with easypar}
%\usepackage[UTF-8]{inputenc}
---
`easypar` can be used to generate scripts that submit array jobs to the LSF cluster system.
First, write in R your code.
```{r, eval=FALSE}
# Computation function
FUN = function(x, y){ ... }
# Input for 25 array jobs that match FUN arguments
PARAMS = data.frame(x = runif(25), y = runif(25))
# Generates submission files
run_lsf(FUN, PARAMS)
```
Then, in your terminal.
```{
# Test if the generated script runs with the first input
head -1 EASYPAR_LSF_input_jobarray.csv | Rscript EASYPAR_LSF_Run.R
# Submit array jobs (after loading the cluster module)
bsub < EASYPAR_LSF_submission.sh
```
#### Requirements
<!-- To use `run_lsf` you need: -->
- a function `FUN` (e.g.,: `FUN = ls`) that can run as a stand-alone R application, with its own parameters and that manages explicitly its dependencies.
> Note: `FUN` will be run as an indipendent process.
- a dataframe `PARAMS` where every row is an input for `FUN`. The column order must match `FUN` arguments.
Conceptually, you set up the data as for an `apply(FUN, MARGIN = 1)` by row.
The input should have column names without dots or spaces; these will match the arguments of `FUN`. So, for instance, an input with 2-columns will only work if `FUN` has 2 parameters.
#### Output
`run_lsf` generates 3 files:
- an R script wrapping the definition of `FUN`, with extra code to call `FUN` using parameters from the command line.
Your function in this script is called with a fake name;
- a `csv` file containing the input `PARAMS`, without any header (column names), and row names.
- a LSF array job submission script with `N` jobs where `N` are the rows of `PARAMS`.
Before submitting the job, test the computation as explained above.
#### Customising jobs
Cluster-specific BSUB instructions can be specified, as well as other dependencies from modules available on the cluster.
Function `run_lsf` allows to:
- specify a list of modules that will be added as dependencies of the LSF submission script. For instance, `modules = 'R/3.5.0'` will generate the dependecy for a specific R version (`3.5.0`).
- customize the BSUB parameters of the generated script.
The package comes with a default BSUB configuration, that **has to be updated according to your cluster setup**.
```{r, eval=T}
library(easypar)
# Default parameters in the package
default_BSUB_config()
```
These are classical BSUB parameters:
- `-J`, the job ID;
- `-P`, the project ID;
- `-q`, the queue ID;
- `-n` and `-R`, the resources to allocate;
- `-W` the wall time of the jobs;
- `-o` and `-e`, the outputs and the error filenames. Notice that by default
we have the job array ID in the filename, so to have one log per job.
> It is required to modify the default values of `-P` and `-q`, the project and queue ID,
according to your LSF configuration. Otherwise, the submission script will
generate an error becaue the default values do not mean anything.
Modifications are done to the default list of parameters; other BSUB flags can be
used as well. No checkings on their correctness are done by `easypar`.
```{r, eval=T}
custom_BSUB = default_BSUB_config()
# More informative job ID
custom_BSUB$`-J` = "bwa_aligner"
# A token for a project allowed to run on the cluster
custom_BSUB$`-P` = "DKSMWOP331"
# A queue name that is valid on the cluster
custom_BSUB$`-q` = "bioinformatics"
print(custom_BSUB)
# Shorter version
custom_BSUB = default_BSUB_config(J = 'bwa_aligner', P = 'DKSMWOP331', q = 'bioinformatics')
print(custom_BSUB)
```
Once the BSUB has been customized, you can either:
- generate the submission scripts, and submit your job manually
- generate the submission scripts and submit the jobs with a `system` call.
By default (`run = FALSE`) the `run_lsf` function outputs the shell command that should be used to submit the jobs, but leaves the user to submit the job. This is because we experienced some command line issues calling
modules with a system call.
#### Example
An example computation follows.
```{r, eval=T}
# A simple function that prints some outputs
FUN = function(x, y){
print(x, y)
}
# input for 25 array jobs
PARAMS = data.frame(
x = runif(25),
y = runif(25)
)
# generates the input files, adding some module dependencies
run_lsf(FUN,
PARAMS,
BSUB_config = custom_BSUB,
modules = 'R/3.5.0'
)
```
#### Submitting the job
If you do not try to run it automatically, command `bsub < EASYPAR_LSF_submission.sh` will submit the jobs to the cluster.