add ADR for return value of the compare endpoint

[nsheff]

Adds an ADR for the agreed upon comparison function return value.

TODO:

• [x] look at some real examples

[nsheff]

We can now demo some real examples as I have this working on the server. http://seqcolapi.databio.org/docs#/

Here's a comparison for 2 versions of hg38: http://seqcolapi.databio.org/comparison/514c871928a74885ce981faa61ccbb1a/c345e091cce0b1df78bfc124b03fba1c

[nsheff]

I posted a matrix of links to comparisons here: http://cloud.databio.org/links.html

[nsheff]

@daviesrob above I posted a link to the examples you requested :)

[nsheff]

Despite the approvals here, in our meeting in December there was a lot of concern that the values returned from the function were not detailed enough.

So, I now rewrote the function to include counts of shared elements, not just whether elements are shared. The new return values are active in the above demos. I'd like to know if people thing this is acceptable and then I can rewrite this ADR.

[andrewyatz]

This is also good. Is there a sense of totality of overlap i.e. from just a raw number it's hard to get a sense of how much overlap we're seeing. At the same time I conceded that this might be unnecessary information.

[nsheff]

This is also good. Is there a sense of totality of overlap i.e. from just a raw number it's hard to get a sense of how much overlap we're seeing. At the same time I conceded that this might be unnecessary information.

Well, this is why I included the 'total' arrays. So you can see there are X overlaps of Y elements. But, you do have to do a little math, comparing those numbers. it's not handed to you as easily as in the previous way, where it just said "Yes" or "No". I think that's a price you pay with increasing the complexity of the return value.

[andrewyatz]

Helps if I read the output fully. I saw the total section and I don't know why I didn't click it was the thing I was asking about. Wow need more caffeine

This is also good. Is there a sense of totality of overlap i.e. from just a raw number it's hard to get a sense of how much overlap we're seeing. At the same time I conceded that this might be unnecessary information.

Well, this is why I included the 'total' arrays. So you can see there are X overlaps of Y elements. But, you do have to do a little math, comparing those numbers. it's not handed to you as easily as in the previous way, where it just said "Yes" or "No". I think that's a price you pay with increasing the complexity of the return value.

[nsheff]

I updated this to reflect the most recent comparison return changes. please have another look.

[nsheff]

change overlap to a-and-b

change order-match to a-and-b-same-order