RGalaxy

丹特南鲍姆

星系是一个开放的，基于网络的数据密集型生物医学研究平台。它提供了一个易于使用的web界面，并可以公开用任何编程语言编写的生物信息学工作流程。

通常，为了在一个Galaxy实例中公开新功能(Galaxy术语中的工具)，您必须手动创建一个XML文件，其中包含关于该功能的信息，并修改一个额外的XML文件。

的RGalaxy包自动执行此过程，从函数本身及其手册页中提取大部分必要的信息(将其余信息作为参数提供给星系功能)。

一个简单的例子

假设您想要创建一个用于添加两个数字的Galaxy工具。

首先,负载RGalaxy：

库(RGalaxy)

然后写一个这样的函数:

addTwoNumbers <- function(number1=GalaxyNumericParam(required=TRUE)， number2=GalaxyNumericParam(required=TRUE)， sum=GalaxyOutput("sum"， "txt")) {cat(number1 + number2, file=sum)}

关于这个函数有几点需要注意:

每个参数的数据类型是指定的。而不仅仅是具体说明R的数字类型，我们正在使用一个特殊的类GalaxyNumericParam．这是因为银河(不像R)需要知道每个参数的类型，以及其他信息
函数名是描述性的。
函数的返回值并不重要。
函数的所有输入和输出都在其签名中作为参数指定。Galaxy通过向工具发送文件并读取它们生成的文件来与它们通信，这是必需的。
默认情况下，Galaxy将参数标记为不需要。添加要求= TRUE告诉Galaxy不允许空值。
这个函数可以在R中运行，通过普通方式传递给它数字价值观:

t <- tempfile() addTwoNumbers(2,2, t) readLines(t, warn = FALSE)

##[1]“4”

记录示例

我们几乎已经准备好告诉Galaxy我们的功能，但首先我们需要用手册页记录它。RGalaxy将使用本页中的信息来创建Galaxy工具，并且手册页对于想要在其中运行您的函数的任何人也很有用R．

手册页可能是这样的:

\name{addTwoNumbers} \alias{addTwoNumbers} \title{添加两个数字}\description{一个可以成为Galaxy工具的示例函数。取两个数字，将它们相加，并返回包含结果的文件。} \usage{addTwoNumbers(number1=GalaxyNumericParam(required=TRUE)， number2=GalaxyNumericParam(required=TRUE)， sum=GalaxyOutput("sum"， "txt"))} \arguments{\item{number1}{第一个要添加的数字}\item{number2}{第二个要添加的数字}\item{sum}{添加结果写入的位置。}} \value{invisible(NULL)} \seealso{\code{\link{galaxy}}， \code{\link{GalaxyConfig}}， \code{\link{GalaxyOutput}}， \code{\link{addTwoNumbers}} \examples{t <- tempfile() addTwoNumbers(2,2, t) readLines(t, warn=FALSE)}

关于这个手册页需要注意的一些事情:

的的名字，别名，描述，标题，使用,参数章节是必需的。的细节节不是必需的，但鼓励使用(RGalaxy如果此部分缺失，将通知您)。
虽然有一个很好的例子节，此节只对运行函数的人有用R．不使用此节RGalaxy．

安装星系

在告诉Galaxy我们的功能之前，我们必须安装Galaxy。

的Galaxy安装页面给出了完整的说明，但简单地说，你可以按照以下方法安装Galaxy(你可能需要安装水银，它提供hg命令):

Hg克隆https://bitbucket.org/galaxy/galaxy-dist/

刚刚安装Galaxy的目录(以。结尾的完整路径)galaxy-dist)是您的“Galaxy Home”目录，由galaxyHome在下面的代码片段中。

告诉Galaxy这个功能

现在我们将Galaxy指向我们刚刚写的函数:

galaxy("addTwoNumbers"， galaxyConfig= galaxyConfig (galaxyHome， "mytool"， "Test Section"， "testSectionId"))

##警告:没有足够的信息来创建功能测试。

##注意:在手册页中没有找到“详细信息”部分。

## [1] "/tmp/RtmpFw6xY7/Rbuild23da15a19787/RGalaxy/vignettes/tools/mytool/ addtwonnumbers .xml"

注意关于功能测试的警告。我们将在稍后的小插图中介绍这一点。

的星系函数通知您细节手册页的部分为空。它还返回它创建的XML工具包装器的路径。

在Galaxy中运行示例函数

要启动Galaxy，打开一个命令窗口并更改到Galaxy主目录(前面定义的)。然后发出这个命令:

。/ run.sh重载

如果Galaxy已经在运行，您应该停止它(使用control-C)并使用上面的命令重新启动它。操作后，应始终重新启动Galaxy星系函数。

你现在可以通过http://localhost:3000．

如果您单击“Test Section”，然后单击“Add Two Numbers”，您应该会看到类似图1的内容。

银河的两个数字相加工具

注意事项:

