add properties and an explanation of the example to the documentation

README.md

@@ -18,6 +18,18 @@ SPDX-License-Identifier: GPL-3.0-or-later
 # SAS: Singular Angle Similarity
 Method for comparing the singular angle similarity of arbitrary matrices of the same shape, based on singular value decomposition.
 
+## Properties of SAS
+
+- SAS attains values between $0$ and $1$ where higher values imply greater similarity.
+- SAS is invariant under actions of identical orthogonal maps from the left or the right on the compared matrices.
+- SAS is invariant under transposition of both matrices; this includes the consistent permutation of rows and columns as a special case.
+- SAS is invariant under scaling with a positive factor; in particular, SAS $= 1$ for $M_b = c_{1} M_a$ where $c_1 \in \mathbb{R}^+$.
+- SAS is zero if scaled with a negative factor; in particular, SAS $= 0$ for $M_b = c_2 M_a$ where $c_{2} \in \mathbb{R}^-$.
+
+The formal derivation of the measure and its properties is presented [here](link_to_paper). In particular, the linked manuscript provides cases for which SAS detects similarity where traditional measures such as the Frobenius norm or the cosine similarity fail.
+
+We recommend to use the `match_values` method of SAS, which is selected by default. When multiple singular values are close in magnitude and noise is present, it may be beneficial to select pairs of vectors based on their alignment rather than based on their singular value. Possible applications of this method, in this implementation called `match_vectors`, are discussed in the publication linked above.
+
 ## Installation
 ```bash
 pip install .
@@ -44,6 +56,8 @@ similarity = sas.compare(matrix_a, matrix_b)
 
 ### Calculating the similarity across instances
 
+Here, we show that two generative models of matrices can be distinguished from each other: a normally distributed matrix with a block in its upper left quarter is more similar to another instantiation of the same matrix type than to a normally distributed matrix with no blocks.
+
 ```python
 import numpy as np
 import sas