> For the complete documentation index, see [llms.txt](https://documentation.dnanexus.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.dnanexus.com/admin/trusted-research-environments/pseudonymization.md).

# Pseudonymization in Trusted Research Environments

Learn how participant pseudonymization protects sensitive identifiers in Trusted Research Environments by replacing PIDs with unique EIDs.

{% hint style="info" %}
Apollo and Trusted Research Environments licenses are required to use Trusted Research Environments on the DNAnexus Platform. [Contact DNAnexus Sales](mailto:sales@dnanexus.com) for more information.
{% endhint %}

Trusted Research Environments (TREs) support participant pseudonymization to protect privacy when sharing sensitive biomedical data. When enabled, pseudonymization replaces source participant identifiers with unique, project-specific pseudonyms across all data modalities dispensed to approved researchers.

This capability helps data providers meet governance requirements and data use agreements without manually generating and managing separate identifiers for each data release.

## Participant Identifiers and Pseudonyms

Pseudonymization uses two forms of participant identifiers:

* **PID** (Participant Identifier) — The source participant identifier held by the data provider in the original dataset or file inventory.
* **EID** (Encoded Identifier) — The pseudonymized participant identifier that replaces the PID in dispensed data.

In a File Inventory TSV, the participant identifier column header is always `eid`. In your source inventory, this column holds the source PID before pseudonymization replaces it with the mapped EID in dispensed data.

Each Data Access Request (DAR) receives its own independent set of EIDs. The same participant receives different EIDs across different approved researcher projects, preventing cross-project linkage of participant records.

## Enabling Pseudonymization

A TRE Admin enables pseudonymization in the **Data Governance** settings modal during initial environment configuration.

Enabling pseudonymization has the following rules:

* **Draft state only** — You can configure pseudonymization only while the research environment is in **Draft** state. While the TRE remains in **Draft** state, you can toggle the setting on or off.
* **Permanent after publishing** — Once you publish the TRE, the setting is permanently locked. You cannot enable or disable pseudonymization while the environment is in **Active** or **Maintenance** state, and if enabled, it applies permanently to all future data dispensals from that environment.
* **Admin permission required** — Only users with the TRE Admin role can modify Data Governance settings.

To learn how to configure this setting during setup, see [create and publish a TRE](https://documentation.dnanexus.com/admin/trusted-research-environments/creating-a-tre.md). For asset preparation guidelines, see [plan a TRE](https://documentation.dnanexus.com/admin/trusted-research-environments/planning-a-tre.md).

## Participant ID Source Priority

When creating EID mappings for a data release, the platform determines the complete list of unique participant identifiers using the following source priority:

| Priority | Participant ID source                 | Condition                                                             | Enforce Full Set Selection |
| -------- | ------------------------------------- | --------------------------------------------------------------------- | -------------------------- |
| 1        | **Data Showcase**                     | Present in Resource Inventory                                         | Configurable               |
| 2        | **Tabular Data Inventory**            | Present and no Data Showcase configured                               | Configurable               |
| 3        | **Participant IDs (PID) CSV**         | Neither database configured and optional Participant IDs CSV supplied | Mandatory                  |
| 4        | **File Inventory TSV (`eid` column)** | Neither database configured and no Participant IDs CSV supplied       | Mandatory                  |

When both a Data Showcase and a Tabular Data Inventory are configured, the Data Showcase is the authoritative source for the participant list.

When neither database is configured (a file-only inventory), the platform derives participant identifiers from the `eid` column of the File Inventory TSV by default. You can optionally supply a [Participant IDs (PID) CSV](https://documentation.dnanexus.com/admin/trusted-research-environments/preparing-resource-inventory-for-file-only-tre.md#prepare-the-participant-ids-pid-csv-optional) in the Resource Inventory to override automatic derivation and ensure that the full participant cohort is represented when not every participant has a per-participant file in the File Inventory TSV. Because an environment without a Data Showcase does not support cohort selection, **Enforce Full Set Selection** is mandatory.

## Pseudonymized Dispensal Results

When pseudonymization is enabled, the platform transforms participant identifiers across all supported data modalities on dispensal:

| Data modality                  | Transformation result                                                                                                    |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| **Per-participant bulk files** | Dispensed file names use the remapped EID instead of the original PID.                                                   |
| **Array files**                | Participant identifiers in FAM, SAMPLE, and REL files are replaced by remapped EIDs.                                     |
| **pVCF files**                 | Participant identifiers in the pVCF sample header line are replaced by remapped EIDs through a watermark.                |
| **Tabular data**               | Values in `participant.eid` are replaced with remapped EIDs.                                                             |
| **Assay data**                 | Assay linking tables map assay records to remapped EIDs so you can view assay data alongside pseudonymized tabular data. |

Within a single dispensed project, the platform uses the same mapping across all applicable modalities, ensuring consistency across tabular data, bulk files, and assay records.

## Identifier Mapping Lifecycle and Access

The platform creates the PID-to-EID mapping automatically on the first data dispensal for a DAR:

* **Cohort-scoped requests** — For environments that allow cohort selection, the platform generates mappings only for participants in the selected cohort.
* **Full-participant requests** — For environments with Enforce Full Set Selection enabled, the platform generates mappings for all participants in the environment.

When an administrator updates the Resource Inventory to a new version, previously assigned PID-to-EID mappings remain unchanged for existing participants. Any new participants added in the revised inventory receive newly generated EIDs on subsequent dispensals.

### Access to Mapping Artifacts

Each dispensal generates an `eid_mapping.csv` file with the following header:

```csv
dnx_eid,eid
```

In this file, `dnx_eid` is the source PID and `eid` is the mapped pseudonymized EID for the dispensed project.

Access to the mapping artifact is restricted:

* **TRE Admins only** — TRE Admins can download the mapping CSV for any dispensed DAR project using the [`/system/downloadEIDMapping`](https://documentation.dnanexus.com/developer/api/system-methods.md#api-method-system-downloadeidmapping) API method to support authorized re-identification, audit, or data management workflows. For instructions, see [Download EID Mapping Artifacts](https://documentation.dnanexus.com/admin/trusted-research-environments/managing-tre-lifecycle.md#download-eid-mapping-artifacts).
* **Not accessible to researchers** — Researchers and other project members cannot view, access, or download the mapping artifact. Source PIDs are never exposed within researcher projects.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://documentation.dnanexus.com/admin/trusted-research-environments/pseudonymization.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
