react-cheminfo 0.46.0 → 0.48.0

package/src/taxonomy/core/lineage.ts

@@ -0,0 +1,161 @@
+/**
+ * A lineage: the taxa from the top of the tree of life down to one of them.
+ *
+ * It is read three ways, because the family meets it in three shapes: a map of
+ * NCBI nodes each pointing at its parent (what a database built on the NCBI
+ * dump answers), a record of names by rank (what octochemdb stores), or a list
+ * already in order.
+ */
+
+import {
+  TAXON_RANKS,
+  isGenusOrBelow,
+  isPrincipalRank,
+  rankOrder,
+} from './ranks.ts';
+
+/** One taxon of a lineage. */
+export interface Taxon {
+  /** The rank, as NCBI writes it: `genus`, `no rank`, `clade`… */
+  rank: string;
+  /** The scientific name. */
+  name: string;
+  /**
+   * The NCBI Taxonomy id.
+   * @default undefined — the taxon is known by its name alone
+   */
+  taxId?: number;
+}
+
+/** The taxa from the top of the tree down to one of them, in that order. */
+export type TaxonLineage = readonly Taxon[];
+
+/** A taxon of the NCBI tree, as a map of nodes holds it. */
+export interface TaxonNode {
+  /** The scientific name. */
+  name: string;
+  /** The rank, as NCBI writes it. */
+  rank: string;
+  /** The id of the taxon above; the root is its own parent. */
+  parentId: number;
+}
+
+/**
+ * The taxa a lineage is summarised by: those of a principal rank (domain,
+ * kingdom, phylum, class, order, family, genus, species), and the last one
+ * whatever its rank, since it is the taxon the lineage leads to.
+ *
+ * An NCBI placeholder for an unidentified species ('Streptomyces sp.') says
+ * no more than its genus, so it is left out and the genus is the leaf. The
+ * root, 'cellular organisms', the clades and the steps of no rank above the
+ * leaf never show.
+ * @param lineage - The lineage, from the top down.
+ * @returns The taxa kept, in the same order.
+ */
+export function principalLineage(lineage: TaxonLineage): Taxon[] {
+  const kept: Taxon[] = [];
+  let last = lineage.length - 1;
+  if (last > 0 && isPlaceholderTaxon(lineage[last] as Taxon)) {
+    // The genus becomes the leaf, past 'unclassified Streptomyces'.
+    last--;
+    while (last > 0 && !isPrincipalRank((lineage[last] as Taxon).rank)) last--;
+  }
+  for (let index = 0; index <= last; index++) {
+    const taxon = lineage[index] as Taxon;
+    if (index < last && isPlaceholderTaxon(taxon)) continue;
+    if (index === last || isPrincipalRank(taxon.rank)) kept.push(taxon);
+  }
+  return kept;
+}
+
+/**
+ * Whether a taxon is an NCBI placeholder for an unidentified species of a
+ * genus: a species named the genus and 'sp.', such as 'Streptomyces sp.'.
+ * One named for a strain ('Streptomyces sp. CNQ-509') is a taxon of its own.
+ * @param taxon - The taxon.
+ * @returns Whether it is one.
+ */
+export function isPlaceholderTaxon(taxon: Taxon): boolean {
+  return taxon.rank === 'species' && /\ssp\.$/.test(taxon.name);
+}
+
+/**
+ * The lineage of a taxon, walked up a map of NCBI nodes to the root.
+ * @param nodes - The nodes, by id: a record keyed by the id written as a
+ * string, as JSON delivers it, or a map keyed by the number.
+ * @param taxId - The taxon to start from.
+ * @returns Every taxon from the root down to it, each with its id; empty when
+ * the map does not hold the taxon.
+ */
+export function lineageFromNodes(
+  nodes: Readonly<Record<string, TaxonNode>> | ReadonlyMap<number, TaxonNode>,
+  taxId: number,
+): Taxon[] {
+  const read =
+    nodes instanceof Map
+      ? (id: number) => nodes.get(id)
+      : (id: number) =>
+          (nodes as Readonly<Record<string, TaxonNode>>)[String(id)];
+  const upward: Taxon[] = [];
+  const seen = new Set<number>();
+  let id = taxId;
+  while (!seen.has(id)) {
+    const node = read(id);
+    if (node === undefined) break;
+    seen.add(id);
+    upward.push({ rank: node.rank, name: node.name, taxId: id });
+    id = node.parentId;
+  }
+  return upward.toReversed();
+}
+
+/**
+ * The lineage written by a record of names by rank, the shape octochemdb
+ * stores (`{ kingdom: 'Fungi', genus: 'Penicillium', … }`).
+ *
+ * A key is matched whatever its case, so `superKingdom` reads as
+ * `superkingdom`; a key that names no rank, and an empty name, are left out.
+ * @param ranks - The names, by rank.
+ * @returns The taxa, from the top down.
+ */
+export function lineageFromRanks(
+  ranks: Readonly<Record<string, string | null | undefined>>,
+): Taxon[] {
+  const byRank = new Map<string, string>();
+  for (const key of Object.keys(ranks)) {
+    const name = ranks[key]?.trim();
+    if (name === undefined || name === '') continue;
+    const rank = key.toLowerCase();
+    if (rankOrder(rank) !== undefined) byRank.set(rank, name);
+  }
+  const lineage: Taxon[] = [];
+  for (const rank of TAXON_RANKS) {
+    const name = byRank.get(rank);
+    if (name !== undefined) lineage.push({ rank, name });
+  }
+  return lineage;
+}
+
+/**
+ * Which taxa of a lineage sit at the genus or under it — the ones whose names
+ * nomenclature sets in italics.
+ *
+ * A taxon with no rank (a clade, a strain NCBI left unranked) takes the place
+ * of the taxa above it: under a genus it is one of the genus's, above it it is
+ * a clade like Embryophyta, written upright.
+ * @param lineage - The lineage, from the top down.
+ * @returns One flag per taxon.
+ */
+export function genusOrBelow(lineage: TaxonLineage): boolean[] {
+  const flags: boolean[] = [];
+  let below = false;
+  for (const taxon of lineage) {
+    if (isGenusOrBelow(taxon.rank)) {
+      below = true;
+    } else if (rankOrder(taxon.rank) !== undefined) {
+      below = false;
+    }
+    flags.push(below);
+  }
+  return flags;
+}

