DRAFT Chapter 2: Browsing and Searching Investigations

Contents of this Page

The CSSI DCC Portal is a public repository of experiment-related information describing cancer research investigations. You can use the portal to browse, search, and download eight Physical Sciences Oncology Network (PSON) data sets. These data sets are in ISA-TAB format, which organizes investigation, study, and assay data according to the rules in the ISA-TAB specification .

Each data set contains three files--investigation, study, and assay--that conform to the ISA-TAB structure and naming conventions. Within this structure are fields that are standard for each type of file, though null values are allowed; that is, not every data set includes values for each field. The portal allows you to filter these fields in an interactive way so that you can visualize the data in a pie chart or list.

You can also search investigations, studies, and assays using any keyword. You can download selected files, the entire data archive, or only the metadata associated with a study.

This chapter provides detailed instructions on how to browse, search, and download data.

Browsing Investigations

You can browse and explore investigation data from the investigation, study, and assay files.

To browse investigations

From the CSSI Data Portal home page, click the Browse button.

The Browse Investigations page appears, showing pie charts at the top and a list of investigations below them. All eight investigations currently included in this release of the CSSI DCC Portal appear in the list. A subset of the page appears in the following screenshot.

Understanding the Pie Charts and Investigations List

The Browse Investigation page has two interactive components:

Pie charts that show fields from the investigations. When you first open the page or reset it to clear all selections, three pie charts appear at the top. These pie charts represent three of the fields, Study Protocol Name, Study Assay Technology Type, and Study Assay Measurement Type, that occur in the metadata of the eight investigations currently in the portal. The values for those fields, as well as a count for each value, appear in the pie charts. The count represents the number of times that field value occurs in all of the investigations currently in the portal.

For example, in the default pie charts represented in the above screenshot, the Study Assay Measurement Type pie chart shows that one investigation used genome sequencing, six used imaging assay, and two used transcription profiling. Note that there are nine field values and only eight investigations because one investigation listed two values for Study Assay Measurement Type. You can determine which investigation that was by clicking on each pie slice and reviewing the details in the list below.

Click one or more field values in the pie charts ("slices") to filter the data by that/those field value(s). The more field values you select, in one or more pie charts, the more narrowly you filter the investigation data and the fewer investigations match your selections. The investigation list refreshes each time you filter the data in this way. You can also customize which fields appear in the pie charts and how many pie charts appear by adding and removing fields.

In the following screenshot, a user has selected at least one field value in each pie chart. The selected values are sample collection and summarize trimmed reads in the Study Protocol Name chart, nucleotide sequencing in the Study Assay Technology Type chart, and genome sequencing in the Study Assay Measurement Type chart. Only one investigation matches all of these selections and appears in the list below. To reduce the amount of filtering, you can click Reset All to return to the default pie charts, or reset on an individual pie chart. You can also return to the default view by selecting Investigations > Browse.
A list of investigation details below the pie charts. The investigation list shows details associated with the investigations that match your pie chart selections. For example, in the following screenshot, a user has selected one field value in the Study Protocol Name pie chart: plate cells. The number 4 next to the label plate cells means that four investigations are associated with the Study Protocol Name field value of plate cells. Those four have a null value for Study Assay Technology Type, which is the second pie chart, and all use the same Study Assay Measurement Type of imaging assay.

The list below the pie charts match the pie chart selections. The list includes only those four investigations that have a Study Protocol Name field value of plate cells. Details for each investigation in the list includes the same fields represented by the pie charts: Study Protocol Name, Study Assay Technology Type, and Study Assay Measurement Type, plus the study name and description. The list also shows additional data about each investigation, such as the other keywords used in the Study Protocol Name field. You can return to the default (full) list at anytime by selecting Investigations > Browse.

Adding and Removing Fields

You can customize which pie charts appear at the top of the page. Since the pie charts control how you filter the investigation data, you may prefer something other than, or in addition to, the three default fields of Study Protocol Name, Study Assay Technology Type, and Study Assay Measurement Type.

To add or remove fields

On the Browse Investigations page, click .
The Select menu appears to the left of the pie charts.
Expand fields by clicking the plus signs. Note that in the STUDY PROTOCOLS and Study Assays section, the field values of Study Protocol Name, Study Assay Technology Type, and Study Assay Measurement Type are already selected. These field values are the ones that appear in the three default pie charts on the Browse Investigations page. If you clear these check boxes, those pie charts will disappear from the page. When you reset all of the pie charts or select Browse > Investigations, however, they will reappear.
Click any of the field values to select them. For example, select Study Protocol Type.
The pie charts immediately update to reflect the selection and a fourth pie chart appears on the Browse Investigations page.

You could also opt to clear all of the check boxes except for Study Protocol Type. In this case, that is the only pie chart that would appear.
When you have selected or cleared as many fields as you want to use to filter the investigation data, click .
The Select menu moves back to its original position.

Exploring Investigation Details

