NIH | National Cancer Institute | NCI Wiki  

Introduction

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

Interface

org.lexevs.cts2.query.ConceptDomainQueryOperation is the main interface for all the queries against Concept Domain. This interface can be accessed using main LexEVSCTS2 interface, like:

org.lexevs.cts2.query.ConceptDomainQueryOperation cdQueryOp = new org.lexevs.cts2.LexEvsCTS2Impl().getQueryOperation().getConceptDomainQueryOperation();

Query Functions

Here are the major query functions available using ConceptDomainQueryOperation interface:

getConceptDomainCodingScheme

This function returns detailed concept domain code system.

getConceptDomainCodingScheme(String codeSystemNameOrURI, String codeSystemVersion)

Description:

Gets the concept domain code system.

Input:

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

Output:

org.LexGrid.codingSchemes.CodingScheme - Detailed concept domain Code System

Exception:

org.LexGrid.LexBIG.Exceptions.LBException

Sample Call:

  • Step 1: Instantiate ConceptDomainQueryOperation if it is not done yet:
    org.lexevs.cts2.query.ConceptDomainQueryOperation cdQueryOp = new org.lexevs.cts2.LexEvsCTS2Impl().getQueryOperation().getConceptDomainQueryOperation();
    
  • Step 2: Call getConceptDomainCodingScheme method to get detailed concept domain code system:
    org.LexGrid.codingSchemes.CodingScheme conceptDomainCS = cdQuery.getConceptDomainCodingScheme("conceptDomainCodingScheme", "1.0");
    

getConceptDomainEntity

This function returns detailed concept domain entity.

getConceptDomainEntity(String conceptDomainId, String namespace, String codeSystemNameOrURI, String codeSystemVersion)

Description:

Returns concept domain entity object of the concept domain id.

Input:

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

Output:

org.LexGrid.concepts.Entity - Detailed concept domain entity

Exception:

org.LexGrid.LexBIG.Exceptions.LBException

Sample Call:

  • Step 1: Instantiate ConceptDomainQueryOperation if it is not done yet:
    org.lexevs.cts2.query.ConceptDomainQueryOperation cdQueryOp = new org.lexevs.cts2.LexEvsCTS2Impl().getQueryOperation().getConceptDomainQueryOperation();
    
  • Step 2: Call getConceptDomainEntity method to get detailed concept domain entity:
    org.LexGrid.concepts.Entity conceptDomainEntity = cdQuery.getConceptDomainEntity("ActAdjudicationInformationCode", null, "conceptDomainCodingScheme", "1.0");
    

getConceptDomainEntitisWithName

This function returns all the concept domain entities that matches the concept domain name supplied.

getConceptDomainEntitisWithName(String conceptDomainName, String codeSystemNameOrURI, String codeSystemVersion, SearchDesignationOption option, String matchAlgorithm, String language)

Description:

Returns list of concept domain entities matching the name provided.

Input:

  • java.lang.String conceptDomainName - (Mandatory) Name of a concept domain to match.
  • java.lang.String codeSystemNameOrURI - (Mandatory) Name or URI of code system that contains the concept domain.
  • java.lang.String codeSystemVersion - (Optional) Version of code system that contains the concept domain.
    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 concept domain entities that match supplied concept domain name.

Exception:

org.LexGrid.LexBIG.Exceptions.LBException

Sample Call:

  • Step 1: Instantiate ConceptDomainQueryOperation if it is not done yet:
    org.lexevs.cts2.query.ConceptDomainQueryOperation cdQueryOp = new org.lexevs.cts2.LexEvsCTS2Impl().getQueryOperation().getConceptDomainQueryOperation();
    
  • Step 2: Call getConceptDomainEntitisWithName method by passing the name to search:
    java.util.List<org.LexGrid.concepts.Entity> conceptDomainEntities = cdQuery.getConceptDomainEntitisWithName("code", "conceptDomainCodingScheme", null, null, "subString", null);
    

getConceptDomainCodedNodeSet

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

getConceptDomainCodedNodeSet(String codeSystemNameOrURI, String codeSystemVersion)

Description:

Returns coded node set for concept domain entities.

Input:

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

Output:

org.LexGrid.LexBIG.LexBIGService.CodedNodeSet - Unresolved Concept Domain coded node set.

Exception:

org.LexGrid.LexBIG.Exceptions.LBException

Sample Call:

  • Step 1: Instantiate ConceptDomainQueryOperation if it is not done yet:
    org.lexevs.cts2.query.ConceptDomainQueryOperation cdQueryOp = new org.lexevs.cts2.LexEvsCTS2Impl().getQueryOperation().getConceptDomainQueryOperation();
    
  • Step 2: Call getConceptDomainCodedNodeSet to get Concept Domain Coded node Set:
    CodedNodeSet conceptDomainCNS = cdQuery.getConceptDomainCodedNodeSet("conceptDomainCodingScheme", null);
    
  • Step 3: Apply restrictions to the CNS and resolve:
    conceptDomainCNS.restrictToMatchingProperties(null, new PropertyType[] { PropertyType.PRESENTATION }, "Auto", "startsWith", null);_
    org.LexGrid.LexBIG.DataModel.Core.ResolvedConceptReference[] rcr = conceptDomainCNS.resolveToList(null, null, null, 1).getResolvedConceptReference();
    

listAllConceptDomainEntities

This function returns all the Concept Domain entities found in supplied code system version.

listAllConceptDomainEntities(String codeSystemNameOrURI, String codeSystemVersion)

Description:

Returns all the Concept Domain entities found in supplied code system version.

Input:

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

Output:

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

Exception:

org.LexGrid.LexBIG.Exceptions.LBException

