NIH | National Cancer Institute | NCI Wiki  

Introduction

LexEVS CTS2 Value Set Query API provides capability to query Value Sets available in the system and also to query the binding between Value Set and Concept Domain.

Interface

org.lexevs.cts2.query.ValueSetQueryOperation is the main interface for all the queries against Value Set. This interface can be accessed using main LexEVSCTS2 interface, like:

org.lexevs.cts2.query.ValueSetQueryOperation vsQueryOp = new org.lexevs.cts2.LexEvsCTS2Impl().getQueryOperation().getValueSetQueryOperation();

Query Functions

Here are the major query functions available using ValueSetQueryOperation interface:

listValueSets

This function returns value sets that are available in the system. Optionally, the list can be filtered by providing the criteria as input parameters.

listValueSets(String codeSystemId, String conceptDomainId, String usageContextId, String codeSystemURI, SortOption sortOption)

Description:

Lists the value sets that are available to the CTS 2 service.

Input:

  • java.lang.String codeSystemId - (Optional) code system id the value set should reference.
  • java.lang.String conceptDomainId - (Optional) conceptDomain the value set should be bound to.
  • java.lang.String usageContextId - (Optional) usage context in which the value set can be used.
  • java.lang.String codeSystemURI - (Optional) URI of code system the codeSystemId or conceptDomainId or usageContextId belongs to.
    org.LexGrid.LexBIG.DataModel.InterfaceElements.SortOption sortOption - (Optional) to sort the return list of value set identifiers in Ascending or Descending.

Output:

java.util.List<java.lang.String> - List of value set identifiers

Exception:

org.LexGrid.LexBIG.Exceptions.LBException

Sample Call:

  • Step 1: Instantiate ValueSetQueryOperation if it is not done yet:
    org.lexevs.cts2.query.ValueSetQueryOperation vsQueryOp = new org.lexevs.cts2.LexEvsCTS2Impl().getQueryOperation().getValueSetQueryOperation();
    
  • Step 2: Set SortOption to sort the list in ascending order:
    SortOption sortOption = new SortOption();
    sortOption.setAscending(true);
    
  • Step 3: Call listValueSets method by passing any filter criteria:
    java.util.List<java.lang.String> valueSetList = vsQuery.listValueSets("Automobiles", "Autos", null, null, sortOption); 
    

listAllValueSets

This function returns all the value sets that are available in the system.

listAllValueSets(SortOption sortOption)

Description:

Lists all the value sets that are available to the CTS 2 service.

Input:

org.LexGrid.LexBIG.DataModel.InterfaceElements.SortOption sortOption - (Optional) to sort the return list of value set identifiers in Ascending or Descending.

Output:

java.util.List<java.lang.String> - List of value set identifiers

Exception:

org.LexGrid.LexBIG.Exceptions.LBException

Sample Call:

  • Step 1: Instantiate ValueSetQueryOperation if it is not done yet:
    org.lexevs.cts2.query.ValueSetQueryOperation vsQueryOp = new org.lexevs.cts2.LexEvsCTS2Impl().getQueryOperation().getValueSetQueryOperation();
    
  • Step 2: Set SortOption to sort the list in ascending order:
    SortOption sortOption = new SortOption();
    sortOption.setAscending(true);
    
  • Step 3: Call listAllValueSets method to get all the value sets loaded in the system:
    java.util.List<java.lang.String> valueSetList = vsQuery.listAllValueSets(sortOption); 
    

getValueSetDetails

This function returns detailed information about the value set.

getValueSetDetails(String valueSetId, String valueSetVersion)

Description:

Returns detailed information about the value set.

Input:

  • java.lang.String valueSetId - (Mandatory) Id of an value set.
  • java.lang.String valueSetVersion - (Optional) Version of an value set.

Output:

org.LexGrid.valueSets.ValueSetDefinition - Value Set Definition object with the details of value set

Exception:

org.LexGrid.LexBIG.Exceptions.LBException

Sample Call:

  • Step 1: Instantiate ValueSetQueryOperation if it is not done yet:
    org.lexevs.cts2.query.ValueSetQueryOperation vsQueryOp = new org.lexevs.cts2.LexEvsCTS2Impl().getQueryOperation().getValueSetQueryOperation();
    
  • Step 2: Call getValueSetDetails method by providing value set id:
    org.LexGrid.valueSets.ValueSetDefinition vsd = vsQuery.getValueSetDetails("SRITEST:AUTO:AllDomesticButGM", null);
    