RGalaxy生成了一个工具，其中每个参数都有一些来自手册页的解释性文本。
工具名(“Add Two Numbers”)来自函数名(这可以通过传递重写的名字来星系()）.
如果您尝试输入一个非数字，银河将投诉。这是因为我们指定了GalaxyNumericParam在函数中。
如果你试图让任何一个数字空白，银河将投诉。这是因为我们指定了要求= TRUE．

如果我们输入10和5，然后点击“执行”，Galaxy将运行，完成后将在右侧的历史窗格中显示“sum.txt”。单击它应该会显示如图2所示的内容。你可以下载结果或发送到另一个Galaxy工具。

两个数字相加的结果

功能测试

我们只是运行了Galaxy并确保我们的工具能够正常工作。这将是一个很好的自动化过程，这样我们就可以知道输入x而且y，我们的工具总是会产生输出d．

通过一些小的添加，我们可以实现这一点。我们的函数将有一个独立的测试。

此外，在向公共Galaxy实例提交工具时，还需要这样的功能测试。

这是我们的addTwoNumbers再次使用函数，这次是功能测试:

addTwoNumbersWithTest <- function(number1=GalaxyNumericParam(required=TRUE, testValues=5L)， number2=GalaxyNumericParam(required=TRUE, testValues=5L)， sum=GalaxyOutput("sum"， "txt")) {cat(number1 + number2, file=sum)}

唯一明显的区别是我们增加了atestValues参数赋给每个输入参数。另一个微妙的区别是，我们在包中添加了一个名为本月/ functionalTests / addTwoNumbersWithTest /求和，其中包含函数的预期输出。通过使用这个约定，我们可以确保RGalaxy可以找到这个文件。

该功能是否通过了功能测试?

runFunctionalTest (addTwoNumbersWithTest)

##[1]真

注意，这只是运行函数R在美国，它不会在运行中的银河系中测试。而是因为功能测试基础结构呈现在由RGalaxy，你可以从你的Galaxy主目录，如下所示:

./run_functional_tests.sh -id addTwoNumbersWithTest .sh

测试的输出将被写入run_functional_tests.html．

请注意,R并不总是每次产生相同的输出，即使文件可能看起来相同。的pdf函数可能会产生不同的文件。您可以使用png作为一个变通方案。

我的函数应该放在一个包中吗?

到目前为止我们已经忽略了，但是addTwoNumbers ()函数及其手册页存在一个包RGalaxy在这种情况下包装)。在Galaxy中可以暴露一个不在包中的函数，但必须提供大量额外的信息。我们建议您公开的函数存在于包中(并在您的NAMESPACE文件中导出)。

最佳实践

如果您的函数依赖于其他包，请使用图书馆()在你的职责范围内。
您的代码应该使用该函数处理不正确的输入和其他错误情况gstop ()．Galaxy用户将看到错误消息。也使用gwarning ()而且gmessage ()用于警告和信息消息。

使用reserve获得更好的性能

Galaxy通过在命令行上调用各种语言的脚本来运行工具。这些脚本通常是自包含的。有时脚本需要很长时间才能加载依赖项。有时，这比脚本应该执行的实际工作要长。的远程实例，则可以停止等待脚本加载其依赖项R其中已经加载了依赖项。我们使用Rserve包中。

使用Rserve，创建Rserv.conf包含如下语句的文件:

(2) LongLoadingPackage2

将包名替换为函数使用的加载时间较长的包。

开始预留如下:

R CMD Rserve——vanilla——RS-conf Rserv.conf

在你的函数上重新运行Galaxy，指定应该使用Rserv:

galaxy("addTwoNumbersWithTest"， galaxyConfig= galaxyConfig (galaxyHome， "mytool"， "Test Section"， "testSectionId")， RserveConnection=RserveConnection())

安装RSclient包:

来源(“//www.anjoumacpherson.com/biocLite.R”)biocLite(“RSclient”，siteRepos =“http://www.rforge.net”)

重新启动Galaxy，如果它已经在运行。你的函数应该快得多。

方法将此信息传递给Rserve，可以在不同的机器上(和不同的端口上)运行RserveRserveConnection ()功能:

RserveConnection(host = "mymachine"， port = 2012L)

## RserveConnection类的对象## Slot "host": ## [1] "mymachine" ## ## Slot "port": ## [1] 2012

注意，另一台机器应该与运行Galaxy的机器共享磁盘空间。

一个实际的例子

假设您有一些Affymetrix探测id，并且希望为它们查找PFAM和符号名称。在Galaxy中编写一个函数来公开这一点非常简单:

probeLookup <- function(probe_ids=GalaxyCharacterParam(required=TRUE, testValues="1002_f_at 1003_s_at")， outputfile=GalaxyOutput("probeLookup"， "csv")) {suppressPackageStartupMessages(library(hgu95av2.db)) ids <- strsplit(probe_ids， " ")[[1]] results <- select(hgu95av2.db, keys=ids, columns=c("SYMBOL"，"PFAM")， keytype="PROBEID") write.csv(results, file=outputfile)}

在幕后，我们还为该函数编写了一个手册页，并在我们的包中放置了一个测试fixture(可以在本月/ functionalTests probeLookup / outputfile）.

让我们运行它，确保它工作:

runFunctionalTest (probeLookup)

##[1]真