A View view is a type of Synapse Table that queries across metadata (Annotations) for particular items (projects, files or submissions) with a particular “scope”. A File View lists all Files or Tables within one or more Folders or Projects. A Project View lists all Projects you’ve added to the view. A Submission View lists all Submissions within one or multiple Evaluation Queues. Views can:

• Allow Projects, Files, Submissions, and Tables to be easily searched and queried

• Allow view/editing metadata attributes in bulk

• Provide a way of isolating or linking data based on similarities

• Provide the ability to link Projects, Files, Submissions, and Tables together by their annotations

Create a File View

To create a File View, select the Project in which you would like to create the View. The Project table. Views display rows and columns of information, and they can be shared and queried just like a table. Unlike tables, views are essentially queries of other data already in Synapse. They allow you to see groups of files, tables, projects, or submissions and any associated annotations about those items.

Annotations are an essential component to building a view. Annotations are labels that you apply to your data, stored as key-value pairs in Synapse.

Find more information on annotating your data at /wiki/spaces/DOCS/pages/2667708522.

You can use annotations to select specific subsets of your data across many projects or folders and group things together in one view.

You can use a view to:

• Search and query many files, tables, projects, and submissions at once

• View and edit file or table annotations in bulk

• Group or link files, tables, projects, or submissions together by their annotations

This guide explains how to create views from the web client. Instructions for creating views using the programmatic clients can be found in the Python docs and the R docs.

Creating a File View

A file view lists all files or tables within one or more folders or projects. To create a file view, navigate to the project where you would like to create the view. The project you choose does not have to contain the files items you are including in your file view. In order to create the File View, navigate to Navigate into the Tables tab and select “Add Add File View” in View from the Tables Tools menu. You will select the files of interest by defining the scope, which is the Projectproject(s) and Folders folders that contain your files. File Views views can also contain Tables tables or Foldersfolders; you can choose which kinds of items you would like to include during this the setup process.

Instructions for creating Views using the clients can be found in the Python docs and in the R docs.

Create a Project View

...

Creating a Project View

A project view lists all projects you’ve added to the view. To create a project view, select the project in which you would like to create the view. Navigate into the Tables tab and select Add Project View from the Tables Tools menu. You will select the projects of interest by defining the scope as above for file views. The only notable difference between creating a Project View project view and a File View file view is that for project views, there is a 1:1 relationship between the projects you select in your scope and the projects that are shown in the view.

...

View Limits

File and Project views are limited in the count of objects in scope.

• File views can have a maximum of 35,000 containers in scope.

• Project/Folder views can have a maximum of 10,000 child objects.

For example: A single view for a project may have 35,000 folders, with 10,000 files in each folder for a total of 350,000,000 child objects.

Creating a Submission View

A submission view lists all submissions within one or multiple evaluation queues. To create a Submission View, select the Project in which submission view, navigate to the project where you would like to create the view. The Project project you choose does not have to contain the submissions or the evaluation queues that are included in the view. Navigate to the Tables tab and select “Add Add Submission View” View in the Tables Tools menu. The submissions that are included in the view are defined by its scope, which is the list of Evaluation Queues evaluation queues containing the submissions. For more information, read about how to use Submission Views with Evaluation Queues.

...

submission views with evaluation queues. The scope of a

...

submission view can have a maximum of 20,000 evaluation queues.

Instructions for creating Views using the clients can be found in the Python docs and in the R docs.

Updating the Scope or Content

...

of a View

Views can be edited to change the scope of the view (e.g. the Project or Folder the view is showing) or which types of content is shown. Both of these options are found by navigating to “Show Scope of View” in the Tools menu; from there you may View and Edit the scope and the content-type of the view.

Note that it may take a few moments for the updated View to rebuild as it queries across the system.

...

The scope of a view defines what items are grouped together to appear in the view. For example, you can set the scope to be multiple projects or a small number of folders. You can change the scope to edit the types of content displayed. Navigate to the view and then select Show Scope of View in the Tools menu. Click Edit Scope to view and change your view preferences. Once you click Save, Synapse may take a few moments to rebuild the updated view.

Querying a View

A view can be queried exactly the same as like any other Table table in Synapse. Please see Tables for more examples. See the Using Simple Search and Using Advanced Search sections below.

For example, to query for everything in syn123:

Command Line

synapse query 'SELECT * FROM syn123'

Python

query = syn.tableQuery('SELECT * FROM syn123')

R

query <- synTableQuery('SELECT * FROM syn123')

