使用差分隐私进行 NLP 混淆的PYTHON 包.zip

# pyPANTERA ## A Python **P**ackage for n**A**tural la**N**guage obfusca**T**ion **E**nforcing p**R**ivacy & **A**nonymization <p align="center"> <img src="./images/pyPANTER.webp" width="255"> </p> ## What is pyPANTERA? pyPANTERA[^1] is a Python package that provides a simple interface to obfuscate natural language text. It is designed to help developers and data scientists to implement, reproduce and test State-of-the-Art techniques for natural language obfuscation that implements $\varepsilon$ -Differential Privacy. The package is built using numpy, pandas, and scikit-learn libraries, and it is designed to be easy to use and integrate with other Python packages. The package offers a combination of natural language processing and mathematical transformations to obfuscate natural language text. It replaces the original string texts with their obfuscated versions, ensuring that the obfuscated text is not directly related to the original text. The obfuscation is performed using word embeddings and word sampling mechanisms, and it is designed to be $\varepsilon$-Differential Privacy compliant. ## Virtual Environment We provide also a virtual environment to run the package: 1. You can create the virtual environment ***virtualEnvPyPANTERA*** using the ```environment.yml``` file, and running in your terminal: ```bash conda env create -f environment.yml ``` 2. Once the environment is created, you can verify that it is installed by running: ```bash conda env list ``` 3. Finnally, you can activate the virtual environment by running: ```bash conda activate virtualEnvPyPANTERA ``` In the ```requirements.txt``` file you can find the list of the packages exported from the virtual environment. ## How to use pyPANTERA? pyPANTERA is designed to be easy to use and accessible for everyone. You can install it using pip: ```bash pip install pypantera ``` Once installed, you can use it in your Python code by importing it as follows: ```python import pypantera ``` ## What can pyPANTERA do? pyPANTERA implements current State-of-the-Art mechanisms that uses $\varepsilon$-Differential Privacy to obfuscate natural language text. The mechansims implemented in pyPANTERA are divided in two categories: - **Word Embeddings Perturbation**: This mechanism uses word embeddings to obfuscate the text. It replaces the original words ebeddings with a perturbated version of them. Such perturbation is done by adding a statistical noise depending on the mechansim design. The mechansim implemented are the following: - Calibrated Multivariate Perturbations (**CMP**): Addition of sferical noise to the word embeddings. See reference [^2] for more information. - Mahalanobis Perturbations (**Mahalanobis**): Addition of eliptical noise to the word embeddings. See reference [^3] for more information. - Vickrey family of mechanisms (**Vickrey**): Perturbation performed using a treshold value to select the nearest perturbed embedding of a term. See reference [^4] for more information. - **Word Sampling Perturbation**: This mechanism uses word sampling to obfuscate the text. The mechanism computes for each word in the text a list of neighbouring words with the respective scores, then it samples a substitution candidate from basing such sampling on the scores of the neighbouring terms and teh privacy budget $\varepsilon$. The mechansim implemented are the following: - Customized Text (**CusText**): Sampling of the substitution candidate from the neighbouring $k$ words of the original word. See reference [^5] for more information. - Sanitization Text (**SanText**): Sampling of the substitution candidate from the neighbouring words of the original word. See reference [^6] for more information. - Truncated Exponential Mechanism (**TEM**): Sampling of the substitution candidate using the exponential mechanism with the scores of the neighbouring words. See reference [^7] for more information. ## How does pyPANTERA work? We provide a simple example to show how pyPANTERA works with a concrete example. We suggest to use the prepared virtual environment to run the example and the base script `test.py` to run the obfuscation pipeline. ```bash python test.py --embPath /absolute/path/to/embeddings --inputPath /absolute/path/to/input/data --outputPath /absolute/path/to/output/data --mechanism MECHANISM --epsilon EPSILON --task TASK --numberOfObfuscations N --PARAMETERS ``` The script will run the obfuscation pipeline using the embeddings in the path provided in the `--embPath | -eP` argument, the input data in the path provided in the `--inputPath | -i` argument, and `--outputPath | -o` is used as output path for storing the results. If `--outputPath` is not provided, it creates a folder `./results/task/mechanism/` to save the obfuscated data frames. pyPANTERA requires that the input data is a CSV file with a column named `text` that contains the text to obfuscate and an `id` to keep trace of the correspondance between original and obfuscated versions. The `--task | -tk` argument is used to specify the future task that you want to perform using the new obfuscated texts. The `--epsilon | -e` argument is used to specify the epsilon value for the differential privacy mechanism. The `--mechanism | -m` argument is used to specify the mechanism to use for the obfuscation. The `--numberOfObfuscations | -n` argument is used to specify the number of obfuscations to perform for the same text. Finally, the `--PARAMETERS` are the parameters for the mechanism that you want to use. We provide a specific list of parameters for each mechanism in the following section. ## UML of pyPANTERA The UML diagram of the pyPANTERA source code is displayied below: <center>  </center> ## Prameters The script `test.py` has the following parameters, based on the mechanism parameters that you want to use: - **General Parameters**: - `--embPath | -eP`: The path to the word embeddings file (default str: None, **required**) - `--inputPath | -i`: The path to the input data file (default str: None, **required**) - `--outputPath | -o`: The path to the output data file (default str: None) - `--task | -tk`: The future task that you want to perform using the new obfuscated texts (default str: 'retrieval') - `--epsilon | -e`: The epsilon value for the differential privacy mechanism (default List[float]: [1.0, 5.0, 10.0, 12.5, 15.0, 17.5, 20.0, 50.0]) - `--mechanism | -m`: The mechanism to use for the obfuscation (default str: 'CMP', choices: ['CMP', 'Mahalanobis', 'VickreyCMP', 'VickreyMhl', 'CusText', 'SanText', 'TEM']) - `--numberOfObfuscations | -n`: The number of obfuscations to perform for the same text (default int: 1) - **CMP**: The parameters for the CMP mechanism are only the general ones. - **Mahalanobis**: The parameters for the Mahalanobis mechanism are the following: - `--lam`: The lambda value for the Mahalanobis norm (default float: 1) - **VickreyCMP/VickreyMhl**: The parameters for the Vickrey mechanism are the following: - `--t`: The treshold value for the Vickrey mechanism (default float: 0.75). Eventually, if you use the `VickreyMhl` mechanism, you can also use the `--lam` parameter to set the lambda value for the Mahalanobis norm (default float: 1) - **CusText**: The parameters for the CusText mechanism are the following: - `--k`: The number of neighbouring words to consider for the sampling (default int: 10) - `--distance | -d`: The distance metric to use for the sampling (default str: 'euclidean') - **SanText**: The parameters for the SanText mechanism are only the general ones. - **TEM**: The parameters for the TEM mechanism are the following: - `--beta`: The beta value for the exponential mechanism (default float: 0.001) ## Example Suppose you want to run the obfuscation pipeline using the `CMP` mechanism with the embeddings in the path `./embeddings/glove.6B.50d.txt