Merge pull request #1133 from microbiomedata/756-show-both-depth-valu…

…es-minmax-when-present

Show depth as range or with units, if possible

web/src/components/Presentation/AttributeItem.vue

@@ -1,7 +1,7 @@
 <script lang="ts">
 import { defineComponent, PropType } from '@vue/composition-api';
 import { getField } from '@/encoding';
-import { fieldDisplayName, valueDisplayName } from '@/util';
+import { fieldDisplayName, formatBiosampleDepth, valueDisplayName } from '@/util';
 import { BaseSearchResult, BiosampleSearchResult } from '@/data/api';
 
 export default defineComponent({
@@ -41,6 +41,11 @@ export default defineComponent({
 
   setup(props) {
     function getValue(field: string) {
+      // For the "depth" field, format it as a string or `null`.
+      // Note: I assert some types here to work around the inaccurate type definitions in `api.ts`.
+      if (field === 'depth') {
+        return formatBiosampleDepth(props.item.annotations?.depth as object | null, props.item.depth as number | null);
+      }
       if (field === 'geo_loc_name') {
         return props.item.annotations.geo_loc_name;
       }

web/src/components/Presentation/AttributeList.vue

@@ -5,6 +5,7 @@ import { isObject } from 'lodash';
 import { BaseSearchResult, BiosampleSearchResult } from '@/data/api';
 import { getField } from '@/encoding';
 import AttributeItem from './AttributeItem.vue';
+import { formatBiosampleDepth } from '@/util';
 
 export default defineComponent({
   components: { AttributeItem },
@@ -41,6 +42,14 @@ export default defineComponent({
         if (includeFields.has(field)) {
           return true;
         }
+
+        // For the "depth" field, we only include it if it is something we can format as a string.
+        // Note: I assert some types here to work around the inaccurate type definitions in `api.ts`.
+        if (field === 'depth') {
+          const formattedDepth = formatBiosampleDepth(props.item.annotations?.depth as object | null, props.item.depth as number | null);
+          return formattedDepth !== null;
+        }
+
         const value = props.item[field];
         return !isObject(value) && value && (!getField(field) || !getField(field).hideAttr);
       });

web/src/util.js

@@ -141,3 +141,50 @@ export function saveAs(filename, text) {
   element.click();
   document.body.removeChild(element);
 }
+
+/**
+ * Returns a string describing the depth of a biosample, or returns null.
+ *
+ * If the biosample's depth annotation contains enough information for this function to format the depth into a string
+ * having one of the formats listed below, the function formats it that way. Otherwise, the function returns whatever
+ * the biosample's top-level `depth` property contains, which could be `null` (per `nmdc_server/ingest/biosample.py`).
+ *
+ * Formats:
+ * 1. Range with unit (e.g. "1 - 2 meters")
+ * 2. Range without unit (e.g. "1 - 2")
+ * 3. Number with unit (e.g. "1 meter")
+ *
+ * Note: I check values' types instead of their truthiness here because I consider `0` to be a valid depth magnitude,
+ *       while JavaScript considers it to be falsy (per https://developer.mozilla.org/en-US/docs/Glossary/Falsy).
+ *
+ * References:
+ * - https://jsdoc.app/tags-param#parameters-with-properties
+ * - https://microbiomedata.github.io/nmdc-schema/QuantityValue/
+ *
+ * @param depthAnnotation {object | null} Value of the biosample's `annotations.depth` property
+ * @param depthAnnotation.has_minimum_numeric_value {number?} Lower magnitude of the quantity's range
+ * @param depthAnnotation.has_maximum_numeric_value {number?} Upper magnitude of the quantity's range
+ * @param depthAnnotation.has_numeric_value {number?} Magnitude of the quantity
+ * @param depthAnnotation.has_unit {string?} Unit of the quantity
+ * @param depth {number | null} Value of the biosample's top-level `depth` property
+ * @return {string | null} Either a string describing the depth of the biosample, or `null`
+ */
+export function formatBiosampleDepth(depthAnnotation, depth) {
+  let formattedStr = depth; // fallback value
+  if (depthAnnotation !== null) {
+    const {
+      has_minimum_numeric_value: minMagnitude,
+      has_maximum_numeric_value: maxMagnitude,
+      has_numeric_value: magnitude,
+      has_unit: unit,
+    } = depthAnnotation;
+    if (typeof minMagnitude === 'number' && typeof maxMagnitude === 'number' && typeof unit === 'string') {
+      formattedStr = `${minMagnitude} - ${maxMagnitude} ${unit}`; // range with unit
+    } else if (typeof minMagnitude === 'number' && typeof maxMagnitude === 'number') {
+      formattedStr = `${minMagnitude} - ${maxMagnitude}`; // range without unit
+    } else if (typeof magnitude === 'number' && typeof unit === 'string') {
+      formattedStr = `${magnitude} ${unit}`; // number with unit
+    }
+  }
+  return formattedStr;
+}