@macrostrat/column-views 1.0.3 → 2.0.1

package/src/prepare-units/helpers.ts

@@ -0,0 +1,226 @@
+import type { BaseUnit, UnitLong } from "@macrostrat/api-types";
+import { group } from "d3-array";
+import { ColumnAxisType } from "@macrostrat/column-components";
+import {
+  unitsOverlap,
+  getUnitHeightRange,
+  createUnitSorter,
+  ensureArray,
+  ensureRealFloat,
+} from "./utils";
+
+const dt = 0.001;
+
+export interface StratigraphicPackage {
+  /** A collection of stratigraphic information organized in time, corresponding
+   * to single or multiple columns. */
+  t_age: number;
+  b_age: number;
+}
+
+export interface SectionInfo<T extends UnitLong = ExtUnit>
+  extends StratigraphicPackage {
+  /** A time-bounded part of a single stratigraphic column. */
+  section_id: number | number[];
+  units: T[];
+}
+
+export interface ExtUnit extends UnitLong {
+  bottomOverlap: boolean;
+  overlappingUnits: number[];
+  column?: number;
+  /* Positions (ages or heights) where the unit is clipped to its containing section.
+   * This is relevant if we are filtering by age/height/depth range.
+   */
+  t_clip_pos?: number;
+  b_clip_pos?: number;
+}
+
+export function preprocessUnits<T extends UnitLong = UnitLong>(
+  section: SectionInfo<T>,
+  axisType: ColumnAxisType = ColumnAxisType.AGE
+): ExtUnit[] {
+  /** Preprocess units to add overlapping units and columns. */
+  const units = section.units;
+  let divisions = units.map((...args) => extendDivision(...args, axisType));
+  for (let d of divisions) {
+    const overlappingUnits = divisions.filter((u) =>
+      d.overlappingUnits.includes(u.unit_id)
+    );
+
+    // Overlapping columns
+    const columns = overlappingUnits.map((d) => d.column);
+
+    if (columns.includes(d.column)) {
+      let col = 0;
+      // Go through columns to find a better index
+      while (columns.includes(col)) {
+        col++;
+      }
+      d.column = col;
+    }
+
+    // If unit overlaps the edges of a section, set the clip positions
+    if (axisType == ColumnAxisType.AGE) {
+      const [b_pos, t_pos] = getUnitHeightRange(d, axisType);
+      if (b_pos > section.b_age) {
+        d.b_clip_pos = section.b_age;
+      }
+      if (t_pos < section.t_age) {
+        d.t_clip_pos = section.t_age;
+      }
+    }
+  }
+
+  if (axisType != ColumnAxisType.AGE) {
+    return preprocessSectionUnits(divisions, axisType);
+  }
+
+  return divisions;
+}
+
+function extendDivision(
+  unit: UnitLong,
+  i: number,
+  divisions: UnitLong[],
+  axisType: ColumnAxisType = ColumnAxisType.AGE
+): ExtUnit {
+  const overlappingUnits = divisions.filter(
+    (d) => d.unit_id != unit.unit_id && unitsOverlap(unit, d, axisType)
+  );
+  const u_pos = getUnitHeightRange(unit, axisType);
+  const bottomOverlap = overlappingUnits.some((d) => {
+    const d_pos = getUnitHeightRange(d, axisType);
+    // Check if the unit is below the current unit
+    return d_pos[0] < u_pos[0] + dt;
+  });
+  let column = 0;
+  if (overlappingUnits.length == 1) {
+    column = 1;
+  }
+
+  return {
+    ...unit,
+    bottomOverlap,
+    column,
+    overlappingUnits: overlappingUnits.map((d) => d.unit_id),
+  };
+}
+
+export function groupUnitsIntoSections<T extends UnitLong>(
+  units: T[],
+  axisType: ColumnAxisType = ColumnAxisType.AGE
+): SectionInfo<T>[] {
+  let groups = Array.from(group(units, (d) => d.section_id));
+  const unitComparator = createUnitSorter(axisType);
+
+  const groups1 = groups.map(([section_id, sectionUnits]) => {
+    const [b_age, t_age] = getSectionAgeRange(sectionUnits);
+    // sort units by position
+    sectionUnits.sort(unitComparator);
+    return { section_id, t_age, b_age, units: sectionUnits };
+  });
+  // Sort sections by increasing top age, then increasing bottom age.
+  // Sections have no relative ordinal position other than age...
+  const compareSections = createUnitSorter(ColumnAxisType.AGE) as (
+    a: StratigraphicPackage,
+    b: StratigraphicPackage
+  ) => number;
+  groups1.sort(compareSections);
+  return groups1;
+}
+
+export function getSectionAgeRange(units: BaseUnit[]): [number, number] {
+  /** Get the overall age range of a set of units. */
+  const t_ages = units.map((d) => d.t_age);
+  const b_ages = units.map((d) => d.b_age);
+  const t_age = Math.min(...t_ages);
+  const b_age = Math.max(...b_ages);
+  return [b_age, t_age];
+}
+
+export function mergeOverlappingSections<T extends UnitLong>(
+  sections: SectionInfo<T>[]
+): SectionInfo<T>[] {
+  /** Columns can have sections that overlap in time. Here, we merge overlapping
+   * sections into a single section to correctly render gap-bound packages.
+   */
+  const [firstSection, ...rest] = sections;
+  const newSections = [firstSection];
+  for (const section of rest) {
+    const lastSection = newSections[newSections.length - 1];
+    if (
+      lastSection.b_age < section.t_age ||
+      lastSection.t_age > section.b_age
+    ) {
+      // No overlap, add the section as normal
+      newSections.push(section);
+      continue;
+    }
+
+    // Overlap, merge the sections
+    lastSection.section_id = [
+      ...ensureArray(lastSection.section_id),
+      ...ensureArray(section.section_id),
+    ];
+    lastSection.units.push(...section.units);
+    lastSection.b_age = Math.max(lastSection.b_age, section.b_age);
+    lastSection.t_age = Math.min(lastSection.t_age, section.t_age);
+  }
+  return newSections;
+}
+
+function preprocessSectionUnits(
+  units: UnitLong[],
+  axisType: ColumnAxisType = ColumnAxisType.DEPTH
+): ExtUnit[] {
+  /** Preprocess units for a "section" column type, which is guaranteed to be simpler. */
+  // We have to assume the units are ordered...
+  let thickness = 0;
+  return units.map((unit, i) => {
+    let u1 = preprocessSectionUnit(unit, i, units, thickness, axisType);
+    thickness += Math.abs(u1.t_pos - u1.b_pos);
+    return u1;
+  });
+}
+
+function preprocessSectionUnit(
+  unit: UnitLong,
+  i: number,
+  units: UnitLong[],
+  accumulatedThickness: number = 0,
+  axisType: ColumnAxisType = ColumnAxisType.DEPTH
+): ExtUnit {
+  /** Preprocess a single unit for a "section" column type.
+   * No provision for overlapping units.
+   * */
+
+  let b_pos = unit.b_pos;
+  let t_pos = unit.t_pos;
+
+  if (b_pos == t_pos && axisType == ColumnAxisType.ORDINAL) {
+    t_pos = t_pos - 1;
+  }
+
+  let unit_name = unit.unit_name;
+
+  // eODP columns sometimes have overlapping core sections, which are encoded in the name field
+  // Match eODP section names
+  const match = unit.unit_name.match(/^(\d+(\.\d+)?)-(\d+(\.\d+)?): (.+)/);
+
+  if (match) {
+    // These values should already be set if we've used the show_positions flag
+    t_pos ??= ensureRealFloat(match[1]);
+    b_pos ??= ensureRealFloat(match[3]);
+    unit_name = match[5];
+  }
+
+  return {
+    ...unit,
+    b_pos: ensureRealFloat(b_pos),
+    t_pos: ensureRealFloat(t_pos),
+    unit_name,
+    bottomOverlap: false,
+    overlappingUnits: [],
+  };
+}

