Table of Contents

       Tutorial: Lists
         Step 1: Set Up List Tutorial
         Step 2: Create a Joined Grid
         Step 3: Add a URL Property

Tutorial: Lists

This tutorial introduces you to the simplicity of lists, plus the power of lookups, URL properties and joins for generating insights into your results.

This tutorial can be completed using a free 30-day trial version of LabKey Server.

This "Rats of NIMH" demo uses four lists containing information about animal subjects and blood samples from those animals. Samples were subdivided into portions, then into slides, on which experiments were run. Gaining insight into these results requires joining them with information about samples and demographics to get the full picture.

Lookups and URL properties help you to navigate your data more easily. A lookup can let you display the name of the subject instead of displaying an obscure SubjectID. Lookups also let you link sample data to other information (such as demographic data). URL properties can help you link directly to relevant visualizations or outside sources from subject data. Joins help you gain insight across different lists of data by letting you view data from related lists together in common views.

Completing this tutorial requires administrative permissions, which you will have if you create your own server trial instance in the first step. The covered features, however, are not restricted to admin users.

Tutorial Steps

View the interactive example of the lists used in this tutorial.

Related Topics

First Step

Step 1: Set Up List Tutorial

In this first step, we set up a work space and import a set of lists to work with.

Set Up

  • Log in to your server and navigate to your "Tutorials" project. Create it if necessary.
    • If you don't already have a server to work on where you can create projects, start here.
    • If you don't know how to create projects and folders, review this topic.
  • Create a new subfolder named "List Tutorial". Accept all defaults.

Import a List Archive

  • In the Lists web part, click Manage Lists.
  • Click Import List Archive.
  • Click Choose File and select [LabKeyDemoFiles]/Lists/NIMH/ from the unzipped demo files.
  • Click Import List Archive.

The list archive includes four lists interconnected with some specific fields defined as lookups to other lists. You can continue the tutorial using the newly imported set of lists.

Related Topics

  • Connect Lists: Walkthrough the process used to create the list archive you imported.

Start Over | Next Step (2 of 3)

Step 2: Create a Joined Grid

The imported list archive includes four lists interconnected with some lookups between them. These lookups allow us to create joins between these lists which pays off when we investigate our experimental results in the NIMHSlides list. The Slides list shows an interesting pattern in positive/negative stains, but you won't see this pattern unless you first join in some information from another list (NIMHDemographics).

  • Click the NIMHSlides list from the Lists web part.

The grid shows all the uploaded slide data. You may or may not be able to spot a pattern at this point. Familiarity with the novel might help in this very simple example, but we can also use additional data to help us.

Create a Joined Grid

  • On the NIMHSlides grid, select (Grid Views) > Customize Grid.
  • In the Available Fields panel, expand the node SubjectID by clicking on the icon next to it.
  • Place checkmarks next to the Name, Family, and Species fields. (Note that these fields are added to the Selected Fields panel.)
  • Click Save.
  • In the Save Custom Grid View popup menu, select Named and name this view NIMHSlideDataJoinedView. Click Save.
  • You'll now see additional columns in the grid view. To view an interactive example, see: NIMHSlideDataJoinedView

Find a Pattern in the Data

Do positive/negative stains correlate with any other characteristics in our subjects?

First, let's do the simplest possible data analysis: sorting the data.

  • Click the column header Stain Positive to bring up a menu of sorting and filter options.
  • Choose Sort Descending.
  • Examine the results and notice that almost all of the positive stains came from field mice.
  • Looks like we have a pattern worth further investigation.

Previous Step | Next Step (3 of 3)

Step 3: Add a URL Property

In this previous step, we used lookups to link our lists to each other. In this step, we explore two ways to use the URL property of list fields to create other links that might be useful to researchers using the data.

Create Links to Filtered Results

It can be handy to generate an active filtering link in a list or dataset. For example, here we use a URL property to turn the values in the species column into links to a filtered subset of the data. When you click one species value, you get a grid showing only subjects of the same species.

  • Click the List Tutorial link above the grid to return to the main folder page.
  • From the Lists web part, click NIMHDemographics to open the grid view of the list.
  • Notice that in the "Species" column, the values are just text, not links (yet).
  • Click the column header Species, then Filter....
  • Click the label Rat to select only that single value.
  • Click OK.
  • Notice the URL in your browser, which might look something like this - the full path and your list ID number may vary, but the filter you applied (Species = Rat) is encoded at the end. This will show only rows where the species is Rat.
  • Clear the "Species=Rat" filter using the in the filter bar, or by clicking the column header Species and then clicking Clear Filter.

Next we'll modify the design of the list to turn the values in the Species column into custom links that filter to just the species name that we click.

  • Click Design.
  • Click the Fields section to expand it.
  • Scroll down and click the expansion icon for the Species field.
  • Enter this value for the URL field:
    • The filter portion of this URL replaces "Rat" with the substitution string "${Species}", meaning the value of the Species column. (If we were to specify "Rat", clicking any species link in the list would filter the list to only show the rats!)
    • The "listId" portion of the URL has been replaced with "name=NIMHDemographics."
  • Scroll down and click Save.

Now notice that the values in the "Species" column are all links. When you click one, you will get the filtering behavior we just defined.

  • Click Field mouse in any row and you will see the demographics list filtered to display only rows for field mice.

Create Links to Files

A column value can also include link to a file. All the values in a column could link to a fixed file (such as to a protocol document) or you can make row-specific links to files where a portion of the filename matches a value in the row such as the Subject ID in this example. Open this link in a new browser window:

Edit the URL, incrementing the file name 20023.png, 20024.png, 20025.png. These are simply cartoon images of our sample characters stored on a public server, but in actual use you might have slide images or other files of interest stored on your local machine and named by subjectId.

Here is a generalized version, using substitution syntax for the URL property, for use in the list design. It is already included in the list archive we provided.${SubjectID}.png&renderAs=IMAGE

  • Click the List Tutorial link near the top of the page, then click the NIMHDemographics list in the Lists web part.
  • Click Design.
  • Click the expansion icon to expand the CartoonAvailable field.
  • Notice the URL property for this field. It is the generalized version of the link above.
  • Scroll down to click Cancel to return to the grid for this list.
  • Observe that clicking true in the CartoonAvailable column opens an image of the 'subject' in that row. Click the 'true' link for the SubjectID 20022 to see the same image you opened earlier.


You've now completed the list tutorial. Learn more about lists in the related topics.

Related Topics

Previous Step