update introduction, small fixes, typos, bias discussion

introduction.md

@@ -1,9 +1,9 @@
 # Italian CLIP
 
-CLIP ([Radford et al., 2021](https://arxiv.org/abs/2103.00020)) is an amazing model that can learn to represent images and text jointly in the samp space.
+CLIP ([Radford et al., 2021](https://arxiv.org/abs/2103.00020)) is an amazing model that can learn to represent images and text jointly in the same space.
 
 In this project, we aim to propose the first CLIP model trained on Italian data, that in this context can be considered a
-low resource language. Using a few smart techniques, we have been able to fine-tune a SOTA Italian CLIP model with **only 1.4 million** training samples. Our Italian CLIP model
+low resource language. Using a few techniques, we have been able to fine-tune a SOTA Italian CLIP model with **only 1.4 million** training samples. Our Italian CLIP model
 is built upon the pre-trained [Italian BERT](https://huggingface.co/dbmdz/bert-base-italian-xxl-cased) model provided by [dbmdz](https://huggingface.co/dbmdz) and the OpenAI
 [vision transformer](https://huggingface.co/openai/clip-vit-base-patch32).
 
@@ -14,8 +14,8 @@ In building this project we kept in mind the following principles:
 + **Broader Outlook**: We always kept in mind which are the possible usages and limitations of this model.
 
 We put our **hearts** and **souls** into the project during this week! Not only did we work on a cool project, but we were
-able to make new friends and and learn a lot from each other to work towards a common goal! 
-Thank you for this amazing opportunity, we hope you will like the results. :heart:
+able to make new friends and learn a lot from each other to work towards a common goal! 
+Thank you for this amazing opportunity, we hope you will like the results! :heart:
 
 # Demo
 
@@ -33,15 +33,15 @@ different applications that can start from here.
 
 # Novel Contributions
 
-The original CLIP model was trained on 400 million image-text pairs; this amount of data is not available for Italian. 
+The original CLIP model was trained on 400 million image-text pairs; this amount of data is currently not available for Italian. 
 We indeed worked in a **low-resource setting**. The only datasets for Italian captioning in the literature are MSCOCO-IT (a translated version of MSCOCO) and WIT. 
 To get competitive results we followed three strategies:
   1. more and better data;
   2. better augmentations;
-  3. better training.
+  3. better training strategies.
 
 For those interested, we have a :comet: [Comet](https://www.comet.ml/g8a9/clip-italian/reports/clip-italian-training-metrics) report 
-that shows a **subset** of the experiments we run. Different hyper-parameters played a role in reducing the validation 
+that shows a **subset** of the experiments we ran. Different hyper-parameters played a role in reducing the validation 
 loss. The optimizer we used gave us great performance and huge conversion speed, more data and augmentations helped a lot in generalizing,
 working on the training and on the loss gave us the final increase that you can see in the results.
 
@@ -73,7 +73,9 @@ this dataset and these have been collected from the web. We downloaded the image
 could not retrieve them all. Eventually, we had to translate the captions to Italian. We have been able to collect
 a dataset with 700K translated captions.
 
-+ [La Foto del Giorno](https://www.ilpost.it/foto-del-giorno/). This image-caption dataset is collected from [Il Post](https://www.ilpost.it/), a prominent Italian online newspaper. The collection contains almost 30K pairs: starting from early 2011, for each day, editors at Il Post pick several images picturing the most salient events in the world. Each photo comes along with an Italian caption.
++ [La Foto del Giorno](https://www.ilpost.it/foto-del-giorno/). This image-caption dataset is collected from [Il Post](https://www.ilpost.it/), a prominent Italian online newspaper. 
+The collection contains almost 30K pairs: starting from early 2011, for each day, editors at Il Post pick several images picturing the most salient events in the world. 
+Each photo comes along with an Italian caption.
 
 
 ### A Note on Translations
@@ -101,7 +103,8 @@ that those interested can check the quality. The Google Sheet is [here](https://
 
 ## Better Augmentations
 
-We knew that without a good augmentation strategy we could never get competitive results to a model trained on 400 million images. Therefor we implemented heavy augmentations to make the training more data efficient. They include random affine transformations and perspective changes, as well as occasional equalization and random changes to brightness, contrast, saturation and hue. We made sure to keep hue augmentations limited however to still give the model the ability to learn color definitions.  
+We knew that without a good augmentation strategy we could never get competitive results to a model trained on 400 million images. Therefore we implemented heavy augmentations to make the training more data efficient.
+They include random affine transformations and perspective changes, as well as occasional equalization and random changes to brightness, contrast, saturation and hue. We made sure to keep hue augmentations limited however, to still give the model the ability to learn color definitions.  
 While we would have liked to have augmentations for the captions as well after some experimentation we settled with random sampling from the five captions available in MSCOCO and leaving the rest of the captions unmodified. 
 
 ## Better Training
@@ -112,20 +115,23 @@ training pipeline: the optimizer, the training with frozen components and the lo
 
 ### Optimizer
 
-While the initial code used AdamW as an optimizer we soon noticed that it introduced some bad properties into the training. The model strated to overfit relatively quickly and the weight decay made this effect worse. We eventually decided to an optimization strategy that had worked well for us in similar cases and used AdaBelief with Adaptive Gradient Clipping (AGC) and a Cosine Annealing Schedule. Together with slightly tuning the learning rate this helped us to reduce the validation loss by 25%.
+While the initial code used AdamW as an optimizer, we soon noticed that it introduced some bad properties into the training. The model strated to overfit relatively quickly and the weight decay made this effect worse. 
+We eventually decided to use an optimization strategy that had worked well for us in similar cases and used AdaBelief with Adaptive Gradient Clipping (AGC) and a Cosine Annealing Schedule.
+Together with slightly tuning the learning rate this helped us to reduce the validation loss by more than 25%.
 Our implementation is available online [here](https://github.com/clip-italian/clip-italian/blob/master/hybrid_clip/run_hybrid_clip.py#L667).
 
 ### Backbone Freezing
 
-The ViT used by OpenAI was already trained on 400 million images and it is the element in our architecture that probably required less training.
-The same is true for the BERT model we use. To allow the randomly initialized Re-projection Layers to warm up without messing with the tuned weights of the backbones we decided to do a first training with the backbones of our architecture completely frozen. Only after these layers converged we unfreezed the rest of the model to fine-tune all the components. This technique allowed us to reach a much better validation loss.
+The ViT used by OpenAI was already trained on 400 million images and it is the element in our architecture that probably required the least training.
+The same is true for the BERT model we use. To allow the randomly initialized re-projection layers to warm up without messing with the tuned weights of the backbones we decided to do a first training with the backbones of our architecture completely frozen. 
+Only after these layers converged we unfreezed the rest of the model to fine-tune all the components. This technique allowed us to reach a much better validation loss.
 
 <img src="https://huggingface.co/spaces/clip-italian/clip-italian-demo/raw/main/static/img/clip-italian.png" alt="drawing" width="95%"/>
 
 ### Logit Scale
 
 We tried to improve the loss function in different ways: for example, we tried something similar to a margin based loss but that experiments
-didn't go well. Eventually, the thing that worked out the best was fixing the logit_scale value to 20. This value
+did not yield the results we hoped for. Eventually, the thing that worked out the best was fixing the logit_scale value to 20. This value
 is used after the computation of the similarity between the images and the texts in CLIP (see the code [here](https://github.com/clip-italian/clip-italian/blob/master/hybrid_clip/modeling_hybrid_clip.py#L64)).
 We got this idea from Nils' [video](https://youtu.be/RHXZKUr8qOY) on sentence embeddings.
 
@@ -135,23 +141,23 @@ The following picture showcase the effect that these edits have had on our evalu
 
 <img src="https://huggingface.co/spaces/clip-italian/clip-italian-demo/raw/main/static/img/improvements.png" alt="drawing" width="95%"/>
 
-The purple line is the original training without any of our improvements, you can see how many steps we needed to get the loss down. 
+The purple line is the original training without any of our improvements, you can see that we needed a lot of training steps to get the loss down. 
 Yellow line is the loss with the new optimizer, it is **striking** to see the time we save from this addition! Not only the loss improves, it 
-also converges much faster! Blue line shows the results when
-fixed scaling is added with the new optimization. Finally, we added the backbone freezing part and you can see the
+also converges significantly faster! The blue line shows the results when
+fixed scaling is used in addition to the new optimizer. Finally, we added the backbone freezing strategy and you can see the
 results in the light blue loss. Nonetheless, as common in deep learning, having more data played a big role and was another key element
 to reduce the loss.
 
 
 # Scientific Validity
 
-We split this section in two: we first provide a quantitative evaluation to ensure that what we are learning is good and we then
-show some qualitative examples of images found by the model. **All the code we have written** to run our experiments (in combination with
+We split this section in two: we first provide a quantitative evaluation to ensure that what we are learning is really good.
+We then show some qualitative examples of images found by the model. **All the code we have written** to run our validation experiments (in combination with
 code made available by Nils Reimers and by the authors of the original CLIP) is available.
 
 ## Quantitative Evaluation
-Those images are definitely cool and interesting, but a model is nothing without validation.
- Since this is the first clip-based model in Italian, we decided to use the multilingual CLIP model as a comparison baseline. 
+Showing great images is definitely cool and interesting, but a model is nothing without validation.
+Since this is the first clip-based model in Italian, we decided to use the multilingual CLIP model as a comparison baseline. 
 
 ### mCLIP
 
@@ -163,13 +169,13 @@ great capabilities in representing multilingual text in the same space of the im
 ### Tasks
 
 We selected two different tasks: 
-+ image-retrieval, in which given a caption the model finds the most similar image
++ image-retrieval, in which given a caption the model finds the most semantically similar image
 + zero-shot classification, in which given an image and a set of captions (or labels), the model finds 
 the best matching caption for the image 
 
 ### Reproducibiliy
 
-Both experiments should be very easy to replicate, we share the two colab notebook we used to compute the two results
+In order to make both experiments very easy to replicate, we share the colab notebooks we used to compute the results.
 
 + [Image Retrieval](https://colab.research.google.com/drive/1bLVwVKpAndpEDHqjzxVPr_9nGrSbuOQd?usp=sharing)
 + [ImageNet Zero Shot Classification](https://colab.research.google.com/drive/1zfWeVWY79XXH63Ci-pk8xxx3Vu_RRgW-?usp=sharing)
@@ -177,8 +183,8 @@ Both experiments should be very easy to replicate, we share the two colab notebo
 
 ### Image Retrieval
 
-This experiment is run against the MSCOCO-IT validation set (that we haven't used in training). Given in input
-a caption from the dataset, we search for the most similar image in the MSCOCO-IT validation set and check if this is the one that was
+This experiment is run against the MSCOCO-IT validation set (that we haven't used during training). Given an input caption from the dataset, 
+we search for the most similar image in the MSCOCO-IT validation set and check if this is the one that was
 described by the original caption. As evaluation metrics we use the MRR@K.
 
 | MRR             | CLIP-Italian | mCLIP |
@@ -187,13 +193,14 @@ described by the original caption. As evaluation metrics we use the MRR@K.
 | MRR@5           | **0.5039**   | 0.3957|
 | MRR@10          | **0.5204**   | 0.4129|
 
-It is true that we used MSCOCO-IT in training, and this might give us an advantage. However, the original CLIP model was trained
-on 400million images (and some of them probably were from MSCOCO).
+It is true that we used the training set of MSCOCO-IT in training, and this might give us an advantage. However, the original CLIP model was trained
+on 400million images (and some of them might have been from MSCOCO).
 
 ### Zero-shot image classification
 
 This experiment replicates the original one run by OpenAI on zero-shot image classification on ImageNet. 
-To do this, we used DeepL to translate the image labels in ImageNet. We evaluate the models computing the accuracy at different levels. 
+To do this, we used DeepL to automatically translate the image labels in ImageNet. No manual engineering of the labels or prompts was done. 
+We evaluate the models computing the accuracy at different levels. 
 
 | Accuracy        | CLIP-Italian | mCLIP |
 | --------------- | ------------ |-------|
@@ -206,26 +213,26 @@ To do this, we used DeepL to translate the image labels in ImageNet. We evaluate
 
 Our results confirm that CLIP-Italian is very competitive and beats mCLIP on the two different task
 we have been testing. Note, however, that our results are lower than those shown in the original OpenAI
-paper (see, [Radford et al., 2021](https://arxiv.org/abs/2103.00020)) that was evaluated on English data. 
+paper (see, [Radford et al., 2021](https://arxiv.org/abs/2103.00020)) that was trained and evaluated on English data. 
 However, considering that our results are in line with those obtained by mCLIP we think that the translated image 
-labels might have had an impact on the final scores.
+labels most probably had an impact on the final scores.
 
 ## Qualitative Evaluation
 
-We hereby show some very interesting properties of the model. One is its ability to detect colors, 
+We hereby show some interesting properties of the model. One is its ability to detect colors, 
 then there is its (partial) counting ability and finally the ability of understanding more complex queries. You can find
 more examples in the "*Examples & Applications*" section of this demo.
 
 To our own surprise, many of the answers the model gives make a lot of sense! Note that the model, in this case,
 is searching the right image from a set of 25K images from an Unsplash dataset.
 
-Look at the following - slightly cherry picked (but not even that much) - examples:
+Look at the following - slightly cherry picked - examples:
 
 ### Colors
-Here's a yellow flower
+Here's "a yellow flower"
 <img src="https://huggingface.co/spaces/clip-italian/clip-italian-demo/raw/main/static/img/fiore_giallo.png" alt="drawing" width="600"/>
 
-And here's a blu flower
+And here's "a blu flower"
 <img src="https://huggingface.co/spaces/clip-italian/clip-italian-demo/raw/main/static/img/fiore_blu.png" alt="drawing" width="600"/>
 
 ### Counting
@@ -246,24 +253,26 @@ And finally, here's a very nice "cat on a chair"
 # Broader Outlook
 
 We believe that this model can be useful for many different applications. From image classification 
-to clustering, a model like CLIP Italian can be used to support researchers and practitioners in many different tasks.
-Indeed, not only it can be useful in research, but also in industry. A very interesting use-case is given by ecommerce platforms:
+to clustering, a model like our Italian CLIP can be used to support researchers and practitioners in many different tasks.
+Indeed, not only can it be useful in research, but also in industry. A very interesting use-case is given by ecommerce platforms:
 these website often deal with a main source of text that is the query engine and with lots of images of the products. CLIP Italian
 can be a killer app in this context, providing a way to search for images and text. Nonetheless, Italy has many different collections
-of photos in digital format. For example, the [Istituto Luce Cinecittà](https://it.wikipedia.org/wiki/Istituto_Luce_Cinecitt%C3%A0) is an Italian governative entity that collects photos of Italy since the
-early 1900 and it is part of the largest movie studios in Europe (Cinecittà). 
+of photos in digital format that are difficult to categorize efficiently. 
+For example, the [Istituto Luce Cinecittà](https://it.wikipedia.org/wiki/Istituto_Luce_Cinecitt%C3%A0) is an Italian governative entity that collects photos of Italy since the
+early 1900 and is part of the largest movie studios in Europe (Cinecittà). A semantic way of finding images in their catalog could be an amazing use case.
 
 # Limitations and Bias
 
 Currently, the model is not without limits. To mention one, its counting capabilities seem very cool, but from our experiments the model 
-finds difficult to count after three; this is a general limitation that is common to many model like this.  
+finds difficult to count after three; this is a general limitation that is common to many models of this type.  
 
-There are even more evident issues: we found some emergence of biases and stereotypes that got in our model from different factors:
- searching for "una troia" ("a bitch") on the CC dataset shows the picture of a woman. The model's capability even increase this issue, as searching for "due troie" ("two bitches") 
-gives again, as a results, the picture of two women. BERT models are not free from bias.  Indeed, different BERT models - Italians included - are prone to create stereotyped sentences that are hurtful ([Nozza et al., 2021](https://www.aclweb.org/anthology/2021.naacl-main.191.pdf))
+There are even more evident issues that we found in our model. Due to the unfiltered nature of our training data the model is exposed to many biases such as sexism, racism, stereotypes, 
+slurs and gore that it might replicate without the awareness of their hurtful and harmful nature. Indeed, different BERT models - Italian ones included - are prone to create stereotyped 
+sentences that are hurtful ([Nozza et al., 2021](https://www.aclweb.org/anthology/2021.naacl-main.191.pdf)).  
+While this is not something we intended, it certainly is something that we share the blame for since we were not able to avoid it.
   
-Unfortunately, this kind of issues is common to many machine learning algorithms (check [Abit et al., 2021](https://arxiv.org/abs/2101.05783) for bias in GPT-3 as an example) and
-suggest we need to work even harder on this problem that affects our **society**. 
+Unfortunately, these kinds of issues are common to many machine learning algorithms (check [Abit et al., 2021](https://arxiv.org/abs/2101.05783) for bias in GPT-3 as an example).
+This suggests we need to find better approaches to counteract this problem that affects **our society**. 
 
 # Useful Links