### 7.5.2. The Cosine Similarity algorithm

This section describes the Cosine Similarity algorithm in the Neo4j Graph Algorithms library.

Cosine similarity is the cosine of the angle between two n-dimensional vectors in an n-dimensional space. It is the dot product of the two vectors divided by the product of the two vectors' lengths (or magnitudes).

 The Cosine Similarity algorithm is experimental and not officially supported.

This section includes:

#### 7.5.2.1. History and explanation

Cosine similarity is computed using the following formula: Values range between -1 and 1, where -1 is perfectly dissimilar and 1 is perfectly similar.

The library contains both procedures and functions to calculate similarity between sets of data. The function is best used when calculating the similarity between small numbers of sets. The procedures parallelize the computation and are therefore more appropriate for computing similarities on bigger datasets.

#### 7.5.2.2. Use-cases - when to use the Cosine Similarity algorithm

We can use the Cosine Similarity algorithm to work out the similarity between two things. We might then use the computed similarity as part of a recommendation query. For example, to get movie recommendations based on the preferences of users who have given similar ratings to other movies that you’ve seen.

#### 7.5.2.3. Cosine Similarity algorithm function sample

The Cosine Similarity function computes the similarity of two lists of numbers.

 Cosine Similarity is only calculated over non-NULL dimensions. When calling the function, we should provide lists that contain the overlapping items.

We can use it to compute the similarity of two hardcoded lists.

The following will return the cosine similarity of two lists of numbers:

``RETURN algo.similarity.cosine([3,8,7,5,2,9], [10,8,6,6,4,5]) AS similarity``

Table 7.75. Results
`similarity`

0.8638935626791596

These two lists of numbers have a Cosine similarity of 0.863. We can see how this result is derived by breaking down the formula: We can also use it to compute the similarity of nodes based on lists computed by a Cypher query.

The following will create a sample graph:

``````MERGE (french:Cuisine {name:'French'})
MERGE (italian:Cuisine {name:'Italian'})
MERGE (indian:Cuisine {name:'Indian'})
MERGE (lebanese:Cuisine {name:'Lebanese'})
MERGE (portuguese:Cuisine {name:'Portuguese'})
MERGE (british:Cuisine {name:'British'})
MERGE (mauritian:Cuisine {name:'Mauritian'})

MERGE (zhen:Person {name: "Zhen"})
MERGE (praveena:Person {name: "Praveena"})
MERGE (michael:Person {name: "Michael"})
MERGE (arya:Person {name: "Arya"})
MERGE (karin:Person {name: "Karin"})

MERGE (praveena)-[:LIKES {score: 9}]->(indian)
MERGE (praveena)-[:LIKES {score: 7}]->(portuguese)
MERGE (praveena)-[:LIKES {score: 8}]->(british)
MERGE (praveena)-[:LIKES {score: 1}]->(mauritian)

MERGE (zhen)-[:LIKES {score: 10}]->(french)
MERGE (zhen)-[:LIKES {score: 6}]->(indian)
MERGE (zhen)-[:LIKES {score: 2}]->(british)

MERGE (michael)-[:LIKES {score: 8}]->(french)
MERGE (michael)-[:LIKES {score: 7}]->(italian)
MERGE (michael)-[:LIKES {score: 9}]->(indian)
MERGE (michael)-[:LIKES {score: 3}]->(portuguese)

MERGE (arya)-[:LIKES {score: 10}]->(lebanese)
MERGE (arya)-[:LIKES {score: 10}]->(italian)
MERGE (arya)-[:LIKES {score: 7}]->(portuguese)
MERGE (arya)-[:LIKES {score: 9}]->(mauritian)

MERGE (karin)-[:LIKES {score: 9}]->(lebanese)
MERGE (karin)-[:LIKES {score: 7}]->(italian)
MERGE (karin)-[:LIKES {score: 10}]->(portuguese)``````

The following will return the Cosine similarity of Michael and Arya:

``````MATCH (p1:Person {name: 'Michael'})-[likes1:LIKES]->(cuisine)
MATCH (p2:Person {name: "Arya"})-[likes2:LIKES]->(cuisine)
RETURN p1.name AS from,
p2.name AS to,
algo.similarity.cosine(collect(likes1.score), collect(likes2.score)) AS similarity``````

Table 7.76. Results
`from` `to` `similarity`

"Michael"

"Arya"

0.9788908326303921

