synapseClient (version 1.14-0)

synapseExecute: Execute Code and Upload Results to Synapse

Description

Function for executing code, uploading results, and creating a provenance record in Synapse

Usage

synapseExecute(executable, args, resultParentId, codeParentId, resultEntityProperties,  resultEntityName, replChar=".")

Arguments

executable

a function, file, or github reference

args

a list of arguments passed to the function via 'do.call'

resultParentId

the Synapse ID of the project or folder in which the result entity is created

codeParentId

the Synapse ID of the project or folder in which the executed code is placed

resultEntityProperties

an optional list of named values to be added to the result entity as annotations

resultEntityName

the name for the result entity

replChar

an optional replacement character used when 'scrubbing' illegal characters from entity names. Default is "."

Value

The Synapse Entity containing the result.

Details

Executable may be one of the following:

• a function defined in the current session.
• a file on the local file system, including its full path and ending in ".R"
• a Github Repository reference in the form of list(repoName=, sourceFile=). The repo name is of the form /owner/reponame. The source file is the full path to the R source file.

A Code entity is created for the given Code. If there is an existing Code entity in the target Synapse location (described below), and if the code file differs from the existing, then a new revision of the existing Code entity is created. If the Code entity is a file or an in-memory function, then then the Code entity created is placed in the folder or project given by codeParentId parameter. If the Code entity is a file, then then the Code entity created is named using the file path of the code file. If the Code entity is a github reference then an entity hierarchy is created under the folder/project given by codeParentId having the structure ///. The if the code is in a (local or github) file, the file is loaded. Since a Code file can contain multiple functions, synapseExecute disambiguates the function to call as follows: If there's just one function, that is the one called. If there are multiple functions and one is named according to the containing file, that is the one called. Otherwise, synapseExecute stops. An Activity (provenance record) is created which 'generates' the output entity and whose 'used' entities are (1) the aforementioned Code object, (2) any Synapse entities included in args. The args and resultEntityProperties lists are added as annotations of the result entity. The result entity is created in the given parent project/folder and having the given name. If such an entity already exists then a new revision of the entity is created.

Examples

## Not run: 
#   ## execute code in a local file
#   resultEntity <- synapseExecute(
#   		executable="/path/to/file.R", 
#   		args=list(x=1, y="syn102987"), 
#   		resultParentId="syn123456", 
#   		codeParentId="syn987654", 
#   		resultEntityProperties=list(a="foo", b="bar),  
#   		resultEntityName="exampleOutput")
#   
#   ## execute code in Github
#   resultEntity <- synapseExecute(
#   		executable=list(repoName="/githubUser/ProjectRepo", sourceFile="path/to/file.R"), 
#   		args=list(x=1, y="syn102987"), 
#   		resultParentId="syn123456", 
#   		codeParentId="syn987654", 
#   		resultEntityProperties=list(a="foo", b="bar),  
#   		resultEntityName="exampleOutput")
# ## End(Not run)