Package 'synapser'

Description

An activity is a Synapse object that helps to keep track of what objects were used in an analysis step, as well as what objects were generated. Thus, all relationships between Synapse objects and an activity are governed by dependencies. That is, an activity needs to know what it used, and outputs need to know what activity they were generatedBy.

Usage

Activity(id=NULL, name=NULL, description=NULL, etag=NULL, created_on=NULL, modified_on=NULL, created_by=NULL, modified_by=NULL, used=list(), executed=list())

Arguments

Format

An S3-style class object.

Value

NULL

Methods

• Activity(id=NULL, name=NULL, description=NULL, etag=NULL, created_on=NULL, modified_on=NULL, created_by=NULL, modified_by=NULL, used=list(), executed=list()): Constructor for Activity

• synDisassociateActivityFromEntity(cls, parent, synapse_client=NULL): Disassociate the Activity from the parent entity. This is the first step in deleting the Activity. If you have other entities that are associated with this Activity you must disassociate them by calling this method on them as well.

• synGetFromParent(cls, parent, parent_version_number=NULL, synapse_client=NULL): Get the Activity from Synapse based on the parent entity.

Examples

## Not run: 
## Example 1: Store an Activity on a File
    # Record the provenance of a file: what it used, and what was executed to
    # create it. Storing the Activity with a parent associates it with that entity.
    library(synapser)
    synLogin()

    file = synGet("syn123", file_options = FileOptions(download_file = FALSE))

    activity = Activity(
        name = "Normalization",
        description = "Normalized the raw counts",
        used = list(
            UsedEntity(target_id = "syn456", target_version_number = 1L),
            UsedURL(name = "Reference genome", url = "https://www.ncbi.nlm.nih.gov/grc/human")
        ),
        executed = list(
            UsedURL(name = "Analysis code", url = "https://github.com/my-org/my-analysis")
        )
    )
    activity = activity |> synStore(parent = file)
    print(activity$id)

## Example 2: Delete an Activity
    # Disassociate the Activity from its parent entity. The Activity itself is
    # deleted once it has been disassociated from every entity it is attached to;
    # until then you'll receive an error for each remaining entity.
    library(synapser)
    synLogin()

    Activity() |> synDelete(parent = "syn123") # parent is the entity that the Activity is associated with

## End(Not run)

Description

Configuration options for entities that support activity/provenance tracking.

This class controls whether activity information (provenance data) should be included when retrieving entities. Activity information tracks the computational steps, data sources, and relationships that led to the creation of an entity.

Usage

ActivityOptions(include_activity=FALSE)

Arguments

Format

An S3-style class object.

Value

NULL

Methods

• ActivityOptions(include_activity=FALSE): Constructor for ActivityOptions

Note

Activity information is only available for entities that support provenance tracking (File, Table, Dataset, etc...). For other entity types, this option is ignored.

Examples

## Not run: 
    # Configure activity inclusion:
    library(synapser)

    # Include activity information
    with_activity = ActivityOptions(include_activity = TRUE)

    # Skip activity information (faster retrieval)
    without_activity = ActivityOptions(include_activity = FALSE)

## End(Not run)

Description

Represents a Synapse Agent Registration

Usage

Agent(cloud_agent_id=NULL, cloud_alias_id=NULL, registration_id=NULL, registered_on=NULL, type=NULL, sessions=list(), current_session=NULL)

Arguments

Format

An S3-style class object.

Value

NULL

Methods

• Agent(cloud_agent_id=NULL, cloud_alias_id=NULL, registration_id=NULL, registered_on=NULL, type=NULL, sessions=list(), current_session=NULL): Constructor for Agent

• synGetChatHistory(instance): Gets the chat history for the current session.

• synGetSession(instance, session_id, synapse_client=NULL): Gets an existing agent session. Adds the session to the Agent's sessions named list and sets it as the current session.

• synPrompt(instance, prompt, enable_trace=FALSE, print_response=FALSE, session=NULL, newer_than=NULL, timeout=120L, synapse_client=NULL): Sends a prompt to the agent for the current session. If no session is currently active, a new session will be started.

• synRegister(instance, synapse_client=NULL): Registers an agent with the Synapse API. If agent already exists, it will be retrieved.

• synStartSession(instance, access_level="PUBLICLY_ACCESSIBLE", synapse_client=NULL): Starts an agent session. Adds the session to the Agent's sessions named list and sets it as the current session.

Examples

## Not run: 
## Example 1: Chat with the baseline Synapse Agent
    # You can chat with the same agent which is available in the Synapse UI
    # at https://www.synapse.org/Chat:default. By default, this "baseline" agent
    # is used when a registration ID is not provided. In the background,
    # the Agent class will start a session and set that new session as the
    # current session if one is not already set.
    library(synapser)
    synLogin()

    my_agent = Agent()
    my_agent |> synPrompt(
        prompt = "Can you tell me about the AD Knowledge Portal dataset?",
        enable_trace = TRUE,
        print_response = TRUE
    )

## Example 2: Register and chat with a custom agent
    # Only available for internal users (Sage Bionetworks employees).
    #
    # Alternatively, you can register a custom agent and chat with it provided
    # you have already created it.
    library(synapser)
    synLogin()

    my_agent = Agent(cloud_agent_id = "foo") |> synRegister()
    my_agent |> synPrompt(
        prompt = "Hello",
        enable_trace = TRUE,
        print_response = TRUE
    )

## Example 3: Prompt an existing custom agent
    # If you have already registered a custom agent, you can chat with it by
    # constructing an Agent with its registration ID and sending it a prompt.
    library(synapser)
    synLogin()

    my_agent = Agent(registration_id = "foo")
    my_agent |> synPrompt(
        prompt = "Hello",
        enable_trace = TRUE,
        print_response = TRUE
    )

## Advanced Example: Start and prompt multiple sessions
    # Here, we connect to a custom agent and start one session with the prompt "Hello".
    # In the background, this first session is being set as the current session
    # and future prompts will be sent to this session by default. If we want to send a
    # prompt to a different session, we can do so by starting it and calling synPrompt again,
    # but with our new session as an argument. We now have two sessions, both stored in the
    # my_agent$sessions named list. After the second prompt, my_second_session is now
    # the current session.
    library(synapser)
    synLogin()

    my_agent = Agent(registration_id = "foo")

    my_agent |> synPrompt(
        prompt = "Hello",
        enable_trace = TRUE,
        print_response = TRUE
    )

    my_second_session = my_agent |> synStartSession()
    my_agent |> synPrompt(
        prompt = "Hello again",
        enable_trace = TRUE,
        print_response = TRUE,
        session = my_second_session
    )

## End(Not run)

Description

Represents a prompt, response, and metadata within an AgentSession.

Usage

AgentPrompt(concrete_type="org.sagebionetworks.repo.model.agent.AgentChatRequest", id=NULL, session_id=NULL, prompt=NULL, response=NULL, enable_trace=FALSE, trace=NULL)

Arguments

Format

An S3-style class object.

Value

NULL

Methods

• AgentPrompt(concrete_type="org.sagebionetworks.repo.model.agent.AgentChatRequest", id=NULL, session_id=NULL, prompt=NULL, response=NULL, enable_trace=FALSE, trace=NULL): Constructor for AgentPrompt

Examples

## Not run: 
## Inspecting the prompts in a session
    # AgentPrompt objects are created for you when you prompt an agent. They make up
    # the chat history of an AgentSession.
    library(synapser)
    synLogin()

    my_agent = Agent()
    my_agent |> synPrompt(prompt = "Hello", print_response = FALSE)

    for (agent_prompt in my_agent |> synGetChatHistory()) {
        print(agent_prompt$prompt)
        print(agent_prompt$response)
    }

## End(Not run)

Description

Represents a Synapse Agent Session

Usage

AgentSession(id=NULL, access_level="PUBLICLY_ACCESSIBLE", started_on=NULL, started_by=NULL, modified_on=NULL, agent_registration_id=NULL, etag=NULL, chat_history=list())

Arguments

Format

An S3-style class object.

Value

NULL

Methods

• AgentSession(id=NULL, access_level="PUBLICLY_ACCESSIBLE", started_on=NULL, started_by=NULL, modified_on=NULL, agent_registration_id=NULL, etag=NULL, chat_history=list()): Constructor for AgentSession

• synPrompt(instance, prompt, enable_trace=FALSE, print_response=FALSE, newer_than=NULL, timeout=120L, synapse_client=NULL): Sends a prompt to the agent and adds the response to the AgentSession's chat history. A session must be started before sending a prompt.

• synStart(instance, synapse_client=NULL): Starts an agent session.

• synUpdate(instance, synapse_client=NULL): Updates an agent session. Only updates to the access level are currently supported.

Note

It is recommended to use the Agent class to conduct chat sessions, but you are free to use AgentSession directly if you wish.

Examples

## Not run: 
## Example 1: Start a session and send a prompt.
    # Start a session with a custom agent by providing the agent's registration ID
    # and calling synStart(). Then, send a prompt to the agent.
    library(synapser)
    synLogin()

    my_session = AgentSession(agent_registration_id = "foo") |> synStart()
    my_session |> synPrompt(
        prompt = "Hello",
        enable_trace = TRUE,
        print_response = TRUE
    )

## Example 2: Prompt an existing session.
    # If you already have an existing session, you can send it a prompt by
    # constructing an AgentSession with its session ID.
    library(synapser)
    synLogin()

    my_session = AgentSession(id = "foo")
    my_session |> synPrompt(
        prompt = "Hello",
        enable_trace = TRUE,
        print_response = TRUE
    )

## Example 3: Update the access level of an existing session.
    # Construct an AgentSession with its session ID, set the access level you
    # want, and call synUpdate().
    library(synapser)
    synLogin()

    my_session = AgentSession(id = "foo")
    my_session$access_level = "READ_YOUR_PRIVATE_DATA"
    my_session = my_session |> synUpdate()

## End(Not run)

Description

A column model contains the metadata of a single column of a table or view.

Usage

Column(id=NULL, name=NULL, column_type=NULL, facet_type=NULL, default_value=NULL, maximum_size=NULL, maximum_list_length=NULL, enum_values=NULL, json_sub_columns=NULL)

Arguments

Format

An S3-style class object.

Value

NULL

Methods

• Column(id=NULL, name=NULL, column_type=NULL, facet_type=NULL, default_value=NULL, maximum_size=NULL, maximum_list_length=NULL, enum_values=NULL, json_sub_columns=NULL): Constructor for Column

• synList(prefix=NULL, limit=100L, offset=0L, synapse_client=NULL): List columns with optional prefix filtering.

Examples

## Not run: 
## Creating a table with columns
    library(synapser)
    synLogin()

    columns = list(
        Column(name = "my_string_column", column_type = "STRING", maximum_size = 100L),
        Column(name = "my_integer_column", column_type = "INTEGER"),
        Column(name = "my_status_column", column_type = "STRING", enum_values = list("pending", "done")),
        Column(name = "my_list_column", column_type = "STRING_LIST", maximum_list_length = 10L)
    )
    table = Table(name = "My Table", parent_id = "syn123", columns = columns) |> synStore()

## Listing existing column models
    library(synapser)
    synLogin()

    columns = synList(prefix = "my_", limit = 10L)
    

## End(Not run)

Description

A Dataset object represents the metadata of a Synapse Dataset. https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/table/Dataset.html

Usage

Dataset(id=NULL, name=NULL, parent_id=NULL, activity=NULL, version_number=NULL, view_entity_type="dataset", view_type_mask=128L, include_default_columns=TRUE, description=NULL, etag=NULL, created_on=NULL, modified_on=NULL, created_by=NULL, modified_by=NULL, version_label=NULL, version_comment=NULL, is_latest_version=NULL, is_search_enabled=NULL, items=list(), size=NULL, checksum=NULL, count=NULL, columns=list(), annotations=list())

Arguments

library(synapser)
synLogin()

dataset = Dataset(id = "syn1234") |> synGet()
dataset$columns[["my_column"]]$column_type = "DOUBLE"
dataset = dataset |> synStore()

Format

An S3-style class object.

Value

NULL

Methods

• Dataset(id=NULL, name=NULL, parent_id=NULL, activity=NULL, version_number=NULL, view_entity_type="dataset", view_type_mask=128L, include_default_columns=TRUE, description=NULL, etag=NULL, created_on=NULL, modified_on=NULL, created_by=NULL, modified_by=NULL, version_label=NULL, version_comment=NULL, is_latest_version=NULL, is_search_enabled=NULL, items=list(), size=NULL, checksum=NULL, count=NULL, columns=list(), annotations=list()): Constructor for Dataset

• synAddColumn(instance, column, index=NULL): Add column(s) to the table. Note that this does not store the column(s) in Synapse. You must call the synStore() function on this Dataset instance to store the column(s) in Synapse. This is a convenience function to eliminate the need to manually add the column(s) to the $columns list.
  
  This function will add an item to the $columns attribute of the Dataset instance. $columns is a named list where the key is the name of the column and the value is the Column object.

• synAddItem(instance, item, synapse_client=NULL): Adds an item in the form of an EntityRef to the dataset. For Folders, children are added recursively. Effect is not seen until the dataset is stored.

• synDeleteColumn(instance, name): Mark a column for deletion. Note that this does not delete the column from Synapse. You must call the synStore() function on this Dataset instance to delete the column from Synapse. This is a convenience function to eliminate the need to manually delete the column from the named list and add it to the $_columns_to_delete attribute.