package/src/taxonomy/core/ncbi.ts

@@ -0,0 +1,9 @@
+/**
+ * The page of a taxon in the NCBI Taxonomy Browser.
+ * @param taxId - The NCBI Taxonomy id.
+ * @returns Its address, e.g.
+ * `https://www.ncbi.nlm.nih.gov/Taxonomy/Browser/wwwtax.cgi?id=5076`.
+ */
+export function ncbiTaxonomyUrl(taxId: number): string {
+  return `https://www.ncbi.nlm.nih.gov/Taxonomy/Browser/wwwtax.cgi?id=${encodeURIComponent(String(taxId))}`;
+}

package/src/taxonomy/core/organismName.ts

@@ -0,0 +1,217 @@
+/**
+ * Which parts of an organism's name nomenclature sets in italics.
+ *
+ * The genus, the species epithet and an infraspecific epithet are italic; the
+ * authority, a strain, `sp.`, a cultivar and the words announcing a rank
+ * (`subsp.`, `var.`, `f.`) are upright. Names arrive the way their source wrote
+ * them — "Catharanthus roseus (L.) G. Don", "Streptomyces sp. CHQ-64",
+ * "Isodon Shikokiana Var. Occidentalis" — so this reads them by their shape,
+ * and a name it cannot place is left upright rather than guessed at.
+ */
+
+import {
+  BEFORE_EPITHET,
+  CANDIDATUS,
+  HYBRID,
+  NOT_EPITHET,
+  NOT_GENUS,
+  RANK_MARKERS,
+  UNNAMED,
+} from './organismWords.ts';
+
+/** A run of an organism's name, set one way. */
+export interface OrganismNamePart {
+  /** The text, exactly as the name carries it. */
+  text: string;
+  /** Whether nomenclature sets it in italics. */
+  italic: boolean;
+}
+
+interface Piece {
+  text: string;
+  word: boolean;
+  italic: boolean;
+}
+
+const CONSORTIUM = /(?<plus>\s+\+\s+)/;
+const VIRUS = /\b(?:virus|viruses|phage|bacteriophage|viroid|satellite)\b/i;
+const SEPARATOR = /^[\s_]+$/;
+const TRAILING_MARK = /^(?<word>.+?)(?<mark>[,;]+)$/;
+const GENUS = /^[A-Z][a-z]+$/;
+const ABBREVIATED_GENUS = /^[A-Z]\.$/;
+// A family, a subfamily or a tribe written where a genus would stand:
+// -aceae, -oideae and -eae in botany, -idae in zoology. No genus ends so.
+const FAMILY = /(?:eae|idae)$/;
+const BRACKETED_GENUS = /^\[(?<genus>[A-Z][a-z]+)\]$/;
+const JOINED_MARKER =
+  /^(?<marker>subsp\.|ssp\.|var\.|f\.|pv\.)(?<epithet>[a-z][a-z-]+)$/i;
+const EPITHET = /^[a-zß-öø-ÿ][a-zß-öø-ÿ-]+$/;
+const CAPITALISED_EPITHET = /^[A-Z][a-zß-öø-ÿ-]+$/;
+const STARTS_WITH_LETTER = /^\p{L}/u;
+const STARTS_UPPERCASE = /^\p{Lu}/u;
+
+/**
+ * The runs of an organism's name, each set upright or in italics.
+ *
+ * Joined together, the runs give back the name exactly. A consortium written
+ * `A + B` is read as two names; a virus, and anything that does not open with
+ * a genus, is one upright run.
+ * @param name - The name, as its source writes it.
+ * @returns The runs, consecutive runs never set the same way.
+ */
+export function splitOrganismName(name: string): OrganismNamePart[] {
+  if (name === '') return [];
+  if (VIRUS.test(name)) return [{ text: name, italic: false }];
+  const pieces: Piece[] = [];
+  for (const segment of name.split(CONSORTIUM)) {
+    if (CONSORTIUM.test(segment)) {
+      pieces.push({ text: segment, word: false, italic: false });
+    } else {
+      pieces.push(...styledPieces(segment));
+    }
+  }
+  return mergedRuns(pieces);
+}
+
+function styledPieces(text: string): Piece[] {
+  const pieces = tokenize(text);
+  const words = pieces.filter((piece) => piece.word);
+  styleWords(words);
+  for (let index = 0; index < pieces.length; index++) {
+    const piece = pieces[index] as Piece;
+    if (piece.word) continue;
+    piece.italic =
+      pieces[index - 1]?.italic === true && pieces[index + 1]?.italic === true;
+  }
+  return pieces;
+}
+
+function tokenize(text: string): Piece[] {
+  const pieces: Piece[] = [];
+  for (const chunk of text.split(/(?<gap>[\s_]+)/)) {
+    if (chunk === '') continue;
+    if (SEPARATOR.test(chunk)) {
+      pieces.push({ text: chunk, word: false, italic: false });
+      continue;
+    }
+    // A comma or a semicolon closing a word is punctuation, not part of it.
+    const { word: bare = chunk, mark } =
+      TRAILING_MARK.exec(chunk)?.groups ?? {};
+    const joined = JOINED_MARKER.exec(bare)?.groups;
+    const bracketed = BRACKETED_GENUS.exec(bare)?.groups;
+    const words =
+      joined !== undefined
+        ? [joined.marker, joined.epithet]
+        : bracketed !== undefined
+          ? ['[', bracketed.genus, ']']
+          : [bare];
+    for (const word of words) {
+      pieces.push({ text: word ?? '', word: true, italic: false });
+    }
+    if (mark !== undefined) {
+      pieces.push({ text: mark, word: false, italic: false });
+    }
+  }
+  return pieces;
+}
+
+function styleWords(words: Piece[]): void {
+  let index = words[0]?.text === '×' ? 1 : 0;
+  const first = words[index];
+  if (first === undefined) return;
+  if (CANDIDATUS.has(first.text)) {
+    first.italic = true;
+    return;
+  }
+
+  let genus: Piece | undefined;
+  if (first.text === '[' && words[index + 2]?.text === ']') {
+    genus = words[index + 1];
+    index += 3;
+  } else if (GENUS.test(first.text) || ABBREVIATED_GENUS.test(first.text)) {
+    genus = first;
+    index += 1;
+  }
+  if (
+    genus === undefined ||
+    NOT_GENUS.has(genus.text.toLowerCase()) ||
+    FAMILY.test(genus.text)
+  ) {
+    return;
+  }
+  genus.italic = true;
+
+  const titleCase = isTitleCase(words);
+  const next = words[index]?.text;
+  if (next === undefined || UNNAMED.has(next.toLowerCase())) return;
+  let announced = false;
+  if (HYBRID.has(next) || BEFORE_EPITHET.has(next.toLowerCase())) {
+    index += 1;
+    announced = true;
+  }
+  if (isEpithet(words[index], titleCase || announced)) {
+    (words[index] as Piece).italic = true;
+    index += 1;
+    // A zoological trinomial names its subspecies with no word announcing it.
+    if (isEpithet(words[index], false)) {
+      (words[index] as Piece).italic = true;
+      index += 1;
+    }
+  }
+
+  for (; index < words.length; index++) {
+    const word = (words[index] as Piece).text;
+    const marks = RANK_MARKERS.has(word.toLowerCase()) || HYBRID.has(word);
+    if (marks && isEpithet(words[index + 1], true)) {
+      (words[index + 1] as Piece).italic = true;
+      index += 1;
+    }
+  }
+}
+
+function isEpithet(word: Piece | undefined, capitalised: boolean): boolean {
+  if (word === undefined) return false;
+  const lower = word.text.toLowerCase();
+  if (
+    NOT_EPITHET.has(lower) ||
+    UNNAMED.has(lower) ||
+    RANK_MARKERS.has(lower) ||
+    HYBRID.has(word.text)
+  ) {
+    return false;
+  }
+  return (
+    EPITHET.test(word.text) ||
+    (capitalised && CAPITALISED_EPITHET.test(word.text))
+  );
+}
+
+// A source that capitalises every word ("Agave Americana") still means a
+// binomial; the words announcing a rank are left out of the count.
+function isTitleCase(words: readonly Piece[]): boolean {
+  let lettered = 0;
+  for (const { text } of words) {
+    const lower = text.toLowerCase();
+    if (RANK_MARKERS.has(lower) || UNNAMED.has(lower) || HYBRID.has(text)) {
+      continue;
+    }
+    if (!STARTS_WITH_LETTER.test(text)) continue;
+    if (!STARTS_UPPERCASE.test(text)) return false;
+    lettered += 1;
+  }
+  return lettered >= 2;
+}
+
+function mergedRuns(pieces: readonly Piece[]): OrganismNamePart[] {
+  const runs: OrganismNamePart[] = [];
+  for (const piece of pieces) {
+    if (piece.text === '') continue;
+    const last = runs.at(-1);
+    if (last?.italic === piece.italic) {
+      last.text += piece.text;
+    } else {
+      runs.push({ text: piece.text, italic: piece.italic });
+    }
+  }
+  return runs;
+}

