Pseudonymization (Beta)

Beta Feature

Pseudonymization is currently in beta. The API and behavior may change in future releases.

Pseudonymization is a data protection technique that replaces personally identifiable information (PII) with artificial identifiers, reducing the risk of direct re-identification while preserving data structure. In the Avatar platform, pseudonymization is available as an optional post-processing step that complements the anonymization process.

note

Pseudonymization and anonymization serve different but complementary purposes. Anonymization (via the Avatar method) protects against re-identification through statistical transformation, while pseudonymization replaces direct identifiers with substitutes. Used together, they provide layered privacy protection.

Why Pseudonymize?

When working with sensitive datasets, direct identifiers such as names, email addresses, or social security numbers must be handled carefully. While the Avatar anonymization method operates on pseudonymized data (without direct identifiers), you may need to:

• Preserve PII columns in the output with realistic but fake replacements for testing or demonstration purposes
• Maintain referential integrity across related tables — ensuring that a patient ID in a child table still correctly references its parent
• Comply with data handling policies that require PII to be systematically replaced rather than simply removed
• Streamline your workflow by handling pseudonymization and anonymization in a single pipeline

How It Works

Pseudonymization in the Avatar platform is applied after the anonymization process completes. The pipeline works as follows:

1. Before anonymization: PII columns are extracted and set aside — they do not participate in the Avatar method's statistical modeling
2. Anonymization: The Avatar method generates synthetic data based on the non-PII variables
3. After anonymization: Each PII column is pseudonymized using the configured strategy, and the resulting values are reattached to the anonymized output
4. Output: The final dataset contains anonymized statistical data alongside pseudonymized identifiers

This separation ensures that the anonymization quality is unaffected by the presence of direct identifiers.

Pseudonymization Strategies

Six strategy classes are available, each suited to different use cases. All strategies (except HashSha256Strategy and ConstantStrategy) accept a consistent parameter: when True (the default), the same source value always maps to the same replacement within a pipeline run, preserving referential integrity across tables.

FakeDataStrategy — Realistic Synthetic Values

Generates plausible fake values that match the type of PII. For example, an email column produces realistic email addresses, a name column produces realistic names.

• Best for: Testing, demonstrations, and scenarios where output data must look realistic
• Requires: The type of PII must be specified via pii_type (e.g., PiiType.EMAIL, PiiType.FIRST_NAME)
• Example: FakeDataStrategy(pii_type=PiiType.EMAIL)

high_variability parameter

The high_variability parameter controls the trade-off between speed and uniqueness of the generated values:

• high_variability=False (default): Avatar samples from a pre-generated pool of fake values using indexing. This is significantly faster, but different source values can receive the same fake value (collision possible).
• high_variability=True: Avatar generates a unique fake value for each row or for each unique source value (depending on consistent). This avoids collisions but is slower.

Use the default (False) in most cases. Set high_variability=True only when you need to guarantee that no two distinct source values receive the same fake replacement. Note that this is subject to the limits of the underlying library

HashSha256Strategy — Deterministic Hashing

Replaces each value with its SHA-256 cryptographic hash. The same input always produces the same output.

• Best for: Consistent key replacement across datasets and runs
• Behavior: Deterministic — identical inputs always yield identical outputs
• Note: Hashed values are not human-readable. Avoid this strategy for low-entropy columns (e.g. short codes or integers) as they are vulnerable to brute-force dictionary attacks
• Example: HashSha256Strategy()

Uuid4Strategy — Random Unique Identifiers

Replaces each value with a randomly generated UUID (version 4).

• Best for: Primary keys and identifiers where uniqueness matters more than readability
• Example: Uuid4Strategy()

ConstantStrategy — Fixed Replacement

Replaces every value in the column with the same fixed string, regardless of the original content.

• Best for: Fully suppressing or redacting a column
• Example: ConstantStrategy(value="REDACTED")

IntegerStrategy — Pseudonymous Integer IDs

Maps each unique source value to a unique pseudonymous integer. The mapping is randomized so that the original sort order is not preserved.

• Best for: Numeric identifiers (e.g. customer IDs, account numbers) when downstream code expects an integer type
• Example: IntegerStrategy()

SpecificIdStrategy — Structured Pattern-Based IDs

Generates structured identifiers from a user-defined pattern, combining literal characters with placeholders.

Placeholder	Description
#	Random digit (0–9)
?	Random letter (case controlled by letter_case)
^	Random alphanumeric character
{{col}}	Value of another column for the same row

The letter_case parameter (a SpecificIdLetterCase value) controls letter casing: UPPER, LOWER, or BOTH (default).

• Best for: Domain-specific identifiers with a required format (e.g. employee codes, reference numbers)
• Example: SpecificIdStrategy(pattern="EMP-####"), SpecificIdStrategy(pattern="{{dept}}-???##", letter_case=SpecificIdLetterCase.UPPER)

Supported PII Types

The platform recognizes the following types of personally identifiable information. These types guide the FakeDataStrategy in generating appropriate replacement values:

PII Type	Description	Example Original	Example Pseudonymized (FakeDataStrategy)
Email	Email addresses	jane.doe@corp.com	sarah.miller@example.net
First Name	Given names	Jane	Sarah
Last Name	Family names	Doe	Miller
Full Name	Complete names	Jane Doe	Sarah Miller
Phone	Phone numbers	+33 6 12 34 56 78	+33 6 98 76 54 32
SSN	Social security numbers	1 85 12 75 108 042	2 91 03 69 205 118
Address	Physical addresses	12 Rue de Rivoli	45 Avenue des Champs
Free Text	Arbitrary text fields	Patient note...	Lorem ipsum...

tip

The PII type only needs to be specified when using FakeDataStrategy. All other strategies work independently of the PII type.

Multi-Table Referential Integrity

When working with multi-table datasets (e.g., a patients table linked to a visits table), pseudonymization automatically maintains referential integrity:

• A pseudonymized primary key in the parent table is consistently applied to matching foreign keys in child tables
• This ensures that relationships between tables remain valid after pseudonymization
• Child table foreign keys automatically inherit the parent's pseudonymization mapping — no additional configuration is needed

For example, if patient_id in the patients table is pseudonymized with UUID, the same mapping is applied to patient_id in the visits table, preserving the parent-child relationship.

Getting Started

Pseudonymization is configured per column when setting up your avatarization parameters. You pass a strategy object for each column that should be pseudonymized — no configuration is needed for foreign key columns, which automatically inherit their parent's mapping.

For technical documentation, code examples, and step-by-step tutorials, refer to the Python Client documentation:

• User Guide — How to pseudonymize PII columns
• Tutorial — Pseudonymization walkthrough