• synDeletePermissions(instance, include_self=TRUE, include_container_content=FALSE, recursive=FALSE, target_entity_types=NULL, dry_run=FALSE, show_acl_details=TRUE, show_files_in_containers=TRUE, synapse_client=NULL): Delete the entire Access Control List (ACL) for a given Entity. This is not scoped to a specific user or group, but rather removes all permissions associated with the Entity. After this operation, the Entity will inherit permissions from its benefactor, which is typically its parent entity or the Project it belongs to.
  
  In order to remove permissions for a specific user or group, you should use the synSetPermissions() function with the access_type set to an empty list.
  
  By default, Entities such as FileEntity and Folder inherit their permission from their containing Project. For such Entities the Project is the Entity's 'benefactor'. This permission inheritance can be overridden by creating an ACL for the Entity. When this occurs the Entity becomes its own benefactor and all permission are determined by its own ACL.
  
  If the ACL of an Entity is deleted, then its benefactor will automatically be set to its parent's benefactor.
  
  Special notice for Projects: The ACL for a Project cannot be deleted, you must individually update or revoke the permissions for each user or group.

• synGetAcl(instance, principal_id=NULL, check_benefactor=TRUE, synapse_client=NULL): Get the ACL that a user or group has on an Entity.

• synGetPermissions(instance, synapse_client=NULL): Get the permissions that the caller has on an Entity.

• synListAcl(instance, recursive=FALSE, include_container_content=FALSE, target_entity_types=NULL, log_tree=FALSE, synapse_client=NULL): List the Access Control Lists (ACLs) for this entity and optionally its children.
  
  This function returns the local sharing settings for the entity and optionally its children. It provides a mapping of all ACLs for the given container/entity.
  
  Important Note: This function returns the LOCAL sharing settings only, not the effective permissions that each Synapse User ID/Team has on the entities. More permissive permissions could be granted via a Team that the user has access to that has permissions on the entity, or through inheritance from parent entities.

• synQuery(query, include_row_id_and_row_version=TRUE, convert_to_datetime=FALSE, download_location=NULL, quote_character="\"", escape_character=r"(\)", line_end="\n", separator=",", header=TRUE, timeout=250L, synapse_client=NULL): Query for data on a table stored in Synapse. The results will always be returned as a data frame unless you specify a download_location in which case the results will be downloaded to that location. There are a number of arguments that you may pass to this function depending on if you are getting the results back as a data frame or downloading the results to a file.

• synQueryPartMask(query, part_mask, timeout=250L, synapse_client=NULL): Query for data on a table stored in Synapse. This is a more advanced use case of the synQuery() function that allows you to determine what additional metadata about the table or query should also be returned. If you do not need this additional information then you are better off using the synQuery() function.
  
  The query for this method uses this Rest API: https://rest-docs.synapse.org/rest/POST/entity/id/table/query/async/start.html

• synRemoveItem(instance, item, synapse_client=NULL): Removes an item from the dataset. For Folders, all children of the folder are removed recursively. Effect is not seen until the dataset is stored.

• synReorderColumn(instance, name, index): Reorder a column in the table. Note that this does not store the column in Synapse. You must call the synStore() function on this Dataset instance to store the column in Synapse. This is a convenience function to eliminate the need to manually reorder the named list stored in the $columns attribute.
  
  You must ensure that the index is within the bounds of the number of columns in the table. If you pass in an index that is out of bounds the column will be added to the end of the list.

• synSetPermissions(instance, principal_id=NULL, access_type=NULL, modify_benefactor=FALSE, warn_if_inherits=TRUE, overwrite=TRUE, synapse_client=NULL): Sets permission that a user or group has on an Entity. An Entity may have its own ACL or inherit its ACL from a benefactor.

• synSnapshot(instance, comment=NULL, label=NULL, include_activity=TRUE, associate_activity_to_new_version=TRUE, timeout=120L, synapse_client=NULL): Creates a snapshot of the dataset. A snapshot is a saved, read-only version of the dataset at the time it was created. Dataset snapshots are created using the asynchronous job API.

• synUpdateRows(instance, values, primary_keys, dry_run=FALSE, rows_per_query=50000L, update_size_bytes=1992294.4, insert_size_bytes=943718400L, job_timeout=600L, date_columns=NULL, date_format=NULL, wait_for_eventually_consistent_view=FALSE, wait_for_eventually_consistent_view_timeout=600L, synapse_client=NULL): Update the values of rows in the dataset. This method can only be used to update values in custom columns. Default columns cannot be updated, but may be used as primary keys.
  
  Limitations:
  
  - When updating many rows the requests to Synapse will be chunked into smaller requests. The limit is 2MB per request. This chunking will happen automatically and should not be a concern for most users. If you are having issues with the request being too large you may lower the number of rows you are trying to update.
  - The primary_keys argument must contain at least one column.
  - The primary_keys argument cannot contain columns that are a LIST type.
  - The primary_keys argument cannot contain columns that are a JSON type.
  - The values used as the primary_keys must be unique in the table. If there are multiple rows with the same values in the primary_keys the behavior is that an error will be raised.
  - The columns used in primary_keys cannot contain updated values. Since the values in these columns are used to determine if a row exists, they cannot be updated in the same transaction.

Examples

## Not run: 
## Example 1: Create a new dataset from a list of EntityRefs.
    # Dataset items consist of references to Synapse Files using an Entity Reference.
    # If you are adding items to a Dataset directly, you must provide them in the form of
    # an EntityRef class instance.
    library(synapser)
    synLogin()

    my_entity_refs = list(EntityRef(id = "syn1234"), EntityRef(id = "syn1235"), EntityRef(id = "syn1236"))
    my_dataset = Dataset(parent_id = "syn987", name = "my-new-dataset", items = my_entity_refs)
    my_dataset |> synStore()

## Example 2: Add entities to an existing dataset.
    # Using synAddItem(), you can add Synapse entities that are Files, Folders, or EntityRefs that point to a Synapse entity.
    # If the entity is a Folder (or an EntityRef that points to a folder), all of the child Files
    # within the Folder will be added to the Dataset recursively.
    library(synapser)
    synLogin()

    my_dataset = Dataset(id = "syn1234") |> synGet()

    # Add a file to the dataset
    my_dataset |> synAddItem(File(id = "syn1235"))

    # Add a folder to the dataset
    # All child files are recursively added to the dataset
    my_dataset |> synAddItem(Folder(id = "syn1236"))

    # Add an entity reference to the dataset
    my_dataset |> synAddItem(EntityRef(id = "syn1237", version = 1L))

    my_dataset |> synStore()

## Example 3: Remove entities from a dataset.
    library(synapser)
    synLogin()

    my_dataset = Dataset(id = "syn1234") |> synGet()

    # Remove a file from the dataset
    my_dataset |> synRemoveItem(File(id = "syn1235"))

    # Remove a folder from the dataset
    # All child files are recursively removed from the dataset
    my_dataset |> synRemoveItem(Folder(id = "syn1236"))

    # Remove an entity reference from the dataset
    my_dataset |> synRemoveItem(EntityRef(id = "syn1237", version = 1L))

    my_dataset |> synStore()

## Example 4: Query data from a dataset.
    library(synapser)
    synLogin()

    row = synQuery(query = "SELECT * FROM syn1234 WHERE id = 'syn1235'")
    print(row)

## Example 5: Add a custom column to a dataset.
    library(synapser)
    synLogin()

    my_dataset = Dataset(id = "syn1234") |> synGet()
    my_dataset |> synAddColumn(Column(name = "my_annotation", column_type = "STRING"))
    my_dataset |> synStore()

## Example 6: Update custom column values in a dataset.
    library(synapser)
    synLogin()

    my_dataset = Dataset(id = "syn1234") |> synGet()
    # my_annotation must already exist in the dataset as a custom column
    modified_data = data.frame(
        id = c("syn1234"),
        my_annotation = c("good data")
    )
    my_dataset |> synUpdateRows(values = modified_data, primary_keys = list("id"), dry_run = FALSE)

## Example 7: Save a snapshot of a dataset.
    library(synapser)
    synLogin()

    my_dataset = Dataset(id = "syn1234") |> synGet()
    my_dataset |> synSnapshot(comment = "My first snapshot", label = "My first snapshot")

## Example 8: Deleting a dataset.
    library(synapser)
    synLogin()

    Dataset(id = "syn4567") |> synDelete()

## End(Not run)

Description

A DatasetCollection object represents the metadata of a Synapse Dataset Collection. https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/table/DatasetCollection.html

A Dataset Collection is a type of view defined by a flat list of Datasets.

Usage

DatasetCollection(id=NULL, name=NULL, parent_id=NULL, activity=NULL, version_number=NULL, view_entity_type="datasetcollection", view_type_mask=256L, include_default_columns=TRUE, description=NULL, etag=NULL, created_on=NULL, modified_on=NULL, created_by=NULL, modified_by=NULL, version_label=NULL, version_comment=NULL, is_latest_version=NULL, is_search_enabled=NULL, items=list(), columns=list(), annotations=list())

Arguments

library(synapser)
synLogin()

collection = DatasetCollection(id = "syn1234") |> synGet()
collection$columns[["my_column"]]$column_type = "DOUBLE"
collection = collection |> synStore()

Format

An S3-style class object.

Value

NULL

Methods

• DatasetCollection(id=NULL, name=NULL, parent_id=NULL, activity=NULL, version_number=NULL, view_entity_type="datasetcollection", view_type_mask=256L, include_default_columns=TRUE, description=NULL, etag=NULL, created_on=NULL, modified_on=NULL, created_by=NULL, modified_by=NULL, version_label=NULL, version_comment=NULL, is_latest_version=NULL, is_search_enabled=NULL, items=list(), columns=list(), annotations=list()): Constructor for DatasetCollection

• synAddColumn(instance, column, index=NULL): Add column(s) to the table. Note that this does not store the column(s) in Synapse. You must call the synStore() function on this DatasetCollection instance to store the column(s) in Synapse. This is a convenience function to eliminate the need to manually add the column(s) to the $columns list.
  
  This function will add an item to the $columns attribute of the DatasetCollection instance. $columns is a named list where the key is the name of the column and the value is the Column object.

• synAddItem(instance, item): Adds a dataset to the dataset collection. Effect is not seen until the dataset collection is stored.

• synDeleteColumn(instance, name): Mark a column for deletion. Note that this does not delete the column from Synapse. You must call the synStore() function on this DatasetCollection instance to delete the column from Synapse. This is a convenience function to eliminate the need to manually delete the column from the named list and add it to the $_columns_to_delete attribute.

• synDeletePermissions(instance, include_self=TRUE, include_container_content=FALSE, recursive=FALSE, target_entity_types=NULL, dry_run=FALSE, show_acl_details=TRUE, show_files_in_containers=TRUE, synapse_client=NULL): Delete the entire Access Control List (ACL) for a given Entity. This is not scoped to a specific user or group, but rather removes all permissions associated with the Entity. After this operation, the Entity will inherit permissions from its benefactor, which is typically its parent entity or the Project it belongs to.
  
  In order to remove permissions for a specific user or group, you should use the synSetPermissions() function with the access_type set to an empty list.
  
  By default, Entities such as FileEntity and Folder inherit their permission from their containing Project. For such Entities the Project is the Entity's 'benefactor'. This permission inheritance can be overridden by creating an ACL for the Entity. When this occurs the Entity becomes its own benefactor and all permission are determined by its own ACL.
  
  If the ACL of an Entity is deleted, then its benefactor will automatically be set to its parent's benefactor.
  
  Special notice for Projects: The ACL for a Project cannot be deleted, you must individually update or revoke the permissions for each user or group.

• synGetAcl(instance, principal_id=NULL, check_benefactor=TRUE, synapse_client=NULL): Get the ACL that a user or group has on an Entity.

• synGetPermissions(instance, synapse_client=NULL): Get the permissions that the caller has on an Entity.

• synListAcl(instance, recursive=FALSE, include_container_content=FALSE, target_entity_types=NULL, log_tree=FALSE, synapse_client=NULL): List the Access Control Lists (ACLs) for this entity and optionally its children.
  
  This function returns the local sharing settings for the entity and optionally its children. It provides a mapping of all ACLs for the given container/entity.
  
  Important Note: This function returns the LOCAL sharing settings only, not the effective permissions that each Synapse User ID/Team has on the entities. More permissive permissions could be granted via a Team that the user has access to that has permissions on the entity, or through inheritance from parent entities.

• synQuery(query, include_row_id_and_row_version=TRUE, convert_to_datetime=FALSE, download_location=NULL, quote_character="\"", escape_character=r"(\)", line_end="\n", separator=",", header=TRUE, timeout=250L, synapse_client=NULL): Query for data on a table stored in Synapse. The results will always be returned as a data frame unless you specify a download_location in which case the results will be downloaded to that location. There are a number of arguments that you may pass to this function depending on if you are getting the results back as a data frame or downloading the results to a file.

• synQueryPartMask(query, part_mask, timeout=250L, synapse_client=NULL): Query for data on a table stored in Synapse. This is a more advanced use case of the synQuery() function that allows you to determine what additional metadata about the table or query should also be returned. If you do not need this additional information then you are better off using the synQuery() function.
  
  The query for this method uses this Rest API: https://rest-docs.synapse.org/rest/POST/entity/id/table/query/async/start.html