The following will return the Cosine similarity of Michael and the other people that have a cuisine in common:

``````MATCH (p1:Person {name: 'Michael'})-[likes1:LIKES]->(cuisine)
MATCH (p2:Person)-[likes2:LIKES]->(cuisine) WHERE p2 <> p1
RETURN p1.name AS from,
p2.name AS to,
algo.similarity.cosine(collect(likes1.score), collect(likes2.score)) AS similarity
ORDER BY similarity DESC``````

Table 7.77. Results
`from` `to` `similarity`

"Michael"

"Arya"

0.9788908326303921

"Michael"

"Zhen"

0.9542262139256075

"Michael"

"Praveena"

0.9429903335828894

"Michael"

"Karin"

0.8498063272285821

#### 7.5.2.4. Cosine Similarity algorithm procedures sample

The Cosine Similarity procedure computes similarity between all pairs of items. It is a symmetrical algorithm, which means that the result from computing the similarity of Item A to Item B is the same as computing the similarity of Item B to Item A. We can therefore compute the score for each pair of nodes once. We don’t compute the similarity of items to themselves.

The number of computations is `((# items)^2 / 2) - # items`, which can be very computationally expensive if we have a lot of items.

 Cosine Similarity is only calculated over non-NULL dimensions. The procedures expect to receive the same length lists for all items, so we need to pad those lists with `algo.NaN()` where necessary.

The following will create a sample graph:

``````MERGE (french:Cuisine {name:'French'})
MERGE (italian:Cuisine {name:'Italian'})
MERGE (indian:Cuisine {name:'Indian'})
MERGE (lebanese:Cuisine {name:'Lebanese'})
MERGE (portuguese:Cuisine {name:'Portuguese'})
MERGE (british:Cuisine {name:'British'})
MERGE (mauritian:Cuisine {name:'Mauritian'})

MERGE (zhen:Person {name: "Zhen"})
MERGE (praveena:Person {name: "Praveena"})
MERGE (michael:Person {name: "Michael"})
MERGE (arya:Person {name: "Arya"})
MERGE (karin:Person {name: "Karin"})

MERGE (praveena)-[:LIKES {score: 9}]->(indian)
MERGE (praveena)-[:LIKES {score: 7}]->(portuguese)
MERGE (praveena)-[:LIKES {score: 8}]->(british)
MERGE (praveena)-[:LIKES {score: 1}]->(mauritian)

MERGE (zhen)-[:LIKES {score: 10}]->(french)
MERGE (zhen)-[:LIKES {score: 6}]->(indian)
MERGE (zhen)-[:LIKES {score: 2}]->(british)

MERGE (michael)-[:LIKES {score: 8}]->(french)
MERGE (michael)-[:LIKES {score: 7}]->(italian)
MERGE (michael)-[:LIKES {score: 9}]->(indian)
MERGE (michael)-[:LIKES {score: 3}]->(portuguese)

MERGE (arya)-[:LIKES {score: 10}]->(lebanese)
MERGE (arya)-[:LIKES {score: 10}]->(italian)
MERGE (arya)-[:LIKES {score: 7}]->(portuguese)
MERGE (arya)-[:LIKES {score: 9}]->(mauritian)

MERGE (karin)-[:LIKES {score: 9}]->(lebanese)
MERGE (karin)-[:LIKES {score: 7}]->(italian)
MERGE (karin)-[:LIKES {score: 10}]->(portuguese)``````

The following will return a stream of node pairs along with their Cosine similarities:

``````MATCH (p:Person), (c:Cuisine)
OPTIONAL MATCH (p)-[likes:LIKES]->(c)
WITH {item:id(p), weights: collect(coalesce(likes.score, algo.NaN()))} as userData
WITH collect(userData) as data
CALL algo.similarity.cosine.stream(data)
YIELD item1, item2, count1, count2, similarity
RETURN algo.asNode(item1).name AS from, algo.asNode(item2).name AS to, similarity
ORDER BY similarity DESC``````

Table 7.78. Results
`from` `to` `similarity`

"Praveena"

"Karin"

1.0

"Michael"

"Arya"

0.9788908326303921

"Arya"

"Karin"

0.9610904115204073

"Zhen"

"Michael"

0.9542262139256075

"Praveena"

"Michael"

0.9429903335828895

"Zhen"

"Praveena"

0.9191450300180579

"Michael"

"Karin"

