Table of Contents

 guest
2025-06-21
         Manage Participant IDs
           Alternate Participant IDs
           Alias Participant IDs

Manage Participant IDs


These topics help you solve common problems when working the participant/subject ids.


Alternate Participant IDs


When exporting study data, you can obscure the real participant ids by replacing them with randomly generated, alternate ids. You can also shift participant dates to obscure the exact dates but preserve the elapsed time between them.

Alternate IDs are unique and automatically generated for each participant. Once generated, the alternate IDs will not change unless you explicitly request to change them. Multiple publications of the same study will use the same alternate IDs and date offsets.

Note that alternate ids are not the same as alias ids. Alias participant ids are used for aligning data from different sources, where each may use different names, or aliases, for the same participant or organism; whereas alternate ids are used to hide the real participant ids from your audience.

Change Alternate IDs

You can control the prefix and number of digits in the generated alternate IDs: go to (Admin) > Manage Study > Manage Alternate Participant IDs and Aliases. You can also export a list of the alternate IDs and date offsets from this page.

  • Click the Manage tab.
  • Click Manage Alternate Participant IDs and Aliases.
  • For Prefix, enter a fixed prefix to use for all alternate IDs.
  • Select the number of digits you want the alternates to use.
  • Click Change Alternate IDs. Click to confirm; these alternates will not match any previously used alternate IDs.
  • Scroll down and click Done.

Change Participant ID

If you want to change a participant ID within a study, perhaps because naming conventions have changed, or data was accidentally entered with the wrong ID, you can do so as follows.

  • Go to (Admin) > Manage Study > Manage Alternate Participant IDs and Aliases.
  • Click Change or Merge ParticipantID.
  • Enter the participant id to change, and the value to change it to. If you are changing to a participant ID which already exists within the study, see the next section about Merging Participant Data.
  • Click Preview.
  • LabKey Server searches all of the data in the folder and presents a list of datasets to be changed.
  • Click Merge to complete the participant ID change.

Merging Participant Data

Suppose you discover that data for the same individual in your study has been entered under two participant IDs. This can happen when naming conventions change, or when someone accidentally enters the incorrect participant id. Now LabKey Server thinks there are two participants, when in fact there is only one actual participant. To fix these sort of naming mistakes and merge the data associated with the "two" participants into one, LabKey Server can systematically search for an id and replace it with a new id value.

  • Decide which participant ID you want to remove from the study. This is the "old" ID you need to change to the one you want to retain.
  • Follow the same procedure as for changing a participant ID above.
  • Enter the "old" value to change (9 digits in the following screencap), followed by the ID to use for the merged participant (6 digits shown here).
  • Click Preview.
  • LabKey Server searches all of the data in the folder and presents a list of datasets to be changed.
  • Click link text in the report to see filtered views of the data to be changed.
  • If conflicts are found, i.e., when a dataset contains both ids, use the radio buttons in the right hand column to choose which participantID's set of rows to retain.
  • Click Merge to run the replacement.
If your folder contains a configured alias mapping table, you will have the option to convert the old name to an alias by selecting Create an Alias for the old ParticipantId. When this option is selected, a new row will be added to the alias table. For details on configuring an alias table, see Alias Participant IDs.
  • If an alias is defined for an old id, the server won't update it on the merge. A warning is provided in the preview table: "Warning: <old id> has existing aliases".

Note that if a dataset is marked as read-only (a common option for specimen-related datasets), a red warning message appears in the status column as shown above.

Related Topics

  • Publish a Study - Export randomized dates; hold back protected data columns.
  • Alias Participant IDs - Align participant data from sources that use different names for the same subject.


Alias Participant IDs


A single participant can be known by different names in different research contexts. One lab might study a participant using the name "LK002-234001", whereas another lab might study the very same organism knowing it only by the name "WISC Primate 44". It is often desirable to keep different audiences in ignorance of the fact that these names point to one and the same entity. LabKey Server can align the various aliases for a given subject and control which alias is used for which research audience. In this way, alias ids provide functionality similar to an "honest broker" system.

LabKey Server's aliasing system works by internally mapping different aliases to a central participant id, while externally preserving the aliases known to the different data sources. This allows for:

  • merging records with different ids for the same animal
  • consolidating search results around a central id
  • retaining data as originally provided by a client

Merge Data Containing Participant Alias Names

To set up alias ids, point to a dataset that contains the aliases for each participant, where one column contains the aliases for a given participant and other column which contains the source organizations that use those aliases.

  • Add a dataset containing the alias and source organization information. See below for an example file.
  • Go to (Admin) > Manage Study > Manage Alternate Participant IDs and Aliases.
  • Point to the dataset using the dropdown field Dataset Containing Aliases.
  • Point to the column containing alias names using Alias Column.
  • Point to the column containing the source organization using Source Column.
  • Click Save Changes and Done.

Once an alias has been defined for a given participant, an automatic name substitution is performed on any imported data that contains that alias. For example, if participant "100123" has a defined alias "Primate 44", then any data containing a reference to "Primate 44" will be changed to "100123" before it is inserted into the database.

An example alias mapping file is shown below. Note that the file must contain a date (or visit) column.

ParticipantIdAliasesSourceOrganizationDate
101344Primate 44ABC Labs10/10/2010
101344Macaque 1Research Center A11/11/2011
103505Primate 45ABC Labs10/10/2010
103866Primate 46ABC Labs10/10/2010

Resolving Naming Conflicts

What if incoming data contains an id that is already used being used in the system to refer to a different subject? To resolve naming conflicts like this, you can systematically search and replace a given id, and optionally retain one of the conflicting names as an alias. For details see Alternate Participant IDs.

Once you have an alias dataset in place, you can add more records to it by clicking Import Aliases.

To clean all alias mappings, but leave the alias dataset in place, click Clear All Alias Settings.

Viewing the Original, Non-Alias Participant Ids

Note that clearing the alias settings in a study does not revert the participant ids back to their original, non-aliased values. Alias participant ids are determined at import time and are written into the imported dataset. But you can add a column to your datasets that shows the original ParticiantIds, which can be useful for displaying the dataset to the source organization that knows the participant by the non-aliased id. To display the original ParticipantId values, add the Aliases column to the imported dataset as follows:

  • Navigate to the dataset where you want to display the original, non-alias ParticipantIds.
  • Select (Grid Views) > Customize Grid.
  • In the Available Fields panel, click the plus sign next to Datasets to see the available datasets in the study. (Don't open the node "Dataset", which contains metadata about the current dataset.)
  • Locate the dataset that contains the alias id mappings. Click the plus sign next to that table, and place a checkmark next to the field that contains the alias ids, adding it to the dataset for display.
  • Save the grid view, either as the default grid view, or as a named view.
  • The dataset now displays both the alias id and the original id.