fhirsmith 0.17.0 → 0.18.0

package/tx/cs/cs-icf.js

@@ -0,0 +1,418 @@
+/**
+ * ICF (http://hl7.org/fhir/sid/icf).
+ *
+ * The content is an ordinary CodeSystem resource (fhir.tx.support has 2001a and 2017a), so
+ * this extends FhirCodeSystemProvider rather than being a factory with its own data:
+ * FhirCodeSystemProvider.create() picks this class by url.
+ *
+ * What ICF adds is a grammar: a category may be followed by '.' and qualifier digits, one per
+ * position, and what the positions are depends on the component - the first letter of the code
+ * (see QUALIFIERS):
+ *   b  body functions             extent
+ *   s  body structures            extent, nature, localization
+ *   d  activities/participation   performance, capacity, then optionally capacity with
+ *                                 assistance and performance without assistance
+ *   e  environmental factors      not supported yet (barriers '.', facilitators '+')
+ * Each digit must be a value of its position's scale, which the code system carries as the
+ * concepts q1-n (extent of impairment), q2-n (nature), q3-n (localization) and q4-n (extent of
+ * problem), under the group concepts q1..q4. A position cannot be omitted; 8 (not specified) is
+ * what fills it, and 8 says nothing in the display. Each position is reported by $lookup as the
+ * property named in QUALIFIERS.
+ *
+ * Qualifiers are not mandatory at the code system level: a plain category is still a valid
+ * code. Qualified codes cannot be enumerated, so the code system is not closed.
+ *
+ * Value sets control qualifiers with filters:
+ *   <qualifier property> exists true|false - the qualifier is required / not allowed. 8 (not
+ *       specified) counts as absent, so it never satisfies exists = true, and always satisfies
+ *       exists = false. A qualifier the code's component does not have is absent
+ *   qualified  =  true|false  - qualified codes only / no qualified codes at all (b1100.888
+ *       is qualified, though it says nothing)
+ * These combine with the other filters in an include as usual. A qualified code is in any
+ * other filter's results when its category is.
+ */
+
+const { CodeSystem } = require('../library/codesystem');
+const { Issue } = require('../library/operation-outcome');
+const { FhirCodeSystemProvider, FhirCodeSystemProviderContext, FhirCodeSystemProviderFilterContext } = require('./cs-cs');
+
+/**
+ * The qualifier positions of each component: the property that reports the qualifier, the
+ * scale (group concept) its values come from, and the label that introduces its value in the
+ * display (none for b and s, whose qualifiers say what they are).
+ */
+const QUALIFIERS = {
+  b: [
+    { property: 'extent', scale: 'q1' }
+  ],
+  s: [
+    { property: 'extent', scale: 'q1' },
+    { property: 'nature', scale: 'q2' },
+    { property: 'localization', scale: 'q3' }
+  ],
+  d: [
+    { property: 'performance', scale: 'q4', label: 'performance' },
+    { property: 'capacity', scale: 'q4', label: 'capacity' },
+    { property: 'capacity-with-assistance', scale: 'q4', label: 'capacity with assistance' },
+    { property: 'performance-without-assistance', scale: 'q4', label: 'performance without assistance' }
+  ],
+  e: null // barriers and facilitators: not supported yet
+};
+
+const COMPONENT_NAMES = { b: 'body functions', s: 'body structures', d: 'activities and participation', e: 'environmental factors' };
+const COMPONENT_CODES = { b: 'a body functions (b) code', s: 'a body structures (s) code', d: 'an activities and participation (d) code' };
+
+const QUALIFIER_PROPERTIES = new Set(Object.values(QUALIFIERS).filter(q => q).flatMap(q => q.map(p => p.property)));
+
+/**
+ * A category with qualifiers. code and concept are the category's, so whatever is inherited
+ * from FhirCodeSystemProvider describes the category; qualifiedCode is the code as a whole.
+ */
+class IcfQualifiedContext extends FhirCodeSystemProviderContext {
+  /**
+   * @param {string} qualifiedCode - e.g. s7300.183
+   * @param {Object} concept - the category's concept
+   * @param {{position: number, digit: string, code: string, concept: Object, property: string}[]} qualifiers
+   */
+  constructor(qualifiedCode, concept, qualifiers) {
+    super(concept.code, concept);
+    this.qualifiedCode = qualifiedCode;
+    this.qualifiers = qualifiers;
+  }
+}
+
+/**
+ * The result of a qualifier filter. test() decides membership for a located code, qualified or
+ * not. concepts (what iteration walks) holds only the plain categories that pass, since
+ * qualified codes cannot be listed; closesQualified marks the one filter (qualified = false)
+ * that admits no qualified code, so an include with it is closed again.
+ */
+class IcfQualifierFilter extends FhirCodeSystemProviderFilterContext {
+  constructor(test, closesQualified) {
+    super();
+    this.test = test;
+    this.closesQualified = closesQualified;
+  }
+}
+
+function propertyValue(concept, code) {
+  const p = (concept.property || []).find(p => p.code === code);
+  return p ? (p.valueCode ?? p.valueBoolean ?? p.valueString) : undefined;
+}
+
+class IcfCodeSystemProvider extends FhirCodeSystemProvider {
+
+  /** Qualified codes are a grammar: they cannot all be listed. */
+  isNotClosed() {
+    return true;
+  }
+
+  // -- locating -------------------------------------------------------------------------
+
+  /**
+   * A code in the code system, or a selectable category followed by '.' and one to three
+   * qualifier digits. An unknown category is a plain miss (no message); a known category
+   * with bad qualifiers says what is wrong with them.
+   */
+  async locate(code) {
+    const base = await super.locate(code);
+    if (base.context || typeof code !== 'string') {
+      return base;
+    }
+    const dot = code.indexOf('.');
+    if (dot <= 0) {
+      return base;
+    }
+    const stemCode = code.substring(0, dot);
+    const digits = code.substring(dot + 1);
+    const stem = this.codeSystem.getConceptByCode(stemCode);
+    if (!stem) {
+      return { context: null, message: undefined };
+    }
+    if (!this.#isQualifiable(stem)) {
+      return { context: null, message: `The ICF code '${code}' is not valid: qualifiers can only follow a selectable ICF category, and '${stemCode}' is not one` };
+    }
+    const component = stemCode[0];
+    const positions = QUALIFIERS[component];
+    if (!positions) {
+      return { context: null, message: `The ICF code '${code}' is not valid: qualifiers on ${COMPONENT_NAMES[component] || 'these'} codes are not supported` };
+    }
+    const names = positions.map(q => q.property).join(', ');
+    if (!new RegExp(`^[0-9]{1,${positions.length}}$`).test(digits)) {
+      return { context: null, message: positions.length === 1
+        ? `The ICF code '${code}' is not valid: ${COMPONENT_CODES[component]} takes one qualifier digit after the '.' (${names})`
+        : `The ICF code '${code}' is not valid: ${COMPONENT_CODES[component]} takes 1 to ${positions.length} qualifier digits after the '.' (${names})` };
+    }
+    const qualifiers = [];
+    for (let i = 0; i < digits.length; i++) {
+      const position = positions[i];
+      const concept = this.codeSystem.getConceptByCode(position.scale + '-' + digits[i]);
+      if (!concept) {
+        return { context: null, message: `The ICF code '${code}' is not valid: '${digits[i]}' is not a valid value for qualifier ${i + 1} (${position.property})` };
+      }
+      qualifiers.push({ position: i + 1, digit: digits[i], code: concept.code, concept, property: position.property, label: position.label });
+    }
+    return { context: new IcfQualifiedContext(code, stem, qualifiers), message: null };
+  }
+
+  /** A selectable primary category: not a heading, and not a qualifier value. */
+  #isQualifiable(concept) {
+    const kind = propertyValue(concept, 'kind');
+    if (kind !== undefined && kind !== 'primary') {
+      return false;
+    }
+    return propertyValue(concept, 'notSelectable') !== true;
+  }
+
+  async #resolve(context) {
+    if (typeof context === 'string') {
+      const r = await this.locate(context);
+      if (!r.context) {
+        throw new Error(r.message ? r.message : `Code '${context}' not found in CodeSystem '${this.system()}'`);
+      }
+      return r.context;
+    }
+    return context || null;
+  }
+
+  // -- concept information --------------------------------------------------------------
+
+  async code(context) {
+    const ctxt = await this.#resolve(context);
+    return ctxt instanceof IcfQualifiedContext ? ctxt.qualifiedCode : super.code(ctxt);
+  }
+
+  /** The category's display, then the qualifiers' displays, leaving out any 8 (not specified). */
+  async display(context) {
+    const ctxt = await this.#resolve(context);
+    const display = await super.display(ctxt);
+    if (!(ctxt instanceof IcfQualifiedContext)) {
+      return display;
+    }
+    const parts = ctxt.qualifiers.filter(q => q.digit !== '8')
+      .map(q => (q.label ? q.label + ' ' : '') + (q.concept.display || '').trim());
+    return parts.length > 0 ? display + ': ' + parts.join(', ') : display;
+  }
+
+  /** A qualified code has one designation: its display. The category's translations do not describe it. */
+  async designations(context, displays) {
+    const ctxt = await this.#resolve(context);
+    if (!(ctxt instanceof IcfQualifiedContext)) {
+      return super.designations(ctxt, displays);
+    }
+    const lang = this.defaultLanguage ? this.defaultLanguage.toString() : null;
+    displays.addDesignation(true, 'active', lang, CodeSystem.makeUseForDisplay(), await this.display(ctxt));
+  }
+
+  /**
+   * A qualified code has the category's properties, less parent (its parent is the category),
+   * plus one property per qualifier, named by the qualifier's scale (extent, nature, localization).
+   */
+  async properties(context) {
+    const ctxt = await this.#resolve(context);
+    const props = await super.properties(ctxt);
+    if (!(ctxt instanceof IcfQualifiedContext)) {
+      return props;
+    }
+    const result = props.filter(p => p.code !== 'parent');
+    for (const q of ctxt.qualifiers) {
+      result.push({ code: q.property, valueCode: q.code, definition: this.getPropertyDefinition(this.codeSystem.jsonObj, q.property) });
+    }
+    return result;
+  }
+
+  async parent(context) {
+    const ctxt = await this.#resolve(context);
+    return ctxt instanceof IcfQualifiedContext ? ctxt.code : super.parent(ctxt);
+  }
+
+  async sameConcept(a, b) {
+    const ca = await this.#resolve(a);
+    const cb = await this.#resolve(b);
+    if (!ca || !cb) {
+      return false;
+    }
+    return (await this.code(ca)) === (await this.code(cb));
+  }
+
+  /** As for any concept, but a qualified code has no children. */
+  async extendLookup(ctxt, props, params) {
+    const start = params.length;
+    await super.extendLookup(ctxt, props, params);
+    if (ctxt instanceof IcfQualifiedContext) {
+      for (let i = params.length - 1; i >= start; i--) {
+        if (params[i].name === 'property' && params[i].part?.[0]?.valueCode === 'child') {
+          params.splice(i, 1);
+        }
+      }
+    }
+  }
+
+  // -- hierarchy ------------------------------------------------------------------------
+
+  /**
+   * Whether `general` subsumes `specific` or is it: a qualified code sits under its category,
+   * and so under everything the category does. Qualified codes are related only to themselves.
+   */
+  #isA(specific, general) {
+    if (general instanceof IcfQualifiedContext) {
+      return specific instanceof IcfQualifiedContext && specific.qualifiedCode === general.qualifiedCode;
+    }
+    const code = specific.code; // the category, for a qualified code
+    if (code === general.code) {
+      return true;
+    }
+    return this.codeSystem.isDescendantOf(code, general.code);
+  }
+
+  async locateIsA(code, parent, disallowSelf = false) {
+    const codeResult = await this.locate(code);
+    if (!codeResult.context) {
+      return codeResult;
+    }
+    const parentResult = await this.locate(parent);
+    if (!(codeResult.context instanceof IcfQualifiedContext) && !(parentResult.context instanceof IcfQualifiedContext)) {
+      return super.locateIsA(code, parent, disallowSelf);
+    }
+    if (!parentResult.context) {
+      return { context: null, message: `Parent code '${parent}' not found in CodeSystem '${this.system()}'` };
+    }
+    if (code === parent) {
+      return disallowSelf ? { context: null, message: `Code '${code}' cannot be the same as its parent` } : codeResult;
+    }
+    if (this.#isA(codeResult.context, parentResult.context)) {
+      return codeResult;
+    }
+    return { context: null, message: `Code '${code}' is not a descendant of '${parent}'` };
+  }
+
+  async subsumesTest(codeA, codeB) {
+    const a = (await this.locate(codeA)).context;
+    if (!a) {
+      throw new Error(`Unknown Code "${codeA}"`);
+    }
+    const b = (await this.locate(codeB)).context;
+    if (!b) {
+      throw new Error(`Unknown Code "${codeB}"`);
+    }
+    if (!(a instanceof IcfQualifiedContext) && !(b instanceof IcfQualifiedContext)) {
+      return super.subsumesTest(codeA, codeB);
+    }
+    if ((await this.code(a)) === (await this.code(b))) {
+      return 'equivalent';
+    }
+    if (this.#isA(b, a)) {
+      return 'subsumes';
+    }
+    if (this.#isA(a, b)) {
+      return 'subsumed-by';
+    }
+    return 'not-subsumed';
+  }
+
+  /** A qualified code has no children. */
+  async iterator(context) {
+    if (context) {
+      const ctxt = await this.#resolve(context);
+      if (ctxt instanceof IcfQualifiedContext) {
+        return { type: 'children', parentCode: ctxt.qualifiedCode, codes: [], current: 0, total: 0 };
+      }
+      return super.iterator(ctxt);
+    }
+    return super.iterator(context);
+  }
+
+  // -- filters --------------------------------------------------------------------------
+
+  #isQualifierFilter(prop, op) {
+    return (op === 'exists' && QUALIFIER_PROPERTIES.has(prop)) || (prop === 'qualified' && op === '=');
+  }
+
+  async doesFilter(prop, op, value) {
+    if (this.#isQualifierFilter(prop, op)) {
+      return value === 'true' || value === 'false';
+    }
+    return super.doesFilter(prop, op, value);
+  }
+
+  async filter(filterContext, forIteration, prop, op, value, fc) {
+    if (!this.#isQualifierFilter(prop, op)) {
+      return super.filter(filterContext, forIteration, prop, op, value, fc);
+    }
+    if (value !== 'true' && value !== 'false') {
+      throw new Issue('error', 'exception', null, 'FILTER_NOT_UNDERSTOOD',
+        this.opContext.i18n.translate('FILTER_NOT_UNDERSTOOD', this.opContext.langs, [prop, op, value]), 'vs-invalid', 422);
+    }
+    const want = value === 'true';
+    let test;
+    if (prop === 'qualified') {
+      test = (ctxt) => (ctxt instanceof IcfQualifiedContext) === want;
+    } else {
+      test = (ctxt) => {
+        const q = ctxt instanceof IcfQualifiedContext ? ctxt.qualifiers.find(q => q.property === prop) : undefined;
+        return (q !== undefined && q.digit !== '8') === want;
+      };
+    }
+    const results = new IcfQualifierFilter(test, prop === 'qualified' && !want);
+    // the plain categories that pass: none for exists = true or qualified = true
+    for (const code of this.codeSystem.getAllCodes()) {
+      const concept = this.codeSystem.getConceptByCode(code);
+      if (concept && this.#isPrimary(concept) && test(new FhirCodeSystemProviderContext(code, concept))) {
+        results.add(concept);
+      }
+    }
+    if (!filterContext.filters) {
+      filterContext.filters = [];
+    }
+    filterContext.filters.push(results);
+    return results;
+  }
+
+  /** A primary ICF category (heading or not), as opposed to a qualifier value. */
+  #isPrimary(concept) {
+    const kind = propertyValue(concept, 'kind');
+    return kind === undefined || kind === 'primary';
+  }
+
+  /** Every include can admit qualified codes, unless it has a qualified = false filter. */
+  async filtersNotClosed(filterContext) {
+    return !(filterContext.filters || []).some(f => f instanceof IcfQualifierFilter && f.closesQualified);
+  }
+
+  async filterCheck(filterContext, set, concept) {
+    if (set instanceof IcfQualifierFilter && concept instanceof IcfQualifiedContext) {
+      return set.test(concept) ? true : `Code '${concept.qualifiedCode}' does not meet the qualifier rules`;
+    }
+    return super.filterCheck(filterContext, set, concept);
+  }
+
+  /**
+   * A qualified code is in a filter's results when its category is: it is-a the category,
+   * and has the category's properties. (filterCheck needs nothing extra: it checks the
+   * context's concept, which is the category's.)
+   */
+  async filterLocate(filterContext, set, code) {
+    if (set instanceof IcfQualifierFilter) {
+      const loc = await this.locate(code);
+      if (!loc.context) {
+        return null;
+      }
+      return (await this.filterCheck(filterContext, set, loc.context)) === true ? loc.context : null;
+    }
+    const found = await super.filterLocate(filterContext, set, code);
+    if (found) {
+      return found;
+    }
+    const loc = await this.locate(code);
+    if (!(loc.context instanceof IcfQualifiedContext)) {
+      return found;
+    }
+    const stem = await super.filterLocate(filterContext, set, loc.context.code);
+    return stem && typeof stem !== 'string' ? loc.context : null;
+  }
+}
+
+module.exports = {
+  IcfCodeSystemProvider,
+  IcfQualifiedContext
+};