listValueSetContents

This function returns the contents of value set (expanded value set).

listValueSetContents(String valueSetId, String valueSetVersion, AbsoluteCodingSchemeVersionReferenceList csVersionList, String versionTag, SortOption sortOption)

Description:

Returns the contents of value set (expanded value set).

Input:

  • java.lang.String valueSetId - (Mandatory) Id of an value set.
  • java.lang.String valueSetVersion - (Optional) Version of an value set.
  • jorg.LexGrid.LexBIG.DataModel.Collections.AbsoluteCodingSchemeVersionReferenceList csVersionList - (Optional) Code System Version reference list to be used to resolve value set.
  • java.lang.String versionTag - (Optional) The tag (e.g. "devel", "production", ...) to be used to determine which code system to be used.
  • org.LexGrid.LexBIG.DataModel.InterfaceElements.SortOption sortOption - (Optional) to sort the contents of value set in Ascending or Descending.

Output:

org.lexgrid.valuesets.dto.ResolvedValueSetDefinition - A resolved Value Set definition containing the code system version reference list that was used to resolve the value set and an iterator for resolved concepts.

Exception:

org.LexGrid.LexBIG.Exceptions.LBException

Sample Call:

  • Step 1: Instantiate ValueSetQueryOperation if it is not done yet:
    org.lexevs.cts2.query.ValueSetQueryOperation vsQueryOp = new org.lexevs.cts2.LexEvsCTS2Impl().getQueryOperation().getValueSetQueryOperation();
    
  • Step 2: Populate the Code System Version reference list to be used for resolving the value set definition:
    AbsoluteCodingSchemeVersionReference acsvr = new AbsoluteCodingSchemeVersionReference();
    acsvr.setCodingSchemeURN("urn:oid:11.11.0.1");
    acsvr.setCodingSchemeVersion("1.0");
    AbsoluteCodingSchemeVersionReferenceList csList = new AbsoluteCodingSchemeVersionReferenceList();
    csList.addAbsoluteCodingSchemeVersionReference(acsvr);
    
  • Step 3: Call listValueSetContents method by providing value set id and code system version list:
    ResolvedValueSetDefinition vsdResolved = vsQueryop.listValueSetContents("SRITEST:AUTO:DomasticLeafOnly", null, csList, null, null); |
    

checkValueSetSubsumption

This function determines whether one of the two supplied value sets subsumes the other.

checkValueSetSubsumption(String childValueSetId, String childValueSetVersion, String parentValueSetId, String parentValueSetVersion, AbsoluteCodingSchemeVersionReferenceList csVersionList, String versionTag)

Description:

Determine whether one of the two supplied value sets subsumes the other.

Input:

  • java.lang.String childValueSetId - (Mandatory) Id of a child value set.
  • java.lang.String childValueSetVersion - (Optional) Version of a child value set.
  • java.lang.String parentValueSetId - (Mandatory) Id of a parent value set.
  • java.lang.String parentValueSetVersion - (Optional) Version of a parent value set.
  • jorg.LexGrid.LexBIG.DataModel.Collections.AbsoluteCodingSchemeVersionReferenceList csVersionList - (Optional) Code System Version reference list to be used to resolve both value sets.
  • java.lang.String versionTag - (Optional) The tag (e.g. "devel", "production", ...) to be used to determine which code system to be used.

Output:

boolean - True; if childValueSet subsumes parentValueSet. False; otherwise.

Exception:

org.LexGrid.LexBIG.Exceptions.LBException

Sample Call:

  • Step 1: Instantiate ValueSetQueryOperation if it is not done yet:
    org.lexevs.cts2.query.ValueSetQueryOperation vsQueryOp = new org.lexevs.cts2.LexEvsCTS2Impl().getQueryOperation().getValueSetQueryOperation();
    
  • Step 2: Populate the Code System Version reference list to be used for resolving the value set definitions:
    AbsoluteCodingSchemeVersionReference acsvr = new AbsoluteCodingSchemeVersionReference();
    acsvr.setCodingSchemeURN("urn:oid:11.11.0.1");
    acsvr.setCodingSchemeVersion("1.0");
    AbsoluteCodingSchemeVersionReferenceList csList = new AbsoluteCodingSchemeVersionReferenceList();
    csList.addAbsoluteCodingSchemeVersionReference(acsvr);
    
  • Step 3: Call checkValueSetSubsumption method by providing child and parent value set id and code system version list:
    boolean subsume = vsQueryop.checkValueSetSubsumption("SRITEST:AUTO:DomasticLeafOnly", null, "SRITEST:AUTO:EveryThing", null, csList, null); |
    

