Document creating / updating external vocabularies for term labeling

[surchs]

in https://github.com/neurobagel/planning/issues/52#issuecomment-1790775259 we created a filtered view of SNOMED-CT diagnoses (and likely similar for cogAtlas). These lists are used by n-APIs to label terms in search results, and also by the annotation tool as annotation options. Now we have some controlled terms in the graph that are not in these vocabulary files, so we need to update them. To make this easier, we want to clarify and then document the process:

ToDo:

• [x] Clarify
  • [x] what vocabulary file the annotation uses to display the diagnosis and assessment tool options
  • [x] what vocabulary files are used to annotate n-API responses (so they are shown in the query tool)
  • [x] document that (on hackMD)
• [ ] document how the current files were created, especially for SNOMED
  • [ ] what were the input files (likely downloaded from OHDSI athena)
  • [ ] how did we read them in (i.e. how could we do that again)
  • [ ] what filter criteria did we use to go from SNOMED=very long list to SNOMED=reasonably shorter list
  • [ ] what code did we use to do that
• [ ] How do I update the vocabulary now
  • [ ] what do I need to do to find controlled terms for which we don't have labels in our vocabulary files
  • [ ] what is a good automated way to add more vocabulary files (or should this be done manually)

[rmanaem]

what vocabulary file the annotation uses to display the diagnosis and assessment tool options

The annotation tool uses toolTerms.json for displaying assessment tool options and diagnosisTerms.json for displaying diagnosis options

what vocabulary files are used to annotate n-API responses (so they are shown in the query tool)

The n-API uses snomedct_disorder.json and cogatlas_task.json

Which have the same terms as the files in the annotation tool. Documented here: https://hackmd.io/@neurobagel/Hk7_WQLNR

[surchs]

What remains to be done here is to

• find the original issue where we described how SNOMED was filtered
• link the issue here
• and then eventually copy the information from the issue into our internal dev docs

[alyssadai]

• Issue with context for getting the required files for terms from SNOMED-CT via OHDSI/Athena: https://github.com/neurobagel/planning/issues/52#issuecomment-1789705499
• Code snippet we used to filter the the terms we wanted using their parents