repository·main·Indexed 43 days ago
https://github.com/opendp/smartnoise-sdkA suite of tools for differential privacy on tabular data, featuring smartnoise-sql for differentially private SQL queries and smartnoise-synth for synthetic data generation using MWEM and PATE-CTGAN. Includes smartnoise-eval (v0.3.1) for assessing privacy and accuracy through dataset analysis and result evaluation, requiring PySpark.
The SmartNoise SDK provides tools for applying differential privacy to tabular data. It is composed of two primary packages:
Both packages support Python 3.10 through 3.14.
The SmartNoise Evaluator is a toolset for assessing the privacy and accuracy of differentially private queries. It consists of two primary capabilities:
Requirement: These tools currently require PySpark to function.
The SmartNoise Eval library provides three main classes for managing data and performing analysis/evaluation:
sneval.Analyze: The entry point for performing data analysis to inform your synthesis strategy.sneval.Dataset: A class used to represent and manage the datasets being analyzed or evaluated.sneval.Evaluate: The entry point for comparing original data with synthetic/private data to assess quality.The smartnoise-synth package provides several differentially private synthesizers for tabular data, including:
Privacy parameters (epsilon and delta) apply to each computed column for the life of the session.
reader.odometer.spent.reader.get_privacy_cost(query_string) to estimate the cost of a query before executing it. This does not advance the odometer.odometer.spent) may accrue at a slower rate than the sum of individual get_privacy_cost calls due to how mechanisms are composed.# Estimating cost without executing
cost = reader.get_privacy_cost('SELECT AVG(age), AVG(income) FROM PUMS.PUMS')
# Checking total spent after execution
print(reader.odometer.spent)SmartNoise provides different tools depending on your data type and privacy requirements. Use the following rules of thumb to select a component:
Privacy parameters epsilon and delta are set when instantiating a Privacy object and apply to each computed column for the session. Privacy cost accumulates as queries are executed. You can track the total accumulated cost using the spent property of the connection's odometer.
Key behaviors:
get_privacy_cost because the odometer tracks all mechanism invocations for the life of the session.odometer across multiple readers to track a single privacy budget across different workloads.from snsql import Privacy, from_connection
# Initialize privacy
privacy = Privacy(epsilon=0.1, delta=10e-7)
reader = from_connection(conn, metadata=metadata, privacy=privacy)
print(reader.odometer.spent) # (0.0, 0.0)
# Execute query and see cost increase
result = reader.execute('SELECT COUNT(*) FROM PUMS.PUMS')
print(reader.odometer.spent) # approximately (0.1, 10e-7)The Evaluate capability compares an original data file against one or more comparison (privatized) files. It can compare single-file metrics produced by Analyze or perform two-dataset comparisons. If multiple comparison datasets are provided, the tool provides comparisons for each against the original, allowing you to aggregate results (e.g., by averaging).
Metrics provided include:
< 1000, >= 1000).The Analyze capability provides detailed metrics about a single dataset to help prepare for differential privacy workflows. Key metrics provided include:
MWEM's performance depends on the quality of its candidate query workload. By default, it generates workloads consisting of all one-way and two-way marginals. You can tune this behavior using the following parameters:
marginal_width: Controls the complexity of marginals. Increasing this ensures three-way or higher marginals are included as candidates. Setting marginal_width=1 suppresses two-way marginals.add_ranges: When used (especially with ordinal data or binned continuous values), this ensures candidate queries include range queries.q_count: Specifies a fixed number of candidate queries to generate, regardless of the number of iterations. This is useful if you want to prioritize range queries over marginals.measure_only: If set to True, the algorithm skips the query selection step and samples uniformly from the workload. This doubles the epsilon budget available for measuring queries but is generally only recommended for very small datasets.When using the MWEM or MST synthesizers, input columns must be categorical.
If your dataset contains continuous values, you must discretize them before fitting the model. Warning: Ensure that the discretization process itself is performed in a way that does not reveal information about the underlying data distribution.