Skip to end of metadata
Go to start of metadata

This chapter describes how to review results of TCIA database searches.

Topics in this chapter include:

Search Results Overview

In reviewing search results, it is important to review the hierarchy of submissions in TCIA.

Collection > Patient (Subject) > Study > Series > Images

A Simple Search, Text Search, and Advanced Search each orders search results by Subject ID on the Search Results (by Subject) page. Clicking that Subject ID displays the studies and image series matching the search criteria for that subject. For more information, see Search Results (Studies for Subject).

You can view images associated with studies for the selected subject in various ways, including:

  • viewing all study images in a DICOM web viewer,
  • viewing thumbnails of all study images on the Search Results (Images for Series) page
  • viewing selected images in your desktop DICOM viewer,
  • viewing all study images in a cine loop,
  • or viewing the DICOM header of the first image in the series.

Retrieving objects for download

At any point in the process of reviewing results, you can add items - all data pertaining to a patient, study, or an image series - to your data basket. When items are in your data basket, you must take a subsequent step to download them.

When you download a series that has annotation files (indicated by Yes in the Contains Annotations column), they are automatically downloaded as well.

Return to top of page

Search Results (Studies for Subject)

The Search Results (Studies for Subject) page shows studies associated with the subject that you selected on the Search Results by Subject page. Each study, identified by Study Instance ID, Description, and Date, is followed by a table with rows for each image series in the study. At the top and bottom of the page, breadcrumbs in the format Search >> Study show the level of the data on the page. Clicking Search in those breadcrumbs returns you to your original search results.

The following table describes the data available for each study and image series in that study.

Field

Description

DICOM Web Viewer link

Click this link to see all study images in the DICOM Web Viewer.

Series

Series identification number

Description

Description of the Series

Modality

Image modality

Manufacturer

Name of the manufacturer of the image series

Images

Displays the number of images in the series. This number includes visible images that meet the search criteria.

Thumbnails

Click this link to display thumbnails of the series' images. For more information, see Search Results (Images for Series).

Cine Mode

Click cine mode button in a series record to launch an animation of the series. This feature is only available when two or more thumbnails are available for the series. For more information, see Viewing Image Animation.

DICOM
Click DICOM button to open a new window that displays DICOM metadata about the first image in the series. 
Each image series can have multiple images whose thumbnails display in this search results page. While each image has its own DICOM file whose attributes may vary slightly from the others in the series, the DICOM file that opens displays values for only the first image in the series. These values represent the values for all images in the series.

Add to Basket


 

  • Click add to data basket to select the series and remove from basket to clear it.
  • To mark all series in the search results as records you want to add to your data basket, click the basket icon in the column header or click add found to basket

For more information, see Managing the Data Basket.

Add a Study series to Basket
To mark only the series in the search results of a particular study as records you want to add to your data basket, click the basket icon in that study's column header

Return to top of page

Search Results (Images for Series)

Clicking the icon in the Search Results (by Subject) page opens thumbnails of all images in the selected series. In this documentation, this page is called Search Results (Images for Series).

Click View Image under any thumbnail to save the image as a file or open it in the DICOM viewer.

Return to top of page

Viewing Image Animation

You can launch an image animation where there are more than two images in the series using one of these methods:
  • On the Search Results (Studies for Subject) page, you can launch an animation of thumbnails if there is more than one image in the series. Click cine mode button in a series record in the search results.

    OR
  • You can launch the animation of an image series from the data basket. In the View column of the data basket, click the magnifying glass symbol,magnifying glass icon, corresponding to the series you want to view. On the View Series Images page, click the View Series in Cine Mode link.
    Animation viewer, described in text
    When the viewer opens (figure above), the animation controls display below the image. When you use the controls, TCIA proceeds to display the images sequentially, like a movie.

The following table describes the action of each of the animation controls.

Animation Controls

Action

arrow for controlling movie frame, described in text

Drag the arrow to set which frame of the movie displays. This also monitors the progress of the animation.

Drag ends of the yellow bar to vary the range of images playing.