0.8498063272285821

"Praveena"

"Arya"

0.7194014606174091

"Zhen"

"Arya"

0.0

"Zhen"

"Karin"

0.0

Praveena and Karin have the most similar food tastes, with a score of 1.0, and there are also several other pairs of users with similar tastes. The scores here are unusually high because our users haven’t liked many of the same cuisines. We also have 2 pairs of users who are not similar at all. We’d probably want to filter those out, which we can do by passing in the `similarityCutoff` parameter.

The following will return a stream of node pairs that have a similarity of at least 0.1, along with their cosine similarities:

``````MATCH (p:Person), (c:Cuisine)
OPTIONAL MATCH (p)-[likes:LIKES]->(c)
WITH {item:id(p), weights: collect(coalesce(likes.score, algo.NaN()))} as userData
WITH collect(userData) as data
CALL algo.similarity.cosine.stream(data, {similarityCutoff: 0.0})
YIELD item1, item2, count1, count2, similarity
RETURN algo.asNode(item1).name AS from, algo.asNode(item2).name AS to, similarity
ORDER BY similarity DESC``````

Table 7.79. Results
`from` `to` `similarity`

"Praveena"

"Karin"

1.0

"Michael"

"Arya"

0.9788908326303921

"Arya"

"Karin"

0.9610904115204073

"Zhen"

"Michael"

0.9542262139256075

"Praveena"

"Michael"

0.9429903335828895

"Zhen"

"Praveena"

0.9191450300180579

"Michael"

"Karin"

0.8498063272285821

"Praveena"

"Arya"

0.7194014606174091

We can see that those users with no similarity have been filtered out. If we’re implementing a k-Nearest Neighbors type query we might instead want to find the most similar `k` users for a given user. We can do that by passing in the `topK` parameter.

The following will return a stream of users along with the most similar user to them (i.e. `k=1`):

``````MATCH (p:Person), (c:Cuisine)
OPTIONAL MATCH (p)-[likes:LIKES]->(c)
WITH {item:id(p), weights: collect(coalesce(likes.score, algo.NaN()))} as userData
WITH collect(userData) as data
CALL algo.similarity.cosine.stream(data, {topK:1, similarityCutoff: 0.0})
YIELD item1, item2, count1, count2, similarity
RETURN algo.asNode(item1).name AS from, algo.asNode(item2).name AS to, similarity
ORDER BY from``````

Table 7.80. Results
`from` `to` `similarity`

"Arya"

"Michael"

0.9788908326303921

"Karin"

"Praveena"

1.0

"Michael"

"Arya"

0.9788908326303921

"Praveena"

"Karin"

1.0

"Zhen"

"Michael"

0.9542262139256075

These results will not be symmetrical. For example, the person most similar to Zhen is Michael, but the person most similar to Michael is Arya.

The following will find the most similar user for each user, and store a relationship between those users:

``````MATCH (p:Person), (c:Cuisine)
OPTIONAL MATCH (p)-[likes:LIKES]->(c)
WITH {item:id(p), weights: collect(coalesce(likes.score, algo.NaN()))} as userData
WITH collect(userData) as data
CALL algo.similarity.cosine(data, {topK: 1, similarityCutoff: 0.1, write:true})
YIELD nodes, similarityPairs, write, writeRelationshipType, writeProperty, min, max, mean, stdDev, p25, p50, p75, p90, p95, p99, p999, p100
RETURN nodes, similarityPairs, write, writeRelationshipType, writeProperty, min, max, mean, p95``````

Table 7.81. Results
`nodes` `similarityPairs` `write` `writeRelationshipType` `writeProperty` `min` `max` `mean` `p95`

5

5

TRUE

"SIMILAR"

"score"

0.9542236328125

1.0000038146972656

0.9824020385742187

1.0000038146972656

We then could write a query to find out what types of cuisine that other people similar to us might like.

The following will find the most similar user to Praveena, and return their favourite cuisines that Praveena doesn’t (yet!) like:

``````MATCH (p:Person {name: "Praveena"})-[:SIMILAR]->(other),
(other)-[:LIKES]->(cuisine)
WHERE not((p)-[:LIKES]->(cuisine))
RETURN cuisine.name AS cuisine``````

Table 7.82. Results
`cuisine`

Italian

Lebanese

#### 7.5.2.5. Specifying source and target ids