• synRemoveItem(instance, item): Removes an entity from the dataset collection. Must be a Dataset or EntityRef. Effect is not seen until the dataset collection is stored. Unless the version is specified, all entities with the same ID will be removed.

• synReorderColumn(instance, name, index): Reorder a column in the table. Note that this does not store the column in Synapse. You must call the synStore() function on this DatasetCollection instance to store the column in Synapse. This is a convenience function to eliminate the need to manually reorder the named list stored in the $columns attribute.
  
  You must ensure that the index is within the bounds of the number of columns in the table. If you pass in an index that is out of bounds the column will be added to the end of the list.

• synSetPermissions(instance, principal_id=NULL, access_type=NULL, modify_benefactor=FALSE, warn_if_inherits=TRUE, overwrite=TRUE, synapse_client=NULL): Sets permission that a user or group has on an Entity. An Entity may have its own ACL or inherit its ACL from a benefactor.

• synSnapshot(instance, comment=NULL, label=NULL, include_activity=TRUE, associate_activity_to_new_version=TRUE, timeout=120L, synapse_client=NULL): Creates a snapshot of the dataset collection. A snapshot is a saved, read-only version of the dataset collection at the time it was created. Dataset collection snapshots are created using the asynchronous job API.

• synUpdateRows(instance, values, primary_keys, dry_run=FALSE, rows_per_query=50000L, update_size_bytes=1992294.4, insert_size_bytes=943718400L, job_timeout=600L, date_columns=NULL, date_format=NULL, wait_for_eventually_consistent_view=FALSE, wait_for_eventually_consistent_view_timeout=600L, synapse_client=NULL): Update the values of rows in the dataset collection. This method can only be used to update values in custom columns. Default columns cannot be updated, but may be used as primary keys.
  
  Limitations:
  
  - When updating many rows the requests to Synapse will be chunked into smaller requests. The limit is 2MB per request. This chunking will happen automatically and should not be a concern for most users. If you are having issues with the request being too large you may lower the number of rows you are trying to update.
  - The primary_keys argument must contain at least one column.
  - The primary_keys argument cannot contain columns that are a LIST type.
  - The primary_keys argument cannot contain columns that are a JSON type.
  - The values used as the primary_keys must be unique in the table. If there are multiple rows with the same values in the primary_keys the behavior is that an error will be raised.
  - The columns used in primary_keys cannot contain updated values. Since the values in these columns are used to determine if a row exists, they cannot be updated in the same transaction.

Examples

## Not run: 
## Example 1: Create a new Dataset Collection from a list of Datasets.
    library(synapser)
    synLogin()

    my_datasets = list(Dataset(id = "syn1234"), Dataset(id = "syn1235"), Dataset(id = "syn1236"))
    my_collection = DatasetCollection(parent_id = "syn987", name = "my-new-collection", items = my_datasets)
    my_collection |> synStore()

## Example 2: Add Datasets to an existing Dataset Collection.
    library(synapser)
    synLogin()

    my_collection = DatasetCollection(id = "syn1234") |> synGet()

    # Add a dataset to the collection
    my_collection |> synAddItem(Dataset(id = "syn1235"))
    my_collection |> synStore()

## Example 3: Remove Datasets from a Dataset Collection.
    library(synapser)
    synLogin()

    my_collection = DatasetCollection(id = "syn1234") |> synGet()

    # Remove a dataset from the collection
    my_collection |> synRemoveItem(Dataset(id = "syn1235"))
    my_collection |> synStore()

## Example 4: Query data from a Dataset Collection.
    library(synapser)
    synLogin()

    row = synQuery(query = "SELECT * FROM syn1234 WHERE id = 'syn1235'")
    print(row)

## Example 5: Add a custom column to a Dataset Collection.
    library(synapser)
    synLogin()

    my_collection = DatasetCollection(id = "syn1234") |> synGet()
    my_collection |> synAddColumn(Column(name = "my_annotation", column_type = "STRING"))
    my_collection |> synStore()

## Example 6: Update custom column values in a Dataset Collection.
    library(synapser)
    synLogin()

    my_collection = DatasetCollection(id = "syn1234") |> synGet()
    # my_annotation must already exist in the dataset collection as a custom column
    modified_data = data.frame(
        id = c("syn1234"),
        my_annotation = c("good data")
    )
    my_collection |> synUpdateRows(values = modified_data, primary_keys = list("id"), dry_run = FALSE)

## Example 7: Save a snapshot of a Dataset Collection.
    library(synapser)
    synLogin()

    my_collection = DatasetCollection(id = "syn1234") |> synGet()
    my_collection |> synSnapshot(comment = "My first snapshot", label = "My first snapshot")

## Example 8: Deleting a Dataset Collection.
    library(synapser)
    synLogin()

    DatasetCollection(id = "syn4567") |> synDelete()

## End(Not run)

Description

A single item for a user's download list.

https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/download/DownloadListItem.html

Usage

DownloadListItem(file_entity_id, version_number=NULL)

Arguments

Format

An S3-style class object.

Value

NULL

Methods

• DownloadListItem(file_entity_id, version_number=NULL): Constructor for DownloadListItem

Examples

## Not run: 
## Using this class
    # Identify files (and optionally their versions) on your download list
    library(synapser)
    synLogin()

    items = list(
        DownloadListItem(file_entity_id = "syn123"),
        DownloadListItem(file_entity_id = "syn456", version_number = 2L)
    )
    # Add files to the cart
    count = synDownloadListAdd(items)
    print(count)

    # Download all files in the cart to a local directory.
    items = synDownloadListFiles()
    print(items)
    
    # Remove files from the cart
    count = synDownloadListRemove(items)
    print(count)

    

## End(Not run)

Description

Represents a reference to the id and version of an entity to be used in Dataset and DatasetCollection objects.

Usage

EntityRef(id, version)

Arguments

Format

An S3-style class object.

Value

NULL

Methods

• EntityRef(id, version): Constructor for EntityRef

Examples

## Not run: 
## Adding a specific entity version to a Dataset
    library(synapser)
    synLogin()

    my_dataset = Dataset(id = "syn123") |> synGet()
    my_dataset |> synAddItem(EntityRef(id = "syn456", version = 1L))
    my_dataset = my_dataset |> synStore()

## End(Not run)

Description

A view of Entities within a defined scope. The purpose of an EntityView, also known as a FileView, is to create a SQL-like view of entities within a defined scope. The scope is defined by the scope_ids attribute. The scope_ids attribute is a list of syn container ids that define where to search for rows to include in the view. Entities within the scope are included in the view if they match the criteria defined by the view_type_mask attribute. The view_type_mask attribute is a bit mask representing the types to include in the view. You may set this to a single integer value, or you may combine multiple values using a bitwise OR (bitwOr() in R).

Usage

EntityView(id=NULL, name=NULL, parent_id=NULL, activity=NULL, version_number=NULL, view_entity_type=NULL, view_type_mask=NULL, include_default_columns=TRUE, description=NULL, etag=NULL, created_on=NULL, modified_on=NULL, created_by=NULL, modified_by=NULL, version_label=NULL, version_comment=NULL, is_latest_version=NULL, columns=list(), is_search_enabled=NULL, scope_ids=list(), annotations=list())

Arguments

library(synapser)
synLogin()

view = EntityView(
    name = "My EntityView",
    parent_id = "syn1234",
    scope_ids = list("syn1234"),
    view_type_mask = bitwOr(0x01L, 0x08L) # File | Folder
) |> synStore()

library(synapser)
synLogin()

view = EntityView(id = "syn1234") |> synGet()
view$columns[["my_column"]]$column_type = "DOUBLE"
view = view |> synStore()

Format

An S3-style class object.

Value

NULL

Methods

• EntityView(id=NULL, name=NULL, parent_id=NULL, activity=NULL, version_number=NULL, view_entity_type=NULL, view_type_mask=NULL, include_default_columns=TRUE, description=NULL, etag=NULL, created_on=NULL, modified_on=NULL, created_by=NULL, modified_by=NULL, version_label=NULL, version_comment=NULL, is_latest_version=NULL, columns=list(), is_search_enabled=NULL, scope_ids=list(), annotations=list()): Constructor for EntityView

• synAddColumn(instance, column, index=NULL): Add column(s) to the EntityView. Note that this does not store the column(s) in Synapse. You must call the synStore() function on this EntityView instance to store the column(s) in Synapse. This is a convenience function to eliminate the need to manually add the column(s) to the $columns list.
  
  This function will add an item to the $columns attribute of the EntityView instance. $columns is a named list where the key is the name of the column and the value is the Column object.

• synBindSchema(instance, json_schema_uri, enable_derived_annotations=FALSE, synapse_client=NULL): Bind a JSON schema to the entity.

• synDeleteColumn(instance, name): Mark a column for deletion. Note that this does not delete the column from Synapse. You must call the synStore() function on this EntityView instance to delete the column from Synapse. This is a convenience function to eliminate the need to manually delete the column from the named list and add it to the $_columns_to_delete attribute.

• synDeletePermissions(instance, include_self=TRUE, include_container_content=FALSE, recursive=FALSE, target_entity_types=NULL, dry_run=FALSE, show_acl_details=TRUE, show_files_in_containers=TRUE, synapse_client=NULL): Delete the entire Access Control List (ACL) for a given Entity. This is not scoped to a specific user or group, but rather removes all permissions associated with the Entity. After this operation, the Entity will inherit permissions from its benefactor, which is typically its parent entity or the Project it belongs to.
  
  In order to remove permissions for a specific user or group, you should use the synSetPermissions() function with the access_type set to an empty list.
  
  By default, Entities such as FileEntity and Folder inherit their permission from their containing Project. For such Entities the Project is the Entity's 'benefactor'. This permission inheritance can be overridden by creating an ACL for the Entity. When this occurs the Entity becomes its own benefactor and all permission are determined by its own ACL.
  
  If the ACL of an Entity is deleted, then its benefactor will automatically be set to its parent's benefactor.
  
  Special notice for Projects: The ACL for a Project cannot be deleted, you must individually update or revoke the permissions for each user or group.

• synGetAcl(instance, principal_id=NULL, check_benefactor=TRUE, synapse_client=NULL): Get the ACL that a user or group has on an Entity.

• synGetPermissions(instance, synapse_client=NULL): Get the permissions that the caller has on an Entity.

• synGetSchema(instance, synapse_client=NULL): Get the JSON schema bound to the entity.

• synGetSchemaDerivedKeys(instance, synapse_client=NULL): Retrieve derived JSON schema keys for the entity.

• synListAcl(instance, recursive=FALSE, include_container_content=FALSE, target_entity_types=NULL, log_tree=FALSE, synapse_client=NULL): List the Access Control Lists (ACLs) for this entity and optionally its children.
  
  This function returns the local sharing settings for the entity and optionally its children. It provides a mapping of all ACLs for the given container/entity.
  
  Important Note: This function returns the LOCAL sharing settings only, not the effective permissions that each Synapse User ID/Team has on the entities. More permissive permissions could be granted via a Team that the user has access to that has permissions on the entity, or through inheritance from parent entities.

• synQuery(query, include_row_id_and_row_version=TRUE, convert_to_datetime=FALSE, download_location=NULL, quote_character="\"", escape_character=r"(\)", line_end="\n", separator=",", header=TRUE, timeout=250L, synapse_client=NULL): Query for data on a table stored in Synapse. The results will always be returned as a data frame unless you specify a download_location in which case the results will be downloaded to that location. There are a number of arguments that you may pass to this function depending on if you are getting the results back as a data frame or downloading the results to a file.

• synQueryPartMask(query, part_mask, timeout=250L, synapse_client=NULL): Query for data on a table stored in Synapse. This is a more advanced use case of the synQuery() function that allows you to determine what additional metadata about the table or query should also be returned. If you do not need this additional information then you are better off using the synQuery() function.
  
  The query for this method uses this Rest API: https://rest-docs.synapse.org/rest/POST/entity/id/table/query/async/start.html

• synReorderColumn(instance, name, index): Reorder a column in the EntityView. Note that this does not store the column in Synapse. You must call the synStore() function on this EntityView instance to store the column in Synapse. This is a convenience function to eliminate the need to manually reorder the named list stored in the $columns attribute.
  
  You must ensure that the index is within the bounds of the number of columns in the EntityView. If you pass in an index that is out of bounds the column will be added to the end of the list.

• synSetPermissions(instance, principal_id=NULL, access_type=NULL, modify_benefactor=FALSE, warn_if_inherits=TRUE, overwrite=TRUE, synapse_client=NULL): Sets permission that a user or group has on an Entity. An Entity may have its own ACL or inherit its ACL from a benefactor.

• synSnapshot(instance, comment=NULL, label=NULL, include_activity=TRUE, associate_activity_to_new_version=TRUE, timeout=120L, synapse_client=NULL): Creates a snapshot of the EntityView entity. Synapse handles snapshot creation differently for Table- and View-like entities. View snapshots are created using the asynchronous job API.
  
  Making a snapshot of a view allows you to create an immutable version of the view at the time of the snapshot. This is useful to create checkpoints in time that you may go back and reference, or use in a publication. Snapshots are immutable and cannot be changed. They may only be deleted.