checkConceptValueSetMembership

This function determines whether the supplied coded concept exists in the supplied value set.

checkConceptValueSetMembership(String conceptCode, URI entityCodeNamespace, AbsoluteCodingSchemeVersionReference codeSystemAndVersion, String valueSetId, String valueSetVersion, String versionTag)

Description:

Determine whether the supplied coded concept exists in the supplied value set.

Input:

  • java.lang.String conceptCode - (Mandatory) Coded concept to check membership.
  • java.net.URI entityCodeNamespace - (Optional) Namespace of coded concept.
  • jorg.LexGrid.LexBIG.DataModel.Collections.AbsoluteCodingSchemeVersionReference codeSystemAndVersion - (Optional) Code System Version that contains the coded concept and to be used to resolve value set.
  • java.lang.String valueSetId - (Mandatory) Id of a value set.
  • java.lang.String valueSetVersion - (Optional) Version of a value set.
  • java.lang.String versionTag - (Optional) The tag (e.g. "devel", "production", ...) to be used to determine which code system to be used.

Output:

boolean - True; if coded concept exists in value set. False; otherwise.

Exception:

org.LexGrid.LexBIG.Exceptions.LBException

Sample Call:

  • Step 1: Instantiate ValueSetQueryOperation if it is not done yet:
    org.lexevs.cts2.query.ValueSetQueryOperation vsQueryOp = new org.lexevs.cts2.LexEvsCTS2Impl().getQueryOperation().getValueSetQueryOperation();
    
  • Step 2: Populate the Code System Version reference that contains the coded concept and to be used for resolving the value set definition:
    AbsoluteCodingSchemeVersionReference acsvr = new AbsoluteCodingSchemeVersionReference();
    acsvr.setCodingSchemeURN("urn:oid:11.11.0.1");
    acsvr.setCodingSchemeVersion("1.0");
    
  • Step 3: Call checkConceptValueSetMembership method by providing coded concept, code system version and value set id:
    boolean member = vsQueryop.checkConceptValueSetMembership("GMC", new URI("Automobiles"), acsvr, "SRITEST:AUTO:GM", null, null); |
    

listValueSetsWithConceptCode

This function returns all the value set identifiers that contains supplied concept code.

listValueSetsWithConceptCode(String conceptCode, URI entityCodeNamespace, AbsoluteCodingSchemeVersionReferenceList csVersionList, String versionTag)

Description:

Returns all the value set identifiers that contains supplied concept code.

Input:

  • java.lang.String conceptCode - (Mandatory) Coded concept to check membership.
  • java.net.URI entityCodeNamespace - (Optional) Namespace of coded concept.
  • jorg.LexGrid.LexBIG.DataModel.Collections.AbsoluteCodingSchemeVersionReferenceList csVersionList - (Optional) Code System Version List that contains the coded concept and to be used to resolve value set.
  • java.lang.String versionTag - (Optional) The tag (e.g. "devel", "production", ...) to be used to determine which code system to be used.

Output:

java.util.List<java.lang.String> - List of value set identifiers that contains the supplied concept code.

Exception:

org.LexGrid.LexBIG.Exceptions.LBException

Sample Call:

  • Step 1: Instantiate ValueSetQueryOperation if it is not done yet:
    org.lexevs.cts2.query.ValueSetQueryOperation vsQueryOp = new org.lexevs.cts2.LexEvsCTS2Impl().getQueryOperation().getValueSetQueryOperation();
    
  • Step 2: Populate the Code System Version reference list to be used for resolving the value sets:
    AbsoluteCodingSchemeVersionReference acsvr = new AbsoluteCodingSchemeVersionReference();
    acsvr.setCodingSchemeURN("urn:oid:11.11.0.1");
    acsvr.setCodingSchemeVersion("1.0");
    AbsoluteCodingSchemeVersionReferenceList csList = new AbsoluteCodingSchemeVersionReferenceList();
    csList.addAbsoluteCodingSchemeVersionReference(acsvr);
    
  • Step 3: Call listValueSetsWithConceptCode method by providing coded concept and code system version list:
    List<String> valueSetIdList = vsQueryop.listValueSetsWithConceptCode("GMC", new URI("Automobiles"), csList, null);