synapseExecute: Execute Code and Upload Results to Synapse

In Sage-Bionetworks/rSynapseClient: Synapse R Client from Sage Bionetworks

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

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=<repository name>, sourceFile=<source File>). 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 <codeParentId>/<githubrepo>/<commit>/<filepath>.

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.

Value

The Synapse Entity containing the result.

Author(s)

Bruce Hoff <[e-mail]>

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)

Sage-Bionetworks/rSynapseClient documentation built on May 9, 2019, 7:04 p.m.