package/src/taxonomy/core/organismWords.ts

@@ -0,0 +1,86 @@
+/**
+ * The words an organism's name is read by: the signs and abbreviations that
+ * announce a rank or qualify a name, and the ordinary words a source writes
+ * where a genus or an epithet would stand.
+ */
+
+/** The hybrid sign, and the letters written for it. */
+export const HYBRID = new Set(['×', 'x', 'X']);
+/** The word that opens a provisional bacterial name; it alone is italic. */
+export const CANDIDATUS = new Set(['Candidatus', 'Ca.']);
+/** Qualifiers set before the epithet they qualify, in lower case. */
+export const BEFORE_EPITHET = new Set(['cf.', 'cf', 'aff.', 'aff', 'nr.']);
+/** An unnamed species of the genus, in lower case. */
+export const UNNAMED = new Set(['sp.', 'sp', 'spp.', 'spp']);
+/** The abbreviations announcing a lower-rank epithet, in lower case. */
+export const RANK_MARKERS = new Set([
+  'subsp.',
+  'ssp.',
+  'nothosubsp.',
+  'var.',
+  'nothovar.',
+  'subvar.',
+  'f.',
+  'fo.',
+  'forma',
+  'subf.',
+  'pv.',
+  'subgen.',
+  'sect.',
+  'subsect.',
+  'ser.',
+  'subser.',
+]);
+/** Words that open a description rather than a binomial, in lower case. */
+export const NOT_GENUS = new Set([
+  'unknown',
+  'unidentified',
+  'uncultured',
+  'unclassified',
+  'environmental',
+  'fungal',
+  'bacterial',
+  'marine',
+  'endophytic',
+  'mixed',
+  'fungus',
+  'bacterium',
+  'endophyte',
+  'strain',
+  'isolate',
+  'plant',
+  'soil',
+  'sponge',
+]);
+/** Lower-case words that follow a binomial without being an epithet. */
+export const NOT_EPITHET = new Set([
+  'strain',
+  'isolate',
+  'symbiont',
+  'endophyte',
+  'clone',
+  'group',
+  'complex',
+  'culture',
+  'cultivar',
+  'serovar',
+  'biovar',
+  'pathovar',
+  'species',
+  'incertae',
+  'sedis',
+  'and',
+  'et',
+  'ex',
+  'in',
+  'non',
+  'sensu',
+  'auct',
+  'de',
+  'du',
+  'la',
+  'le',
+  'van',
+  'von',
+  'der',
+]);

