Clarification: getDissimilarity overlap metric appears to measure similarity

[ShivangPB]

In the documentation for getDissimilarity: (https://microbiome.github.io/mia/reference/getDissimilarity.html)
, the Details section states: “Overlap reflects similarity between sample-pairs. When overlap is calculated using relative abundances, the higher the value the higher the similarity is. When using relative abundances, overlap value 1 means that all the abundances of features are equal between two samples, and 0 means that samples have completely different relative abundances.”
This suggests that the overlap metric measures similarity (where values closer to 1 indicate higher similarity and 0 indicates dissimilar samples). However, since the function is named getDissimilarity, this might be confusing — one would expect higher values to correspond to greater dissimilarity.

[TuomasBorman]

Thanks @ShivangPB !

What do you think; would improving the documentation be enough?

I see couple possible options:

1. Improve documentation be highlighting this
2. Change the name of function from getDissimilarity to getSimilarity (dissimilarity is similarity)

However, I would avoid big changes to function naming if possible. We could have aliases for this method, but it can also be confusing.

@antagomir

[antagomir]

I consider both documentation and function name change solutions as problematic because they will not address the core issue. To me the least ambiguous solution would be to provide a new measure, "reciprocal overlap" (1-O) and explain in the documentation that it is 1-O, where O comes from the original paper. This way O can be calculated as 1-(1-O) by those who need.

Alternatively we can create a new function getSimilarity that includes similarity measures (as opposed to getDissimilarity which includes dissimilarity measures).

Also with alpha diversity the sign is always the same, and inverse or reciprocal are used if needed to get that.

[TuomasBorman]

Function names are always trade-off. They should describe what they are doing, but they should be short and there should not be many functions doing similar things.

I would keep "overlap" available as that is probably the one that users actually want.

Maybe getDissimilarity & getSimilarity would solve this but it adds maintenance burden (for instance, we should keep up with the changes in dependency packages).

[antagomir]

In my view we cannot keep "overlap" as such in getDissimilarity because it is inconsistent with the function naming and the other included measures. This can lead to problems down the line.

[TuomasBorman]

So is the solution:

getDissimilarity(x, method = c("inverse overlap", "unifrac", ...))

getSimilarity(x, method = c("overlap"))