package/tx/cs/cs-loinc.js

@@ -149,6 +149,12 @@ class LoincServices extends BaseCSServices {
     return 'LOINC';
   }
 
+  /** $lookup's display name: the code system's title. */
+  // eslint-disable-next-line no-unused-vars
+  lookupName(languages) {
+    return 'Logical Observation Identifier Names and Codes (LOINC)';
+  }
+
   description() {
     return 'LOINC';
   }
@@ -607,12 +613,18 @@ class LoincServices extends BaseCSServices {
   // Filter support
   async doesFilter(prop, op, value) {
     // Relationship filters
-    if (this.relationships.has(prop) && ['=', 'in', 'exists', 'regex'].includes(op)) {
+    if (this.relationships.has(prop) && ['=', 'in', 'regex'].includes(op)) {
+      return true;
+    }
+    if (this.relationships.has(prop) && op === 'exists' && ['true', 'false'].includes(value)) {
       return true;
     }
 
     // Property filters
-    if (this.propertyList.has(prop) && ['=', 'in', 'exists', 'regex'].includes(op)) {
+    if (this.propertyList.has(prop) && ['=', 'in', 'regex'].includes(op)) {
+      return true;
+    }
+    if (this.propertyList.has(prop) && op === 'exists' && ['true', 'false'].includes(value)) {
       return true;
     }
 
@@ -748,26 +760,26 @@ class LoincServices extends BaseCSServices {
                 AND TargetKey IN (SELECT CodeKey FROM Codes WHERE Code IN (${codes}))
                 AND SourceKey = `;
     }
-    // Relationship 'exists' filter
+    // Relationship 'exists' filter: value is true or false (doesFilter rejects anything else).
+    // true = codes that have at least one relationship of this type; false = every other code
+    // in the code system (Parts, AnswerLists and Answers included - combine with e.g.
+    // CLASSTYPE exists true to restrict to LOINC terms)
     else if (this.relationships.has(prop) && op === 'exists') {
-      if (this.codes.has(value)) {
+      const rk = this.relationships.get(prop);
+      if (value === 'true') {
         sql = `SELECT DISTINCT SourceKey as Key FROM Relationships
-               WHERE RelationshipTypeKey = ${this.relationships.get(prop)}
-                 AND EXISTS (SELECT CodeKey FROM Codes WHERE Code = '${this.#sqlWrapString(value)}')
+               WHERE RelationshipTypeKey = ${rk}
                ORDER BY SourceKey ASC`;
-        lsql = `SELECT COUNT(DISTINCT SourceKey) FROM Relationships
-                WHERE RelationshipTypeKey = ${this.relationships.get(prop)}
-                  AND EXISTS (SELECT CodeKey FROM Codes WHERE Code = '${this.#sqlWrapString(value)}')
-                  AND SourceKey = `;
-      } else {
-        sql = `SELECT DISTINCT SourceKey as Key FROM Relationships
-               WHERE RelationshipTypeKey = ${this.relationships.get(prop)}
-                 AND EXISTS (SELECT CodeKey FROM Codes WHERE Description = '${this.#sqlWrapString(value)}' COLLATE NOCASE)
-               ORDER BY SourceKey ASC`;
-        lsql = `SELECT COUNT(DISTINCT SourceKey) FROM Relationships
-                WHERE RelationshipTypeKey = ${this.relationships.get(prop)}
-                  AND EXISTS (SELECT CodeKey FROM Codes WHERE Description = '${this.#sqlWrapString(value)}' COLLATE NOCASE)
+        lsql = `SELECT COUNT(SourceKey) FROM Relationships
+                WHERE RelationshipTypeKey = ${rk}
                   AND SourceKey = `;
+      } else if (value === 'false') {
+        sql = `SELECT CodeKey as Key FROM Codes
+               WHERE NOT EXISTS (SELECT 1 FROM Relationships r WHERE r.RelationshipTypeKey = ${rk} AND r.SourceKey = Codes.CodeKey)
+               ORDER BY CodeKey ASC`;
+        lsql = `SELECT COUNT(CodeKey) FROM Codes
+                WHERE NOT EXISTS (SELECT 1 FROM Relationships r WHERE r.RelationshipTypeKey = ${rk} AND r.SourceKey = Codes.CodeKey)
+                  AND CodeKey = `;
       }
     }
     // Relationship regex filter
@@ -820,14 +832,24 @@ class LoincServices extends BaseCSServices {
                 AND PropertyValues.Value IN (${codes}) COLLATE NOCASE
                 AND CodeKey = `;
     }
-    // Property 'exists' filter
+    // Property 'exists' filter: value is true or false, as for relationships above
     else if (this.propertyList.has(prop) && op === 'exists') {
-      sql = `SELECT DISTINCT CodeKey as Key FROM Properties
-             WHERE Properties.PropertyTypeKey = ${this.propertyList.get(prop)}
-             ORDER BY CodeKey ASC`;
-      lsql = `SELECT COUNT(CodeKey) FROM Properties
-              WHERE Properties.PropertyTypeKey = ${this.propertyList.get(prop)}
-                AND CodeKey = `;
+      const pk = this.propertyList.get(prop);
+      if (value === 'true') {
+        sql = `SELECT DISTINCT CodeKey as Key FROM Properties
+               WHERE Properties.PropertyTypeKey = ${pk}
+               ORDER BY CodeKey ASC`;
+        lsql = `SELECT COUNT(CodeKey) FROM Properties
+                WHERE Properties.PropertyTypeKey = ${pk}
+                  AND CodeKey = `;
+      } else if (value === 'false') {
+        sql = `SELECT CodeKey as Key FROM Codes
+               WHERE NOT EXISTS (SELECT 1 FROM Properties p WHERE p.PropertyTypeKey = ${pk} AND p.CodeKey = Codes.CodeKey)
+               ORDER BY CodeKey ASC`;
+        lsql = `SELECT COUNT(CodeKey) FROM Codes
+                WHERE NOT EXISTS (SELECT 1 FROM Properties p WHERE p.PropertyTypeKey = ${pk} AND p.CodeKey = Codes.CodeKey)
+                  AND CodeKey = `;
+      }
     }
     // Property regex filter
     else if (this.propertyList.has(prop) && op === 'regex') {

package/tx/cs/cs-omop.js

@@ -151,7 +151,13 @@ class OMOPServices extends BaseCSServices {
   }
 
   name() {
-    return `OMOP Concepts`;
+    return 'OMOP_Concepts';
+  }
+
+  /** $lookup's display name: the code system's title. */
+  // eslint-disable-next-line no-unused-vars
+  lookupName(languages) {
+    return 'OMOP Unified Vocabularies';
   }
 
   description() {
@@ -952,7 +958,8 @@ class OMOPServicesFactory extends CodeSystemFactoryProvider {
    * @param version
    * @returns {ConceptMap}
    */
-  async findImplicitConceptMaps(conceptMaps, source, dest) {
+  // eslint-disable-next-line no-unused-vars
+  async findImplicitConceptMaps(conceptMaps, source, sourceVersion, dest) {
     if (source == 'https://fhir-terminology.ohdsi.org') {
       let key = this.#getVocabId(dest);
       if (key) {
@@ -1007,7 +1014,7 @@ class OMOPServicesFactory extends CodeSystemFactoryProvider {
 
 
   name() {
-    return `OMOP Concepts`;
+    return 'OMOP_Concepts';
   }
 
   id() {