package/src/prepare-units/index.ts

@@ -0,0 +1,177 @@
+import {
+  getSectionAgeRange,
+  groupUnitsIntoSections,
+  mergeOverlappingSections,
+  preprocessUnits,
+} from "./helpers";
+import { ColumnAxisType } from "@macrostrat/column-components";
+import { useMemo } from "react";
+import type { ExtUnit } from "./helpers";
+import { UnitLong } from "@macrostrat/api-types";
+import {
+  collapseUnconformitiesByPixelHeight,
+  ColumnScaleOptions,
+  CompositeColumnData,
+  computeSectionHeights,
+  finalizeSectionHeights,
+  PackageLayoutData,
+} from "./composite-scale";
+import type { SectionInfo } from "./helpers";
+import { agesOverlap, unitsOverlap } from "./utils";
+
+export * from "./utils";
+export { preprocessUnits, groupUnitsIntoSections };
+
+export interface PrepareColumnOptions extends ColumnScaleOptions {
+  axisType: ColumnAxisType;
+  t_age?: number;
+  b_age?: number;
+  mergeSections?: MergeSectionsMode;
+  collapseSmallUnconformities?: boolean | number;
+}
+
+export enum MergeSectionsMode {
+  ALL = "all",
+  OVERLAPPING = "overlapping",
+}
+
+export interface PreparedColumnData extends CompositeColumnData {
+  sections: PackageLayoutData[];
+  units: ExtUnit[];
+}
+
+export function usePreparedColumnUnits(
+  data: UnitLong[],
+  options: PrepareColumnOptions
+): PreparedColumnData {
+  /** This function wraps and memoizes all preparation steps for converting
+   * an array of units from the /units route to a form ready for usage.
+   */
+  return useMemo(() => {
+    return prepareColumnUnits(data, options);
+  }, [data, ...Object.values(options)]);
+}
+
+export function prepareColumnUnits(
+  units: UnitLong[],
+  options: PrepareColumnOptions
+): PreparedColumnData {
+  /** Prepare units for rendering into Macrostrat columns */
+
+  const {
+    t_age,
+    b_age,
+    mergeSections = MergeSectionsMode.OVERLAPPING,
+    axisType,
+    unconformityHeight,
+    collapseSmallUnconformities = false,
+  } = options;
+
+  /** Prototype filtering to age range */
+  let units1 = units.filter((d) => {
+    // Filter units by t_age and b_age, inclusive
+    return agesOverlap(d, { t_age, b_age });
+  });
+
+  let sections0: SectionInfo<UnitLong>[];
+  if (
+    mergeSections == MergeSectionsMode.ALL &&
+    axisType != ColumnAxisType.ORDINAL
+  ) {
+    // For the "merge sections" mode, we need to create a single section
+    const [b_unit_age, t_unit_age] = getSectionAgeRange(units1);
+    sections0 = [
+      {
+        section_id: 0,
+        /**
+         * If ages limits are directly specified, use them to define the section bounds.
+         * */
+        t_age: t_age ?? t_unit_age,
+        b_age: b_age ?? b_unit_age,
+        units: units1,
+      },
+    ];
+  } else {
+    sections0 = groupUnitsIntoSections(units1, axisType);
+  }
+
+  /** Merging overlapping sections really only makes sense for age/height/depth
+   * columns. Ordinal columns are numbered by section so merging them
+   * results in collisions.
+   */
+  let sections = sections0;
+  if (
+    mergeSections == MergeSectionsMode.OVERLAPPING &&
+    axisType != ColumnAxisType.ORDINAL
+  ) {
+    sections = mergeOverlappingSections(sections);
+  }
+  // Filter out undefined sections just in case
+  sections = sections.filter((d) => d != null);
+
+  /* Now that we are done merging sections, we can ensure that our sections
+   * are correctly limited to the t_age and b_age applied to the overall column.
+   */
+  sections = sections.map((section) => {
+    const { t_age, b_age } = section;
+    return {
+      ...section,
+      t_age: Math.max(t_age, options.t_age ?? -Infinity),
+      b_age: Math.min(b_age, options.b_age ?? Infinity),
+    };
+  });
+
+  /* Compute pixel scales etc. for sections
+   * We need to do this now to determine which unconformities
+   * are small enough to collapse.
+   */
+  let sectionsWithScales = computeSectionHeights(sections, options);
+
+  if (collapseSmallUnconformities ?? false) {
+    let threshold = unconformityHeight ?? 30;
+    if (typeof collapseSmallUnconformities == "number") {
+      threshold = collapseSmallUnconformities;
+    }
+
+    sectionsWithScales = collapseUnconformitiesByPixelHeight(
+      sectionsWithScales,
+      threshold,
+      options
+    );
+  }
+
+  /** Reconstitute the units so that they are sorted by section.
+   * This is mostly important so that unit keyboard navigation
+   * predictably selects adjacent units.
+   */
+  const units2 = sectionsWithScales.reduce((acc, group) => {
+    const { units } = group;
+    for (const unit of units) {
+      acc.push(unit);
+    }
+    return acc;
+  }, []);
+
+  /** Prepare section scale information using groups */
+  const { totalHeight, sections: sections2 } = finalizeSectionHeights(
+    sectionsWithScales,
+    unconformityHeight
+  );
+
+  /** For each section, find units that are overlapping.
+   * We do this after merging sections so that we can
+   * handle cases where there are overlapping units across sections
+   * */
+  const sectionsOut = sections2.map((section) => {
+    return {
+      ...section,
+      units: preprocessUnits(section, axisType),
+    };
+  });
+
+  return {
+    units: units2,
+    totalHeight,
+    sections: sectionsOut,
+  };
+}