package/src/taxonomy/core/ranks.ts

@@ -0,0 +1,134 @@
+/**
+ * The ranks of the NCBI Taxonomy, from the top of the tree down.
+ *
+ * NCBI also files taxa under ranks that are not steps of a hierarchy — `no
+ * rank`, `clade`, the two roots — and those are deliberately absent here: a
+ * clade can sit anywhere, so it has no place in an order.
+ */
+
+/**
+ * Every rank NCBI places in its hierarchy, from the top down.
+ *
+ * `realm` heads the viruses and `domain` the cellular organisms, the name NCBI
+ * gave in 2025 to what it called `superkingdom` before; all three stand at the
+ * top, so a lineage read from an older dump sorts the same way.
+ */
+export const TAXON_RANKS = [
+  'realm',
+  'domain',
+  'superkingdom',
+  'kingdom',
+  'subkingdom',
+  'superphylum',
+  'phylum',
+  'subphylum',
+  'superclass',
+  'class',
+  'subclass',
+  'infraclass',
+  'cohort',
+  'subcohort',
+  'superorder',
+  'order',
+  'suborder',
+  'infraorder',
+  'parvorder',
+  'superfamily',
+  'family',
+  'subfamily',
+  'tribe',
+  'subtribe',
+  'genus',
+  'subgenus',
+  'section',
+  'subsection',
+  'series',
+  'subseries',
+  'species group',
+  'species subgroup',
+  'species',
+  'forma specialis',
+  'subspecies',
+  'varietas',
+  'subvariety',
+  'forma',
+  'pathogroup',
+  'serogroup',
+  'serotype',
+  'biotype',
+  'genotype',
+  'morph',
+  'strain',
+  'isolate',
+] as const;
+
+/** A rank of the NCBI hierarchy. */
+export type TaxonRank = (typeof TAXON_RANKS)[number];
+
+/**
+ * The ranks a lineage is summarised by: the eight a textbook names, with the
+ * three names the top of the tree goes by.
+ */
+export const PRINCIPAL_RANKS = [
+  'realm',
+  'domain',
+  'superkingdom',
+  'kingdom',
+  'phylum',
+  'class',
+  'order',
+  'family',
+  'genus',
+  'species',
+] as const satisfies readonly TaxonRank[];
+
+const ORDER = new Map<string, number>();
+for (let index = 0; index < TAXON_RANKS.length; index++) {
+  ORDER.set(TAXON_RANKS[index] as string, index);
+}
+
+const PRINCIPAL = new Set<string>(PRINCIPAL_RANKS);
+
+const GENUS = ORDER.get('genus') ?? 0;
+
+/**
+ * Where a rank stands in the hierarchy.
+ * @param rank - The rank, as NCBI writes it.
+ * @returns Its position from the top, 0 for `realm`, or `undefined` for a
+ * rank that is not a step of the hierarchy (`no rank`, `clade`).
+ */
+export function rankOrder(rank: string): number | undefined {
+  return ORDER.get(rank);
+}
+
+/**
+ * Whether a rank is one a lineage is summarised by.
+ * @param rank - The rank, as NCBI writes it.
+ * @returns Whether it is one of {@link PRINCIPAL_RANKS}.
+ */
+export function isPrincipalRank(rank: string): boolean {
+  return PRINCIPAL.has(rank);
+}
+
+/**
+ * Whether a rank is the genus or one under it — the ranks whose names
+ * nomenclature sets in italics.
+ * @param rank - The rank, as NCBI writes it.
+ * @returns `false` for a rank above the genus and for one with no place in the
+ * hierarchy.
+ */
+export function isGenusOrBelow(rank: string): boolean {
+  const order = ORDER.get(rank);
+  return order !== undefined && order >= GENUS;
+}
+
+/**
+ * Whether a rank stands above the genus, so its name is set upright.
+ * @param rank - The rank, as NCBI writes it.
+ * @returns `false` for the genus and below, and for a rank with no place in
+ * the hierarchy.
+ */
+export function isAboveGenus(rank: string): boolean {
+  const order = ORDER.get(rank);
+  return order !== undefined && order < GENUS;
+}

