This topic is under construction for the July 2020 release of LabKey Server. For current documentation of this feature, click here.
LabKey provides a customizable framework for longitudinal study data. A study tracks information about subjects over time. You can explore a read-only example here:
This topic assumes you have your own time series data about some study subjects and helps you create your own study where you can upload and analyze data of your own. To do that, you will use a cloud-hosted trial version of LabKey Server. It takes a few minutes to set up and you can use it for 30 days.
If you already have a Trial Server to use, you can log in to it and skip ahead
Start a Trial Server
Log In Here
To start a trial, you need a free account on www.labkey.org.
Start a Trial Server
- Logged in to your www.labkey.org account, click here. It will open in a new tab:
- Use that new tab in parallel with this topic to complete the process:
- Click Add Product.
- Under LabKey Server - Trial, click Create Site.
- Give your site a Name: This will be shown in the header (where you see "LabKey Support" on this page).
- Select your unique URL: Something short and memorable that will be the first segment of your URL.
- Leave the Product, "LabKey Server - Trial" selected.
- Click Create Site.
Site creation takes approximately 5 minutes. While you wait, let's plan the design of your study and gather information.
Plan Your Study Framework
You may already have data you plan to upload. If not, we will provide example files to get you started.
Identify your Study Subjects
The subjects being studied, "participants" by default, can be humans, animals, trees, cells, or anything else you want to track.
Look at a dataset you plan to use. How are subjects under study identified. What column holds identifying information?
Decide How To Track TimeTime Based
The example study to explore
tracks time using dates. The date of each data collection are entered and the study is configured to break these into month-long timepoints
, labeled as "Month 1", "Month 2" etc.Visit Based
You can also track time in a visit-by-visit manner. If the elapsed time between events is not relevant but you have a fixed sequence of visit events, a visit-based study may be appropriate. Visits are identified by sequence numbers.Continuous
A continuous study is used when there is no strong concept of visits or fixed buckets of time. Data is entered and tracked by date without using timepoints.
If your study will integrate with data from analysis of specimens, you can incorporate that information. This walkthrough does not cover that scenario - you can learn more in this topic: Specimens: Administrator Guide
Identify your security requirements and how you plan to use the data in your study. Who will need access to what data. Will you want to be able to assign access 'per dataset' or is folder level security sufficient?
When you select your Security Mode
, use basic if folder-level is sufficient and "custom" otherwise. Learn more about study security in this topic: Manage Study Security (Dataset-Level Security)
Create Your Study
- Once your trial server has been created, you will receive an email notification with a direct link to it, or you can click Go To Site in the trial manager.
- Click the Create Project button on the home page.
- Enter Name "Tutorials", leave the default folder type and click Next, then Next and then Finish to create the new project with all the default settings.
- In the new project, click Create New Subfolder.
- Enter the Name you want. In our example, it is named "My New Study".
- Select the folder type Study and click Next.
- Click Finish to create the folder.
- Click Create Study.
- Under Look and Feel Properties:
- Study Label: Notice your folder name has the word "Study" added; you can edit to remove redundancy here if you like.
- Subject Noun (Singular and Plural): If you want to use a word other than "Participant/Participants" in the user interface, enter other nouns here.
- Subject Column Name: Look at the heading in your dataset for the column containing indentifiers. Edit this field to match that column.
- Under Visit/Timepoint Tracking:
- Select the type of time tracking you will use. Dates, Assigned Visits, or Continuous.
- If needed for your selection, enter Start Date and/or Default Timepoint Duration.
- Under Specimen Management:
- Leave the default selection. You can change it later if you decide to add specimen data to the study.
- Under Security Mode:
- Select whether to use basic or custom security and whether to make datasets editable or read-only.
- To maximize the configurability of this study, choose Custom security with editable datasets.
- Click Create Study.
- You will now be on the Manage tab of your own new study. This tab exists in the read-only exploration study we provided, but you cannot see it there. It is visible only to administrators.
Upload Your Data
Add Demographic Data
Begin with your demographic dataset. Every study is required to have one, and it contains one row per study participant (or subject). It does not have to be named "Demographics.xls", and you do not have to name your dataset "Demographics"; that is just the convention used in LabKey examples and tutorials.
- On the Manage tab of your new study, click Manage Datasets.
- Click Create New Dataset.
- Give the dataset a short name (such as "Demographics"). This name does not have to match your filename.
- Under Data Row Uniqueness, select Participants Only (demographic data).
- Click the Fields section to open it.
- Drag your demographic data spreadsheet into the Infer fields from file target area.
- The column names and data types will be inferred. You can change types or columns as needed.
- In the Column Mapping section, be sure that your mappings are as intended: Participant (or Subject) column and either "Date" for date-based or "Sequence Num" for visit-based studies.
- Note: All your study data is assumed to have these two columns.
- Notice the Import data from this file upon dataset creation? section is enabled and preview the first few lines of your data.
- Click Save to create and populate the dataset.
- Click View Data to see it in a grid.
You can now click the Participants/Subjects
tab in your study and see the list gleaned from your spreadsheet. Each participant has a built in participant report that will contain (so far) their demographic data.
Add More Datasets
Repeat the above process for the other data from your study, except under Data Row Uniqueness
, non-demographic datasets will use the default Participants and Visits
. For example, you might have some sort of Lab Results for a set of subjects. Each row in a dataset like this will have one row per participant and visit/date combination. This enables studying results over time.
For each data spreadsheet:
- Select Manage > Manage Datasets > Create New Dataset.
- Name each dataset, select the data row uniqueness, upload the file, confirm the fields, and import.
Once you have uploaded all your data, click the Clinical and Assay Data
tab to see the list of datasets.
Join your Data
With only two datasets, one demographic, you can begin to integrate your data.
- Click the Clinical and Assay Data tab.
- Click the name of a non-demographic dataset, such as one containing "Lab Results". You will see your data.
- Select (Grid Views) > Customize Grid.
- You will see a Datasets node under Available Fields.
- Click the to expand it.
- Click the for the Demographics dataset.
- Check one or more boxes to add Demographics columns to your grid view.
- Click View Grid to see the joined view. Save to save it either as the default or as a named grid view.
Learn more about creating joined grids in this topic: Customize Grid Views