package/src/prepare-units/utils.ts

@@ -0,0 +1,98 @@
+import type { BaseUnit } from "@macrostrat/api-types";
+import {
+  AgeRangeRelationship,
+  compareAgeRanges,
+} from "@macrostrat/stratigraphy-utils";
+import { ColumnAxisType } from "@macrostrat/column-components";
+import { StratigraphicPackage } from "./helpers";
+
+const dt = 0.001;
+
+interface UnitsOverlap {
+  (
+    a: StratigraphicPackage,
+    b: StratigraphicPackage,
+    axisType?: ColumnAxisType.AGE,
+    tolerance?: number
+  ): boolean;
+  (
+    a: BaseUnit,
+    b: BaseUnit,
+    axisType: ColumnAxisType,
+    tolerance?: number
+  ): boolean;
+}
+
+export const unitsOverlap: UnitsOverlap = function (
+  a,
+  b,
+  axisType: ColumnAxisType = ColumnAxisType.AGE,
+  tolerance: number = 0.001
+): boolean {
+  const rel = compareAgeRanges(
+    getUnitHeightRange(a, axisType),
+    getUnitHeightRange(b, axisType),
+    tolerance
+  );
+  return rel != AgeRangeRelationship.Disjoint;
+};
+
+/** A more permissive overlap function in the age space */
+export function agesOverlap(
+  a: StratigraphicPackage,
+  b: StratigraphicPackage,
+  tolerance: number = dt
+): boolean {
+  return unitsOverlap(a, b, ColumnAxisType.AGE, tolerance);
+}
+
+interface PossiblyClippedUnit extends BaseUnit {
+  // Internally created clipped positions
+  t_clip_pos?: number;
+  b_clip_pos?: number;
+}
+
+export function getUnitHeightRange(
+  unit: PossiblyClippedUnit,
+  axisType: ColumnAxisType
+): [number, number] {
+  switch (axisType) {
+    case ColumnAxisType.AGE:
+      return [unit.b_clip_pos ?? unit.b_age, unit.t_clip_pos ?? unit.t_age];
+    case ColumnAxisType.DEPTH:
+    case ColumnAxisType.ORDINAL:
+    case ColumnAxisType.HEIGHT:
+      return [unit.b_clip_pos ?? unit.b_pos, unit.t_clip_pos ?? unit.t_pos];
+    default:
+      throw new Error(`Unknown axis type: ${axisType}`);
+  }
+}
+
+export const createUnitSorter = (axisType: ColumnAxisType) => {
+  return (a: BaseUnit, b: BaseUnit) => {
+    const a_pos = getUnitHeightRange(a, axisType);
+    const b_pos = getUnitHeightRange(b, axisType);
+    const d_top = a_pos[1] - b_pos[1];
+    if (d_top != 0) {
+      return d_top;
+    }
+    return a_pos[0] - b_pos[0];
+  };
+};
+
+export function ensureArray<T>(x: T | T[]): T[] {
+  if (Array.isArray(x)) {
+    return x;
+  }
+  return [x];
+}
+
+export function ensureRealFloat(x: number | string | null): number | null {
+  if (typeof x == "string") {
+    x = parseFloat(x);
+  }
+  if (isNaN(x)) {
+    return null;
+  }
+  return x;
+}