Skip to content

Quickstart

This walkthrough takes you from a clean checkout to a privatized CSV and a privacy audit report in about five minutes. It uses JSON mode, so you do not need MongoDB.

1. Install

git clone https://github.com/philterd/philter-diffuse.git
cd philter-diffuse
python -m venv venv
source venv/bin/activate            # Windows: venv\Scripts\activate
pip install -r requirements.txt

Confirm the tool runs:

python main.py --version

2. Create some input counts

Philter Diffuse privatizes counts of PII entities. These usually come from the PII counts Philter records, but for this quickstart create a small JSON file by hand. Save the following as pii_counts.json:

{
  "ssn": 8,
  "creditcard": 15,
  "age": 120,
  "zipcode": 45,
  "date": 3
}

The keys are PII types and the values are raw counts (for example, 8 documents contained an SSN).

3. Run the privatization

python main.py \
  --input pii_counts.json \
  --source quickstart \
  --output privatized_counts.csv \
  --pii-types ssn,creditcard,age,zipcode,date \
  --scale 2.0 \
  --threshold 5

What each flag does:

  • --input reads the raw counts from your JSON file.
  • --source names the dataset. The privacy budget is tracked under this name, so renaming the file does not reset it.
  • --output writes the differentially private counts to a CSV.
  • --pii-types names the types to release. The output has exactly these rows whether or not the input holds each type, so choose the list before looking at the counts.
  • --scale 2.0 sets the noise level. Each listed PII type costs 1 / scale, because one document can add to every type at once, so these five types spend 5 / 2.0 = 2.5.
  • --threshold 5 masks any privatized count below 5 as None, protecting small cohorts.

4. Read the audit report

The tool prints a privacy audit report to the console. Because the noise is random, your numbers will differ slightly each run:

========================================
PRIVACY AUDIT REPORT
========================================
Privacy Loss (Epsilon): 2.5000
Protection Strength:   MODERATE
Influence Limit:      e^2.50 (12.18x)
Output File:          privatized_counts.csv
Count Threshold:      5
----------------------------------------
PII Type        | Private
----------------------------------------
ssn             | 9
creditcard      | 14
age             | 122
zipcode         | 49
date            | None
----------------------------------------
  • Privacy Loss (Epsilon) is the budget spent by this query.
  • Protection Strength is a plain-language reading of epsilon (MODERATE here). Raise --scale for stronger protection: --scale 10 spends 0.5 on these five types.
  • The table shows the private counts, the same values as the CSV. The report never prints raw counts, so it is safe in logs.
  • date shows None because its privatized count fell below the threshold of 5.

5. Inspect the CSV

cat privatized_counts.csv

PII Type,Private Count
ssn,9
creditcard,14
age,122
zipcode,49
date,None

This CSV is the artifact you can hand to analysts, auditors, or a downstream dashboard.

6. Watch the privacy budget

Philter Diffuse remembers how much epsilon you have spent against each source. Run the same command again and look at the budget file it created:

cat ~/.philter-diffuse/privacy_budget.json

{"quickstart": 5.0}

Two runs at --scale 2.0 have spent 2.5 + 2.5 = 5.0. The default ceiling is 10.0; once cumulative epsilon would cross it, Philter Diffuse refuses the run: it exits with an error and writes no output. See Privacy Budget Management for how to manage and reset the budget.

Next steps

  • Read counts straight from MongoDB, or Philter's recorded PII counts through its API, in Usage.
  • Understand epsilon, the ceiling, and budget exhaustion in Privacy Budget Management.
  • Check the release state and maturity in Project Status.