...
Code Block |
---|
# we use 'synapseStore=F' to indicate that we only wish to link file <- File(path="file:///corporatenfs/sharedproject/genotypedata.csv", synapseStore=F, name="genotypedata", parentId`Id=pid) # Synapse stores the metadata, but does not upload the file file <- synStore(file) # Now assume a new session, perhaps by a different user # synGet downloads the file to a default location fileId<-"synXXXXX" # we use 'downloadFile=F' to indicate that we do not need a new copy on our local disk file <-synGet(fileId, downloadFile=F) getFileLocation(file) > "/corporatenfs/sharedproject/genotypedata.csv" # now change the meta data and save synAnnot(file, "data type")<-"SNP" # since the File was created with "synapseStore=F", synStore does not upload the file file<-synStore(file) |
...
Command | comments | R Syntax | Python Syntax | Command Line Syntax |
---|---|---|---|---|
1 – Common functions | ||||
Create a Synapse file handle in memory, specifying the path to the file in the local file system, the name in Synapse, and the Folder in Synapse. This step 'stages' a file to be sent to Synapse. Additional parameters (...) are interpreted as properties or annotations, in the manner of synSet(), defined below. If 'synapseStore' is TRUE then file is uploaded to S3, else only the file location is saved. | The specified file doesn't move or get copied. | File(path, parentId, synapseStore=T, ...)
example: File(path="/path/to/file", parentId="syn101") | File(path, parentId, synapseStore=T, **kwargs)
example: File('/foo/baz/bar.txt', 'syn123') | NA |
Create a Synapse file handle in memory which will hold a serialized version of one or more in-memory object. Additional parameters (...) are interpreted as properties or annotations, in the manner of synSet(), defined below. If 'synapseStore' is TRUE then file is uploaded to S3, else only the file location is saved. | The object is not serialized at this time. (We are hoping people will like calling the object a File, even though it's a collecton of in-memory objects.) | File(parentId)
example: file<-File(parentId="syn101") file<-addObject(file, obj)
| Will not be implemented in python. | NA |
Create a Synapse Record in memory, specifying the name and the Folder in Synapse. This step 'stages' a Record to be sent to Synapse. Additional parameters (...) are interpreted as properties or annotations, in the manner of synSet(), defined below.
| Files aren't moved or copied. TODO: How do you specify file annotations (as distinct from Strings)? Shall we introduce in-memory wrappers around files and urls to help distinguish them? | Record(name=NULL, parentId="syn101", ...) example: | Record(name="foo", parentId="syn101", **kwargs) | |
Create a Folder or Project in memory. Name and parentId are optional. | Folder(name=NULL, parentId=NULL, ...) Project(name=NULL, ...) example: | Folder(name="foo", parentId="syn101", **kwargs) Project(name="foo", **kwargs) | ||
Set an entity's attribute (property or annotation) in memory. Client first checks properties, then goes to annotations; (setting to NULL deletes it in R, using DEL operator in python deletes it) | TODO: we want to include files and (for R) in memory objects | synAnnot(entity, name)<-value | entity.parentId="syn101" | synapse update id --parentId syn101 |
Gets an entity's attribute value (property or annotation) from the object already in memory. | synAnnot(entity, name); returns NULL if undefined | entity.name; throws exception if value is undefined | ||
Create or update an entity (File, Folder, etc.) in Synapse. May also specify (1) the list of entities 'used' to generate this one, (2) the list of entities 'executed' to generate this one, (3) the name of the generation activity, and (4) the description of the generation activity, (5) whether a name collision in an attempted 'create' should become an 'update', (6) whether to 'force' a new version to be created, and (7) whether the data is restricted (which will put a download 'lock' on the data and contact the Synapse Access and Compliance team for review. | TODO: Give some examples. | synStore(entity, used=NULL, executed=NULL, activityName=NULL, activityDescription=NULL, createOrUpdate=T, forceVersion=T, isRestricted=F)
synStore(entity, activity=NULL, createOrUpdate=T, forceVersion=T, isRestricted=F) | synapse.store(entity, used, executed, activityName=None, activityDescription=None, createOrUpdate=T, forceVersion=T, isRestricted=F)
synapse.store(entity, activity, createOrUpdate=T, forceVersion=T, isRestricted=F) | synapse create --name NAME --parentid PARENTID --description DESCRIPTION --type TYPE --file PATH --update=T/F --forceVersion=T/F
--annotations={foo=bar, bar=foo} |
Get an entity (file, folder, etc.) from the Synapse server, with its attributes (properties, annotations) and, optionally, with its associated file(s). if.collision is one of "keep.both", "keep.local", or "overwrite.local", telling the system what to do if a different file is found at the given local file location. | 'download' and 'load' are ignored for objects other than Files. If a downloadLocation is not provided a default, read-only cache location is used. If a downloadLocation IS provided, then the client must handle collisions with existing files. Note, 'downloadLocation' must be a directory. | synGet(id, version, downloadFile=T, downloadLocation=NULL, ifcollision="keep.both", load=F) | synapse.get(id, version, downloadFile=True, downloadLocation=None, ifcollision="keep.both", load=False) | synapse get ID -v NUMBER |
Get the downloaded location of the file associated with a File object. | If synGet was called with download=FALSE, this returns NULL. | getFileLocation(file) | TODO: Why not access it as a property of the entity the way it is currently done? | TODO |
Trash an entity, and all of its children (move all Folders and Files within a Folder to the trash can). | synTrash(id) / synTrash(entity) | synapse.trash(id) | synapse trash id | |
Open the web browser to the page for this entity. | onWeb(entityId) / onWeb(entity) | synapse.onweb(entityId) / synapse.onweb(entity) | synapse onweb id | |
log-in | get API key and write to user's properties file | synapseLogin(<user>,<pw>) | synapse.login(<user>,<pw>, sessionToken=None) | synapse login -u USER -p PASSWORD |
log-out | delete API key from properties file | synapseLogout() | synapse.logout() | synapse logout |
2 –Advanced functions | ||||
Execute query | TODO: pagination, e.g. the function returns an iterator. Look at current implementation in R client. | synQuery(queryString) | synapse.query(queryString) | synapse query |
we talked about this, but is it needed? | ||||
we talked about this, but is it needed? | ||||
Retrieve the wiki for an object (Entity or Evaluation) | synapse.getWiki(parentowner, subpageId) Examples: synapse.getWiki(entity) synapse.getWiki(evalution, 2342) | |||
Wiki construction | Wiki(parentowner, title, markdown, attachmentFileHandleIds, parentWikiId=None) | |||
synStore(wiki) | synapse.store(Wiki) | |||
synGetAnnotations() | synapse.getAnnotations(entity/entityId) | |||
synSetAnnotations() | synapse.setAnntotations(entity/entityId, annotations) | |||
synGetProperties() | NA | NA | ||
Access properties, throwing exception if property is not defined. | synSetProperties() | NA | NA | |
synGetAnnotation() | ||||
synSetAnnotation() | ||||
Access property, throwing exception if property is not defined. | synGetProperty() | NA | NA | |
Access property, throwing exception if property is not defined. Setting to NULL deletes. | synSetProperty() | NA | NA | |
Create an Activity (provenance object) in memory. | Activity(name, description, used, executed) | Activity(name, description, used, exectuted) | NA | |
Create or update the Activity in Synapse | synStore(activity) | synapse.store(Activity) | NA | |
Get the Activity which generated the given entity. | synGetActivity(activity) / synGetActivity(activityId) | synapse.getActivity(activity/activityId) | NA | |
Set the Activity which generated the given entity | synSetActivity(entity)<-activity | synapse.setActivity(entity/entityId, activity) | NA | |
Empty trash can | ||||
Restore from trash can | ||||
Run code, capturing output, code and provenance relationship. | synapseExecute(executable, args, resultParentId, codeParentId, resultEntityProperties = NULL, resultEntityName=NULL, replChar=".") | synapse.exceute(executable, args, resultParentId, codeParentId, resultEntityProperties = None, resultEntityName=None, replChar=".") | NA | |
Create evaluation object | Evaluation(name, description, status) | Evaluation(name, description, status, contentSource) | NA | |
Submit for evaluation | submit(evaluation, entity, submissionName) | synapse.submit(evaluation, entity, name=None) | synapse submitEvaluation | |
Adds participant to evaluation, userId is optional | Synapse.addEvaluationParticipant(evaluation, userId=None): | |||
Returns an iterator of submissions | Synapse.getSubmissions(evaluation, status=None): | |||
Get specific submission | Synapse.getSubmission(id): | |||
Get status of of submission | Synapse.getSubmissionStatus(submission): | |||
3 – Web API Level functions | ||||
Execute GET request | See details below. | synRestGET(uri, endpoint) | synapse.restGET(uri, endpoint=None)* | |
Execute POST request | See details below. | synRestPOST(uri, body, endpoint) | synapse.restPOST(uri, body, endpoint=None)* | |
Execute PUT request | See details below. | synRestPUT(uri, body, endpoint) | synapse.restPUT(uri, body, endpoint=None)* | |
Execute DELETE request | See details below. | synRestDELETE(uri, endpoint) | synapse.restDELETE(uri, endpoint=None)* |
...