(Back facing double arrow

Click to return to the first image in the set.

Forward-facing double arrow

Click to progress to the last image in the set.

Back-facing arrow

Click to play animation backwards through the series.

Forward-facing arrow

Click to play animation forward through the series.

minus sign icon

Click to stop the animation; click again to display one image at a time, moving backwards through the series.

plus sign icon

Click to stop the animation; click again to display one image at a time, moving forward through the series.

cycle icon to cycle through image series

Click to cycle the animation forward or backward. Once set, the animation continues ad infinitum.

Tip

If the animation is very sluggish, be sure and note the warning at the bottom of the page.

Return to top of page

Obtaining DICOM Viewers

Most image data and some associated data within The Cancer Imaging Archive (TCIA) is stored in DICOM format.  There are a variety of both open source and commercial DICOM tools that could be used to manipulate and view these files. While TCIA does not endorse nor recommend any particular tool, here is a list of tools that we or our partners have used in our daily work. More information about DICOM is available.

Select Tools > List of DICOM Tools to open a page of selected links to freeware DICOM image viewers. This list is provided for your convenience. Many other DICOM viewers are available on the internet. This is not an endorsement of the listed viewers.

Before using the viewers

The images in this image repository need to be downloaded before you can view them using the viewers.

Return to top of page

Downloading TCIA Images


Access the TCIA Downloader app

Click one of the following links to download the TCIA Downloader app for that operating system.

  • Windows
  • Mac
  • RPM (tested on CentOS)
    To run this file, type the following at the command prompt:
    sudo yum install TCIADownloader-1.0-1.x86_64.rpm
  • DEB (tested on Ubuntu)
    To run this file, type the following at the command prompt:
    sudo dpkg -i tciadownloader_1.0-2_amd64.deb

After you search for images of interest and add them to your data basket, you can download them.

The most convenient method of downloading is by using the TCIA Downloader. You must install the TCIA Downloader before you begin downloading. You only have to install it once to use it in future downloading sessions.

If you cannot install the TCIA Downloader for any reason, you can run the Temporary TCIA Downloader (JNLP) instead.

To download the TCIA Downloader

  1. Download the installer package for Windows, Mac, or Linux (CentOS or Ubuntu).
  2. Save the installer package file to your computer.
  3. Install the app by double-clicking the installer package file.
  4. Agree to the terms in the License Agreement and click Install.
    Installing TCIA Downloader
  5. When the Setup Wizard completes, click Finish.

To download images using the TCIA Downloader

The TCIA Downloader identifies the list of images you added to the data basket to download from TCIA. It also facilitates the connection between the image server and the local machine. It opens manifest files (manifest-xxx.tcia).

You can share the manifest file with collaborators. Collaborators must install the TCIA Downloader app to open the file.

  1. Search for images of interest.
  2. Add those images to your data basket.
  3. Open the My Data Basket page and click Start Download.
  4. Open the manifest-xxx.tcia file.
    The TCIA Downloader appears.
    TCIA Downloader

    The TCIA Downloader lists all items you selected in the data basket. You can hover your mouse over the Patient ID, Study Instance, and Series Instance columns to reveal the complete corresponding IDs. You can also resize a column by selecting and dragging the column border.

  5. Click Browse to navigate to the destination where you want the images/annotations to be downloaded.
  6. Click Start to begin the download. You can monitor the download in the Progress column. The Status column indicates when the download for each item is complete.

    At any point in the process, you can click the Pause and Resume buttons to temporarily stop and restart the process.

    Note that files downloaded this way are not compressed. The downloaded files are stored in a child folder under the destination folder such as Collection name/patient id/study instance UID/series instance UID/image SOP instance UID.

           

Deleting Items

The TCIA Downloader initially lists everything in your data basket. If you do not want to download any of those items, select them in the TCIA Downloader and then click Delete. When you remove an item from the Downloads list, you do NOT also remove it from the data basket.

Network Error?

If network errors occur during large downloads, Download Manager retries the files a the number of times that your administrator has configured.

Using the Temporary TCIA Downloader

The most convenient method of downloading TCIA data is by using the TCIA Downloader. You must install the TCIA Downloader before you begin downloading data.

However, if you cannot download the TCIA Downloader, the alternative is to use the Temporary TCIA Downloader, previously called the NBIA Download Manager.

The Temporary TCIA Downloader allows you to replicate items in your Data Basket, downloading them to your local machine. It is a Java program and requires that you install a Java Runtime Environment (JRETM) on your machine to run it. You can download the JRE. The Temporary TCIA Downloader does not limit the total size of the download.

JRE

You must have version 8 or higher of the Java Runtime Environment (JRE) installed to be able to open the Download Manager.

  • If JRE 8 is installed, the Temporary TCIA Downloader attempts to start. To run the application, you must click Run in the Warning dialog box indicating the application's digital signature cannot be verified. Before doing so, you can select the More Information... link at the bottom of the dialog to view a more detailed report of any security issues. Then you can evaluate whether you want to run the application.
  • If JRE is installed but the version is older than version 6, the browser automatically attempts to upgrade the JRE to version 8.
  • If the JRE is not installed, when you click the Download Manager button, the browser prompts you for what it should do with the JNLP file. The My Data Basket page includes a link to a page where you can download the JRE.

  • If the Temporary TCIA Downloader fails to work properly, this could be a JRE version issue. The Temporary TCIA Downloader has been tested successfully with Version 8 Update 101.

Java Security settings

Java Security may block the installation of the Temporary TCIA Downloader. You may see a window like the following.

Application blocked by Java Security due to a certificate problem

To resolve this issue, do the following.

  1. Select Start menu > Configure Java.
    The Java Control Panel appears.
  2. Select the Security tab.
  3. Click Edit Site List and then enter https://public.cancerimagingarchive.net/ncia as the location.
  4. Click OK.
  5. Click the JNLP file to run the Temporary TCIA Downloader again.
    A message window appears, asking you if you want to run this application.
  6. Select I accept the risk and want to run this application. 
  7. Click Run.
    The Temporary TCIA Downloader successfully launches.

    NBIA Download Manager

Removing items

The Temporary TCIA Downloader initially lists everything in your data basket. You can remove items from the Downloads list in the Temporary TCIA Downloader that you do not want to download. When you remove an item from the Downloads list, it remains in the data basket. You just do not download it.

To download objects using the Temporary TCIA Downloader

Mac OS X

The following instructions apply to Windows PCs but you can also use the Temporary TCIA Downloader on Mac OS X.

  1. At the top of the My Data Basket page, click the Download Manager link. You are prompted to open or save the Temporary TCIA Downloader. Open it in the JRETM you installed. If you have any issues opening the Temporary TCIA Downloader, see the note about Java Security settings.

         

The v lists all items you selected in the data basket. You can hover your mouse over the Patient ID, Study Instance, and Series Instance columns to reveal the complete corresponding IDs. You can also resize a column by selecting and dragging the column border.

  1. Click Browse to navigate to the destination where you want the images/annotations to be downloaded.

  2. Click Start to begin the download. You can monitor the download in the Progress column. The Status column indicates when the download for each item is complete.

    At any point in the process, you can click the Pause and Resume buttons to temporarily stop and restart the process.

    NBIA Download Manager, Downloads Complete

    Note that files downloaded this way are not compressed. The downloaded files are stored in a child folder under the destination folder such as Collection name/patient id/study instance UID/series instance UID/image SOP instance UID.

Removing items

The Temporary TCIA Downloader initially lists everything in your data basket. You can remove items from the Downloads list in the Temporary TCIA Downloader that you do not want to download. When you remove an item from the Downloads list, it remains in the data basket. You just do not download it.

Network error?

If network errors occur during large downloads, the Temporary TCIA Downloader retries the download the number of times that your administrator configured.

Return to top of page

Working with the Data Basket

As you search TCIA, you can add any data items to your Data Basket to download later. The items in your Data Basket remain there only for the current work session.

Adding Items to Your Basket

You can add the images associated with a subject, a single series, or the entire study to your data basket. You can also choose individual images to add to your data basket. When you have marked a record for addition to the data basket, it is highlighted in yellow.

  • Click add to data basket to select the record and remove from basket to clear it.
  • To mark all records in the search results as records you want to add to your data basket, click the basket icon in the column header or click add found to basket.

Managing the Data Basket

After you search for items in TCIA and add them to your data basket, click Manage Data Basket in the top menu to see the list of those items you added during this work session only in the My Data Basket page.

The following is an example of the My Data Basket page with just one image collection in it. The estimated download time and total size of your data basket appear at the bottom.

My Data Basket

The following table describes each item in the table.

Data Basket Field

Description

Subject ID

Subject identification number

Study UID

Study identification number

Study DateDate of study
Study DescriptionDescription of the study

Series ID

Series identification number

Series DescriptionDescription of the series

Number of Images

Number of Images for series

Image Size (in MB)

Size of the image file in megabytes

Annotation File Size (in MB)

Size of the annotations file in megabytes. This column is N/A if there are no annotations.

Remove

Remove the item from the basket.

To delete all items from your basket, click the Empty Data Basket link. You can continue to add items to your data basket from the Search Results pages.

Deletion details

If the series you mark for deletion is part of a shared list, a message appears alerting you to that fact. The message also includes the name of the shared list and the shared list creator's email address. This gives you the opportunity to back out of the deletion. For more information see Working With Shared Lists.

You can now download the data in your data basket using the TCIA Downloader. You must install it before you proceed with downloading.

Return to top of page

Downloading the Data Basket

In the data basket, select the items you want to download.

Tip

Disable popup blockers before you download the files. If you do not want to download the annotation files, deselect the Include annotation files in your download check box.

Once you are satisfied with your selections, click Download at the top left of the results table to use the Download Manager.

Return to top of page

Working With Shared Lists

TCIA provides a way for you to identify and label a collection of image series for you to use or share with other TCIA users.

Creating a Shared List

You can create a shared list by clicking Tools > Create Shared List link or by putting a series in the data basket, as explained below.

Who can create a shared list?

Anyone can create a shared list. Once you do so, you must record the exact name of the shared list to distribute to others who may want to use the list. That is the only way they can access it.

To create a shared list

You can create a shared list from the Tools menu or the data basket. Procedures for both methods follow.

Menu Option:

  1. Click Tools > Create Shared List.
    The Create Shared List page appears.
    Create Shared List page
  2. On this page, do the following:
    1. Enter a Name for the list (required).
    2. Add Comments and a Hyperlink, where appropriate, which links to relevant or more detailed information about the list (optional).
    3. In the Upload File field, enter the name of a file that includes all of the series instance IDs you want to be in the shared list. This file should have a series instance UID per line.
    4. For your convenience, a Java tool is available to aid in generating a CSV of your series instance UIDs. 
      Download: ExtractSeriesUIDs.zip
      Do the following to use this tool to generate the file to upload in the last field of our online Create Shared List form:
      1. Download the zip file, then move it to a top-level directory of DICOM files you want indexed.
      2. Extract the zip file to the top level directory where your DICOM data resides (all sub-directories will be scanned). It should extract two things.
      3. Then run ExtractSeriesUIDs.bat which should flash a quick command line window and then automatically disappear.
        A file with a name similar to SeriesUIDs.CSV is created as an output.
      4. Enter the output filename into the form.
  3. Click Submit.
    The image series from the uploaded file is added to the data basket.

Data Basket

  1. Add an image series that you want to include in the shared list to the data basket.
  2. Click the Create Shared List button.
  3. Do the following:
    1. Enter a Name for the list (required).
    2. Optionally, add a description and a URL. The URL links to relevant or more detailed information about the list.
    3. Click Browse to upload a file in comma separated value format (.csv) that includes all of the series instance IDs you want to be in the shared list. This file should have one series instance UID per line.
  4. Click Submit.
    The image series from the uploaded file is added to the data basket.

Access to your list

TCIA warns you that not all public users will have access to your list if the list contains any non-public image series.

Return to top of page

Editing a Shared List

You can edit the list only by uploading a .csv file with all the series instance IDs for the list. You can only edit/delete shared lists you have created yourself.

Shared List

From the data basket, you can export image series instance IDs to a .csv file for later use in creating or editing a shared list. See Exporting a Shared List for more information.

To edit a shared list

  1. Click the Edit Shared List link under Tools on the menu bar.
    The Edit My Shared List page appears, displaying a list of shared lists you have created.
    Edit My Shared List page
  2. Click the name of the shared list you want to edit.
    List details appear.
    expanded Edit My Shared List page showing details about the list
  3. In the description field, optionally enter a comment about the list or your edit.
  4. In the URL field, optionally enter a web address that provides more information about the shared list.
  5. Click Browse to locate the file you want to upload. Doing this replaces the current shared list.

To delete a shared list

  1. Click Tools > Edit Shared List.
    The Edit My Shared List page appears, displaying a list of Shared Lists you have created.
  2. In the row of the shared list you want to delete, click .

Because editing a shared list is only possible by replacing it, you might consider backing up a shared list when you create it. To do so, export the shared list as a file when you create it. See Exporting a Shared List.

Return to top of page

Searching a Shared List

Any user can search for a shared list.

To search for a shared list

  1. From http://www.cancerimagingarchive.net/, click Search Data Portal button.
  2. Click Tools > Search Shared List.
    The Search Shared List page appears.
    Search Shared List page
  3. Enter the name of an existing shared list. To retrieve the list, you must know the exact name given to the shared list.
  4. Click Submit to launch the search or Reset to clear the field and start again.

If the search is successful, all image series in the shared list are added to the data basket. If the shared list includes series for which you do not have visibility rights, a message appears that informs you that the displayed shared list is not complete.

Return to top of page

Exporting a Shared List

Once you have created a shared list, you can export it as a .csv file.

To export a shared list

  1. Above the data table, click Shared List > Export Series ID.
    The shared list opens in the data basket.
    Data basket displaying export shared list options
    The export begins immediately. A dialog box appears, prompting you to open (in Excel) or save the file.
  2. Select to open or save the file.

Return to top of page

Managing a Shared List

Users with the appropriate administrative privileges can delete shared lists created by other users.

Permissions

This administrative feature is available only to logged in users who have "manage visibility" privileges, as defined in UPT.

 To delete a shared list, follow these steps:

  1. Click Admin > Manage Shared List.
    The Manage Shared List page appears.
    Manage Shared List page with a user name dropdown option only
  2. Select a user name from the list.
    That user's shared list(s) appear.
    Manage Shared List page displaying a selected user's shared list
  3. Click the name link to review the shared list's details or click delete button to delete shared the shared list.

Return to top of page

  • No labels