...

See /wiki/spaces/DOCS/pages/2667642897 for more information.

Inserting a View into a Wiki

Views can also be embedded in a wiki. You can embed the entire view or a subset of it.

Navigate to a wiki and click the Wiki Tools menu. Select Edit Project Wiki. In the wiki editing window, select the Insert tab and then Table: Query on a Synapse Table/View. To embed the entire view into the wiki enter SELECT * FROM syn12345678 in the resulting pop-up window, replacing syn12345678 with the synID for your view.

To embed a subset of a view, use the WHERE clause to select certain rows. For example, entering SELECT * FROM syn12345678 WHERE Cell_Type = ‘PSC’ embeds only rows where the value PSC is entered in the column for cell type. Save the query to embed the view.

...

Updating Annotations in Bulk Using a View

Views can be used to update annotations in bulk. for many files or tables at once.

To add new annotations, see the Annotations article. To update other metadata in bulk, such as provenance, see the Bulk Processing article. /wiki/spaces/DOCS/pages/2667708522.

For example, if you would like to use the Python client to update the annotation “dogSays:bark” to “dogSays:woof” in for every file in a File View file view with the synId syn456synID syn12345678, you can use:

from synapseclient import Table

foo = syn.tableQuery('select * from syn456')

bar = foo.asDataFrame()

# add in annotation as a column
bar['dogSays'] = 'woof'

# store the fileview with the new annotation in Synapse
fv = syn.store(synapseclient.Table(foo.tableId, bar))

Using Simple Search

Views are in Simple Search mode by default. You can filter out Projects or Files of interest by selecting what characteristics you like using the facet menu on the left. You can toggle between simple and advanced search using the Show advanced search/Show simple search link.

...

Using Advanced Search

In advanced search, you can use a SQL-like query to search for items in that view. In the example below, we’re selecting for all files that have a Cell Type of “PSC”.

...

Version a View

Versioning is an essential component of conducting reproducible research. Views can be versioned to create a snapshot of your data at a specific point in time. This snapshot can then be referenced and shared. For example, if you are publishing a collection of sequencing files in a File View, you may want to share your work with others for analysis. You can use the File View to check that your annotations are correct, then create your first version when it’s ready to share. Later, when you’ve added more files and annotations, you can create a second version to share for additional analysis. You can refer back to previous versions to see what Files and Annotations were used at each step of your research.

As you refine a View, changes are saved to the synID (e.g. syn456). Unlike Files, which are automatically versioned anytime the file is changed, you decide when to manually create a View version. Creating a new version adds a number to the parent synID (e.g. syn456.2), which can be used to reference or query that version within Synapse. Navigating to the parent synID (syn456) will always display the most recent changes to the View, regardless of whether you have included them in a version.

Create a View Version

From a View, click Entity View Tools, then select Create a New View Version from the dropdown menu.

Add a label and a comment about this version. Any text entered in the label field is appended with the word “Version” in the version history. For example, entering “Final” as a label appears as “Version Final” in your version history.

Select and Share Versions

Navigate to Entity View Tools and select Version History to see a table with version history information.

Click on your desired version number. After the page updates, your selected version is indicated in bold text in the Version History table, and the View is displayed below.

To return to the current version, click Go to the current version in the top left of the version history.

To share a version, copy the URL at the top of the page to share with other Synapse users, or you can mint a DOI for the selected version.

Delete a Version

To remove a version, navigate to Entity View Tools and select Version History. Click on the “x” on the right hand side of the table to delete a specific version.

Once deleted, a version number cannot be reused. Any URL or Wiki links pointing to a deleted version will break.

Insert a View into a Wiki

Views can also be placed inside a Wiki once they have been created. You can embed the entire view or a subset of a query on it.

To insert a file view with a synId of syn456:

In the Edit Project Wiki window, select Table: Query on a Synapse Table/View under the Insert dropdown. To embed the entire file view into the wiki enter “SELECT * FROM syn456” in the resulting pop-up.

To embed a subset of the file view, like the advanced search query in the previous example, enter “SELECT * FROM syn456 WHERE Cell_Type = ‘PSC’”.

...

Save the query and the edits to the Wiki to embed the view.

See Also

Annotations and Queries, Tables, Wikis

...

Versioning a View

You can create a version history for any view in Synapse. Versioning helps you keep a record of what changes you made to the view and when you made them.

For more information on versioning a view, see /wiki/spaces/DOCS/pages/2667675758.