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.
| ParticipantId | Aliases | SourceOrganization | Date |
|---|
| 101344 | Primate 44 | ABC Labs | 10/10/2010 |
| 101344 | Macaque 1 | Research Center A | 11/11/2011 |
| 103505 | Primate 45 | ABC Labs | 10/10/2010 |
| 103866 | Primate 46 | ABC Labs | 10/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.
