view README.txt @ 14:6f36c696afa5

readme adjustments

**WARNING before you start** This tool should only ever be installed on a private Galaxy instance - Please NEVER use it on a public 
Galaxy because the risks are too awful to contemplate let alone manage. You have been warned.

**Motivation** Simple transformation, filtering or reporting scripts get written, run and lost every day in most busy labs 
- even ours where Galaxy is in use. This 'dark script matter' is pervasive and generally not reproducible.

**Benefits** For our group, this allows Galaxy to fill that important dark script gap - all those "small" bioinformatics 
tasks. Once a user has a working R (or python or perl) script that does something Galaxy cannot currently do (eg transpose a 
tabular file) and takes parameters the way Galaxy supplies them (see example below), they:

1. Install the tool factory on a personal private instance

2. Upload a small test data set

3. Paste the script into the 'script' text box and iteratively run the insecure tool on test data until it works right - 
there is absolutely no reason to do this anywhere other than on a personal private instance. 

4. Once it works right, set the 'Generate toolshed gzip' option and run it again. 

5. A toolshed style gzip appears ready to upload and install like any other Toolshed entry. 

6. Upload the new tool to the toolshed

7. Ask the local admin to check the new tool to confirm it's not evil and install it in the local production galaxy

**What it does** This tool enables a user to paste and submit an arbitrary R/python/perl script to Galaxy. 
New mantra: Galaxy can efficiently soak up all your lab's dark script matter and make it reproducible and shareable.


**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.

**Tool Generation option** Once the script is working with test data, this tool will optionally generate a new Galaxy tool 
in a gzip file ready to upload to your local toolshed for sharing and installation.

**Permission to to use this tool** must be explicitly granted by an administrator adding approved Galaxy user IDs to the local tool XML list of permitted users.  *It will not run otherwise*

**Note to system administrators** This tool offers *NO* built in protection against malicious scripts and should only be installed on private/personnal Galaxy instances.
Under no circumstances should you allow any user to use this tool unless you really, really trust them with the power to do what they want as the Galaxy user.

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.

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

**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.

**Simple examples**

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::

 # 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')
 outp = t(inp)
 write.table(outp,outf, quote=FALSE, sep="\t",row.names=F,col.names=F)

A more complex Rscript example takes no input file but generates a random heatmap pdf - you must make sure the option to create an HTML output file is
turned on for this to work. The heatmap will be presented as a thumbnail linked to the pdf in the resulting HTML page::

 # note this script takes NO input or output because it generates random data
 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( "heattest.pdf" )
 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. Note that you can already do this in Galaxy by setting up the cut columns tool with the
correct number of columns in reverse order,but this script will work for any number of columns so is completely generic::

 # 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()
 

**Attribution** Copyright Ross Lazarus (ross period lazarus at gmail period com) May 2012

All rights reserved.

Licensed under the LGPL_


**Obligatory screenshot**
http://bitbucket.org/fubar/galaxytoolmaker/src/fda8032fe989/images/dynamicScriptTool.png