NIH | National Cancer Institute | NCI Wiki  

Introduction

LexEVS CTS2 Usage Context Query API provides capability to query Usage Context available in the system and also to query the binding between Value Set and Concept Domain in conjunction with Usage Context. In LexEVS, the Usage Context is essentially an entity of type 'usageContext' in a code system version. Using LexEVS CTS 2 Authoring or Loader interfaces, you could create a Code System specially for Usage Context entities, but this is not necessary, but will be convenient to have Usage Context entries in specific code system(s).

Interface

org.lexevs.cts2.query.UsageContextQueryOperation is the main interface for all the queries against Usage Context. This interface can be accessed using main LexEVSCTS2 interface, like:

org.lexevs.cts2.query.UsageContextQueryOperation cdQueryOp = new org.lexevs.cts2.LexEvsCTS2Impl().getQueryOperation().getUsageContextQueryOperation();

Query Functions

Here are the major query functions available using UsageContextQueryOperation interface:

getUsageContextCodingScheme

This function returns detailed usage context code system.

getUsageContextCodingScheme(String codeSystemNameOrURI, String codeSystemVersion)

Description:

Gets the usage context code system.

Input:

  • java.lang.String codeSystemNameOrURI - (Mandatory) Name or URI of the code system that contains usage context entities.
  • java.lang.String codeSystemVersion - (Optional) Version of of the code system that contains usage context entities.

Output:

org.LexGrid.codingSchemes.CodingScheme - Detailed usage context Code System

Exception:

org.LexGrid.LexBIG.Exceptions.LBException

Sample Call:

  • Step 1: Instantiate UsageContextQueryOperation if it is not done yet:
    org.lexevs.cts2.query.UsageContextQueryOperation ucQueryOp = new org.lexevs.cts2.LexEvsCTS2Impl().getQueryOperation().getUsageContextQueryOperation();
    
  • Step 2: Call getUsageContextCodingScheme method to get detailed Usage Context code system:
    org.LexGrid.codingSchemes.CodingScheme usageContextCS = ucQuery.getUsageContextCodingScheme("usageContextCodingScheme", "1.0"); 
    

getUsageContextEntity

This function returns detailed Usage Context entity.

getUsageContextEntity(String usageContextId, String namespace, String codeSystemNameOrURI, String codeSystemVersion)

Description:

Returns Usage Context entity object.

Input:

  • java.lang.String usageContextId - (Mandatory) ID of a Usage Context.
  • java.lang.String namespace - (Optional) Namespace of a Usage Context.
  • java.lang.String codeSystemNameOrURI - (Mandatory) Name or URI of code system that contains the Usage Context.
  • java.lang.String codeSystemVersion - (Optional) Version of code system that contains the Usage Context.

Output:

org.LexGrid.concepts.Entity - Detailed Usage Context Entity

Exception:

org.LexGrid.LexBIG.Exceptions.LBException

Sample Call:

  • Step 1: Instantiate UsageContextQueryOperation if it is not done yet:
    org.lexevs.cts2.query.UsageContextQueryOperation ucQueryOp = new org.lexevs.cts2.LexEvsCTS2Impl().getQueryOperation().getUsageContextQueryOperation();
    
  • Step 2: Call getUsageContextEntity method to get detailed Usage Context Entity:
    org.LexGrid.concepts.Entity usageContextEntity = ucQuery.getUsageContextEntity("ActAdjudicationInformationCode", null, "usageContextCodingScheme", "1.0"); |
    

getUsageContextEntitisWithName

This function returns all the Usage Context entities that matches the name supplied.

getUsageContextEntitisWithName(String usageContextName, String codeSystemNameOrURI, String codeSystemVersion, SearchDesignationOption option, String matchAlgorithm, String language)

Description:

Returns list of Usage Context entities matching the name provided.

Input:

  • java.lang.String usageContextName - (Mandatory) Name of a Usage Context to match.
  • java.lang.String codeSystemNameOrURI - (Mandatory) Name or URI of code system that contains the Usage Context.
  • java.lang.String codeSystemVersion - (Optional) Version of code system that contains the Usage Context.
  • org.LexGrid.LexBIG.LexBIGService.CodedNodeSet.SearchDesignationOption option - (Optional) Indicates the designations to search (one of the enumerated type SearchDesignationOption).
  • java.lang.String matchAlgorithm - (Mandatory) Local name of the match algorithm - possible algorithms are returned in LexEVSCTS2.getSupportedSearchAlgorithmNames().
  • java.lang.String language - (Optional) Language of search string. If missing, uses the default language specified in the context.

Output:

java.util.List<org.LexGrid.concepts.Entity> - List of detailed Usage Context entities that match supplied name.

Exception:

org.LexGrid.LexBIG.Exceptions.LBException