• synUnbindSchema(instance, synapse_client=NULL): Unbind the JSON schema bound to the entity.

• synUpdateRows(instance, values, primary_keys, dry_run=FALSE, rows_per_query=50000L, update_size_bytes=1992294.4, insert_size_bytes=943718400L, job_timeout=600L, date_columns=NULL, date_format=NULL, wait_for_eventually_consistent_view=FALSE, wait_for_eventually_consistent_view_timeout=600L, synapse_client=NULL): This method leverages the logic provided by synUpsertRows() to provide an interface for updating rows in a View-like entity. Update functionality will only work for values in custom columns within a View-like entity.
  
  Limitations:
  
  - When updating many rows the requests to Synapse will be chunked into smaller requests. The limit is 2MB per request. This chunking will happen automatically and should not be a concern for most users. If you are having issues with the request being too large you may lower the number of rows you are trying to update.
  - The primary_keys argument must contain at least one column.
  - The primary_keys argument cannot contain columns that are a LIST type.
  - The primary_keys argument cannot contain columns that are a JSON type.
  - The primary_keys columns must be present in the data being updated. An error is raised if a primary key column is missing.
  - The values in the primary_keys columns cannot be null. A null value cannot be used to match an existing row, so an error is raised if any row has a null value in a primary key column.
  - The values used as the primary_keys must be unique in the table. If there are multiple rows with the same values in the primary_keys the behavior is that an error will be raised.
  - The columns used in primary_keys cannot contain updated values. Since the values in these columns are used to determine if a row exists, they cannot be updated in the same transaction.

• synValidateSchema(instance, synapse_client=NULL): Validate the entity against the bound JSON schema.

Examples

## Not run: 
## Creating an EntityView of the files in a project
    library(synapser)
    synLogin()

    view = EntityView(
        name = "My File View",
        parent_id = "syn123",
        scope_ids = list("syn123"),
        view_type_mask = 1L  # 1 = files
    ) |> synStore()

    results = synQuery(query = sprintf("SELECT * FROM %s", view$id))
    print(results)

## End(Not run)

Description

An Evaluation is the core object of the Evaluation API, used to support collaborative data analysis challenges in Synapse.

An Evaluation object represents an evaluation queue in Synapse: https://rest-docs.synapse.org/rest/org/sagebionetworks/evaluation/model/Evaluation.html

Usage

Evaluation(id=NULL, etag=NULL, name=NULL, description=NULL, owner_id=NULL, created_on=NULL, content_source=NULL, submission_instructions_message=NULL, submission_receipt_message=NULL)

Arguments

Format

An S3-style class object.

Value

NULL

Methods

• Evaluation(id=NULL, etag=NULL, name=NULL, description=NULL, owner_id=NULL, created_on=NULL, content_source=NULL, submission_instructions_message=NULL, submission_receipt_message=NULL): Constructor for Evaluation

• synGetAcl(instance, synapse_client=NULL): Get the access control list (ACL) governing this evaluation.

• synGetAllEvaluations(access_type=NULL, active_only=NULL, evaluation_ids=NULL, offset=NULL, limit=NULL, synapse_client=NULL): Get a list of all Evaluations, within a given range.

• synGetAvailableEvaluations(active_only=NULL, evaluation_ids=NULL, offset=NULL, limit=NULL, synapse_client=NULL): Get a list of Evaluations to which the user has SUBMIT permission, within a given range.

• synGetEvaluationsByProject(project_id, access_type=NULL, active_only=NULL, evaluation_ids=NULL, offset=NULL, limit=NULL, synapse_client=NULL): Get Evaluations tied to a project.

• synGetPermissions(instance, synapse_client=NULL): Get the user permissions for this evaluation.

• synUpdateAcl(instance, principal_id=NULL, access_type=NULL, acl=NULL, synapse_client=NULL): Update the access control list (ACL) for this evaluation.
  
  You can either:
  1. Provide a principal_id and access_type list to update permissions for a specific user/team
  2. Provide a complete ACL named list to update all permissions at once
  
  To remove a principal from the ACL completely, provide an empty list for access_type.
  
  The available access types are:
  
  - "CREATE"
  - "SUBMIT"
  - "READ_PRIVATE_SUBMISSION"
  - "DELETE_SUBMISSION"
  - "UPDATE_SUBMISSION"
  - "CHANGE_PERMISSIONS"
  - "READ"
  - "DELETE"
  - "UPDATE"

Examples

## Not run: 
## Example 1: Create a new evaluation in a project
    # Create a new evaluation on Synapse by storing an evaluation object with the required fields. If there are any fields missing, an error will be raised.
    library(synapser)
    synLogin()

    evaluation = Evaluation(
        name = "My Challenge Evaluation",
        description = "Evaluation for my data challenge",
        content_source = "syn123456",
        submission_instructions_message = "Submit CSV files only",
        submission_receipt_message = "Thank you for your submission!"
    )
    created = evaluation |> synStore()

## Example 2: Get an evaluation by ID and by name
    library(synapser)
    synLogin()

    # Get an evaluation by ID
    evaluation_by_id = Evaluation(id = "9999999") |> synGet()

    # Get an evaluation by name
    evaluation_by_name = Evaluation(name = "My Challenge Evaluation") |> synGet()

## Example 3: Update an existing evaluation retrieved from Synapse by ID
    # You can use synStore() to create and update evaluations.
    library(synapser)
    synLogin()

    evaluation = synGetAllEvaluations(evaluation_ids = list("9999999"))[[1]]
    evaluation$description = "Updated description for my evaluation"
    updated = evaluation |> synStore()

## Example 4: Retrieve and update the ACL of an evaluation
    library(synapser)
    synLogin()

    evaluation = synGetAllEvaluations(evaluation_ids = list("9999999"))[[1]]
    acl = evaluation |> synGetAcl()

    # Let's grant this team READ and SUBMIT permissions
    team_id = "123456"
    evaluation |> synUpdateAcl(principal_id = team_id, access_type = list("READ", "SUBMIT"))

    # Now let's revoke all permissions from this team
    team_to_revoke_from = "654321"
    evaluation |> synUpdateAcl(principal_id = team_to_revoke_from, access_type = list())

## Example 5: Delete an evaluation
    library(synapser)
    synLogin()

    evaluation = synGetAllEvaluations(evaluation_ids = list("9999999"))[[1]]
    evaluation |> synDelete()

## End(Not run)

Description

A file within Synapse.

Usage

File(id=NULL, name=NULL, path=NULL, description=NULL, parent_id=NULL, version_label=NULL, version_comment=NULL, data_file_handle_id=NULL, external_url=NULL, activity=NULL, annotations=list(), content_type=NULL, content_size=NULL, content_md5=NULL, create_or_update=TRUE, force_version=TRUE, is_restricted=FALSE, merge_existing_annotations=TRUE, associate_activity_to_new_version=FALSE, synapse_store=TRUE, download_file=TRUE, if_collision="keep.both", synapse_container_limit=NULL, etag=NULL, created_on=NULL, modified_on=NULL, created_by=NULL, modified_by=NULL, version_number=NULL, is_latest_version=NULL, file_handle=NULL)

Arguments

Format

An S3-style class object.

Value

NULL

Methods

• File(id=NULL, name=NULL, path=NULL, description=NULL, parent_id=NULL, version_label=NULL, version_comment=NULL, data_file_handle_id=NULL, external_url=NULL, activity=NULL, annotations=list(), content_type=NULL, content_size=NULL, content_md5=NULL, create_or_update=TRUE, force_version=TRUE, is_restricted=FALSE, merge_existing_annotations=TRUE, associate_activity_to_new_version=FALSE, synapse_store=TRUE, download_file=TRUE, if_collision="keep.both", synapse_container_limit=NULL, etag=NULL, created_on=NULL, modified_on=NULL, created_by=NULL, modified_by=NULL, version_number=NULL, is_latest_version=NULL, file_handle=NULL): Constructor for File

• synBindSchema(instance, json_schema_uri, enable_derived_annotations=FALSE, synapse_client=NULL): Bind a JSON schema to the entity.

• synChangeMetadata(instance, name=NULL, download_as=NULL, content_type=NULL, synapse_client=NULL): Change File Entity metadata for properties that are immutable after creation through the store method.

• synCopy(instance, parent_id, update_existing=FALSE, copy_annotations=TRUE, copy_activity="traceback", synapse_client=NULL): Copy the file to another Synapse location. Defaults to the latest version of the file, or the version_number specified in the instance.

• synDeletePermissions(instance, include_self=TRUE, include_container_content=FALSE, recursive=FALSE, target_entity_types=NULL, dry_run=FALSE, show_acl_details=TRUE, show_files_in_containers=TRUE, synapse_client=NULL): Delete the entire local Access Control List (ACL) for a given Entity. This is not scoped to a specific user or group, but rather removes all permissions associated with the Entity. After this operation, the Entity will inherit permissions from its benefactor, which is typically its parent entity or the Project it belongs to.

  In order to remove permissions for a specific user or group, you should use the synSetPermissions() function with the access_type set to an empty list.

  By default, Entities such as FileEntity and Folder inherit their permission from their containing Project. For such Entities the Project is the Entity's 'benefactor'. This permission inheritance can be overridden by creating an ACL for the Entity. When this occurs the Entity becomes its own benefactor and all permission are determined by its own ACL.

  If the ACL of an Entity is deleted, then its benefactor will automatically be set to its parent's benefactor.

  Special notice for Projects: The ACL for a Project cannot be deleted, you must individually update or revoke the permissions for each user or group.

• synGetFromId(cls, synapse_id, synapse_client=NULL): Wrapper for synGet.

• synGetFromPath(cls, path, synapse_client=NULL): Get the file from Synapse. If the path of the file matches multiple files within Synapse the first one found will be returned. The other matching files will be printed to the console.

  Wrapper for synGet.

• synGetAcl(instance, principal_id=NULL, check_benefactor=TRUE, synapse_client=NULL): Get the ACL that a user or group has on an Entity.

• synGetPermissions(instance, synapse_client=NULL): Get the permissions that the caller has on an Entity.

• synGetSchema(instance, synapse_client=NULL): Get the JSON schema bound to the entity.

• synGetSchemaDerivedKeys(instance, synapse_client=NULL): Retrieve derived JSON schema keys for the entity.

• synListAcl(instance, recursive=FALSE, include_container_content=FALSE, target_entity_types=NULL, log_tree=FALSE, synapse_client=NULL): List the Access Control Lists (ACLs) for this entity and optionally its children.

  This function returns the local sharing settings for the entity and optionally its children. It provides a mapping of all ACLs for the given container/entity.

  Important Note: This function returns the LOCAL sharing settings only, not the effective permissions that each Synapse User ID/Team has on the entities. More permissive permissions could be granted via a Team that the user has access to that has permissions on the entity, or through inheritance from parent entities.

• synSetPermissions(instance, principal_id=NULL, access_type=NULL, modify_benefactor=FALSE, warn_if_inherits=TRUE, overwrite=TRUE, synapse_client=NULL): Sets permission that a user or group has on an Entity. An Entity may have its own ACL or inherit its ACL from a benefactor.

• synUnbindSchema(instance, synapse_client=NULL): Unbind the JSON schema bound to the entity.

• synValidateSchema(instance, synapse_client=NULL): Validate the entity against the bound JSON schema.

Examples

## Not run: 
## Example 1: Uploading a file
    library(synapser)
    synLogin()

    file = File(
        path = "/path/to/file.txt",
        parent_id = "syn123",
        description = "My data file",
        annotations = list(species = "Homo sapiens")
    ) |> synStore()
    print(file$id)

## Example 2: Getting a file's metadata without downloading it
    library(synapser)
    synLogin()

    file = File(id = "syn456") |> synGet(file_options = FileOptions(download_file = FALSE))
    print(file$name)

## End(Not run)

Description

Configuration options specific to File entities when using the factory methods.

This dataclass allows you to customize how File entities are handled during retrieval, including download behavior, file location, and collision handling.

Usage

FileOptions(download_file=TRUE, download_location=NULL, if_collision="keep.both")

Arguments

Format

An S3-style class object.

Value

NULL

Methods

• FileOptions(download_file=TRUE, download_location=NULL, if_collision="keep.both"): Constructor for FileOptions

Examples

## Not run: 
    # Configure file download options:
    library(synapser)

    # Download file to specific location with overwrite
    file_options = FileOptions(
        download_file = TRUE,
        download_location = "/path/to/downloads/",
        if_collision = "overwrite.local"
    )

    # Only retrieve metadata, don't download file content
    metadata_only = FileOptions(download_file = FALSE)

## End(Not run)

Description

Folder is a hierarchical container for organizing data in Synapse.

Usage

Folder(id=NULL, name=NULL, parent_id=NULL, description=NULL, etag=NULL, created_on=NULL, modified_on=NULL, created_by=NULL, modified_by=NULL, files=list(), folders=list(), tables=list(), entityviews=list(), submissionviews=list(), datasets=list(), datasetcollections=list(), materializedviews=list(), virtualtables=list(), searchindexes=list(), annotations=list(), is_restricted=FALSE, create_or_update=TRUE)

Arguments

Format

An S3-style class object.

Value

NULL

Methods

