Vocabulary (PhenoTips - Vocabularies

```
@Unstable
 @Role
public interface Vocabulary
```
Provides access to a vocabulary, such as the HUGO Gene Nomenclature, or the Human Phenotype Ontology.

Since:

1.2M4 (under different names since 1.0M8)

Version:

$Id: 66a627ea55df195d571020452ca8af391023a44d $

Method Summary

All Methods Instance Methods Abstract Methods Default Methods
Modifier and Type	Method and Description
`long`	`count(Map<String,?> fieldValues)` Get the number of terms that match a specific query.
`Set<String>`	`getAliases()` A vocabulary has an official name, but it can also have other aliases, for example the Human Phenotype Ontology is known both as `HP`, which is the official prefix for its terms, `HPO`, which is its acronym, or the lowercase `hpo`.
`String`	`getCitation()` Get the citation for the vocabulary.
`String`	`getDefaultSourceLocation()` Get the default location where the sources for this vocabulary can be fetched from.
`long`	`getDistance(String fromTermId, String toTermId)` Find the distance between two terms identified by their `term identifiers`, if this is a structured ontology that supports computing such a distance.
`long`	`getDistance(VocabularyTerm fromTerm, VocabularyTerm toTerm)` Find the distance between two terms, if this is a structured ontology that supports computing such a distance.
`List<VocabularyExtension>`	`getExtensions()` Get the list of `VocabularyExtension`s that extend a base vocabulary with additional annotations.
`String`	`getIdentifier()` The identifier of the vocabulary, used internally to differentiate between different vocabularies and different implementations of the same vocabulary.
`String`	`getName()` The official name of the vocabulary.
`default String`	`getSourceLocation()` Get the location where the sources for this vocabulary can be fetched from.
`default Collection<String>`	`getSupportedCategories()` Reports the categories of terms supported by this vocabulary.
`VocabularyTerm`	`getTerm(String id)` Access an individual term from the vocabulary, identified by its `term identifier`.
`Set<VocabularyTerm>`	`getTerms(Collection<String> ids)` Access a list of terms from the vocabulary, identified by their `term identifiers`.
`String`	`getVersion()` Get the available version of the vocabulary.
`String`	`getWebsite()` Get the website url for the vocabulary.
`int`	`reindex(String sourceUrl)` Reindex the whole vocabulary, fetching the source from the specified location.
`List<VocabularyTerm>`	`search(Map<String,?> fieldValues)` Generic search method, which looks for terms that match the specified term properties.
`List<VocabularyTerm>`	`search(Map<String,?> fieldValues, Map<String,String> queryOptions)` Generic search method, which looks for terms that match the specified meta-properties.
`List<VocabularyTerm>`	`search(String input)` Suggest the terms that best match the user's input.
`List<VocabularyTerm>`	`search(String input, int maxResults, String sort, String customFilter)` Suggest the terms that best match the user's input.
`default List<VocabularyTerm>`	`search(String input, String category, int maxResults, String sort, String customFilter)` Suggest the terms that best match the user's input, in a specific sub-category of this vocabulary.
`long`	`size()` Get the size (i.e.

- Method Detail
  - getTerm
```
VocabularyTerm getTerm(String id)
```
    Access an individual term from the vocabulary, identified by its term identifier.
    
    Parameters:
    
    id - the term identifier, in the format <vocabulary prefix>:<term id>, for example HP:0002066
    
    Returns:
    
    the requested term, or null if the term doesn't exist in this vocabulary
  - getTerms
```
Set<VocabularyTerm> getTerms(Collection<String> ids)
```
    Access a list of terms from the vocabulary, identified by their term identifiers.
    
    Parameters:
    
    ids - a set of term identifiers, in the format <vocabulary prefix>:<term id>, for example HP:0002066
    
    Returns:
    
    a set with the requested terms that were found in the vocabulary, an empty set if no terms were found
  - search
```
List<VocabularyTerm> search(Map<String,?> fieldValues)
```
    Generic search method, which looks for terms that match the specified term properties.
    
    Parameters:
    
    fieldValues - a map with term property values that must be matched by the returned terms; the keys are property names, like id, description, is_a, and the values can be either a single value, or a collection of values that can (OR) be matched by the term
    
    Returns:
    
    the matching terms that were found in the vocabulary, an empty list if no terms were found
  - search
```
List<VocabularyTerm> search(Map<String,?> fieldValues,
                            Map<String,String> queryOptions)
```
    Generic search method, which looks for terms that match the specified meta-properties.
    
    Parameters:
    
    fieldValues - a map with term property values that must be matched by the returned terms; the keys are property names, like id, description, is_a, and the values can be either a single value, or a collection of values that can (OR) be matched by the term
    
    queryOptions - a map with additional query options, such as maximum number of terms to return or a different sort order; the accepted keys/values depend on the actual implementation details, and usually correspond to the settings accepted by the storage engine, for example rows -> 10, start -> 50, sort -> nameSort asc for Solr-indexed vocabularies
    
    Returns:
    
    the matching terms that were found in the vocabulary, an empty list if no terms were found
  - search
```
List<VocabularyTerm> search(String input)
```
    Suggest the terms that best match the user's input. This returns at most 10 matching terms, sorted by the match score.
    
    Parameters:
    
    input - the text that the user entered
    
    Returns:
    
    a list of suggestions, possibly empty.
    
    Since:
    
    1.3
  - search
```
List<VocabularyTerm> search(String input,
                            int maxResults,
                            String sort,
                            String customFilter)
```
    Suggest the terms that best match the user's input. This may either search in all supported categories, or in a "default" category, depending on the vocabulary implementation.
    
    Parameters:
    
    input - the text that the user entered
    
    maxResults - the maximum number of terms to be returned
    
    sort - an optional sort parameter, in a format that depends on the actual engine that stores the vocabulary; usually a property name followed by asc or desc; may be null
    
    customFilter - an optional custom filter query to further restrict which terms may be returned, in a format that depends on the actual engine that stores the vocabulary; some vocabularies may not support a filter query; may be null
    
    Returns:
    
    a list of suggestions, possibly empty.
    
    Since:
    
    1.1-rc-1
  - search
```
default List<VocabularyTerm> search(String input,
                                    String category,
                                    int maxResults,
                                    String sort,
                                    String customFilter)
```
    Suggest the terms that best match the user's input, in a specific sub-category of this vocabulary.
    
    Parameters:
    
    input - the text that the user entered
    
    category - the category of terms to search in, one of the supported categories
    
    maxResults - the maximum number of terms to be returned
    
    sort - an optional sort parameter, in a format that depends on the actual engine that stores the vocabulary; usually a property name followed by asc or desc; may be null
    
    customFilter - an optional custom filter query to further restrict which terms may be returned, in a format that depends on the actual engine that stores the vocabulary; some vocabularies may not support a filter query; may be null
    
    Returns:
    
    a list of suggestions, possibly empty.
    
    Since:
    
    1.4
  - count
```
long count(Map<String,?> fieldValues)
```
    Get the number of terms that match a specific query.
    
    Parameters:
    
    fieldValues - a map with term property values that must be matched by the returned terms; the keys are property names, like id, description, is_a, and the values can be either a single value, or a collection of values that can (OR) be matched by the term
    
    Returns:
    
    the number of terms matching the query, or -1 if the query couldn't be run correctly
  - getDistance
```
long getDistance(String fromTermId,
                 String toTermId)
```
    Find the distance between two terms identified by their term identifiers, if this is a structured ontology that supports computing such a distance. The parameters are interchangeable.
    
    Parameters:
    
    fromTermId - the identifier of the term that is considered the start point
    
    toTermId - the identifier of the term that is considered the end point
    
    Returns:
    
    the minimum number of edges that connect the two terms in the DAG representing the ontology, and -1 if this is an unstructured vocabulary, the terms are not connected, or if at least one of the identifiers is invalid
    
    See Also:
    
    getDistance(VocabularyTerm, VocabularyTerm)
  - getDistance
```
long getDistance(VocabularyTerm fromTerm,
                 VocabularyTerm toTerm)
```
    Find the distance between two terms, if this is a structured ontology that supports computing such a distance. The parameters are interchangeable.
    
    Parameters:
    
    fromTerm - the term that is considered the start point
    
    toTerm - the term that is considered the end point
    
    Returns:
    
    the minimum number of edges that connect the two terms in the DAG representing the ontology, and -1 if this is an unstructured vocabulary, the terms are not connected, or if at least one of the terms is null
  - getIdentifier
```
String getIdentifier()
```
    The identifier of the vocabulary, used internally to differentiate between different vocabularies and different implementations of the same vocabulary.
    
    Returns:
    
    a simple string, for example hpo, omim, or hgncRemote
    
    Since:
    
    1.3M1
  - getName
```
String getName()
```
    The official name of the vocabulary.
    
    Returns:
    
    a string, for example The Human Phenotype Ontology
    
    Since:
    
    1.3M1
  - getAliases
```
Set<String> getAliases()
```
    A vocabulary has an official name, but it can also have other aliases, for example the Human Phenotype Ontology is known both as HP, which is the official prefix for its terms, HPO, which is its acronym, or the lowercase hpo.
    
    Returns:
    
    a set of identifiers which can be used to reference this vocabulary, including the official name
  - getSupportedCategories
```
default Collection<String> getSupportedCategories()
```
    Reports the categories of terms supported by this vocabulary. For every supported category, the search(String, String, int, String, String) method will be called whenever suggestions/matches for a specify type of terms are requested. If no categories are reported as supported, then this vocabulary must be used explicitly to search for terms.
    
    Returns:
    
    a collection of vocabulary term categories, as short names, for example disorder, feature , or feature-qualifier; may be empty
    
    Since:
    
    1.4
  - size
```
long size()
```
    Get the size (i.e. total number of terms) in this vocabulary.
    
    Returns:
    
    the number of terms in the vocabulary
  - reindex
```
int reindex(String sourceUrl)
```
    Reindex the whole vocabulary, fetching the source from the specified location.
    
    Parameters:
    
    sourceUrl - the URL to be indexed
    
    Returns:
    
    0 if the indexing succeeded, 1 if writing to the Solr server failed, 2 if the specified URL is invalid
  - getDefaultSourceLocation
```
String getDefaultSourceLocation()
```
    Get the default location where the sources for this vocabulary can be fetched from.
    
    Returns:
    
    the string containing the default URL for the vocabulary source
  - getSourceLocation
```
default String getSourceLocation()
```
    Get the location where the sources for this vocabulary can be fetched from.
    
    Returns:
    
    the string containing the URL for the vocabulary source
    
    Since:
    
    1.4
  - getVersion
```
String getVersion()
```
    Get the available version of the vocabulary.
    
    Returns:
    
    a version identifier, or null if the version cannot be determined
  - getWebsite
```
String getWebsite()
```
    Get the website url for the vocabulary.
    
    Returns:
    
    a String representation of the url for the vocabulary website.
  - getCitation
```
String getCitation()
```
    Get the citation for the vocabulary.
    
    Returns:
    
    the string containing the citation for the vocabulary.
  - getExtensions
```
List<VocabularyExtension> getExtensions()
```
    Get the list of VocabularyExtensions that extend a base vocabulary with additional annotations.
    
    Returns:
    
    the list of vocabulary extensions.

Interface Vocabulary

Method Summary

Method Detail

getTerm

getTerms

search

search

search

search

search

count

getDistance

getDistance

getIdentifier

getName

getAliases

getSupportedCategories

size

reindex

getDefaultSourceLocation

getSourceLocation

getVersion

getWebsite

getCitation

getExtensions