Sometimes, we don’t want to compute all pairs similarity, but would rather specify subsets of items to compare to each other. We do this using the `sourceIds` and `targetIds` keys in the config.

We could use this technique to compute the similarity of a subset of items to all other items.

The following will find the most similar person (i.e. `k=1`) to Arya and Praveena:

``````MATCH (p:Person), (c:Cuisine)
OPTIONAL MATCH (p)-[likes:LIKES]->(c)
WITH {item:id(p), name: p.name, weights: collect(coalesce(likes.score, algo.NaN()))} as userData
WITH collect(userData) as personCuisines

// create sourceIds list containing ids for Praveena and Arya
WITH personCuisines,
[value in personCuisines WHERE value.name IN ["Praveena", "Arya"] | value.item ] AS sourceIds

CALL algo.similarity.cosine.stream(personCuisines, {sourceIds: sourceIds, topK: 1})
YIELD item1, item2, similarity
WITH algo.getNodeById(item1) AS from, algo.getNodeById(item2) AS to, similarity
RETURN from.name AS from, to.name AS to, similarity
ORDER BY similarity DESC``````

Table 7.83. Results
`from` `to` `similarity`

Praveena

Karin

1.0

Arya

Michael

0.9788908326303921

#### 7.5.2.6. Skipping values

By default the `skipValue` parameter is `algo.Nan()`. The algorithm checks every value against the `skipValue` to determine whether that value should be considered as part of the similarity result. For cases where no values should be skipped, skipping can be disabled by setting `skipValue` to `null`.

The following will create a sample graph:

``````MERGE (french:Cuisine {name:'French'})          SET french.embedding = [0.71, 0.33, 0.81, 0.52, 0.41]
MERGE (italian:Cuisine {name:'Italian'})        SET italian.embedding = [0.31, 0.72, 0.58, 0.67, 0.31]
MERGE (indian:Cuisine {name:'Indian'})          SET indian.embedding = [0.43, 0.26, 0.98, 0.51, 0.76]
MERGE (lebanese:Cuisine {name:'Lebanese'})      SET lebanese.embedding = [0.12, 0.23, 0.35, 0.31, 0.39]
MERGE (portuguese:Cuisine {name:'Portuguese'})  SET portuguese.embedding = [0.47, 0.98, 0.81, 0.72, 0.89]
MERGE (british:Cuisine {name:'British'})        SET british.embedding = [0.94, 0.12, 0.23, 0.4, 0.71]
MERGE (mauritian:Cuisine {name:'Mauritian'})    SET mauritian.embedding = [0.31, 0.56, 0.98, 0.21, 0.62]``````

The following will find the similarity between cuisines based on the `embedding` property:

``````MATCH (c:Cuisine)
WITH {item:id(c), weights: c.embedding} as userData
WITH collect(userData) as data
CALL algo.similarity.cosine.stream(data, {skipValue: null})
YIELD item1, item2, count1, count2, similarity
RETURN algo.asNode(item1).name AS from, algo.asNode(item2).name AS to, similarity
ORDER BY similarity DESC``````

#### 7.5.2.7. Cypher projection

If the similarity lists are very large they can take up a lot of memory. For cases where those lists contain lots of values that should be skipped, you can use the less memory-intensive approach of using Cypher statements to project the graph instead.

The Cypher loader expects to receive 3 fields:

• `item` - should contain node ids, which we can return using the `id` function.
• `category` - should contain node ids, which we can return using the `id` function.
• `weight` - should contain a double value.

Set `graph:'cypher'` in the config:

``````WITH "MATCH (person:Person)-[likes:LIKES]->(c)
RETURN id(person) AS item, id(c) AS category, likes.score AS weight" AS query
CALL algo.similarity.cosine(query, {
graph: 'cypher', topK: 1, similarityCutoff: 0.1, write:true
})
YIELD nodes, similarityPairs, write, writeRelationshipType, writeProperty, min, max, mean, stdDev, p95
RETURN nodes, similarityPairs, write, writeRelationshipType, writeProperty, min, max, mean, p95``````

#### 7.5.2.8. Syntax

The following will run the algorithm and write back results:

``````CALL algo.similarity.cosine(userData:List<Map> or String, {
topK: 1, similarityCutoff: 0.1, write:true, writeProperty: "cosineSimilarity"
})
YIELD nodes, similarityPairs, write, writeRelationshipType, writeProperty, min, max, mean, stdDev, p25, p50, p75, p90, p95, p99, p999, p100``````

