diff --git a/CITATION.cff b/CITATION.cff new file mode 100644 index 00000000..2ef119a7 --- /dev/null +++ b/CITATION.cff @@ -0,0 +1,25 @@ +cff-version: 1.2.0 +message: "If you use this software, please cite it as below." +authors: +- family-names: "Dumitrescu" + given-names: "Delia" + orcid: "https://orcid.org/0000-0002-0065-3875" +- family-names: "Ulusoy" + given-names: "Inga" + orcid: "https://orcid.org/0000-0001-7294-4148" +- family-names: "Andriushchenko" + given-names: "Petr" + orcid: "https://orcid.org/0000-0002-4518-6588" +- family-names: "Daskalakis" + given-names: "Gwydion" + orcid: "https://orcid.org/0000-0002-7557-1364" +- family-names: "Kempf" + given-names: "Dominic" + orcid: "https://orcid.org/0000-0002-6140-2332" +- family-names: "Ma" + given-names: "Xianghe" +title: "AMMICO, an AI Media and Misinformation Content Analysis Tool" +version: 0.2.0 +doi: 10.31235/osf.io/v8txj +date-released: 2023-9-4 +url: "https://github.com/ssciwr/AMMICO" diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..11701949 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,36 @@ +# Contributing to ammico + +Welcome to `ammico`! Contributions to the package are welcome. Please adhere to the following conventions: + +- fork the repository, make your changes, and make sure your changes pass all the tests (Sonarcloud, unit and integration tests, codecoverage limits); then open a Pull Request for your changes. Tag one of `ammico`'s developers for review. +- install and use the pre-commit hooks by running `pre-commit install` in the repository directory so that all your changes adhere to the PEP8 style guide and black code formatting +- make sure to update the documentation if applicable + +The tests are located in `ammico/tests`. Unit tests are named `test` following an underscore and the name of the module; inside the unit test modules, each test function is named `test` followed by an underscore and the name of the function/method that is being tested. + +To report bugs and issues, please [open an issue](https://github.com/ssciwr/ammico/issues) describing what you did, what you expected to happen, and what actually happened. Please provide information about the environment as well as OS. + +For any questions and comments, feel free to post to our [Discussions forum]((https://github.com/ssciwr/AMMICO/discussions/151)). + +**Thank you for contributing to `ammico`!** + +## Templates +### Template for pull requests + +- issues that are addressed by this PR: [*For example, this closes #33 or this addresses #29*] + +- changes that were made: [*For example, updated version of dependencies or added a file type for input reading*] + +- if applicable: Follow-up work that is required + +### Template for bug report + +- what I did: + +- what I expected: + +- what actually happened: + +- Python version and environment: + +- Operating system: diff --git a/README.md b/README.md index e61f1a01..988f0b80 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ ![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=ssciwr_ammico&metric=alert_status) ![Language](https://img.shields.io/github/languages/top/ssciwr/AMMICO) -This package extracts data from images such as social media posts that contain an image part and a text part. The analysis can generate a very large number of features, depending on the user input. +This package extracts data from images such as social media posts that contain an image part and a text part. The analysis can generate a very large number of features, depending on the user input. See [our paper](https://dx.doi.org/10.31235/osf.io/v8txj) for a more in-depth description. **_This project is currently under development!_** @@ -16,7 +16,6 @@ Use pre-processed image files such as social media posts with comments and proce 1. Translation into English or other languages 1. Cleaning of the text, spell-check 1. Sentiment analysis - 1. Subjectivity analysis 1. Named entity recognition 1. Topic analysis 1. Content extraction from the images @@ -27,11 +26,12 @@ Use pre-processed image files such as social media posts with comments and proce 1. Face mask detection 1. Age, gender and race detection 1. Emotion recognition -1. Object detection in images - 1. Detection of position and number of objects in the image; currently person, bicycle, car, motorcycle, airplane, bus, train, truck, boat, traffic light, cell phone +1. Color analysis + 1. Analyse hue and percentage of color on image +1. Multimodal analysis + 1. Find best matches for image content or image similarity 1. Cropping images to remove comments from posts - ## Installation The `AMMICO` package can be installed using pip: @@ -40,7 +40,7 @@ pip install ammico ``` This will install the package and its dependencies locally. -Some ammico components require tensorflow (e.g. Emotional detector), some pytorch (e.g. Summary detector). Sometimes there are compatibility problems between these two frameworks. To avoid compatibility problems on your machines, we suggest you to follow these steps before installing the package (you need conda on your machine): +Some ammico components require tensorflow (e.g. Emotion detector), some pytorch (e.g. Summary detector). Sometimes there are compatibility problems between these two frameworks. To avoid compatibility problems on your machines, we suggest you to follow these steps before installing the package (you need conda on your machine): ### 1. First, install tensorflow (https://www.tensorflow.org/install/pip) - create a new environment with python and activate it @@ -78,14 +78,12 @@ Some ammico components require tensorflow (e.g. Emotional detector), some pytorc ```python -m pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118``` -### 3. After we prepared right environment we can install ```AMMICO``` package +### 3. After we prepared right environment we can install the ```ammico``` package - ```python -m pip install ammico``` It is done. - - ### Micromamba If you have micromamba on your machine you can prepare environment with just one command: @@ -140,14 +138,10 @@ The image content ("caption") is extracted using the [LAVIS](https://github.com/ Emotion recognition is carried out using the [deepface](https://github.com/serengil/deepface) and [retinaface](https://github.com/serengil/retinaface) libraries. These libraries detect the presence of faces, and their age, gender, emotion and race based on several state-of-the-art models. It is also detected if the person is wearing a face mask - if they are, then no further detection is carried out as the mask prevents an accurate prediction. -### Object detection - -Object detection is carried out using [cvlib](https://github.com/arunponnusamy/cvlib) and the [YOLOv4](https://github.com/AlexeyAB/darknet) model. This library detects faces, people, and several inanimate objects; we currently have restricted the output to person, bicycle, car, motorcycle, airplane, bus, train, truck, boat, traffic light, cell phone. - ### Color/hue detection Color detection is carried out using [colorgram.py](https://github.com/obskyr/colorgram.py) and [colour](https://github.com/vaab/colour) for the distance metric. The colors can be classified into the main named colors/hues in the English language, that are red, green, blue, yellow, cyan, orange, purple, pink, brown, grey, white, black. ### Cropping of posts -Social media posts can automatically be cropped to remove further comments on the page and restrict the textual content to the first comment only. \ No newline at end of file +Social media posts can automatically be cropped to remove further comments on the page and restrict the textual content to the first comment only.