annotate macros.xml @ 2:495946ffc2d6 draft default tip

planemo upload for repository https://github.com/mvdbeek/docker_scriptrunner/ commit dded837d19aeb3f06b84e5076282cedeeaf713fa

<macro>
    <xml name="help_macro">
    <help>
.. class:: warningmark

**Details and attribution** Docker_toolfactory_

**If you find a bug** please raise an issue at the bitbucket repository Issues_

**What it does** This tool enables a user to paste and submit an arbitrary R/python/perl script to Galaxy.

**Input options** This version is limited to simple transformation or reporting requiring only a single input file selected from the history.

**Output options** Optional script outputs include one single new history tabular file, or for scripts that create multiple outputs,
a new HTML report linking all the files and images created by the script can be automatically generated.

.. class:: warningmark

**Note to system administrators** This tool uses docker containers as protection against malicious scripts. It should only be installed on private/personnal Galaxy instances.

.. class:: warningmark

**Use on public servers**  is STRONGLY discouraged for obvious reasons

The tools generated by this tool will run just as securely as any other normal installed Galaxy tool but like any other new tools, should always be checked carefully before installation.
We recommend that you follow the good code hygiene practices associated with safe toolshed.

**Scripting conventions** The pasted script will be executed with the path to the (optional) input tabular data file path or NONE if you do not select one, and the path to the optional
output file or None if none is wanted, as the first and second command line parameters. The script must deal appropriately with these - see Rscript examples below.
Note that if an optional HTML output is selected, all the output files created by the script will be nicely presented as links, with pdf images linked as thumbnails in that output.
This can be handy for complex scripts creating lots of output.

**Examples**
<![CDATA[

Each of these following trivial examples can be cut and pasted into the script box for testing.
Please make sure you choose the appropriate interpreter and upload and select a suitable small matching test data input

A simple Rscript "filter" showing how the command line parameters can be handled, takes an input file, does something (transpose in this case) and 
writes the results to a new tabular file. Note the use of colClasses to ensure that no fiddling takes place with numeric values by treating everything
as a string::

 # transpose a tabular input file and write as a tabular output file
 ourargs = commandArgs(TRUE)
 inf = ourargs[1]
 outf = ourargs[2]
 inp = read.table(inf,head=F,row.names=NULL,sep='\t',colClasses="character")
 outp = t(inp)
 write.table(outp,outf, quote=FALSE, sep="\t",row.names=F,col.names=F)

Calculate a multiple test adjusted p value from a column of p values - for this script to be useful, it needs the right column for the input to be specified in the code for the
given input file type(s) specified when the tool is generated ::

 # use p.adjust - assumes a HEADER row and column 1 - please fix for any real use
 column = 1 # adjust if necessary for some other kind of input
 ourargs = commandArgs(TRUE)
 inf = ourargs[1]
 outf = ourargs[2]
 inp = read.table(inf,head=T,row.names=NULL,sep='\t')
 p = inp[,column]
 q = p.adjust(p,method='BH')
 outp = cbind(inp,'BH Adjusted p-value'=q)
 write.table(outp,outf, quote=FALSE, sep="\t",row.names=F,col.names=T) 


A demonstration Rscript example takes no input file but generates some random data based pdf images
You must make sure the option to create an HTML output file is
turned on for this to work. Images (pdf) are linked via thumbnails and
all files have a link on the resulting HTML page::

 # note this script takes NO input or output because it generates random data
 for (i in 1:10) {
    foo = runif(100)
    bar = rnorm(100)
    bar = foo + 0.05*bar
    pdf(paste('yet',i,"anotherplot.pdf",sep='_'))
    plot(foo,bar,main=paste("Foo by Bar plot #",i),col="maroon", pch=3,cex=0.6)
    dev.off()
    foo = data.frame(a=runif(100),b=runif(100),c=runif(100),d=runif(100),e=runif(100),f=runif(100))
    bar = as.matrix(foo)
    pdf(paste('yet',i,"anotherheatmap.pdf",sep='_'))
    heatmap(bar,main='Random Heatmap')
    dev.off()
 }

# A slight variation taking an input tabular file from which we read the first number as nreps
# his script takes a single parameter  
# number of replicates  

.. code-block:: R  

  ourargs = commandArgs(TRUE)
  infname = ourargs[1]
  nreps = read.table(infname,head=F)
  nreps = unlist(nreps)[1]
  nreps = max(c(1,nreps))
  nreps = min(c(20,nreps))
  print(paste("Using nreps=",nreps))
  for (i in 1:nreps) {
     foo = runif(100)
     bar = rnorm(100)
     bar = foo + 0.2*bar
     pdf(paste("yet",i,"anotherplot.pdf",sep="_"))
     plot(foo,bar,main=paste("Foo by Bar plot ",i),col="maroon", pch=3,cex=0.6)
     dev.off()
     foo = data.frame(a=runif(100),b=runif(100),c=runif(100),d=runif(100),e=runif(100),f=runif(100))
     bar = as.matrix(foo)
     pdf(paste("yet",i,"anotherheatmap.pdf",sep="_"))
     heatmap(bar,main="Random Heatmap")
     dev.off()
  }
 
A Python example that reverses each row of a tabular file (you'll need to remove the leading spaces 
for this to work if cut and pasted into the script box)::

 # reverse order of columns in a tabular file
 import sys
 inp = sys.argv[1]
 outp = sys.argv[2]
 i = open(inp,'r')
 o = open(outp,'w')
 for row in i:
     rs = row.rstrip().split('\t')
     rs.reverse()
     o.write('\t'.join(rs))
     o.write('\n')
 i.close()
 o.close()
 
A trivial shell script example to show that it works::

 #!/bin/bash
 INF=$1
 OUTF=$2
 cut -c2,4,6,8,10,12 $INF > $OUTF 

A trivial perl script example to show that even perl works::

 #
 # change all occurances of a string in a file to another string
 #
 $oldfile = $ARGV[0];
 $newfile = $ARGV[1];
 $old = "gene";
 $new = "foo";
 open(OF, $oldfile);
 open(NF, ">$newfile");
 # read in each line of the file
 while ($line = <OF>) {
    $line =~ s/$old/$new/;
    print NF $line;
 }
 close(OF);
 close(NF);

]]>

**Citation**


Paper_ :

Creating re-usable tools from scripts: The Galaxy Tool Factory
Ross Lazarus; Antony Kaspi; Mark Ziemann; The Galaxy Team
Bioinformatics 2012; doi: 10.1093/bioinformatics/bts573


**Licensing** 

Copyright Ross Lazarus (ross period lazarus at gmail period com) May 2012
All rights reserved.
Licensed under the LGPL_

.. _LGPL: http://www.gnu.org/copyleft/lesser.html
.. _Docker_toolfactory:  https://bitbucket.org/mvdbeek/dockertoolfactory
.. _Issues:  https://bitbucket.org/mvdbeek/dockertoolfactory/issues
.. _Paper: http://bioinformatics.oxfordjournals.org/cgi/reprint/bts573?ijkey=lczQh1sWrMwdYWJ&amp;keytype=ref

    </help>
<citations>
  <citation type="doi">10.1093/bioinformatics/bts573</citation>
</citations>
    </xml>
    <xml name="test_data_macro">
    </xml>
</macro>