# peace-augmentation

PEACE stands for Providing Explanation and Analysis for Combating Hate Expressions. This framework is engineered to effectively identify, visualize, and elucidate implicit and subtle forms of hate speech. It aims to address the complex nature of modern hate speech by integrating three pivotal components:

- Data Analysis: In-depth examination of cutting-edge data on Implicit and Subtle Hate Speech to understand its nuances and variations. 
- Machine Learning Identification: Employment of sophisticated machine learning classifiers to accurately detect instances of hate speech.
- Explanation Generation: Articulation of clear, understandable explanations concerning why particular messages are classified as hateful.

This repository is only including the **augmentation** extension. The code of the [PEACE augmentation web app](https://3ia-demos.inria.fr/peace/) can be found [here](https://gitlab.inria.fr/nocampo/peace/)

## Installation Instructions

To set up the peace-augmentation app on your local system, you can install it using `pip`:
```
pip install peace-augmentation
```

## Usage

To use it in one of your project, you have to use the `Augmentation` class:
```
from peace_augmentation import Augmentation

my_str = "This string contains hate speech that I want to augment usong PEACE"
augmentation_args = ...
augmentation_method = ...

aug = Augmentation(my_str, *augmentation_args)
result = aug.apply(augmentation_method)

print(result)
```

The detailed docs are available [here](https://peace-augmentation.readthedocs.io/en/latest/) (WIP)

### Args reference
Depending on the method, you can specify a few arguments listed below:

*TO DO*

### Method reference

Here is a list of the different augmentation methods available with their description:

| Identifier | Name | Description |
| ---- | ---------- | ------- |
| `easy_data_augmentation` | Easy Data Augmentation | Given an input sentence: - it randomly replaces a non-stopword expression with a synonym using Word-net; it inserts a synonym of a non-stopword word in a random position; it chooses two words of the sentence and swap their positions; it removes each word in the sentence with a certain probability. Only one of the four operations at a time is applied to a sentence. |
| `replace_adjectives` | Replace Adjectives | It takes all the adjectives or nouns in a sentence and replaces each of them `nof_repl_p_cand` times for a synonym. In particular, if an adjective/noun is selected, then the synonym/hyponym will be an adjective/noun. |
| `replace_in_domain_expressions` | Replace In-domain Expressions | It replaces a list of manually-crafted expressions often used in HS messages with other semantically similar expressions. That is, it checks all the ocurrences of in-domain expressions in sentence, and generates `nof_repl_p_cand` sentences per each candidate by changing it for another manually-collected expression. |
| `replace_scalar_adverbs` | Replace Scalar Adverbs | It selects all the adverbs of pos type 'RB' in the sentence. For each candidate, it generates `nof_repl_p_cand` by replacing the candidate with an scalar adverb. |
| `add_adverbs_to_verbs` | Add adverbs to verbs | It selects all the words in a sentence that are POS labeled with `cand_pos_name`. We called these words as candidates. Each candidate is selected and new sentences are generated by adding an adverb before the candidate. In this case, speculative adverbs are used like certainly, likely, and clearly from a previously collected list. `cand_pos_name` can indicate verbs or adjectives. That is, the following values: - VB Verb, base form. - VBD Verb, past tense. - VBG Verb, gerund or present participle. - VBN Verb, past participle. - VBP Verb, non-3rd person singular present. - VBZ Verb, 3rd person singular present. - JJ, Adjective. |
| `replace_named_entities` | Replace Named Entities | It replaces a named entity (PER, LOC, ORG, and MISC) in the input sentence. A candidate NE in a sentence is replaced by another one according to a previously collected list of NEs. Then, the most similar NE is selected by using pre-trained FastText embeddings. Per each candidate it creates `nof_repl_p_cand` sentences. For example, if `ner_name = 'PER'`, `nof_repl_p_cand = 5` and input sentence has 2 named entities PER, thid method generates 2 * 5 sentences. |
| `back-translation` | Back Translation | *TO DO* |

## Contact Information

For inquiries or additional details, please feel free to reach out to any of the following individuals:

- [Greta Damo](https://grexit-d.github.io/damo.greta.github.io/)
- [Nicolás Benjamín Ocampo](https://www.nicolasbenjaminocampo.com/)
- [Elena Cabrio](https://www-sop.inria.fr/members/Elena.Cabrio/)
- [Serena Villata](https://webusers.i3s.unice.fr/~villata/Home.html)
- [Stéphane Petiot](https://stephanepetiot.github.io/)

Please consider reaching out with respect to the specific areas of the project you are interested in, as this will help direct your queries more effectively.

## Contributing

Your contributions are welcome! If you have suggestions or want to contribute to the PEACE framework, please feel free to open an issue or create a pull request on our repository.

## License

This project is licensed under the Boost Software License 1.0 (BSL-1.0) - see the LICENSE file in the project repository for detailed information and terms.