Table 7.84. Parameters
Name Type Default Optional Description

`data`

list or string

null

no

A list of maps of the following structure: `{item: nodeId, categories: [nodeId, nodeId, nodeId]}` or a Cypher query.

`top`

int

0

yes

The number of similar pairs to return. If `0`, it will return as many as it finds.

`topK`

int

0

yes

The number of similar values to return per node. If `0`, it will return as many as it finds.

`similarityCutoff`

int

-1

yes

The threshold for similarity. Values below this will not be returned.

`degreeCutoff`

int

0

yes

The threshold for the number of items in the `targets` list. If the list contains less than this amount, that node will be excluded from the calculation.

`skipValue`

double

algo.NaN()

yes

Value to skip when executing similarity computation. A value of `null` means that skipping is disabled.

`concurrency`

int

available CPUs

yes

The number of concurrent threads.

`graph`

string

dense

yes

The graph name ('dense' or 'cypher').

`write`

boolean

false

yes

Indicates whether results should be stored.

`writeBatchSize`

int

10000

yes

The batch size to use when storing results.

`writeRelationshipType`

string

SIMILAR

yes

The relationship type to use when storing results.

`writeProperty`

string

score

yes

The property to use when storing results.

`sourceIds`

long[]

null

yes

The ids of items from which we need to compute similarities. Defaults to all the items provided in the `data` parameter.

`targetIds`

long[]

null

yes

The ids of items to which we need to compute similarities. Defaults to all the items provided in the `data` parameter.

Table 7.85. Results
Name Type Description

`nodes`

int

The number of nodes passed in.

`similarityPairs`

int

The number of pairs of similar nodes computed.

`write`

boolean

Indicates whether results were stored.

`writeRelationshipType`

string

The relationship type used when storing results.

`writeProperty`

string

The property used when storing results.

`min`

double

The minimum similarity score computed.

`max`

double

The maximum similarity score computed.

`mean`

double

The mean of similarities scores computed.

`stdDev`

double

The standard deviation of similarities scores computed.

`p25`

double

The 25 percentile of similarities scores computed.

`p50`

double

The 50 percentile of similarities scores computed.

`p75`

double

The 75 percentile of similarities scores computed.

`p90`

double

The 90 percentile of similarities scores computed.

`p95`

double

The 95 percentile of similarities scores computed.

`p99`

double

The 99 percentile of similarities scores computed.

`p999`

double

The 99.9 percentile of similarities scores computed.

`p100`

double

The 100 percentile of similarities scores computed.

The following will run the algorithm and stream results:

``````CALL algo.similarity.cosine.stream(userData:List<Map> or String, {
degreeCutoff: 10, similarityCutoff: 0.1, concurrency:4
})
YIELD item1, item2, count1, count2, intersection, similarity``````

Table 7.86. Parameters
Name Type Default Optional Description

`data`

list or string

null

no

A list of maps of the following structure: `{item: nodeId, categories: [nodeId, nodeId, nodeId]}` or a Cypher query.

`top`

int

0

yes

The number of similar pairs to return. If `0`, it will return as many as it finds.

`topK`

int

0

yes

The number of similar values to return per node. If `0`, it will return as many as it finds.

`similarityCutoff`

int

-1

yes

The threshold for similarity. Values below this will not be returned.

`degreeCutoff`

int

0

yes

The threshold for the number of items in the `targets` list. If the list contains less than this amount, that node will be excluded from the calculation.

`skipValue`

double

null

yes

Value to skip when executing similarity computation. A value of `null` means that skipping is disabled.

`concurrency`

int

available CPUs

yes

The number of concurrent threads.

`graph`

string

dense

yes

The graph name ('dense' or 'cypher').

`sourceIds`

long[]

null

yes

The ids of items from which we need to compute similarities. Defaults to all the items provided in the `data` parameter.

`targetIds`

long[]

null

yes

The ids of items to which we need to compute similarities. Defaults to all the items provided in the `data` parameter.

Table 7.87. Results
Name Type Description

`item1`

int

The ID of one node in the similarity pair.

`item2`

int

The ID of other node in the similarity pair.

`count1`

int

The size of the `targets` list of one node.

`count2`

int

The size of the `targets` list of other node.

`intersection`

int

The number of intersecting values in the two nodes `targets` lists.

`similarity`

int

The cosine similarity of the two nodes.