Project

General

Profile

Feature #18651

Updated by Peter Amstutz 5 months ago

Design sketch to support using the vocabulary in the Python SDK, for review. 

 New class called @Vocabulary@ which is initialized from the vocabulary JSON.    It can be initialized from an API object, in which case it fetches the vocabulary file itself. 

 The @Vocabulary@ has a dict, "key_aliases". 

 The key_aliases has an entry for every alias of every key, as well as the formal identifiers.    The value is an object of type @VocabularyKey@. 

 The @VocabularyKey@ class has fields "identifier" (string), "aliases" (list of strings) and "value_aliases". 

 The "value_aliases" field has an entry for every alias of every value associated with this key, as well as the formal identifiers.    The value is on object of type @VocabularyValue@. 

 The @VocabularyValue@ class has fields "identifier" (string) and "aliases" (list of strings). 

 Support case-insensitive lookup of aliases.    Suggest indexing aliases as all-lowercase.    Lookups check the check the case-insensitive version. 

 This is intended to be used to easily convert "properties" between aliases and formal identifers.    There will be a @Vocabulary.convert_to_labels()@ and @Vocabulary.convert_to_identifiers()@ methods.    The first normalizes based on human-readable labels, the second normalizes based to the machine identifiers. 

 The basic usage would be something like this 

 <pre> 
 vocab = Vocabulary(vocab_json) 

 vocabkey = vocab.key_aliases["species"] 
 print(vocabkey.identifier)    # "id123" 
 print(vocabkey.aliases)       # ["species", "animal"] 

 vocabvalue = vocabkey.value_aliases["human"] 
 print(vocabvalue.identifier)    # "id456" 
 print(vocabvalue.aliases)       # ["homo sapiens", "human"] 

 vocab.convert_to_identifiers({"animal": "human"}) 
 # -> {"id123": "id456"} 

 vocab.convert_to_labels({"id123": "id456"}) 
 # -> {"species": "homo sapiens"} 
 </pre> 

 Additional thought: could have add an indexer on the object so that you can just write @vocab["species"]["human"].identifier@. 

 Suggestion from Tom: wrapper methods which automatically translate the properties field to/from identifiers on get, list, create, update, etc. 

Back