Sample Call:

  • Step 1: Instantiate ConceptDomainQueryOperation if it is not done yet:
    org.lexevs.cts2.query.ConceptDomainQueryOperation cdQueryOp = new org.lexevs.cts2.LexEvsCTS2Impl().getQueryOperation().getConceptDomainQueryOperation();
    
  • Step 2: Call listAllConceptDomainEntities to get all Concept Domains:
    java.util.List<org.LexGrid.concepts.Entity> conceptDomains = cdQuery.listAllConceptDomainEntities("conceptDomainCodingScheme", "1.0");
    

listAllConceptDomainIds

This function is similar to previous one, but instead of returning detailed Concept Domain entities, it just returns identifiers of the concept domain.

listAllConceptDomainIds(String codeSystemNameOrURI, String codeSystemVersion)

Description:

Returns all the Concept Domain identifiers found in supplied code system version.

Input:

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

Output:

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

Exception:

org.LexGrid.LexBIG.Exceptions.LBException

Sample Call:

  • Step 1: Instantiate ConceptDomainQueryOperation if it is not done yet:
    org.lexevs.cts2.query.ConceptDomainQueryOperation cdQueryOp = new org.lexevs.cts2.LexEvsCTS2Impl().getQueryOperation().getConceptDomainQueryOperation();
    
  • Step 2: Call listAllConceptDomainIds to get all Concept Domain identifiers:
    java.util.List<java.lang.String> conceptDomainIds = cdQuery.listAllConceptDomainIds("conceptDomainCodingScheme", "1.0");
    

getConceptDomainBindings

This function returns list of value set definition URIs that are bound to given concept domain.

getConceptDomainBindings(String conceptDomainId, String codeSystemNameOrURI)

Description:

Returns list of value set definition URIs that are bound to given concept domain.

Input:

  • java.lang.String conceptDomainId - (Mandatory) Concept Domain identifier.
  • java.lang.String codeSystemNameOrURI - (Mandatory) Name or URI of code system that contains the concept domain.

Output:

java.util.List<String> - List of Value Set Definition URIs that are bound to supplied concept domain.

Exception:

org.LexGrid.LexBIG.Exceptions.LBException

Sample Call:

  • Step 1: Instantiate ConceptDomainQueryOperation if it is not done yet:
    org.lexevs.cts2.query.ConceptDomainQueryOperation cdQueryOp = new org.lexevs.cts2.LexEvsCTS2Impl().getQueryOperation().getConceptDomainQueryOperation();
    
  • Step 2: Call getConceptDomainBindings to get all Concept Domain identifiers:
    java.util.List<java.lang.String> valueSetURIS = cdQuery.getConceptDomainBindings("AcknowledgementDetailCode", "conceptDomainCodingScheme");
    

isEntityInConceptDomain

This function determines whether the supplied coded concept exists in a code system in use for the specified concept domain, optionally within specific usage contexts. Returns true if a coded concept is an element of a value set expansion bound to the provided concept domain, or bound to both concept domain and usage context.

isEntityInConceptDomain(String conceptDomainId, String namespace, String codeSystemNameOrURI, String entityCode, AbsoluteCodingSchemeVersionReferenceList codingSchemeVersionList, List<String> usageContext)

Description:

Determines whether the supplied coded concept exists in a code system in use for the specified concept domain, optionally within specific usage contexts. Returns true if a coded concept is an element of a value set expansion bound to the provided concept domain, or bound to both concept domain and usage context.

Input:

  • java.lang.String conceptDomainId - (Mandatory) Concept Domain identifier.
  • java.lang.String namespace - (Optional) Concept Domain namespace.
  • java.lang.String codeSystemNameOrURI - (Mandatory) Name or URI of code system that contains the concept domain.
  • java.lang.String entityCode - (Mandatory) Entity code to check if it participates in concept domain.
    org.LexGrid.LexBIG.DataModel.Collections.AbsoluteCodingSchemeVersionReferenceList codingSchemeVersionList - (Mandatory) List of code system URI and version that contains the entity code and to be used to resolve.
  • java.util.List<java.lang.String> usageContext - (Optional) List of usage context.

Output:

java.util.List<String> - List of Value Set Definition URIs that are bound to concept domain (and usageContext) and that contains given entity code.

Exception:

org.LexGrid.LexBIG.Exceptions.LBException

Sample Call:

  • Step 1: Instantiate ConceptDomainQueryOperation if it is not done yet:
    org.lexevs.cts2.query.ConceptDomainQueryOperation cdQueryOp = new org.lexevs.cts2.LexEvsCTS2Impl().getQueryOperation().getConceptDomainQueryOperation();
    
  • Step 2: Populate CodingSchemeVersionList that contains the entity code:
    org.LexGrid.LexBIG.DataModel.Collections.AbsoluteCodingSchemeVersionReferenceList codingSchemeVersionList = new org.LexGrid.LexBIG.DataModel.Collections.AbsoluteCodingSchemeVersionReferenceList();
    org.LexGrid.LexBIG.DataModel.Collections.AbsoluteCodingSchemeVersionReference codingSchemeVersion = new org.LexGrid.LexBIG.DataModel.Collections.AbsoluteCodingSchemeVersionReference();
    codingSchemeVersion.setCodingSchemeURN("urn:oid:cts:1.1.1");
    codingSchemeVersion.setCodingSchemeVersion("1.0");
    codingSchemeVersionList.addAbsoluteCodingSchemeVersionReference(codingSchemeVersion);
    
  • Step 3: Call isEntityInConceptDomain to get all value set definition URIs that are bound to concept domain and contains given entity code:
    java.util.List<java.lang.String> valueSetURIS = cdQuery.isEntityInConceptDomain("Automobiles", null, "conceptDomainCodingScheme", "GM", codingSchemeVersionList, null);