= User stories for using R within the Compute module =
[[TOC()]]
Authors: Danny, Morris, Joeri

== User story: adding an R script ==

How to demo:

Within the user interface you can choose [!ComputeProtocol] and then choose [New].
Then you can give the compute protocol a name, set the type to 'R' and in a text box copy your R script.

For example:

||Name ||!OneTraitQtlMapping ||
||Interpreter ||R ||
||Script ||{{{//I just create any script that works with my parameters}}}[[BR]]{{{genotypes <- getFromDb(genotypes_name)}}}[[BR]]{{{phenotypes <- getFromDb(phenotype_name)}}}[[BR]]{{{onetraitqtlmapping(trait_names, genotypes, phenotypes)}}}||

Next you define the parameters that you have in your script, which are 'traitname' and 'datasetname' and 'iteration'.
These are can be described using ComputeFeature, where we define them as follows:

||'''Name''' ||'''Datatype''' ||'''Description''' ||
||traitnames ||List(String) ||This is a list of trait names such as defined in your data set. For example 'height' or 'probe01' ||
||genotypes_name ||xref(Data) ||This a lookup in the list of available Data so the user can choose the genotypes (implicitly links to map ||
||phenotype_name ||xref(Data) ||This is a lookup in the list of available Data so the user can choose the phenotypes ||
||results_name ||String ||This is the name of the new data set that will be created to store the data in (or if it exists, data will be added to it ||

== User story: running an R script ==

How to demo:

Within the user interface you can choose [Run analyses]. Here you can browse the list of available compute protocols. For example, lets choose the protocol that we defined in the previous user story. Then you are provided with autogenerated input boxes based on the ComputeFeature that you defined; We fill in the parameters:

||traitnames ||height,length ||
||genotypes_name ||geno ||
||phenotypes_name || classic ||
||results_name ||My phenotype qtl profiles ||

And push [Next].

Automatically a new !ComputeApplication is generated that looks as follows. 

script = 
{{{
//sources useful scripts to interact with MOLGENIS
source("path/your/molgenis/instance/source.R")

//autogenerated by MOLGENIS based on your parameters
traitnames <- c("height","length")
genotypes_name <- "geno"
phenotypes_name <- "classic"
results_name <- "My phenotype qtl profiles" //spaces will be removed when storing as file...

//also this includes some useful system parameters
dbPath <-  "xyz"

//here the script as we defined above is copied for full provenance
onetraitqtlmapping(trait_names, genotypes_name, phenotypes_name)

}}}

Notice how the parameters are simply passed at the beginning of your script.
This means you can just copy-paste this script in you R terminal and it should work there as well as on the cluster (ideal for testing)!

If you again push [[NEXT]] this job will be sent to Job manager (user story TODO).

== User story: using R to define large scale analyses ==

How to demo:

Within the user interface you repeat user story on 'adding an R script'. Goal now is to make a script uses MOLGENIS job submission API to automatically calculate qtl profiles on all our phenotypes. We again choose [New !ComputePrococol] and add a script that looks like the following: 

{{{
//here our script will use the job submission API so you can run many R scripts
for(i in 1:number_of_jobs)
{
        //cut out a subset of the phenotypes
        selectedNames <- sliceList(i,number_of_jobs)

        //define what other job MOLGENIS should call 
	submitJob(command="onetraitqtlmapping", genotypes_name=genotypes_name, phenotypes_name=phenotypes_name, traitnames=selectedNames);

	//Note: all parameters you pass to submitJob will be automatically passed to the other protocol
	//result is that a new "computeapplication" will be created programmatically instead of via the UI to be sent to the cluster
}
}}}

Note how we replaced "trait_names" with "number_of_jobs" because we just want to run all phenotypes :-)

||'''Name''' ||'''Datatype''' ||'''Description''' ||
||genotypes_name ||xref(Data) ||This a lookup in the list of available Data so the user can choose the genotypes (implicitly links to map ||
||phenotype_name ||xref(Data) ||This is a lookup in the list of available Data so the user can choose the phenotypes ||
||results_name ||String ||This is the name of the new data set that will be created to store the data in (or if it exists, data will be added to it ||
||number_of_jobs ||Integer ||This will determine how the phenotype dataset will be split in jobs; should be 1 or larger. ||


>>Discussion: we could even decide here to generate a whole R script and pass that as the command. How cool would that be? Than the other protocol doesn't even have to exist in the database.