Sample Call:

  • Step 1: Instantiate UsageContextQueryOperation if it is not done yet:
    org.lexevs.cts2.query.UsageContextQueryOperation ucQueryOp = new org.lexevs.cts2.LexEvsCTS2Impl().getQueryOperation().getUsageContextQueryOperation();
    
  • Step 2: Call getUsageContextEntitisWithName method by passing the name to search:
    java.util.List<org.LexGrid.concepts.Entity> usageContextEntities = ucQuery.getUsageContextEntitisWithName("code", "usageContextCodingScheme", null, null, "subString", null); |
    

getUsageContextCodedNodeSet

This is a helper function that returns Coded Node Set(CNS) for Usage Context entities. Further restrictions like, matchingDesignation, Status, Properties, etc., can be applied on this CNS and than resolved.

getUsageContextCodedNodeSet(String codeSystemNameOrURI, String codeSystemVersion)

Description:

Returns coded node set for UsageContext entities.

Input:

  • java.lang.String codeSystemNameOrURI - (Mandatory) Name or URI of code system that contains the Usage Context.
  • java.lang.String codeSystemVersion - (Optional) Version of code system that contains the Usage Context.

Output:

org.LexGrid.LexBIG.LexBIGService.CodedNodeSet - Unresolved Usage Context coded node set.

Exception:

org.LexGrid.LexBIG.Exceptions.LBException

Sample Call:

  • Step 1: Instantiate UsageContextQueryOperation if it is not done yet:
    org.lexevs.cts2.query.UsageContextQueryOperation ucQueryOp = new org.lexevs.cts2.LexEvsCTS2Impl().getQueryOperation().getUsageContextQueryOperation();
    
  • Step 2: Call getUsageContextCodedNodeSet to get Usage Context Coded node Set:
    CodedNodeSet usageContextCNS = ucQuery.getUsageContextCodedNodeSet("usageContextCodingScheme", null);
    
  • Step 3: Apply restrictions to the CNS and resolve:
    usageContextCNS.restrictToMatchingProperties(null, new PropertyType[] { PropertyType.PRESENTATION }, "Auto", "startsWith", null);
    org.LexGrid.LexBIG.DataModel.Core.ResolvedConceptReference[] rcr = usageContextCNS.resolveToList(null, null, null, 1).getResolvedConceptReference(); 
    

listAllUsageContextEntities

This function returns all the Usage Context entities found in supplied code system version.

listAllUsageContextEntities(String codeSystemNameOrURI, String codeSystemVersion)

Description:

Returns all the Usage Context entities found in supplied code system version.

Input:

  • java.lang.String codeSystemNameOrURI - (Mandatory) Name or URI of code system that contains the Usage Context.
  • java.lang.String codeSystemVersion - (Optional) Version of code system that contains the Usage Context.

Output:

java.util.List<org.LexGrid.concepts.Entity> - List of Usage Context entities found in supplied code system version.

Exception:

org.LexGrid.LexBIG.Exceptions.LBException

Sample Call:

  • Step 1: Instantiate UsageContextQueryOperation if it is not done yet:
    org.lexevs.cts2.query.UsageContextQueryOperation ucQueryOp = new org.lexevs.cts2.LexEvsCTS2Impl().getQueryOperation().getUsageContextQueryOperation();
    
  • Step 2: Call listAllUsageContextEntities to get all Usage Context entities:
    java.util.List<org.LexGrid.concepts.Entity> usageContexts = ucQuery.listAllUsageContextEntities("usageContextCodingScheme", "1.0"); 
    

listAllUsageContextIds

This function is similar to previous one, but instead of returning detailed Usage Context entities, it just returns identifiers of the Usage Context.

listAllUsageContextIds(String codeSystemNameOrURI, String codeSystemVersion)

Description:

Returns all the Usage Context identifiers found in supplied code system version.

Input:

  • java.lang.String codeSystemNameOrURI - (Mandatory) Name or URI of code system that contains the Usage Context.
  • java.lang.String codeSystemVersion - (Optional) Version of code system that contains the Usage Context.

Output:

java.util.List<String> - List of Usage Context identifiers found in supplied code system version.

Exception:

org.LexGrid.LexBIG.Exceptions.LBException

Sample Call:

  • Step 1: Instantiate UsageContextQueryOperation if it is not done yet:
    org.lexevs.cts2.query.UsageContextQueryOperation ucQueryOp = new org.lexevs.cts2.LexEvsCTS2Impl().getQueryOperation().getUsageContextQueryOperation();
    
  • Step 2: Call listAllUsageContextIds to get all Usage Context identifiers:
    java.util.List<java.lang.String> usageContextIds = ucQuery.listAllUsageContextIds("usageContextCodingScheme", "1.0");