privacy_meter package
Subpackages
Submodules
privacy_meter.audit module
- class privacy_meter.audit.Audit(metrics: Union[privacy_meter.constants.MetricEnum, privacy_meter.metric.Metric, List[Union[privacy_meter.constants.MetricEnum, privacy_meter.metric.Metric]]], inference_game_type: privacy_meter.constants.InferenceGame, target_info_sources: Optional[Union[privacy_meter.information_source.InformationSource, List[privacy_meter.information_source.InformationSource]]] = None, reference_info_sources: Optional[Union[privacy_meter.information_source.InformationSource, List[privacy_meter.information_source.InformationSource]]] = None, fpr_tolerances: Optional[Union[float, List[float]]] = None, logs_directory_names: Optional[Union[str, List[str]]] = None)[source]
Bases:
object
This class is here to orchestrate how the Metric objects and the InformationSource objects interact with one another. The three steps of using this class are 1) initialization 2) audit.prepare() 3) audit.run()
- prepare()[source]
Core function that should be called after the initialization and before the audit.run() function. Runs the prepare_metric function of all metric objects, which computes (or load from memory) the signals required for the inference algorithms.
- run() List[privacy_meter.metric_result.MetricResult] [source]
Core function that should be called after the audit.prepare() function. This actually runs the metrics’ inference algorithms.
- Returns
A list of MetricResult objects (one per metric)
privacy_meter.audit_report module
- class privacy_meter.audit_report.AuditReport[source]
Bases:
abc.ABC
An abstract class to display and/or save some elements of a metric result object.
- abstract static generate_report(metric_result: Union[privacy_meter.metric_result.MetricResult, List[privacy_meter.metric_result.MetricResult], dict], inference_game_type: privacy_meter.constants.InferenceGame)[source]
Core function of the AuditReport class, that actually generates the report.
- Parameters
metric_result – MetricResult object, containing data for the report.
inference_game_type – Value from the InferenceGame ENUM type, indicating which inference game was used.
- class privacy_meter.audit_report.ConfusionMatrixReport[source]
Bases:
privacy_meter.audit_report.AuditReport
Inherits of the AuditReport class, an interface class to display and/or save some elements of a metric result object. This particular class is used to generate a confusion matrix.
- static generate_report(metric_result: Union[privacy_meter.metric_result.MetricResult, List[privacy_meter.metric_result.MetricResult]], inference_game_type: privacy_meter.constants.InferenceGame, show: bool = False, save: bool = True, filename: str = 'confusion_matrix.jpg')[source]
Core function of the AuditReport class, that actually generates the report.
- Parameters
metric_result – MetricResult object, containing data for the report.
inference_game_type – Value from the InferenceGame ENUM type, indicating which inference game was used.
show – Boolean specifying if the plot should be displayed on screen.
save – Boolean specifying if the plot should be saved as a file.
filename – File name to be used if the plot is saved as a file.
- class privacy_meter.audit_report.PDFReport[source]
Bases:
privacy_meter.audit_report.AuditReport
Inherits of the AuditReport class, an interface class to display and/or save some elements of a metric result object. This particular class is used to generate a user-friendly report, with multiple plots and some explanations.
- static generate_report(metric_results: Dict[str, Union[privacy_meter.metric_result.MetricResult, List[privacy_meter.metric_result.MetricResult], List[List[privacy_meter.metric_result.MetricResult]]]], inference_game_type: privacy_meter.constants.InferenceGame, figures_dict: dict, system_name: str, call_pdflatex: bool = True, show: bool = False, save: bool = True, filename_no_extension: str = 'report', target_info_source: Optional[privacy_meter.information_source.InformationSource] = None, target_model_to_train_split_mapping: Optional[List[Tuple[int, str, str, str]]] = None, point_type: str = 'any')[source]
Core function of the AuditReport class, that actually generates the report.
- Parameters
metric_results – A dict of lists of MetricResult objects, containing data for the report.
inference_game_type – Value from the InferenceGame ENUM type, indicating which inference game was used.
figures_dict – A dictionary containing the figures to include, for each metric result. E.g. {“shadow_metric”: [“roc_curve”, “confusion_matrix”, “signal_histogram”]}
system_name – Name of the system being audited. E.g. “Purchase100 classifier”
call_pdflatex – Boolean to specify if the pdflatex compiler should be called (to get a PDF file from the TEX file)
show – Boolean specifying if the plot should be displayed on screen.
save – Boolean specifying if the plot should be saved as a file.
filename_no_extension – File name to be used if the plot is saved as a file, without the file extension.
- class privacy_meter.audit_report.ROCCurveReport[source]
Bases:
privacy_meter.audit_report.AuditReport
Inherits of the AuditReport class, an interface class to display and/or save some elements of a metric result object. This particular class is used to generate a ROC (Receiver Operating Characteristic) curve.
- static generate_report(metric_result: Union[privacy_meter.metric_result.MetricResult, List[privacy_meter.metric_result.MetricResult], List[List[privacy_meter.metric_result.MetricResult]]], inference_game_type: privacy_meter.constants.InferenceGame, show: bool = False, save: bool = True, filename: str = 'roc_curve.jpg')[source]
Core function of the AuditReport class, that actually generates the report.
- Parameters
metric_result – A list of MetricResult objects, containing data for the report.
inference_game_type – Value from the InferenceGame ENUM type, indicating which inference game was used.
show – Boolean specifying if the plot should be displayed on screen.
save – Boolean specifying if the plot should be saved as a file.
filename – File name to be used if the plot is saved as a file.
- class privacy_meter.audit_report.SignalHistogramReport[source]
Bases:
privacy_meter.audit_report.AuditReport
Inherits of the AuditReport class, an interface class to display and/or save some elements of a metric result object. This particular class is used to generate a histogram of the signal values.
- static generate_report(metric_result: Union[privacy_meter.metric_result.MetricResult, List[privacy_meter.metric_result.MetricResult]], inference_game_type: privacy_meter.constants.InferenceGame, show: bool = False, save: bool = True, filename: str = 'signal_histogram.jpg')[source]
Core function of the AuditReport class, that actually generates the report.
- Parameters
metric_result – MetricResult object, containing data for the report.
inference_game_type – Value from the InferenceGame ENUM type, indicating which inference game was used.
show – Boolean specifying if the plot should be displayed on screen.
save – Boolean specifying if the plot should be saved as a file.
filename – File name to be used if the plot is saved as a file.
- class privacy_meter.audit_report.VulnerablePointsReport[source]
Bases:
privacy_meter.audit_report.AuditReport
Inherits of the AuditReport class, an interface class to display and/or save some elements of a metric result object. This particular class is used to identify the most vulnerable points.
- static generate_report(metric_results: List[privacy_meter.metric_result.MetricResult], inference_game_type: privacy_meter.constants.InferenceGame, target_info_source: privacy_meter.information_source.InformationSource, target_model_to_train_split_mapping: List[Tuple[int, str, str, str]], number_of_points: int = 10, save_tex: bool = False, filename: str = 'vulnerable_points.tex', return_raw_values: bool = True, point_type: str = 'any')[source]
Core function of the AuditReport class, that actually generates the report.
- Parameters
metric_results – A dict of lists of MetricResult objects, containing data for the report.
target_info_source – The InformationSource associated with the audited model training
target_model_to_train_split_mapping – The mapping associated with target_info_source
number_of_points – Number of vulnerable to be selected
save_tex – Boolean specifying if a partial .tex file should be generated
filename – Filename of the partial .tex file
return_raw_values – Boolean specifying if the points indices and scores should be returned
point_type – Can be “any” or “image”. If “image”, then the images are displayed as such in the report.
- Returns
Indices of the vulnerable points and their scores
privacy_meter.constants module
- class privacy_meter.constants.InferenceGame(value)[source]
Bases:
enum.Enum
An enumeration.
- AVG_PRIVACY_LOSS_TRAINING_ALGO = 'Average privacy loss of a training algorithm'
- PRIVACY_LOSS_MODEL = 'Privacy loss of a model'
- PRIVACY_LOSS_SAMPLE = 'Privacy loss of a data record'
- WORST_CASE_PRIVACY_LOSS_TRAINING_ALGO = 'Worst-case privacy loss of a training algorithm'
privacy_meter.dataset module
- class privacy_meter.dataset.Dataset(data_dict: dict, default_input: str, default_output: str, preproc_fn_dict: Optional[dict] = None, preprocessed: bool = False)[source]
Bases:
object
Wrapper around a dictionary-like formatted dataset, with functions to run preprocessing, to define default input/output features, and to split a dataset easily.
- get_feature(split_name: str, feature_name: str, indices: Optional[list] = None)[source]
Returns a specific feature from samples of a specific split.
- Parameters
split_name – Name of the split
feature_name – Name of the feature
indices – Optional list of indices. If not specified, the entire subset is returned.
- Returns
The requested feature, from samples of the requested split.
- preprocess()[source]
Preprocessing function, executed by the constructor, based on the preproc_fn_dict attribute.
- subdivide(num_splits: int, split_names: Optional[list] = None, method: str = 'independent', split_size: Optional[Union[int, Dict[str, int]]] = None, delete_original: bool = False, in_place: bool = True, return_results: bool = False)[source]
Subdivides the splits contained in split_names into sub-splits, e.g. for shadow model training.
- Parameters
num_splits – Number of sub-splits per original split.
split_names – The splits to subdivide (e.g. train and test). By default, includes all splits.
method – Either independent or random. If method is independent, then the sub-splits are a partition of the original split (i.e. they contain the entire split without repetition). If method is random, then each sub-split is a random subset of the original split (i.e. some samples might be missing or repeated). If method is hybrid, then each sub-split is a random subset of the original split, with the guarantee that the 1st one is not overlapping with the others.
split_size – If method is random, this is the size of one split (ignored if method is independent). Can either be an integer, or a dictionary of integer (one per split).
delete_original – Indicates if the original split should be deleted.
in_place – Indicates if the new splits should be included in the parent object or not
return_results – Indicates if the new splits should be returned or not
- Returns
If in_place, a list of new Dataset objects, with the sub-splits. Otherwise, nothing, as the results are stored in self.data_dict.
privacy_meter.hypothesis_test module
- privacy_meter.hypothesis_test.threshold_func(distribution: List[float], alpha: float) float [source]
Function that returns the threshold as the alpha quantile of the provided distribution.
- Parameters
distribution – Sequence of values that form the distribution from which
computed. (the threshold is) –
alpha – Quantile value that will be used to obtain the threshold from the
distribution. –
- Returns
alpha quantile of the provided distribution
- Return type
threshold
privacy_meter.information_source module
- class privacy_meter.information_source.InformationSource(models: List[privacy_meter.model.Model], datasets: List[privacy_meter.dataset.Dataset], default_model_to_split_mapping: Optional[List[Tuple[int, str, str, str]]] = None)[source]
Bases:
object
Interface to dispatch Model objects, Dataset objects, and any additional objects required, to Signal objects.
- get_signal(signal: privacy_meter.information_source_signal.Signal, model_to_split_mapping: Optional[List[Tuple[int, str, str, str]]] = None, extra: Optional[dict] = None)[source]
Calls the signal object with the appropriate arguments: Model objects and Dataset objects specified at object instantiation, plus and any additional object required.
- Parameters
signal – The signal object to call
model_to_split_mapping – List of tuples, indicating how each model should query the dataset. More specifically, for model #i: model_to_split_mapping[i][0] contains the index of the dataset in the list, model_to_split_mapping[i][1] contains the name of the split, model_to_split_mapping[i][2] contains the name of the input feature, model_to_split_mapping[i][3] contains the name of the output feature. This can also be provided once and for all at the instantiation of InformationSource, through the default_model_to_split_mapping argument.
extra – Dictionary containing any additional parameter that should be passed to the signal object.
- Returns
The signal value.
privacy_meter.information_source_signal module
- class privacy_meter.information_source_signal.DatasetSample[source]
Bases:
privacy_meter.information_source_signal.Signal
Inherits of the Signal class, used to represent any type of signal that can be obtained from a Model and/or a Dataset. This particular class is used to get a given point from the Dataset.
- class privacy_meter.information_source_signal.ModelGradient[source]
Bases:
privacy_meter.information_source_signal.Signal
Inherits of the Signal class, used to represent any type of signal that can be obtained from a Model and/or a Dataset. This particular class is used to get the gradient of a model.
- class privacy_meter.information_source_signal.ModelIntermediateOutput[source]
Bases:
privacy_meter.information_source_signal.Signal
Inherits of the Signal class, used to represent any type of signal that can be obtained from a Model and/or a Dataset. This particular class is used to get the value of an intermediate layer of model.
- class privacy_meter.information_source_signal.ModelLoss[source]
Bases:
privacy_meter.information_source_signal.Signal
Inherits of the Signal class, used to represent any type of signal that can be obtained from a Model and/or a Dataset. This particular class is used to get the loss of a model.
- class privacy_meter.information_source_signal.ModelOutput[source]
Bases:
privacy_meter.information_source_signal.Signal
Inherits of the Signal class, used to represent any type of signal that can be obtained from a Model and/or a Dataset. This particular class is used to get the output of a model.
privacy_meter.metric module
- class privacy_meter.metric.Metric(target_info_source: privacy_meter.information_source.InformationSource, reference_info_source: privacy_meter.information_source.InformationSource, signals: List[privacy_meter.information_source_signal.Signal], hypothesis_test_func: Optional[Callable], logs_dirname: str)[source]
Bases:
abc.ABC
Interface to construct and perform a membership inference attack on a target model and dataset using auxiliary information specified by the user. This serves as a guideline for implementing a metric to be used for measuring the privacy leakage of a target model.
- abstract prepare_metric()[source]
Function to prepare data needed for running the metric on the target model and dataset, using signals computed on the auxiliary model(s) and dataset.
- abstract run_metric(fpr_tolerance_rate_list=None) Union[privacy_meter.metric_result.MetricResult, List[privacy_meter.metric_result.MetricResult]] [source]
Function to run the metric on the target model and dataset.
- Parameters
fpr_tolerance_rate_list (optional) – List of FPR tolerance values
attack (that may be used by the threshold function to compute the) –
metric. (threshold for the) –
- Returns
Result(s) of the metric
- class privacy_meter.metric.PopulationMetric(target_info_source: privacy_meter.information_source.InformationSource, reference_info_source: privacy_meter.information_source.InformationSource, signals: List[privacy_meter.information_source_signal.Signal], hypothesis_test_func: Optional[Callable], target_model_to_train_split_mapping: Optional[List[Tuple[int, str, str, str]]] = None, target_model_to_test_split_mapping: Optional[List[Tuple[int, str, str, str]]] = None, reference_model_to_train_split_mapping: Optional[List[Tuple[int, str, str, str]]] = None, unique_dataset: bool = False, logs_dirname: Optional[str] = None)[source]
Bases:
privacy_meter.metric.Metric
Inherits the Metric class to perform the population membership inference attack which will be used as a metric for measuring privacy leakage of a target model.
- prepare_metric()[source]
Function to prepare data needed for running the metric on the target model and dataset, using signals computed on the auxiliary model(s) and dataset. For the population attack, the auxiliary model is the target model itself, and the auxiliary dataset is a random split from the target model’s training data.
- run_metric(fpr_tolerance_rate_list=None) List[privacy_meter.metric_result.MetricResult] [source]
Function to run the metric on the target model and dataset.
- Parameters
fpr_tolerance_rate_list (optional) – List of FPR tolerance values
attack (that may be used by the threshold function to compute the) –
metric. (threshold for the) –
- Returns
A list of MetricResult objects, one per fpr value.
- class privacy_meter.metric.ReferenceMetric(target_info_source: privacy_meter.information_source.InformationSource, reference_info_source: privacy_meter.information_source.InformationSource, signals: List[privacy_meter.information_source_signal.Signal], hypothesis_test_func: Optional[Callable], target_model_to_train_split_mapping: Optional[List[Tuple[int, str, str, str]]] = None, target_model_to_test_split_mapping: Optional[List[Tuple[int, str, str, str]]] = None, reference_model_to_train_split_mapping: Optional[List[Tuple[int, str, str, str]]] = None, reference_model_to_test_split_mapping: Optional[List[Tuple[int, str, str, str]]] = None, unique_dataset: bool = False, logs_dirname: Optional[str] = None)[source]
Bases:
privacy_meter.metric.Metric
Inherits the Metric class to perform the reference membership inference attack which will be used as a metric for measuring privacy leakage of a target model.
- prepare_metric()[source]
Function to prepare data needed for running the metric on the target model and dataset, using signals computed on the reference model(s) and dataset. For the reference attack, the reference models will be a list of models trained on data from the same distribution, and the reference dataset will be the target model’s train-test split.
- run_metric(fpr_tolerance_rate_list=None) List[privacy_meter.metric_result.MetricResult] [source]
Function to run the metric on the target model and dataset.
- Parameters
fpr_tolerance_rate_list (optional) – List of FPR tolerance values that may be used by the threshold function
metric. (to compute the attack threshold for the) –
- Returns
A list of MetricResult objects, one per fpr value.
- class privacy_meter.metric.ShadowMetric(target_info_source: privacy_meter.information_source.InformationSource, reference_info_source: privacy_meter.information_source.InformationSource, signals: List[privacy_meter.information_source_signal.Signal], hypothesis_test_func: Optional[Callable], target_model_to_train_split_mapping: Optional[List[Tuple[int, str, str, str]]] = None, target_model_to_test_split_mapping: Optional[List[Tuple[int, str, str, str]]] = None, reference_model_to_train_split_mapping: Optional[List[Tuple[int, str, str, str]]] = None, reference_model_to_test_split_mapping: Optional[List[Tuple[int, str, str, str]]] = None, reweight_samples: bool = True, unique_dataset: bool = False, logs_dirname: Optional[str] = None)[source]
Bases:
privacy_meter.metric.Metric
Inherits the Metric class to perform the shadow membership inference attack which will be used as a metric for measuring privacy leakage of a target model.
- prepare_metric()[source]
Function to prepare data needed for running the metric on the target model and dataset, using signals computed on the reference model(s) and dataset. For the shadow attack, the reference models will be a list of shadow models and the auxiliary dataset will contain the train-test splits of these models.
- run_metric(fpr_tolerance_rate_list=None) privacy_meter.metric_result.MetricResult [source]
Function to run the metric on the target model and dataset.
- Parameters
fpr_tolerance_rate_list (optional) – List of FPR tolerance values that may be used by the threshold function
metric. (to compute the attack threshold for the) –
- Returns
The result of the metric
privacy_meter.metric_result module
privacy_meter.model module
- class privacy_meter.model.HuggingFaceCausalLanguageModel(model_obj, loss_fn, stride=64)[source]
Bases:
privacy_meter.model.LanguageModel
Inherits from the LanguageModel class, an interface to query a language model without any assumption on how it is implemented. This particular class is to be used with HuggingFace causal language models.
- get_grad(batch_samples, batch_labels)[source]
Function to get the gradient of the model loss with respect to the model parameters, on a given input and an expected output.
- Parameters
batch_samples – Model input
batch_labels – Model expected output
- Returns
A list of gradients of the model loss (one item per layer) with respect to the model parameters.
- get_intermediate_outputs(layers, batch_samples, forward_pass=True)[source]
Function to get the intermediate output of layers (a.k.a. features), on a given input.
- Parameters
layers – List of integers and/or strings, indicating which layers values should be returned
batch_samples – Model input
forward_pass – Boolean indicating if a new forward pass should be executed. If True, then a forward pass is executed on batch_samples. Else, the result is the one of the last forward pass.
- Returns
A list of intermediate outputs of layers.
- get_loss(batch_samples, batch_labels=None, per_point=True)[source]
Function to get the model loss on a given input and an expected output.
- Parameters
batch_samples – Model input
batch_labels – Model expected output
per_point – Boolean indicating if loss should be returned per point or reduced
- Returns
The loss value, as defined by the loss_fn attribute.
- class privacy_meter.model.LanguageModel(model_obj, loss_fn)[source]
Bases:
privacy_meter.model.Model
Inherits from the Model class, an interface to query a model without any assumption on how it is implemented. This particular abstract class is to be used with language models.
- class privacy_meter.model.Model(model_obj, loss_fn)[source]
Bases:
abc.ABC
Interface to query a model without any assumption on how it is implemented.
- abstract get_grad(batch_samples, batch_labels)[source]
Function to get the gradient of the model loss with respect to the model parameters, on a given input and an expected output.
- Parameters
batch_samples – Model input
batch_labels – Model expected output
- Returns
A list of gradients of the model loss (one item per layer) with respect to the model parameters.
- abstract get_intermediate_outputs(layers, batch_samples, forward_pass=True)[source]
Function to get the intermediate output of layers (a.k.a. features), on a given input.
- Parameters
layers – List of integers and/or strings, indicating which layers values should be returned
batch_samples – Model input
forward_pass – Boolean indicating if a new forward pass should be executed. If True, then a forward pass is executed on batch_samples. Else, the result is the one of the last forward pass.
- Returns
A list of intermediate outputs of layers.
- abstract get_loss(batch_samples, batch_labels, per_point=True)[source]
Function to get the model loss on a given input and an expected output.
- Parameters
batch_samples – Model input
batch_labels – Model expected output
per_point – Boolean indicating if loss should be returned per point or reduced
- Returns
The loss value, as defined by the loss_fn attribute.
- class privacy_meter.model.PytorchModel(model_obj, loss_fn)[source]
Bases:
privacy_meter.model.Model
Inherits from the Model class, an interface to query a model without any assumption on how it is implemented. This particular class is to be used with pytorch models.
- get_grad(batch_samples, batch_labels)[source]
Function to get the gradient of the model loss with respect to the model parameters, on a given input and an expected output.
- Parameters
batch_samples – Model input
batch_labels – Model expected output
- Returns
A list of gradients of the model loss (one item per layer) with respect to the model parameters.
- get_intermediate_outputs(layers, batch_samples, forward_pass=True)[source]
Function to get the intermediate output of layers (a.k.a. features), on a given input.
- Parameters
layers – List of integers and/or strings, indicating which layers values should be returned
batch_samples – Model input
forward_pass – Boolean indicating if a new forward pass should be executed. If True, then a forward pass is executed on batch_samples. Else, the result is the one of the last forward pass.
- Returns
A list of intermediate outputs of layers.
- get_loss(batch_samples, batch_labels, per_point=True)[source]
Function to get the model loss on a given input and an expected output.
- Parameters
batch_samples – Model input
batch_labels – Model expected output
per_point – Boolean indicating if loss should be returned per point or reduced
- Returns
The loss value, as defined by the loss_fn attribute.
- class privacy_meter.model.TensorflowModel(model_obj, loss_fn)[source]
Bases:
privacy_meter.model.Model
Inherits from the Model class, an interface to query a model without any assumption on how it is implemented. This particular class is to be used with tensorflow models.
- get_grad(batch_samples, batch_labels)[source]
Function to get the gradient of the model loss with respect to the model parameters, on a given input and an expected output.
- Parameters
batch_samples – Model input
batch_labels – Model expected output
- Returns
A list of gradients of the model loss (one item per layer) with respect to the model parameters.
- get_intermediate_outputs(layers, batch_samples, forward_pass=True)[source]
Function to get the intermediate output of layers (a.k.a. features), on a given input.
- Parameters
layers – List of integers and/or strings, indicating which layers values should be returned
batch_samples – Model input
forward_pass – Boolean indicating if a new forward pass should be executed. If True, then a forward pass is
Else (executed on batch_samples.) –
pass. (the result is the one of the last forward) –
- Returns
A list of intermediate outputs of layers.
- get_loss(batch_samples, batch_labels, per_point=True)[source]
Function to get the model loss on a given input and an expected output.
- Parameters
batch_samples – Model input
batch_labels – Model expected output
per_point – Boolean indicating if loss should be returned per point or reduced
- Returns
The loss value, as defined by the loss_fn attribute.