You can continue exploring investigation data by clicking a link to investigation, study, or assay details. Links to these details are on the Browse Investigations page or on the Search Investigations page, after you search on a keyword or phrase. These details include counts of studies, assays, samples, and files. The metadata available for an investigation determines if other entities are available for counts such as sources and collections. From these details pages, you can visualize the structure of the investigation and download selected study files, download the full archive, and download only the metadata.

To explore investigation details

Browse investigation
or search investigations until you find an investigation, study, or assay in which you are interested. This will be either on the Browse Investigations or Search Investigations pages.

Click the link corresponding with the investigation, study, or assay you are interested in exploring.

The details page for the investigation, study, or assay you selected appears. The details page for each entity differs.

Investigation Details Page

The investigation details page shows the investigation name at the top followed by a visualization of the investigation filename, study filename and number of samples in the study, and assay filename and number of files (and total file size) in the assay. Below the visualization are links to download all or part of the investigation, its identifier, and its description.

The currently selected entity has a green box behind its icon in the visualization. When the investigation is selected, its study/studies, and assay(s) are also selected. In the following screenshot, the investigation is selected.

Study Details Page

The study details page

Assay Details Page

The assay details page

Searching Investigation Data

You can search investigations, studies, or assays using any keyword.

To search investigation data

From the CSSI Data Portal home page, click the Search button.

The Search Investigations page appears.
In the search box, enter a keyword or phrase. Keywords are any word that appears in the fields belonging to any investigation, study, or assay in the CSSI DCC Portal. This includes all file columns, field definitions, and placeholders that describe the structure of the data collected in this study.

Search results appear immediately, using the context currently in the Search for box, which by default is Investigations. The time the CSSI DCC Portal took to first search for the keyword or phrase and then render the results on the page also appear.
In the Search for box, change the context for your search if desired. Select Investigations, Studies, or Assays. Examples of each search result follow.

In the following example, the keyword is "genomic" and the context is Investigations. Three investigations appear in the search results, along with information about each one that includes the investigation name, number of studies, number of assays, number of files, and description.

In the following example, the keyword is "genomic" and the context is Studies. Three studies appear in the search results, along with information about each one that includes the study name, name of the investigation the study is associated with, number of assays, number of files, and description. In these cases, the investigation name and study names are identical.

In the following example, the keyword is "genomic" and the context is Assays. Three assays appear in the search results, along with information about each one that includes the assay filename, name of the study that the assay is associated with, name of the investigation the assay is associated with, number of files (such as image files), and description.
Click any investigation name, study name, or assay filename to explore the data further.

Downloading Study Files

You can download selected files, the entire data archive, or only the metadata associated with a study. All of the data currently in the portal is public.

The data archive is a compressed (.zip) file that combines the assay, investigation, and study text files, and associated study data files. The study text files contain the metadata. Downloading the data archive means that you do not need to also download the metadata and files for that investigation.

If you only need the metadata, you can download it as a compressed file (.zip). The metadata includes only the assay, investigation, and study text files, which are the file columns, field definitions, and placeholders that describe the structure of the data collected in this study. They are in Investigation-Study-Assay tab-delimited format (ISA-TAB), which is based on the ISA-TAB specification .

While they are also included in the archive if you choose to download that, you can also download selected study files. These study files might be image files, spreadsheets, or any other data associated with the selected study that is not the metadata.

To download study files

Select an investigation and view its details.
The study details page appears.
In the Files area, click the down arrow to expand it.

To download a single file

To select only one file, click its File Name link.
Your browser's file download dialog box appears, which prompts you to open or save the file.

To download multiple files

Click the box in the Select File column for any of the files in the list.
Click.
The Download window appears.
Enter your email address and click OK.
The Success window appears.
Click OK.
Look for an email in your inbox with the subject line File Download.
Save or open the file.

Downloading Archives

Once you select an investigation and view its study details, you can choose to download the entire archive. An archive is a compressed file (.zip) that combines the assay, investigation, and study files with the metadata and data files.

You do not need to log in to CSSI DCC Portal to download an archive.

To download an archive

Select an investigation and view its details.
The study details page appears.
Click .
The Download window appears.
Enter your email address and click OK.
The Success window appears.
Click OK.
Look for an email in your inbox with the subject line File Download.
Save or open the file.

Downloading Metadata

You do not need to log in to CSSI DCC Portal to download an investigation's metadata. The metadata includes only the assay, investigation, and study text files, which are the file columns, field definitions, and placeholders that describe the structure of the data collected in this study. They are in Investigation-Study-Assay tab-delimited format (ISA-TAB), which is based on the ISA-TAB specification .

To download metadata

Select an investigation and view its details.
The study details page appears.
Click .
Your browser opens a download dialog box with your download file in it.
Open the file or save it for later analysis.
Metadata File Contents
The metadata file is in compressed format. It contains one folder called metadata and a text file for each of the following: assay, investigation, and study.
The contents of the archive folder look similar to the following (10290 is just an example of the file identifier):
metadata/
   a_10290.txt
   i_10290.txt
   s_10290.txt

Content

Space Tools