Comment on page
Scripts
Scripts are defined in the Scripts plugin and can be reused, e.g. as part of reports. By default you can find it in the menu under Plugins, Scripts. The Scripts plugin allows you to create, edit and delete the available scripts.
You open the script editor by clicking the "New script" button.
- Name: The name uniquely identifies the script
- Type: The script type determines how the script is executed.
- R scripts are executed in R
- Python scripts are executed in Python
- Magma JavaScript and JavaScript scripts are executed in a JavaScript context
- Script: The actual script content goes here.
- Result file extension: Allows you to render output in your script. For instance, if you set this to
png, the script will be provided with a parameteroutputFile. You can write your png image to this file. When the script is done, the contents of the file will be served as a result of the script invocation request. - Generate security token: Allows you to use
${molgenisToken}in the script for authentication.
If your Type is R, JavaScript or Python, the Script Content is interpreted as a Freemarker template. The parameters are provided as Freemarker variables. You can render them in the script by typing
${parameter}, but the full Freemarker syntax is at your disposal, so for instance <#if><#else><#/if> constructs are also available.This means that if you want to initialize an R or Python string variable with the value of a parameter string, you'll need to explicitly encapsulate it with quotes.
So in R:
# Assign string parameter
name <- "${name}"
# Assign numeric parameter
amount <- ${amount}
And in Python:
# Assign string parameter
name = "${name}"
# Assign numeric parameter
amount = ${amount}
And in JavaScript:
// Assign string parameter
var name = "${name}"
// Assign numeric parameter
var amount = ${amount}
The script template will be rendered to a file in the File Store and this file will be interpreted using the R or Python interpreter.
If your Type is Magma JavaScript, the parameters are available through Magma's $ selector method. JavaScript will have to do the type conversions for you. Or if you want to be sure, you should cast the values explicitly
// Assign string parameter
var name = $("name")
// Assign numeric parameter
var amount = int($("amount"))
Your script can access data inside a MOLGENIS repository through the APIs. If the data is private data, you can set Generate Security Token to Yes. Then a molgenis security token will be generated for the user running the script and added as a parameter named
molgenisToken. You can pass the token on to the REST API.Pass the token as a parameter when you request the molgenis.R api script:
library('RCurl')
eval(expr = parse(text = getURL("https://molgenis01.target.rug.nl/molgenis.R?molgenis-token=${molgenisToken}")))
molgenis.get("MolgenisUser")
You can run your script by pressing the "Run" button. If the script has parameters, you'll be presented with a popup form to specify them.
You can also run the script through an HTTP request. For instance, to run the
bmi script with parameters weight=50 and height=1.60 on server http://molgenis09.target.rug.nl you can surf to https://molgenis09.target.rug.nl/scripts/bmi/run?weight=50&height=1.60Beware that you need to URL-encode parameter values if they contain special characters
Note that in order to execute scripts, users need
- to be authenticated (i.e. anonymous users cannot execute your scripts)
- View permissions on the Scripts entity
- View permissions on the ScriptParameter entity
- View permissions on the ScriptType entity
Let's take the R script from the previous example and add it to the Script plugin. The script will fetch the public ASE data from https://molgenis56.target.rug.nl/
You'll need a running instance of MOLGENIS. So either run this example locally on your own MOLGENIS instance or Sign Up on our demo server https://molgenis09.target.rug.nl/
Go to the Script plugin and create a new script.
- Name: Any name will do, as long as it's unique. Since the result will be a plot of Allele-Specific Expression for a SNP, we suggest the name
plot-ase. - Type: We're creating an R script, so pick
R. - Generate security token: No, since the data is publicly available and lives on a different server anyways.
- Result file extension: R can plot postscript, pdf, png and jpeg. Let's pick
png. - Content:
library('RCurl')
library('methods')
library('bitops')
eval(expr = parse(text = getURL("https://molgenis56.target.rug.nl/molgenis.R")))
samples <- molgenis.get("SampleAse", q="SNP_ID==${snp_id}")
jpeg('${outputFile}')
max <- max(samples$Ref_Counts, samples$Alt_Counts)
plot(samples$Ref_Counts, samples$Alt_Counts, xlim = c(0, max), ylim = c(0, max), xlab='Reference Allele', ylab='Alternative Allele', main = 'Allele-Specific Expression for ${snp_id}')
lines(c(0,max), c(0, max))
dev.off()
Note: If you are running this on localhost you might have to install the following packages through Rstudio/R command line;
- install.packages('rjson');
- install.packages('RCurl');
- install.packages('methods');
Let's take a closer look at what happens here.
First we fetch and source the MOLGENIS R API from molgenis56. This means it'll be set up to retrieve its data from molgenis56.
Then we retrieve the samples using
molgenis.get.The
snp_id parameter gets filled in into the rsql query q. So if for instance snp_id equals rs2287988, Freemarker will fill the parameter in where it says ${snp_id} so the query becomes q="SNP_ID==rs2287988".The outputFile parameter gets filled in into
jpeg('${outputFile}') so that R plots to the correct output file.In the previous example we manually set the axes to
c(0, 5000), but here the amount of reads depends on the chosen SNP. So we compute the maximum amount of reads in both the Ref_Counts and Alt_Counts attributes of the samples dataframe.Next we create the scatter plot and the reference line, like we did before. Note how we use the
snp_id parameter a second time, to render the plot title.Save the script.
Push the "Run" button.
In the popup, specify the value for
snp_id, for example rs2287988.Click on "Run".
image
The URL to do this is "[MOLGENIS_SERVER]/scripts/{scriptname}/submit". A Json object containing a map of parameters used by the script should be provided.
The server will return a href to the jobExecution of the the scheduled ScriptJob, which can be used to poll the status or get the link to the result of the script.
Last modified 3yr ago