• Folder(id=NULL, name=NULL, parent_id=NULL, description=NULL, etag=NULL, created_on=NULL, modified_on=NULL, created_by=NULL, modified_by=NULL, files=list(), folders=list(), tables=list(), entityviews=list(), submissionviews=list(), datasets=list(), datasetcollections=list(), materializedviews=list(), virtualtables=list(), searchindexes=list(), annotations=list(), is_restricted=FALSE, create_or_update=TRUE): Constructor for Folder

• synBindSchema(instance, json_schema_uri, enable_derived_annotations=FALSE, synapse_client=NULL): Bind a JSON schema to the entity.

• synCopy(instance, parent_id, copy_annotations=TRUE, exclude_types=NULL, file_update_existing=FALSE, file_copy_activity="traceback", synapse_client=NULL): Copy the folder to another Synapse location. This will recursively copy all Tables, Links, Files, and Folders within the folder.

• synDeletePermissions(instance, include_self=TRUE, include_container_content=FALSE, recursive=FALSE, target_entity_types=NULL, dry_run=FALSE, show_acl_details=TRUE, show_files_in_containers=TRUE, synapse_client=NULL): Delete the entire local Access Control List (ACL) for a given Entity. This is not scoped to a specific user or group, but rather removes all permissions associated with the Entity. After this operation, the Entity will inherit permissions from its benefactor, which is typically its parent entity or the Project it belongs to.

  In order to remove permissions for a specific user or group, you should use the synSetPermissions() function with the access_type set to an empty list.

  By default, Entities such as FileEntity and Folder inherit their permission from their containing Project. For such Entities the Project is the Entity's 'benefactor'. This permission inheritance can be overridden by creating an ACL for the Entity. When this occurs the Entity becomes its own benefactor and all permission are determined by its own ACL.

  If the ACL of an Entity is deleted, then its benefactor will automatically be set to its parent's benefactor.

  Special notice for Projects: The ACL for a Project cannot be deleted, you must individually update or revoke the permissions for each user or group.

• synDeleteProjectSetting(instance, setting_id, synapse_client=NULL): Delete a project setting by its setting ID.

• synFlattenFileList(instance): Recursively loop over all of the already retrieved files and folders and return a list of all files in the container.

