describe the api that needs to be built for triptych

[cmcnamara87]

so we have a basically a prototype of what the visualisation could be like, now we need to build the api that goes with it

so we need to document what data the UI needs, and how they would like it from the back

i imagine it will be something like GET /similarities?a=1231231&b=12321213

and it will have to return the comparisons, but also classification information for the hpo terms. maybe its better as two separate requests?

GET /terms?id=12321123&id=12231125

and just marry the data from the two calls together? That way, the front end can filter for just Skeletal Abnormalities, and call the similarities call again, with a smaller filtered list of terms

[davidyu85]

Getting initial data

GET /profilecompare?a={PROFILE_A_HPO_ID}&b={PROFILE_B_HPO_ID}

The data below is used to represent 25% overall matches, with only two abnormalities and three phenotype shown in both Achondroplasia and Pseudoachondroplasia.

For Abnormalities of head and neck, Achondroplasia only has Macrocephaly and Pseudoachondroplasia only has Gait Disturbance. There are no phenotype similarity for both phenotype, therefore the matchScore for Abnormalities of head and neck is 0.

For Abnormalities of skeletal system, Macrocephaly is shown again because it belongs to two classifications. Again Pseudoachondroplasia doesn't have this phenotype and no other phenotypes are similar to this, thus similarity is 0. But both Achondroplasia and Pseudoachondroplasia have Kyphosis, which the similarity of the two phenotype is 100% and the LCS is the same - Kyphosis. So, the matchScore for Abnormalities of skeletal system is 50%.

Overall with only 1 phenotype match between the two profiles, the overallMatchScore is estimate to be 25%.

{
  "data": {
    "profileA": {
      "name": "Achondroplasia",
      "id": "PROFILE_A"
    },

    "profileB": {
      "name": "Pseudoachondroplasia",
      "id": "PROFILE_B"
    },

    "overallMatch": 25,

    "result": {
      "Abnormality of head or neck": {
        "matchScore": 0,
        "phenotypeCompare": [

          {
            "profileAPhenotype": {
              "name": "Macrocephaly",
              "id": "HP:XXXXX",
              "category": [
                { 
                  "name": "Abnormality of head or neck",
                  "id": "HP:XXXXX"
                },
                { 
                  "name": "Abnormality of skeletal system",
                  "id": "HP:XXXXX"
                },
              ]
            },
            "profileBPhenotype": {},
            "lcs": {},
            "similarityScore": 0
          },

          {
            "profileAPhenotype": {},
            "profileBPhenotype": {
              "name": "Gait Disturbance",
              "id": "HP:XXXXX",
              "category": [
                { 
                  "name": "Abnormality of head or neck",
                  "id": "HP:XXXXX"
                }
              ]
            },
            "profileBPhenotype": {},
            "lcs": {},
            "similarityScore": 0
          }

        ]
      },

      "Abnormality of skeletal system": {
        "matchScore": 50,
        "phenotypeCompare": [
          {
            "profileAPhenotype": {
              "name": "Macrocephaly",
              "id": "HP:XXXXX",
              "category": [
                { 
                  "name": "Abnormality of head or neck",
                  "id": "HP:XXXXX"
                },
                { 
                  "name": "Abnormality of skeletal system",
                  "id": "HP:XXXXX"
                },
              ]
            },
            "profileBPhenotype": {},
            "lcs": {},
            "similarityScore": 0
          },

          {
            "profileAPhenotype": {
              "name": "Kyphosis",
              "id": "HP:XXXXX",
              "category": [
                { 
                  "name": "Abnormality of skeletal system",
                  "id": "HP:XXXXX"
                },
              ]
            },
            "profileBPhenotype": {
              "name": "Kyphosis",
              "id": "HP:XXXXX",
              "category": [
                { 
                  "name": "Abnormality of skeletal system",
                  "id": "HP:XXXXX"
                },
              ]
            },
            "lcs": {
              "name": "Kyphosis",
              "id": "HP:XXXXX",
              "category": [
                { 
                  "name": "Abnormality of skeletal system",
                  "id": "HP:XXXXX"
                },
              ]
            },
            "similarityScore": 100
          }

        ]
      }
    }
  }
}

Use of data:

• Profile name for headings (main, triptych and table) => data.profileA.name or data.profileB.name
• Radar axis => Object.keys(data.result).map((category) => category)
• Radar value and hover list => Object.keys(data.result).map((category) => data.result[category])
• Table row => Same as radar but including the display of data.result[category].matchScore
• Table selection to initiate clustering => data.result[category].phenotypeCompare.map(...)
• Triptych data => data.result[category].phenotypeCompare.map(...)

Click to initiate clustering

GET /clustering?a={PHENOTYPE_A1_HPO_ID}&a={PHENOTYPE_A2_HPO_ID}&a={PHENOTYPE_A3_HPO_ID}&b={PHENOTYPE_B1_HPO_ID}&b={PHENOTYPE_B2_HPO_ID}&b={PHENOTYPE_B3_HPO_ID}

Similar to the data structure above showing only:

{
  "data": {
    "overallScore": XX,
    "result": {.....SAME AS ABOVE......}
  }
}

[genome-one]

Thanks a lot @davidyu85 for this. W.r.t. the initial part, the actual GET call is irrelevant, as it could be different for different scenarios. The data format, on the other hand, looks good. Below are some slight changes - please feel free disregard them if you think they don't make sense.

{
    "profiles": {
        "profileA": {
            "name": "Achondroplasia",
            "id": "PROFILE_A"
        },
        "profileB": {
            "name": "Pseudoachondroplasia",
            "id": "PROFILE_B"
        }
    },
    "overallMatch": 25,
    "similarity": {
        "segments": [
            {
                "topLevel": {
                    "id": "HP...",
                    "label": "..."
                },
                "matchScore": 0,
                "comparison": {
                    "profileAPhenotype": [
                        {
                            "name": "Macrocephaly",
                            "id": "HP:XXXXX",
                            "categories": [
                                {
                                    "name": "Abnormality of head or neck",
                                    "id": "HP:XXXXX"
                                },
                                {
                                    "name": "Abnormality of skeletal system",
                                    "id": "HP:XXXXX"
                                }
                            ]
                        }
                    ],
                    "profileBPhenotype": [],
                    "lcs": {
                        "name": "Kyphosis",
                        "id": "HP:XXXXX",
                        "categories": [
                            {
                                "name": "Abnormality of skeletal system",
                                "id": "HP:XXXXX"
                            }
                        ],
                        "similarityScore": 100
                    },
                    "similarityScore": 0
                }
            }
        ]
    }
}

[davidyu85]

@genome-one
Looks good. The term changes make sense. I can incorporate these into my version.

[jmcmurry]

@cmcnamara87 Will see if we get a speed boost by caching everything on the front end. Pouch DB js implementation that talks to all Couch DBs; makes it really easy to work with local storage according to @DoctorBud.