package/src/taxonomy/ui/OrganismName.tsx

@@ -0,0 +1,59 @@
+import type { ReactElement, ReactNode } from 'react';
+import { Fragment } from 'react';
+
+import { joinClassNames } from '../../shared/ui/joinClassNames.ts';
+import { splitOrganismName } from '../core/organismName.ts';
+import { isAboveGenus } from '../core/ranks.ts';
+
+/** What an {@link OrganismName} needs. */
+export interface OrganismNameProps {
+  /** The name, as its source writes it. */
+  name: string;
+  /**
+   * The rank of the taxon the name belongs to. A name ranked above the genus
+   * (a family, an order) is set upright whatever its shape.
+   * @default undefined — the name is read by its shape alone
+   */
+  rank?: string;
+  /**
+   * Class names added to the root element.
+   * @default undefined
+   */
+  className?: string;
+}
+
+/**
+ * An organism's name, with the genus and the epithets in italics and the
+ * authority, the strain and `sp.` upright, as nomenclature sets them.
+ *
+ * The italics are `<i>`, the element HTML names for a taxonomic designation,
+ * and the name keeps every character its source gave it.
+ * @param props - See {@link OrganismNameProps}.
+ * @returns The name.
+ */
+export function OrganismName(props: OrganismNameProps): ReactElement {
+  const { name, rank, className } = props;
+  const parts =
+    rank !== undefined && isAboveGenus(rank)
+      ? [{ text: name, italic: false }]
+      : splitOrganismName(name);
+
+  const children: ReactNode[] = [];
+  let offset = 0;
+  for (const part of parts) {
+    children.push(
+      part.italic ? (
+        <i key={offset}>{part.text}</i>
+      ) : (
+        <Fragment key={offset}>{part.text}</Fragment>
+      ),
+    );
+    offset += part.text.length;
+  }
+
+  return (
+    <span className={joinClassNames('organism-name', className)}>
+      {children}
+    </span>
+  );
+}