Self-Supervised Learning

README.md

@@ -1,29 +1,34 @@
 # TensorFlow Similarity: Metric Learning for Humans
 
-TensorFlow Similarity is a [TensorFlow](https://tensorflow.org) library for [similarity learning](https://en.wikipedia.org/wiki/Similarity_learning) also known as metric learning and contrastive learning.
-
-TensorFlow Similarity is still in beta.
+TensorFlow Similarity is a [TensorFlow](https://tensorflow.org) library for [similarity learning](https://en.wikipedia.org/wiki/Similarity_learning) which includes techniques such as self-supervised learning, metric learning, similarity learning, and contrastive learning. TensorFlow Similarity is still in beta and we may push breaking changes.
 
 ## Introduction
 
-Tensorflow Similarity offers state-of-the-art algorithms for metric learning and all the necessary components to research, train, evaluate, and serve similarity-based models.
+Tensorflow Similarity offers state-of-the-art algorithms for metric learning along with all the necessary components to research, train, evaluate, and serve similarity and contrastive based models. These components include models, losses, metrics, samplers, visualizers, and indexing subsystems to make this quick and easy.
 
 ![Example of nearest neighbors search performed on the embedding generated by a similarity model trained on the Oxford IIIT Pet Dataset.](https://raw.githubusercontent.com/tensorflow/similarity/master/assets/images/similar-cats-and-dogs.jpg)
 
-With TensorFlow Similarity you can train and serve models that find similar items (such as images) in a large corpus of examples. For example, as visible above, you can train a similarity model to find and cluster similar looking images of cats and dogs from the [Oxford IIIT Pet Dataset](https://www.tensorflow.org/datasets/catalog/oxford_iiit_pet) by only training on a few classes. To train your own similarity model see this [notebook](examples/supervised_visualization.ipynb).
-
-Metric learning is different from traditional classification as it's objective is different. The model learns to minimize the distance between similar examples and maximize the distance between dissimilar examples, in a supervised or self-supervised fashion. Either way, TensorFlow Similarity provides the necessary losses, metrics, samplers, visualizers, and indexing sub-system to make this quick and easy.
+With Tensorflow Similarity you can train two main types of models:
 
-**Currently, TensorFlow Similarity supports supervised training.** In future releases, it will support semi-supervised and self-supervised training.
+1. **Self-supervised models**: Used to learn general data representations on unlabeled data to boost the accuracy of downstream tasks where you have few labels. For example, you can pre-train a model on a large number of unlabled images using one of the supported contrastive methods supported by TensorFlow Similarity, and then fine-tune it on a small labeled dataset to achieve higher accuracy. To get started training your own self-supervised model see this [notebook](examples/unsupervised_hello_world.ipynb).
 
-To learn more about the benefits of using similarity training, you can check out the blog post.
+2. **Similarity models**: Output embeddings that allow you to find and cluster similar examples such as images representing the same object within a large corpus of examples. For instance, as visible above, you can train a similarity model to find and cluster similar looking, unseen cat and dog images from the [Oxford IIIT Pet Dataset](https://www.tensorflow.org/datasets/catalog/oxford_iiit_pet) while only training on a few of the dataset classes. To get started training your own similarity model see this [notebook](examples/supervised_visualization.ipynb).
 
 ## What's new
 
-- [Oct 8]: Added `Samplers.*` IO [notebook](examples/sampler_io_cookbook.ipynb) detailing how to efficently sample your data for succesful training.
-- [Oct 8]: 0.14 is out which includes various speed improvements and post initial release bug fixes.
+- [Jan 2022]: 0.15 self-supervised release
+    * Added support for self-supervised contrastive learning. Including SimCLR, SimSiam, and Barlow Twins. Checkout the in-depth [hello world notebook](examples/unsupervised_hello_world.ipynb) to get started.
+    * Soft Nearest Neighbor Loss added thanks to [Abhishar Sinha](https://github.com/abhisharsinha)
+    * Added GenerlizedMeanPooling2D support that improves similarity matching accuracy over GlobalMeanPooling2D.
+    * Numerous speed optimizations and general bug fixes.
+- [Dec 2021]: 
+    * Sampler speed optimizations and general bug fixes.
+- [Oct 2021]: 0.14 similarity release
+    * 0.14 is out which includes various speed improvements and post initial release bug fixes.
+    * Added `Samplers.*` IO [notebook](examples/sampler_io_cookbook.ipynb) detailing how to efficiently sample your data for successful training.
+
 
-For previous changes - see [the release changelog](./releases.md)
+For previous changes and more details - see [the changelog](./releases.md)
 
 ## Getting Started
 
@@ -46,13 +51,15 @@ For more information about specific functions, you can [check the API documentat
 For contributing to the project please check out the [contribution guidelines](CONTRIBUTING.md)
 
 ### Minimal Example: MNIST similarity
+<details>
+   <summary> Click to expand and see how to train a supervised similarity model on mnist using TF.Similarity</summary>
 
 Here is a bare bones example demonstrating how to train a TensorFlow Similarity model on the MNIST data. This example illustrates some of the main components provided by TensorFlow Similarity and how they fit together. Please refer to the [hello_world notebook](examples/supervised_hello_world.ipynb) for a more detailed introduction.
 
 ### Preparing data
 
 TensorFlow Similarity provides [data samplers](api/TFSimilarity/samplers/), for various dataset types, that balance the batches to ensure smoother training.
-In this example, we are using the multi-shot sampler that integrate directly from the TensorFlow dataset catalog.
+In this example, we are using the multi-shot sampler that integrates directly from the TensorFlow dataset catalog.
 
 ```python
 from tensorflow_similarity.samplers import TFDatasetMultiShotMemorySampler
@@ -96,7 +103,7 @@ model.fit(sampler, epochs=5)
 
 ### Building images index and querying it
 
-Once the model is trained, reference examples must indexed via the model index API to be searchable. After indexing, you can use the model lookup API to search the index for the K most similar items.
+Once the model is trained, reference examples must be indexed via the model index API to be searchable. After indexing, you can use the model lookup API to search the index for the K most similar items.
 
 ```python
 from tensorflow_similarity.visualization import viz_neigbors_imgs
@@ -112,15 +119,23 @@ nns = model.single_lookup(qx[0])
 # Visualize the query example and its top 5 neighbors
 viz_neigbors_imgs(qx[0], qy[0], nns)
 ```
+</details>
 
 ## Supported Algorithms
 
+### Self-Supervised Models
+
+- SimCLR 
+- SimSiam
+- Barlow Twins
+
 ### Supervised Losses
 
 - Triplet Loss
 - PN Loss
 - Multi Sim Loss
 - Circle Loss
+- Soft Nearest Neighbor Loss
 
 ### Metrics
 
@@ -140,7 +155,7 @@ Please cite this reference if you use any part of TensorFlow similarity in your
 
 ```bibtex
 @article{EBSIM21,
-  title={TensorFlow Similarity: A Usuable, High-Performance Metric Learning Library},
+  title={TensorFlow Similarity: A Usable, High-Performance Metric Learning Library},
   author={Elie Bursztein, James Long, Shun Lin, Owen Vallis, Francois Chollet},
   journal={Fixme},
   year={2021}

api/README.md

@@ -30,6 +30,8 @@ The default implementation can scale up to medium deployment (1M-10M+ points) ea
 
 - [`architectures`](./TFSimilarity/architectures.md): Deep-learning model architectures tweaked to work well for similarity
 
+- [`augmenters`](./TFSimilarity/augmenters.md)
+
 - [`callbacks`](./TFSimilarity/callbacks.md): Specialized callbacks that track similarity metrics during training
 
 - [`classification_metrics`](./TFSimilarity/classification_metrics.md): Classification metrics measure matching classification quality between a