• synGenerateSyncManifest(instance, directory_path, manifest_path, synapse_client=NULL): Walk a local directory, mirror its folder hierarchy under this container in Synapse, and write a CSV manifest ready for synSyncToSynapse().

  The manifest has two columns: path (absolute, symlink-resolved) and parentId (the Synapse ID of the file's containing folder). Existing Synapse folders with matching names and parents are reused. Directory symlinks inside directory_path are not followed; file symlinks record the symlink path and upload the target's contents. Zero-byte files are skipped with a warning — Synapse rejects empty files. I/O errors during walk are logged and skipped; an empty source directory produces a warning and a header-only manifest.

• synGetAcl(instance, principal_id=NULL, check_benefactor=TRUE, synapse_client=NULL): Get the ACL that a user or group has on an Entity.

• synGetInvalidValidation(instance, synapse_client=NULL): Get invalid JSON schema validation results for a container entity.

• synGetPermissions(instance, synapse_client=NULL): Get the permissions that the caller has on an Entity.

• synGetProjectSetting(instance, setting_type="upload", synapse_client=NULL): Get the project setting for this entity.

• synGetSchema(instance, synapse_client=NULL): Get the JSON schema bound to the entity.

• synGetSchemaDerivedKeys(instance, synapse_client=NULL): Retrieve derived JSON schema keys for the entity.

• synGetSchemaValidationStatistics(instance, synapse_client=NULL): Get validation statistics for a container entity.

• synGetStsStorageToken(instance, permission, output_format="json", min_remaining_life=NULL, synapse_client=NULL): Get STS (AWS Security Token Service) credentials for direct access to the storage location backing this entity. These credentials can be used with AWS tools such as the AWS CLI.

• synIndexFilesForMigration(instance, dest_storage_location_id, db_path=NULL, source_storage_location_ids=NULL, file_version_strategy="new", include_table_files=FALSE, continue_on_error=FALSE, synapse_client=NULL): Index files in this entity for migration to a new storage location.

  This is the first step in migrating files to a new storage location. After indexing, use synMigrateIndexedFiles() to perform the actual migration.

• synListAcl(instance, recursive=FALSE, include_container_content=FALSE, target_entity_types=NULL, log_tree=FALSE, synapse_client=NULL): List the Access Control Lists (ACLs) for this entity and optionally its children.

  This function returns the local sharing settings for the entity and optionally its children. It provides a mapping of all ACLs for the given container/entity.

  Important Note: This function returns the LOCAL sharing settings only, not the effective permissions that each Synapse User ID/Team has on the entities. More permissive permissions could be granted via a Team that the user has access to that has permissions on the entity, or through inheritance from parent entities.

• synMapDirectoryToAllContainedFiles(instance, root_path): Recursively loop over all of the already retrieved files and folders. Then return back a named list where the key is the path to the directory at each level. The value is a list of all files in that directory AND all files in the child directories.

  This is used during the creation of the manifest TSV file during the syncFromSynapse utility function.

• synMigrateIndexedFiles(instance, db_path, create_table_snapshots=TRUE, continue_on_error=FALSE, force=FALSE, synapse_client=NULL): Migrate files that have been indexed with synIndexFilesForMigration().

  This is the second step in migrating files to a new storage location. Files must first be indexed using synIndexFilesForMigration().

  Interactive confirmation: When called from an interactive shell and force=FALSE (the default), this function will print the number of items queued for migration and prompt for confirmation before proceeding. If standard output is not connected to an interactive terminal (e.g. a script or CI environment), migration is aborted unless force=TRUE is set.

• synSetPermissions(instance, principal_id=NULL, access_type=NULL, modify_benefactor=FALSE, warn_if_inherits=TRUE, overwrite=TRUE, synapse_client=NULL): Sets permission that a user or group has on an Entity. An Entity may have its own ACL or inherit its ACL from a benefactor.

• synSetStorageLocation(instance, storage_location_id=1L, synapse_client=NULL): Set the upload storage location for this entity. This configures where files uploaded to this entity will be stored.

  This is a destructive update. The provided storage_location_id value(s) will replace any storage locations previously configured on this entity. To add a storage location without removing existing ones, first retrieve the current setting with synGetProjectSetting(), then pass its existing locations together with the new ID as storage_location_id. The first ID in the list is the default upload destination.

• synSyncFromSynapse(instance, path=NULL, recursive=TRUE, download_file=TRUE, if_collision="overwrite.local", failure_strategy="LOG_EXCEPTION", include_activity=TRUE, follow_link=FALSE, link_hops=1L, queue=NULL, include_types=NULL, manifest="all", synapse_client=NULL): Sync this container and all possible sub-folders from Synapse. By default this will download the files that are found and it will populate the files and folders attributes with the found files and folders, along with all other entity types (tables, entityviews, etc.) present in the container. If you only want to retrieve the full tree of metadata about your container specify download_file as FALSE.

  This works similar to the Python synapseutils.syncFromSynapse utility function, and generates a manifest.csv file in each synced directory. The manifest uses CSV format with parentId and ID columns, interoperable with the Synapse UI download cart and synDownloadListFiles() output.

  Supports syncing Files, Folders, Tables, EntityViews, SubmissionViews, Datasets, DatasetCollections, MaterializedViews, and VirtualTables from Synapse. The metadata for these entity types will be populated in their respective attributes (files, folders, tables, entityviews, submissionviews, datasets, datasetcollections, materializedviews, virtualtables) if they are found within the container.

• synSyncToSynapse(instance, manifest_path, dry_run=FALSE, send_messages=TRUE, retries=4L, merge_existing_annotations=TRUE, associate_activity_to_new_version=FALSE, synapse_client=NULL): Upload files to Synapse using a manifest CSV file.

  Accepts manifests produced by synSyncFromSynapse(), synDownloadListFiles(), or the Synapse UI download cart. The manifest must have at minimum a path and parentId column. All other columns that are not part of the standard manifest column set are treated as file annotations.

  Standard manifest columns: ID, name, parentId, contentType, path, synapseStore, activityName, activityDescription, forceVersion, used, executed

• synUnbindSchema(instance, synapse_client=NULL): Unbind the JSON schema bound to the entity.

• synValidateSchema(instance, synapse_client=NULL): Validate the entity against the bound JSON schema.

• synWalk(instance, follow_link=FALSE, include_types=NULL, recursive=TRUE, display_ascii_tree=FALSE, synapse_client=NULL): Traverse through the hierarchy of entities stored under this container. Mimics os.walk() behavior but yields EntityHeader objects, with optional ASCII tree display that continues printing as the walk progresses.

Examples

## Not run: 
## Example 1: Creating a folder
    library(synapser)
    synLogin()

    folder = Folder(name = "My Folder", parent_id = "syn123") |> synStore()
    print(folder$id)

## Example 2: Listing the contents of a folder
    library(synapser)
    synLogin()

    folder = Folder(id = "syn456") |> synSyncFromSynapse(download_file = FALSE, recursive = FALSE)
    for (file in folder$files) {
        print(file$name)
    }

## End(Not run)

Description

A Link entity within Synapse that references another entity.

Represents a Synapse Link.

Usage

Link(name=NULL, description=NULL, id=NULL, etag=NULL, created_on=NULL, modified_on=NULL, created_by=NULL, modified_by=NULL, parent_id=NULL, target_id=NULL, target_version_number=NULL, links_to_class_name=NULL, activity=NULL, annotations=list(), concrete_type=NULL)

Arguments

Format

An S3-style class object.

Value

NULL

Methods

• Link(name=NULL, description=NULL, id=NULL, etag=NULL, created_on=NULL, modified_on=NULL, created_by=NULL, modified_by=NULL, parent_id=NULL, target_id=NULL, target_version_number=NULL, links_to_class_name=NULL, activity=NULL, annotations=list(), concrete_type=NULL): Constructor for Link

Examples

## Not run: 
## Creating a link to another entity
    library(synapser)
    synLogin()

    link = Link(name = "My Link", parent_id = "syn123", target_id = "syn456") |> synStore()
    print(link$id)

    # Link to a specific version of the target
    link = Link(
        name = "My Versioned Link",
        parent_id = "syn123",
        target_id = "syn456",
        target_version_number = 2L
    ) |> synStore()

## End(Not run)

Description

Configuration options specific to Link entities when using the factory methods.

This dataclass controls how Link entities are handled during retrieval, particularly whether the link should be followed to return the target entity or if the Link entity itself should be returned.

Usage

LinkOptions(follow_link=TRUE)

Arguments

Format

An S3-style class object.

Value

NULL

Methods

• LinkOptions(follow_link=TRUE): Constructor for LinkOptions

Note

- When follow_link=TRUE, the returned entity type depends on what the Link points to (could be File, Project, Folder, etc.)
- When follow_link=FALSE, a Link entity is always returned

Examples

## Not run: 
    # Configure link following behavior:
    library(synapser)

    # Follow the link and return the target entity
    follow_target = LinkOptions(follow_link = TRUE)

    # Return the Link entity itself
    return_link = LinkOptions(follow_link = FALSE)

## End(Not run)

Description

A materialized view is a type of table that is automatically built from a Synapse SQL query. Its content is read only and based off the defining_sql attribute. The SQL of the materialized view may contain JOIN clauses on multiple tables.

A MaterializedView object represents this concept in Synapse: <https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/table/MaterializedView.html>

Usage

MaterializedView(id=NULL, name=NULL, parent_id=NULL, activity=NULL, version_number=NULL, description=NULL, etag=NULL, created_on=NULL, modified_on=NULL, created_by=NULL, modified_by=NULL, version_label=NULL, version_comment=NULL, is_latest_version=NULL, columns=list(), is_search_enabled=NULL, defining_sql=NULL, annotations=list())

Arguments

Format

An S3-style class object.

Value

NULL

Methods

• MaterializedView(id=NULL, name=NULL, parent_id=NULL, activity=NULL, version_number=NULL, description=NULL, etag=NULL, created_on=NULL, modified_on=NULL, created_by=NULL, modified_by=NULL, version_label=NULL, version_comment=NULL, is_latest_version=NULL, columns=list(), is_search_enabled=NULL, defining_sql=NULL, annotations=list()): Constructor for MaterializedView

• synGetPermissions(instance, synapse_client=NULL): Get the permissions that the caller has on an Entity.

• synSetPermissions(instance, principal_id=NULL, access_type=NULL, modify_benefactor=FALSE, warn_if_inherits=TRUE, overwrite=TRUE, synapse_client=NULL): Sets permission that a user or group has on an Entity. An Entity may have its own ACL or inherit its ACL from a benefactor.

• synDeletePermissions(instance, include_self=TRUE, include_container_content=FALSE, recursive=FALSE, target_entity_types=NULL, dry_run=FALSE, show_acl_details=TRUE, show_files_in_containers=TRUE, synapse_client=NULL): Delete the entire local Access Control List (ACL) for a given Entity. This is not scoped to a specific user or group, but rather removes all permissions associated with the Entity. After this operation, the Entity will inherit permissions from its benefactor, which is typically its parent entity or the Project it belongs to.
  
  In order to remove permissions for a specific user or group, you should use the synSetPermissions() function with the access_type set to an empty list.
  
  By default, Entities such as FileEntity and Folder inherit their permission from their containing Project. For such Entities the Project is the Entity's 'benefactor'. This permission inheritance can be overridden by creating an ACL for the Entity. When this occurs the Entity becomes its own benefactor and all permission are determined by its own ACL.
  
  If the ACL of an Entity is deleted, then its benefactor will automatically be set to its parent's benefactor.
  
  Special notice for Projects: The ACL for a Project cannot be deleted, you must individually update or revoke the permissions for each user or group.

• synGetAcl(instance, principal_id=NULL, check_benefactor=TRUE, synapse_client=NULL): Get the ACL that a user or group has on an Entity.

• synListAcl(instance, recursive=FALSE, include_container_content=FALSE, target_entity_types=NULL, log_tree=FALSE, synapse_client=NULL): List the Access Control Lists (ACLs) for this entity and optionally its children.
  
  This function returns the local sharing settings for the entity and optionally its children. It provides a mapping of all ACLs for the given container/entity.
  
  Important Note: This function returns the LOCAL sharing settings only, not the effective permissions that each Synapse User ID/Team has on the entities. More permissive permissions could be granted via a Team that the user has access to that has permissions on the entity, or through inheritance from parent entities.

• synQuery(query, include_row_id_and_row_version=TRUE, convert_to_datetime=FALSE, download_location=NULL, quote_character="\"", escape_character=r"(\)", line_end="\n", separator=",", header=TRUE, timeout=250L, synapse_client=NULL): Query for data on a table stored in Synapse. The results will always be returned as a data frame unless you specify a download_location in which case the results will be downloaded to that location. There are a number of arguments that you may pass to this function depending on if you are getting the results back as a DataFrame or downloading the results to a file.

• synQueryPartMask(query, part_mask, timeout=250L, synapse_client=NULL): Query for data on a table stored in Synapse. This is a more advanced use case of the synQuery() function that allows you to determine what additional metadata about the table or query should also be returned. If you do not need this additional information then you are better off using the synQuery() function.
  
  The query for this method uses this Rest API:
  <https://rest-docs.synapse.org/rest/POST/entity/id/table/query/async/start.html>

Examples

## Not run: 
## Example 1: Create a new materialized view with a defining SQL query.
    library(synapser)
    synLogin()

    materialized_view = MaterializedView(
        name = "My Materialized View",
        description = "A test materialized view",
        parent_id = "syn12345",
        defining_sql = "SELECT * FROM syn67890"
    ) |> synStore()
    print(sprintf("Created Materialized View with ID: %s", materialized_view$id))

## Example 2: Update the defining SQL of an existing materialized view.
    library(synapser)
    synLogin()

    materialized_view = MaterializedView(id = "syn12345") |>
        synGet() |>
        synSetProperties(defining_sql = "SELECT column1, column2 FROM syn67890") |>
        synStore()
    print("Updated Materialized View defining SQL.")

## Example 3: Delete a materialized view.
    library(synapser)
    synLogin()

    MaterializedView(id = "syn12345") |> synDelete()
    print("Deleted Materialized View.")

## Example 4: Query data from a materialized view.
    library(synapser)
    synLogin()

    query_result = synQuery(query = "SELECT * FROM syn12345")
    print(query_result)

## Example 5: Retrieve and update annotations for a materialized view.
    library(synapser)
    synLogin()

    materialized_view = MaterializedView(id = "syn12345") |> synGet()
    materialized_view = materialized_view |>
        synSetProperties(
            annotations = append(
                materialized_view$annotations,
                list(key1 = "value1", key2 = "value2")
            )
        ) |>
        synStore()
    print("Updated annotations for Materialized View.")

## Example 6: Create a materialized view with a JOIN clause.
    library(synapser)
    synLogin()

    defining_sql = "
    SELECT t1.column1 AS new_column1, t2.column2 AS new_column2
    FROM syn12345 t1
    JOIN syn67890 t2
    ON t1.id = t2.foreign_id
    "

    materialized_view = MaterializedView(
        name = "Join Materialized View",
        description = "A materialized view with a JOIN clause",
        parent_id = "syn11111",
        defining_sql = defining_sql
    ) |> synStore()
    print(sprintf("Created Materialized View with ID: %s", materialized_view$id))

## Example 7: Create a materialized view with a LEFT JOIN clause.
    library(synapser)
    synLogin()

    defining_sql = "
    SELECT t1.column1 AS new_column1, t2.column2 AS new_column2
    FROM syn12345 t1
    LEFT JOIN syn67890 t2
    ON t1.id = t2.foreign_id
    "

    materialized_view = MaterializedView(
        name = "Left Join Materialized View",
        description = "A materialized view with a LEFT JOIN clause",
        parent_id = "syn11111",
        defining_sql = defining_sql
    ) |> synStore()
    print(sprintf("Created Materialized View with ID: %s", materialized_view$id))

## Example 8: Create a materialized view with a RIGHT JOIN clause.
    library(synapser)
    synLogin()

    defining_sql = "
    SELECT t1.column1 AS new_column1, t2.column2 AS new_column2
    FROM syn12345 t1
    RIGHT JOIN syn67890 t2
    ON t1.id = t2.foreign_id
    "

    materialized_view = MaterializedView(
        name = "Right Join Materialized View",
        description = "A materialized view with a RIGHT JOIN clause",
        parent_id = "syn11111",
        defining_sql = defining_sql
    ) |> synStore()
    print(sprintf("Created Materialized View with ID: %s", materialized_view$id))

## Example 9: Create a materialized view with a UNION clause.
    library(synapser)
    synLogin()

    defining_sql = "
    SELECT column1 AS new_column1, column2 AS new_column2
    FROM syn12345
    UNION
    SELECT column1 AS new_column1, column2 AS new_column2
    FROM syn67890
    "

    materialized_view = MaterializedView(
        name = "Union Materialized View",
        description = "A materialized view with a UNION clause",
        parent_id = "syn11111",
        defining_sql = defining_sql
    ) |> synStore()
    print(sprintf("Created Materialized View with ID: %s", materialized_view$id))

## End(Not run)

Description

Represents an Organization.

Usage

Organization(name=NULL, id=NULL, created_on=NULL, created_by=NULL)

Arguments

Format

An S3-style class object.

Value

NULL

Methods

• Organization(name=NULL, id=NULL, created_on=NULL, created_by=NULL): Constructor for Organization

• synGetAcl(instance, synapse_client=NULL): Gets the ACL for this organization

• synGetJsonSchemas(instance, synapse_client=NULL): Gets the JSON Schemas that are part of this organization

• synUpdateAcl(instance, principal_id, access_type, synapse_client=NULL): Updates the ACL for a principal for this organization

Examples

## Not run: 
## Creating a JSON schema organization
    library(synapser)
    synLogin()

    org = Organization(name = "myUniqueOrgName") |> synStore()
    print(org$id)

    # List the JSON schemas in the organization
    schemas = org |> synGetJsonSchemas()

## End(Not run)

Description

A Project is a top-level container for organizing data in Synapse.

Usage

Project(id=NULL, name=NULL, description=NULL, etag=NULL, created_on=NULL, modified_on=NULL, created_by=NULL, modified_by=NULL, alias=NULL, files=list(), folders=list(), tables=list(), entityviews=list(), submissionviews=list(), datasets=list(), datasetcollections=list(), materializedviews=list(), virtualtables=list(), searchindexes=list(), annotations=list(), create_or_update=TRUE, parent_id=NULL)

Arguments

Format

An S3-style class object.

Value

NULL

Methods

• Project(id=NULL, name=NULL, description=NULL, etag=NULL, created_on=NULL, modified_on=NULL, created_by=NULL, modified_by=NULL, alias=NULL, files=list(), folders=list(), tables=list(), entityviews=list(), submissionviews=list(), datasets=list(), datasetcollections=list(), materializedviews=list(), virtualtables=list(), searchindexes=list(), annotations=list(), create_or_update=TRUE, parent_id=NULL): Constructor for Project

• synBindSchema(instance, json_schema_uri, enable_derived_annotations=FALSE, synapse_client=NULL): Bind a JSON schema to the entity.

• synCopy(instance, destination_id, copy_annotations=TRUE, copy_wiki=TRUE, exclude_types=NULL, file_update_existing=FALSE, file_copy_activity="traceback", synapse_client=NULL): You must have already created the Project you will be copying to. It will have its own Synapse ID and unique name that you will use as the destination_id.
  
  Copy the project to another Synapse project. This will recursively copy all Tables, Links, Files, and Folders within the project.

• synDeletePermissions(instance, include_self=TRUE, include_container_content=FALSE, recursive=FALSE, target_entity_types=NULL, dry_run=FALSE, show_acl_details=TRUE, show_files_in_containers=TRUE, synapse_client=NULL): Delete the entire local Access Control List (ACL) for a given Entity. This is not scoped to a specific user or group, but rather removes all permissions associated with the Entity. After this operation, the Entity will inherit permissions from its benefactor, which is typically its parent entity or the Project it belongs to.
  
  In order to remove permissions for a specific user or group, you should use the synSetPermissions() function with the access_type set to an empty list.
  
  By default, Entities such as FileEntity and Folder inherit their permission from their containing Project. For such Entities the Project is the Entity's 'benefactor'. This permission inheritance can be overridden by creating an ACL for the Entity. When this occurs the Entity becomes its own benefactor and all permission are determined by its own ACL.
  
  If the ACL of an Entity is deleted, then its benefactor will automatically be set to its parent's benefactor.
  
  Special notice for Projects: The ACL for a Project cannot be deleted, you must individually update or revoke the permissions for each user or group.

• synDeleteProjectSetting(instance, setting_id, synapse_client=NULL): Delete a project setting by its setting ID.

• synFlattenFileList(instance): Recursively loop over all of the already retrieved files and folders and return a list of all files in the container.

• synGenerateSyncManifest(instance, directory_path, manifest_path, synapse_client=NULL): Walk a local directory, mirror its folder hierarchy under this container in Synapse, and write a CSV manifest ready for synSyncToSynapse().
  
  The manifest has two columns: path (absolute, symlink-resolved) and parentId (the Synapse ID of the file's containing folder). Existing Synapse folders with matching names and parents are reused. Directory symlinks inside directory_path are not followed; file symlinks record the symlink path and upload the target's contents. Zero-byte files are skipped with a warning — Synapse rejects empty files. I/O errors during walk are logged and skipped; an empty source directory produces a warning and a header-only manifest.

• synGetAcl(instance, principal_id=NULL, check_benefactor=TRUE, synapse_client=NULL): Get the ACL that a user or group has on an Entity.

• synGetInvalidValidation(instance, synapse_client=NULL): Get invalid JSON schema validation results for the child entities of a container entity.

• synGetPermissions(instance, synapse_client=NULL): Get the permissions that the caller has on an Entity.

• synGetProjectSetting(instance, setting_type="upload", synapse_client=NULL): Get the project setting for this entity.

• synGetSchema(instance, synapse_client=NULL): Get the JSON schema bound to the entity.

• synGetSchemaDerivedKeys(instance, synapse_client=NULL): Retrieve derived JSON schema keys for the entity.

• synGetSchemaValidationStatistics(instance, synapse_client=NULL): Get validation statistics for a container entity.

• synGetStsStorageToken(instance, permission, output_format="json", min_remaining_life=NULL, synapse_client=NULL): Get STS (AWS Security Token Service) credentials for direct access to the storage location backing this entity. These credentials can be used with AWS tools such as the AWS CLI.

• synIndexFilesForMigration(instance, dest_storage_location_id, db_path=NULL, source_storage_location_ids=NULL, file_version_strategy="new", include_table_files=FALSE, continue_on_error=FALSE, synapse_client=NULL): Index files in this entity for migration to a new storage location.
  
  This is the first step in migrating files to a new storage location. After indexing, use synMigrateIndexedFiles() to perform the actual migration.

• synListAcl(instance, recursive=FALSE, include_container_content=FALSE, target_entity_types=NULL, log_tree=FALSE, synapse_client=NULL): List the Access Control Lists (ACLs) for this entity and optionally its children.
  
  This function returns the local sharing settings for the entity and optionally its children. It provides a mapping of all ACLs for the given container/entity.
  
  Important Note: This function returns the LOCAL sharing settings only, not the effective permissions that each Synapse User ID/Team has on the entities. More permissive permissions could be granted via a Team that the user has access to that has permissions on the entity, or through inheritance from parent entities.

• synMapDirectoryToAllContainedFiles(instance, root_path): Recursively loop over all of the already retrieved files and folders. Then return back a named list where the key is the path to the directory at each level. The value is a list of all files in that directory AND all files in the child directories.
  
  This is used during the creation of the manifest TSV file during the syncFromSynapse utility function.

• synMigrateIndexedFiles(instance, db_path, create_table_snapshots=TRUE, continue_on_error=FALSE, force=FALSE, synapse_client=NULL): Migrate files that have been indexed with synIndexFilesForMigration().
  
  This is the second step in migrating files to a new storage location. Files must first be indexed using synIndexFilesForMigration().
  
  Interactive confirmation: When called from an interactive shell and force=FALSE (the default), this function will print the number of items queued for migration and prompt for confirmation before proceeding. If standard output is not connected to an interactive terminal (e.g. a script or CI environment), migration is aborted unless force=TRUE is set.

• synSetPermissions(instance, principal_id=NULL, access_type=NULL, modify_benefactor=FALSE, warn_if_inherits=TRUE, overwrite=TRUE, synapse_client=NULL): Sets permission that a user or group has on an Entity. An Entity may have its own ACL or inherit its ACL from a benefactor.

• synSetStorageLocation(instance, storage_location_id=1L, synapse_client=NULL): Set the upload storage location for this entity. This configures where files uploaded to this entity will be stored.
  
  This is a destructive update. The provided storage_location_id value(s) will replace any storage locations previously configured on this entity. To add a storage location without removing existing ones, first retrieve the current setting with synGetProjectSetting(), then pass its existing locations together with the new ID as storage_location_id. The first ID in the list is the default upload destination.

• synSyncFromSynapse(instance, path=NULL, recursive=TRUE, download_file=TRUE, if_collision="overwrite.local", failure_strategy="LOG_EXCEPTION", include_activity=TRUE, follow_link=FALSE, link_hops=1L, queue=NULL, include_types=NULL, manifest="all", synapse_client=NULL): Sync this container and all possible sub-folders from Synapse. By default this will download the files that are found and it will populate the files and folders attributes with the found files and folders, along with all other entity types (tables, entityviews, etc.) present in the container. If you only want to retrieve the full tree of metadata about your container specify download_file as FALSE.
  
  This works similarly to the legacy synapseutils.syncFromSynapse utility function, and generates a manifest.csv file in each synced directory. The manifest uses CSV format with parentId and ID columns, interoperable with the Synapse UI download cart and synDownloadListFiles() output.
  
  Supports syncing Files, Folders, Tables, EntityViews, SubmissionViews, Datasets, DatasetCollections, MaterializedViews, and VirtualTables from Synapse. The metadata for these entity types will be populated in their respective attributes (files, folders, tables, entityviews, submissionviews, datasets, datasetcollections, materializedviews, virtualtables) if they are found within the container.

• synSyncToSynapse(instance, manifest_path, dry_run=FALSE, send_messages=TRUE, retries=4L, merge_existing_annotations=TRUE, associate_activity_to_new_version=FALSE, synapse_client=NULL): Upload files to Synapse using a manifest CSV file.
  
  Accepts manifests produced by synSyncFromSynapse(), synDownloadListFiles(), or the Synapse UI download cart. The manifest must have at minimum a path and parentId column. All other columns that are not part of the standard manifest column set are treated as file annotations.
  
  Standard manifest columns: ID, name, parentId, contentType, path, synapseStore, activityName, activityDescription, forceVersion, used, executed

• synUnbindSchema(instance, synapse_client=NULL): Unbind the JSON schema bound to the entity.

• synValidateSchema(instance, synapse_client=NULL): Validate the entity against the bound JSON schema.

• synWalk(instance, follow_link=FALSE, include_types=NULL, recursive=TRUE, display_ascii_tree=FALSE, synapse_client=NULL): Traverse through the hierarchy of entities stored under this container. Mimics os.walk() behavior but yields EntityHeader objects, with optional ASCII tree display that continues printing as the walk progresses.

Examples

## Not run: 
## Example 1: Creating a project
    # This example shows how to create a project
    library(synapser)
    synLogin()

    my_annotations = list(
        my_single_key_string = "a",
        my_key_string = list("b", "a", "c")
    )
    project = Project(
        name = "My unique project name",
        annotations = my_annotations,
        description = "This is a project with random data."
    )

    project = project |> synStore()

    project

## Example 2: Storing several files to a project
    # This example shows how to store several files to a project
    file_1 = File(
        path = path_to_file_1,
        name = name_of_file_1
    )
    file_2 = File(
        path = path_to_file_2,
        name = name_of_file_2
    )
    project$files = list(file_1, file_2)
    project = project |> synStore()

## End(Not run)

Description

A storage location setting describes where files are uploaded to and downloaded from via Synapse. Storage location settings may be created for external locations, such as user-owned Amazon S3 buckets, Google Cloud Storage buckets, SFTP servers, or proxy storage.

Usage

StorageLocation(storage_location_id=NULL, storage_type=NULL, concrete_type=NULL, banner=NULL, description=NULL, bucket=NULL, base_key=NULL, sts_enabled=FALSE, endpoint_url="https://s3.amazonaws.com", url=NULL, supports_subfolders=FALSE, proxy_url=NULL, secret_key=NULL, benefactor_id=NULL, upload_type=NULL, etag=NULL, created_on=NULL, created_by=NULL)

Arguments

Format

An S3-style class object.

Value

NULL

Methods

• StorageLocation(storage_location_id=NULL, storage_type=NULL, concrete_type=NULL, banner=NULL, description=NULL, bucket=NULL, base_key=NULL, sts_enabled=FALSE, endpoint_url="https://s3.amazonaws.com", url=NULL, supports_subfolders=FALSE, proxy_url=NULL, secret_key=NULL, benefactor_id=NULL, upload_type=NULL, etag=NULL, created_on=NULL, created_by=NULL): Constructor for StorageLocation

Examples

## Not run: 
## Example 1: Creating an external S3 storage location
    # Create a storage location backed by your own S3 bucket:
    library(synapser)
    synLogin()

    storage = StorageLocation(
        storage_type = StorageLocationType(
            name = "EXTERNAL_S3",
            concrete_type = "ExternalS3StorageLocationSetting"
        ),
        bucket = "my-external-synapse-bucket",
        base_key = "path/within/bucket"
    ) |> synStore()

    print(sprintf("Storage location ID: %s", storage$storage_location_id))

## Example 2: Creating a Google Cloud storage location
    # Create a storage location backed by your own GCS bucket:
    library(synapser)
    synLogin()

    storage = StorageLocation(
        storage_type = StorageLocationType(
            name = "EXTERNAL_GOOGLE_CLOUD",
            concrete_type = "ExternalGoogleCloudStorageLocationSetting"
        ),
        bucket = "my-gcs-bucket",
        base_key = "path/within/bucket"
    ) |> synStore()

## Example 3: Retrieving a storage location by ID
    # Only the creator of a storage location can retrieve it by its ID.
    library(synapser)
    synLogin()

    storage = StorageLocation(storage_location_id = 12345L) |> synGet()
    print(sprintf("Type: %s, Bucket: %s", storage$storage_type$name, storage$bucket))

## End(Not run)

Description

Describes a Synapse storage location type.

Each instance is a distinct object identified by its name, so SFTP and HTTPS remain separate even though they share the same backend concreteType (ExternalStorageLocationSetting).

Usage

StorageLocationType(name, concrete_type)

Arguments

Format

An S3-style class object.

Value

NULL

Supported storage location types

A StorageLocationType is identified by both its name and its concrete_type, so construct it with one of the following pairs:

Methods

• StorageLocationType(name, concrete_type): Constructor for StorageLocationType

Examples

## Not run: 
## Use a storage location type when creating a storage location
    library(synapser)
    synLogin()

    external_s3 = StorageLocationType(
        name = "EXTERNAL_S3",
        concrete_type = "ExternalS3StorageLocationSetting"
    )
    storage = StorageLocation(
        storage_type = external_s3,
        bucket = "my-external-synapse-bucket"
    ) |> synStore()

## End(Not run)

Description

Options for storing container entities (Project, Folder).

Usage

StoreContainerOptions(failure_strategy=NULL)

Arguments

Format

An S3-style class object.

Value

NULL

Methods

• StoreContainerOptions(failure_strategy=NULL): Constructor for StoreContainerOptions

Examples

## Not run: 
## Using this class
    # Stop storing a folder's children as soon as one of them fails
    library(synapser)
    synLogin()

    folder = Folder(id = "syn123") |> synGet()
    folder = folder |> synStore(
        container_options = StoreContainerOptions(failure_strategy = "RAISE_EXCEPTION")
    )

## End(Not run)

Description

Options for storing File entities.

Usage

StoreFileOptions(synapse_store=NULL, content_type=NULL, merge_existing_annotations=NULL, associate_activity_to_new_version=NULL)

Arguments

Format

An S3-style class object.

Value

NULL

Methods

• StoreFileOptions(synapse_store=NULL, content_type=NULL, merge_existing_annotations=NULL, associate_activity_to_new_version=NULL): Constructor for StoreFileOptions

Examples

## Not run: 
## Using this class
    library(synapser)
    synLogin()

    file = File(path = "/path/to/file.txt", parent_id = "syn123")
    file = file |> synStore(
        file_options = StoreFileOptions(
            content_type = "text/plain",
            merge_existing_annotations = TRUE
        )
    )

## End(Not run)

Description

Options for storing Grid entities.

Usage

StoreGridOptions(attach_to_previous_session=FALSE, timeout=120L)

Arguments

Format

An S3-style class object.

Value

NULL

Methods

• StoreGridOptions(attach_to_previous_session=FALSE, timeout=120L): Constructor for StoreGridOptions

Examples

## Not run: 
## Using this class
    # Pass to synStore() through the grid_options argument when storing a Grid
    grid_options = StoreGridOptions(attach_to_previous_session = TRUE, timeout = 300L)

## End(Not run)

Description

Options for storing JSONSchema entities.

Usage

StoreJSONSchemaOptions(schema_body, version=NULL, dry_run=FALSE)

Arguments

Format

An S3-style class object.

Value

NULL

Methods

• StoreJSONSchemaOptions(schema_body, version=NULL, dry_run=FALSE): Constructor for StoreJSONSchemaOptions

Examples

## Not run: 
## Using this class
    library(synapser)
    synLogin()

    schema_definition = list(
        "$id" = "mySchema",
        type = "object",
        properties = list(foo = list(type = "string")),
        required = list("foo")
    )
    schema = JSONSchema(name = "my.schema", organization_name = "myUniqueOrgName") |> synStore(
        json_schema_options = StoreJSONSchemaOptions(schema_body = schema_definition, version = "0.0.1")
    )

## End(Not run)

Description

Options for storing Table-like entities.

Usage

StoreTableOptions(dry_run=FALSE, job_timeout=600L)

Arguments

Format

An S3-style class object.

Value

NULL

Methods

• StoreTableOptions(dry_run=FALSE, job_timeout=600L): Constructor for StoreTableOptions

Examples

## Not run: 
## Using this class
    # Preview a table schema change without applying it
    library(synapser)
    synLogin()

    table = Table(id = "syn123") |> synGet()
    table |> synAddColumn(Column(name = "new_column", column_type = "STRING"))
    table |> synStore(table_options = StoreTableOptions(dry_run = TRUE))

## End(Not run)

Description

A Submission object represents a Synapse Submission, which is created when a user submits an entity to an evaluation queue. https://rest-docs.synapse.org/rest/org/sagebionetworks/evaluation/model/Submission.html

Usage

Submission(id=NULL, user_id=NULL, submitter_alias=NULL, entity_id=NULL, version_number=NULL, evaluation_id=NULL, evaluation_round_id=NULL, name=NULL, created_on=NULL, team_id=NULL, contributors=list(), submission_status=NULL, entity_bundle_json=NULL, docker_repository_name=NULL, docker_digest=NULL, docker_tag=NULL, etag=NULL)

Arguments

Format

An S3-style class object.

Value

NULL

Methods

• Submission(id=NULL, user_id=NULL, submitter_alias=NULL, entity_id=NULL, version_number=NULL, evaluation_id=NULL, evaluation_round_id=NULL, name=NULL, created_on=NULL, team_id=NULL, contributors=list(), submission_status=NULL, entity_bundle_json=NULL, docker_repository_name=NULL, docker_digest=NULL, docker_tag=NULL, etag=NULL): Constructor for Submission

• synCancel(instance, synapse_client=NULL): Cancel a Submission. Only the user who created the Submission may cancel it.

• synGetEvaluationSubmissions(cls, evaluation_id, status=NULL, synapse_client=NULL): Retrieves all Submissions for a specified Evaluation queue.

• synGetSubmissionCount(evaluation_id, synapse_client=NULL): Gets the number of Submissions for a specified Evaluation queue.

• synGetUserSubmissions(cls, evaluation_id, synapse_client=NULL): Retrieves all user Submissions for a specified Evaluation queue.

Examples

## Not run: 
## Example 1: Create and store a new Submission.
    library(synapser)
    synLogin()

    # Create a new submission
    submission = Submission(
        entity_id = "syn123456",
        evaluation_id = "9999999",
        name = "My Submission"
    )

    # Store the submission
    stored_submission = submission |> synStore()
    print(sprintf("Created submission with ID: %s", stored_submission$id))

## Example 2: Retrieve a Submission.
    library(synapser)
    synLogin()

    submission = Submission(id = "9999999") |> synGet()
    print(submission)

## Example 3: Get all submissions for a user.
    library(synapser)
    synLogin()

    # Get submissions for the current user
    my_submissions = as.list(Submission() |> synGetUserSubmissions(
        evaluation_id = "9999999"
    ))
    print(sprintf("Found %d of my submissions", length(my_submissions)))

## Example 4: Delete a Submission.
    library(synapser)
    synLogin()

    Submission(id = "9999999") |> synDelete()
    print("Submission deleted successfully")

## End(Not run)

Description

A SubmissionBundle object represents a bundle containing a Synapse Submission and its accompanying SubmissionStatus. This bundle provides convenient access to both the submission data and its current status in a single object.

https://rest-docs.synapse.org/rest/org/sagebionetworks/evaluation/model/SubmissionBundle.html

Usage

SubmissionBundle(submission=NULL, submission_status=NULL)

Arguments

Format

An S3-style class object.

Value

NULL

Methods

• SubmissionBundle(submission=NULL, submission_status=NULL): Constructor for SubmissionBundle

• synGetEvaluationSubmissionBundles(cls, evaluation_id, status=NULL, synapse_client=NULL): Retrieves bundled Submissions and SubmissionStatuses for a given Evaluation.

• synGetUserSubmissionBundles(cls, evaluation_id, synapse_client=NULL): Retrieves all user bundled Submissions and SubmissionStatuses for a specified Evaluation.

Examples

## Not run: 
## Example 1: Retrieve submission bundles for an evaluation.
    library(synapser)
    synLogin()

    # Get all submission bundles for an evaluation
    bundles = SubmissionBundle() |> synGetEvaluationSubmissionBundles(
        evaluation_id = "9999999",
        status = "SCORED"
    )

    for (bundle in as.list(bundles)) {
        submission_id = if (is.null(bundle$submission)) "N/A" else bundle$submission$id
        status = if (is.null(bundle$submission_status)) "N/A" else bundle$submission_status$status
        print(sprintf("Submission ID: %s", submission_id))
        print(sprintf("Status: %s", status))
    }

## Example 2: Retrieve user submission bundles for an evaluation.
    library(synapser)
    synLogin()

    # Get current user's submission bundles for an evaluation
    user_bundles = SubmissionBundle() |> synGetUserSubmissionBundles(
        evaluation_id = "9999999"
    )

    for (bundle in as.list(user_bundles)) {
        print(sprintf("Submission ID: %s", bundle$submission$id))
        print(sprintf("Status: %s", bundle$submission_status$status))
    }

## End(Not run)

Description

A SubmissionStatus is a secondary, mutable object associated with a Submission. This object should be used to contain scoring data about the Submission. https://rest-docs.synapse.org/rest/org/sagebionetworks/evaluation/model/SubmissionStatus.html

Usage

SubmissionStatus(id=NULL, etag=NULL, modified_on=NULL, status=NULL, score=NULL, report=NULL, annotations=list(), submission_annotations=list(), private_status_annotations=TRUE, entity_id=NULL, version_number=NULL, status_version=NULL, can_cancel=FALSE, cancel_requested=FALSE)

Arguments

Format

An S3-style class object.

Value

NULL

Methods

• SubmissionStatus(id=NULL, etag=NULL, modified_on=NULL, status=NULL, score=NULL, report=NULL, annotations=list(), submission_annotations=list(), private_status_annotations=TRUE, entity_id=NULL, version_number=NULL, status_version=NULL, can_cancel=FALSE, cancel_requested=FALSE): Constructor for SubmissionStatus

• synBatchUpdateSubmissionStatuses(evaluation_id, statuses, is_first_batch=TRUE, is_last_batch=TRUE, batch_token=NULL, synapse_client=NULL): Update multiple SubmissionStatuses. The maximum batch size is 500.

• synGetAllSubmissionStatuses(evaluation_id, status=NULL, limit=10L, offset=0L, synapse_client=NULL): Gets a collection of SubmissionStatuses to a specified Evaluation.

Examples

## Not run: 
## Example 1: Retrieve and update a SubmissionStatus.
    # This example demonstrates the basic workflow of retrieving an existing submission status, updating its fields, and storing the changes back to Synapse.
    library(synapser)
    synLogin()

    # Get a submission status
    status = SubmissionStatus(id = "9999999") |> synGet()

    # Update the status
    status$status = "SCORED"
    status$submission_annotations = list(score = list(85.5), feedback = list("Good work!"))
    status = status |> synStore()
    print(status)

## Example 2: Get all submission statuses for an evaluation.
    # Retrieve multiple submission statuses for an evaluation queue with optional filtering.
    library(synapser)
    synLogin()

    # Get all RECEIVED statuses for an evaluation
    statuses = synGetAllSubmissionStatuses(
        evaluation_id = "9999999",
        status = "RECEIVED",
        limit = 100L
    )

    print(sprintf("Found %d submission statuses", length(statuses)))
    for (status in statuses) {
        print(sprintf("Status ID: %s, Status: %s", status$id, status$status))
    }

## Example 3: Batch update multiple submission statuses.
    # Efficiently update multiple submission statuses in a single operation.
    library(synapser)
    synLogin()

    # Retrieve statuses to update
    statuses = synGetAllSubmissionStatuses(
        evaluation_id = "9999999",
        status = "RECEIVED"
    )

    # Update each status
    for (status in statuses) {
        status$status = "SCORED"
        status$submission_annotations = list(
            validation_score = 95.0,
            comments = "Passed validation"
        )
    }

    # Batch update all statuses
    response = synBatchUpdateSubmissionStatuses(
        evaluation_id = "9999999",
        statuses = statuses
    )
    print(response)

## End(Not run)

Description

A SubmissionView object represents the metadata of a Synapse Submission View. <https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/table/SubmissionView.html>

Usage

SubmissionView(id=NULL, name=NULL, parent_id=NULL, activity=NULL, version_number=NULL, view_entity_type="submissionview", view_type_mask=NULL, include_default_columns=TRUE, description=NULL, etag=NULL, created_on=NULL, modified_on=NULL, created_by=NULL, modified_by=NULL, version_label=NULL, version_comment=NULL, is_latest_version=NULL, columns=list(), annotations=list(), is_search_enabled=NULL, scope_ids=list())

Arguments

library(synapser)
synLogin()

view = SubmissionView(id = "syn1234") |> synGet()
view$columns[["my_column"]]$column_type = "DOUBLE"
view = view |> synStore()

Format

An S3-style class object.

Value

NULL

Methods

• SubmissionView(id=NULL, name=NULL, parent_id=NULL, activity=NULL, version_number=NULL, view_entity_type="submissionview", view_type_mask=NULL, include_default_columns=TRUE, description=NULL, etag=NULL, created_on=NULL, modified_on=NULL, created_by=NULL, modified_by=NULL, version_label=NULL, version_comment=NULL, is_latest_version=NULL, columns=list(), annotations=list(), is_search_enabled=NULL, scope_ids=list()): Constructor for SubmissionView

• synAddColumn(instance, column, index=NULL): Add column(s) to the table. Note that this does not store the column(s) in Synapse. You must call the synStore() function on this SubmissionView instance to store the column(s) in Synapse. This is a convenience function to eliminate the need to manually add the column(s) to the $columns list.
  
  This function will add an item to the $columns attribute of the SubmissionView instance. $columns is a named list where the key is the name of the column and the value is the Column object.

• synDeleteColumn(instance, name): Mark a column for deletion. Note that this does not delete the column from Synapse. You must call the synStore() function on this SubmissionView instance to delete the column from Synapse. This is a convenience function to eliminate the need to manually delete the column from the named list and add it to the $_columns_to_delete attribute.

• synReorderColumn(instance, name, index): Reorder a column in the table. Note that this does not store the column in Synapse. You must call the synStore() function on this SubmissionView instance to store the column in Synapse. This is a convenience function to eliminate the need to manually reorder the named list stored in the $columns attribute.
  
  You must ensure that the index is within the bounds of the number of columns in the table. If you pass in an index that is out of bounds the column will be added to the end of the list.

• synGetPermissions(instance, synapse_client=NULL): Get the permissions that the caller has on an Entity.

• synSetPermissions(instance, principal_id=NULL, access_type=NULL, modify_benefactor=FALSE, warn_if_inherits=TRUE, overwrite=TRUE, synapse_client=NULL): Sets permission that a user or group has on an Entity. An Entity may have its own ACL or inherit its ACL from a benefactor.

• synDeletePermissions(instance, include_self=TRUE, include_container_content=FALSE, recursive=FALSE, target_entity_types=NULL, dry_run=FALSE, show_acl_details=TRUE, show_files_in_containers=TRUE, synapse_client=NULL): Delete the entire local Access Control List (ACL) for a given Entity. This is not scoped to a specific user or group, but rather removes all permissions associated with the Entity. After this operation, the Entity will inherit permissions from its benefactor, which is typically its parent entity or the Project it belongs to.
  
  In order to remove permissions for a specific user or group, you should use the synSetPermissions() function with the access_type set to an empty list.
  
  By default, Entities such as FileEntity and Folder inherit their permission from their containing Project. For such Entities the Project is the Entity's 'benefactor'. This permission inheritance can be overridden by creating an ACL for the Entity. When this occurs the Entity becomes its own benefactor and all permission are determined by its own ACL.
  
  If the ACL of an Entity is deleted, then its benefactor will automatically be set to its parent's benefactor.
  
  Special notice for Projects: The ACL for a Project cannot be deleted, you must individually update or revoke the permissions for each user or group.

• synGetAcl(instance, principal_id=NULL, check_benefactor=TRUE, synapse_client=NULL): Get the ACL that a user or group has on an Entity.

• synListAcl(instance, recursive=FALSE, include_container_content=FALSE, target_entity_types=NULL, log_tree=FALSE, synapse_client=NULL): List the Access Control Lists (ACLs) for this entity and optionally its children.
  
  This function returns the local sharing settings for the entity and optionally its children. It provides a mapping of all ACLs for the given container/entity.
  
  Important Note: This function returns the LOCAL sharing settings only, not the effective permissions that each Synapse User ID/Team has on the entities. More permissive permissions could be granted via a Team that the user has access to that has permissions on the entity, or through inheritance from parent entities.

• synQuery(query, include_row_id_and_row_version=TRUE, convert_to_datetime=FALSE, download_location=NULL, quote_character="\"", escape_character=r"(\)", line_end="\n", separator=",", header=TRUE, timeout=250L, synapse_client=NULL): Query for data on a table stored in Synapse. The results will always be returned as a data frame unless you specify a download_location in which case the results will be downloaded to that location. There are a number of arguments that you may pass to this function depending on if you are getting the results back as a DataFrame or downloading the results to a file.

• synQueryPartMask(query, part_mask, timeout=250L, synapse_client=NULL): Query for data on a table stored in Synapse. This is a more advanced use case of the synQuery() function that allows you to determine what additional metadata about the table or query should also be returned. If you do not need this additional information then you are better off using the synQuery() function.
  
  The query for this method uses this Rest API:
  <https://rest-docs.synapse.org/rest/POST/entity/id/table/query/async/start.html>

• synSnapshot(instance, comment=NULL, label=NULL, include_activity=TRUE, associate_activity_to_new_version=TRUE, timeout=120L, synapse_client=NULL): Creates a snapshot of the SubmissionView entity. Synapse handles snapshot creation differently for Table- and View-like entities. View snapshots are created using the asynchronous job API.
  
  Making a snapshot of a view allows you to create an immutable version of the view at the time of the snapshot. This is useful to create checkpoints in time that you may go back and reference, or use in a publication. Snapshots are immutable and cannot be changed. They may only be deleted.

Examples

## Not run: 
## Create a new SubmissionView.
    library(synapser)
    synLogin()

    my_submission_view = SubmissionView(
        name = "My Submission View",
        parent_id = "syn1234",
        scope_ids = list("syn5678", "syn6789") # IDs of evaluation queues
    ) |> synStore()
    my_submission_view

## End(Not run)

Description

Add column(s) to the table. Note that this does not store the column(s) in Synapse. You must call the synStore() function on this Dataset instance to store the column(s) in Synapse. This is a convenience function to eliminate the need to manually add the column(s) to the $columns list.

This function will add an item to the $columns attribute of the Dataset instance. $columns is a named list where the key is the name of the column and the value is the Column object.

Usage

synAddColumn(instance, column, index=NULL)

Arguments

Value

NULL

Examples

## Not run: 
## Example 1: Adding a single column
    # This example shows how you may add a single column to a dataset and then
    # store the change back in Synapse.
    library(synapser)
    synLogin()

    dataset = Dataset(id = "syn1234") |> synGet(table_options = TableOptions(include_columns = TRUE))

    dataset |> synAddColumn(
        Column(name = "my_column", column_type = "STRING")
    )
    dataset |> synStore()

## Example 2: Adding multiple columns
    # This example shows how you may add multiple columns to a dataset and then
    # store the change back in Synapse.
    library(synapser)
    synLogin()

    dataset = Dataset(id = "syn1234") |> synGet(table_options = TableOptions(include_columns = TRUE))

    dataset |> synAddColumn(list(
        Column(name = "my_column", column_type = "STRING"),
        Column(name = "my_column2", column_type = "INTEGER")
    ))
    dataset |> synStore()

## Example 3: Adding a column at a specific index
    # This example shows how you may add a column at a specific index to a
    # dataset and then store the change back in Synapse. If the index is out of
    # bounds the column will be added to the end of the list.
    library(synapser)
    synLogin()

    dataset = Dataset(id = "syn1234") |> synGet(table_options = TableOptions(include_columns = TRUE))

    dataset |> synAddColumn(
        Column(name = "my_column", column_type = "STRING"),
        # Add the column at the beginning of the list
        index = 0L
    )
    dataset |> synStore()

## End(Not run)

Description

Add column(s) to the table. Note that this does not store the column(s) in Synapse. You must call the synStore() function on this DatasetCollection instance to store the column(s) in Synapse. This is a convenience function to eliminate the need to manually add the column(s) to the $columns list.

This function will add an item to the $columns attribute of the DatasetCollection instance. $columns is a named list where the key is the name of the column and the value is the Column object.

Usage

synAddColumn(instance, column, index=NULL)