react-cheminfo 0.69.0 → 0.71.0

package/src/mass/core/spectrumJcamp.ts

@@ -0,0 +1,186 @@
+/**
+ * Writing spectra back out as JCAMP-DX, so what was loaded can be taken away.
+ *
+ * JCAMP is the format to write rather than two columns of text because it
+ * carries the acquisition records beside the points, so a spectrum that came in
+ * knowing it was an MS2 scan at 3.2 minutes goes out still knowing it — and
+ * comes back into this viewer, or into any other reader of the format, with its
+ * acquisition table intact.
+ *
+ * The points are written as an `##PEAK TABLE=` of explicit `x y` pairs rather
+ * than as a compressed `##XYDATA=` record, and that is a correctness choice. An
+ * XYDATA record states a first x and an increment and lets the reader rebuild
+ * the axis, which is exact only for an evenly sampled trace; a TOF or an FT scan
+ * is not evenly sampled, and writing one that way moves every m/z. Explicit
+ * pairs round trip bit for bit, at about 16 bytes a point.
+ */
+
+import { fromJSON } from 'convert-to-jcamp';
+
+import { metaRecord } from './massMeta.ts';
+import type { MassSpectrum } from './massSpectrum.ts';
+
+/** The extension a written spectrum is saved under. */
+export const JCAMP_EXTENSION = '.jdx';
+
+/** What a JCAMP-DX file is served as. */
+export const JCAMP_MIME_TYPE = 'chemical/x-jcamp-dx';
+
+/**
+ * Write one spectrum as a JCAMP-DX block.
+ *
+ * The trace written is the one the spectrum is the record of: the continuous
+ * profile where the file held one, and the centroid otherwise. Both are never
+ * written, because a reader — this one included — picks the peaks of a profile
+ * as it loads it, so a file carrying the sticks as well would come back as two
+ * spectra of the same acquisition.
+ * @param spectrum - The spectrum.
+ * @returns The block, `##TITLE=` through `##END=`.
+ */
+export function massSpectrumToJcamp(spectrum: MassSpectrum): string {
+  const trace = spectrum.profile ?? spectrum.centroid;
+  return fromJSON(
+    { x: trace.x, y: trace.y },
+    { info: infoRecords(spectrum), meta: metaRecords(spectrum) },
+  );
+}
+
+/**
+ * Write every spectrum of a list as one JCAMP-DX file.
+ *
+ * One file rather than one download per spectrum: a browser asked for eleven
+ * files in a row blocks all but the first. The blocks go inside a `LINK` block,
+ * which is what JCAMP has for a container, so dropping the file back on the
+ * chart brings the whole list back. A list of one is written as that block
+ * alone: wrapping a single spectrum in a container gains nothing.
+ * @param spectra - The spectra, in the order the list holds them.
+ * @param title - What to call the file's own outer block.
+ * @returns The file.
+ */
+export function massSpectraToJcamp(
+  spectra: readonly MassSpectrum[],
+  title = `${spectra.length} mass spectra`,
+): string {
+  const only = spectra.length === 1 ? spectra[0] : undefined;
+  if (only !== undefined) return massSpectrumToJcamp(only);
+
+  const blocks: string[] = [];
+  for (const spectrum of spectra) blocks.push(massSpectrumToJcamp(spectrum));
+  return `##TITLE=${recordValue(title)}
+##JCAMP-DX=4.24
+##DATA TYPE=LINK
+##BLOCKS=${blocks.length}
+${blocks.join('\n')}
+##END=
+`;
+}
+
+/**
+ * The standard records of a block: what it is called, and what its axes are.
+ * @param spectrum - The spectrum.
+ * @returns The records, as `convert-to-jcamp` takes them.
+ */
+function infoRecords(spectrum: MassSpectrum): Record<string, string> {
+  const info: Record<string, string> = {
+    title: recordValue(spectrum.name),
+    dataType: 'MASS SPECTRUM',
+    xUnits: 'M/Z',
+    yUnits: 'RELATIVE ABUNDANCE',
+  };
+  const { meta } = spectrum;
+  if (meta === null) return info;
+
+  for (const field of meta.fields) {
+    const record = metaRecord(field.label);
+    if (record?.info === true) info[record.key] = recordValue(field.value);
+  }
+  if (meta.molecularFormula !== null) {
+    info.MOLFORM = recordValue(meta.molecularFormula);
+  }
+  // `origin` is the one standard record `fromJSON` writes from a lowercase key,
+  // and the reader shows it as the source, so it goes through that key or not at
+  // all: an `##ORIGIN=` written twice is a file two readers disagree about.
+  const source = info.ORIGIN;
+  if (source !== undefined) {
+    info.origin = source;
+    delete info.ORIGIN;
+  }
+  return info;
+}
+
+/**
+ * The `$`-prefixed records of a block: the acquisition, as far as it is known.
+ *
+ * Everything the acquisition table holds, plus whatever the origin knows that
+ * the table does not — an mzML or a netCDF states the MS level and the polarity
+ * in its own structures rather than in a record, and those facts would otherwise
+ * be the one thing a round trip through JCAMP lost.
+ *
+ * The formula is written here as well as into the standard `##MOLFORM=`, which
+ * looks like the same fact stated twice and is: a reader that keeps only the
+ * `$` records — `common-spectrum` is one — would otherwise lose it, and it
+ * drives which masses an annotator looks for.
+ * @param spectrum - The spectrum.
+ * @returns The records, keyed without their `##$`.
+ */
+function metaRecords(spectrum: MassSpectrum): Record<string, string> {
+  const records: Record<string, string> = {};
+  const { meta, origin } = spectrum;
+
+  if (meta !== null) {
+    for (const field of meta.fields) {
+      const record = metaRecord(field.label);
+      if (record !== null && !record.info) {
+        records[record.key] = recordValue(field.value);
+      }
+    }
+    if (meta.conditions !== null) {
+      records.CONDITIONS = recordValue(meta.conditions);
+    }
+    if (meta.molecularFormula !== null) {
+      records.ACCURATE_MF = recordValue(meta.molecularFormula);
+    }
+  }
+
+  fill(records, 'MSLEVEL', origin.msLevel);
+  fill(records, 'MODE', origin.polarity);
+  fill(records, 'ISOLATION', origin.precursorMz);
+  if (origin.retentionTime !== undefined) {
+    fill(records, 'RETENTIONTIME', `${origin.retentionTime} min`);
+  }
+  return records;
+}
+
+/**
+ * Write a fact the origin knows, unless the table already stated it.
+ *
+ * The table wins because it is what the file itself said, whereas the origin is
+ * what was derived from it — and a value shown in the panel that changed on the
+ * way out is worse than a value written in a slightly different spelling.
+ * @param records - The records being built.
+ * @param key - The record to write.
+ * @param value - What it says, absent when nothing is known.
+ */
+function fill(
+  records: Record<string, string>,
+  key: string,
+  value: string | number | undefined,
+): void {
+  if (value === undefined || records[key] !== undefined) return;
+  records[key] = recordValue(String(value));
+}
+
+/**
+ * A value put where a JCAMP record's value goes.
+ *
+ * A record is one line and `$$` opens a comment that runs to the end of it, so
+ * an instrument's scan description — which arrives with newlines in it as often
+ * as not — would otherwise either break the file in two or lose its tail. Both
+ * failures are silent on the way back in, which is why this is done to every
+ * value rather than to the ones known to be long.
+ * @param value - The value as it is held.
+ * @returns The value as one line, with no comment marker in it.
+ */
+function recordValue(value: string): string {
+  return value.replaceAll(/\s+/g, ' ').replaceAll('$$', '$').trim();
+}

package/src/mass/core/toMassSpectrum.ts

@@ -0,0 +1,126 @@
+/**
+ * Turning what a reader produced into what the viewer holds.
+ *
+ * A reader answers about a file and knows nothing about the session it is being
+ * read into — which spectra are already open, what colours they took, what this
+ * one should be called. That is the gap this closes: the peaks are picked here,
+ * the resolution decided, and it is the only place an identity or a colour is
+ * invented.
+ */
+
+import { nextSpectrumColor } from '../../chart/core/spectrumColor.ts';
+
+import type { AnalyseSpectrumOptions } from './analyseSpectrum.ts';
+import { analyseSpectrum } from './analyseSpectrum.ts';
+import type { LoadedMassSpectrum } from './loadedMassSpectrum.ts';
+import type { MassSpectrum } from './massSpectrum.ts';
+import { decideResolution } from './resolutionOf.ts';
+
+/** What has to be decided for a loaded spectrum to become a held one. */
+export interface ToMassSpectrumOptions {
+  /**
+   * Identity, which every later edit and selection is keyed on.
+   * @default a fresh UUID
+   */
+  id?: string;
+  /**
+   * The colour to draw it in.
+   * @default the lowest hue not in `taken`
+   */
+  color?: string;
+  /**
+   * The colours the spectra already open have taken, so a new one is told apart
+   * from them. Ignored when `color` says outright.
+   * @default no colours taken
+   */
+  taken?: readonly string[];
+  /**
+   * What to call it, overriding the file's own title.
+   * @default the file's title, then its name, then `Spectrum`
+   */
+  name?: string;
+  /**
+   * How the peaks are picked, beyond what the file itself said.
+   * @default the analysis's own defaults
+   */
+  analysis?: Omit<AnalyseSpectrumOptions, 'continuous'>;
+}
+
+/**
+ * Make a held spectrum out of a read one.
+ *
+ * The resolution is the strongest verdict there is evidence for, as
+ * `decideResolution` weighs it: measured on the peak widths when the trace is a
+ * profile, otherwise what the file says the instrument was, and only failing
+ * both what the decimals of the masses imply.
+ * @param loaded - What the reader produced.
+ * @param options - The identity, colour and name to give it.
+ * @returns The spectrum as the viewer holds it, its peaks picked.
+ * @throws {Error} Whatever the peak picking refuses the trace with.
+ */
+export function toMassSpectrum(
+  loaded: LoadedMassSpectrum,
+  options: ToMassSpectrumOptions = {},
+): MassSpectrum {
+  const {
+    id = crypto.randomUUID(),
+    color,
+    taken = [],
+    name,
+    analysis,
+  } = options;
+  const analysed = analyseSpectrum(loaded.trace, {
+    ...analysis,
+    ...(loaded.continuous === undefined
+      ? {}
+      : { continuous: loaded.continuous }),
+  });
+  const resolution = decideResolution({
+    measured: analysed.resolution,
+    meta: loaded.meta,
+    masses: analysed.centroid.x,
+  });
+  return {
+    id,
+    name: name ?? loaded.name ?? loaded.origin.fileName ?? 'Spectrum',
+    color: color ?? nextSpectrumColor(taken),
+    profile: analysed.profile,
+    centroid: analysed.centroid,
+    meta: loaded.meta,
+    origin: loaded.origin,
+    // One trace or the other, never both: sticks standing inside the peak
+    // shapes they were picked from read as a second spectrum over the first.
+    showProfile: analysed.profile !== null,
+    showCentroid: analysed.profile === null,
+    resolution,
+  };
+}
+
+/**
+ * Make held spectra out of everything one file held.
+ *
+ * The colours are handed out one at a time against a growing list, so a file
+ * carrying three scans gives three spectra of three colours rather than three
+ * of the same — `nextSpectrumColor` can only answer that if it is told what the
+ * previous call took.
+ * @param loaded - What the reader produced, in file order.
+ * @param options - The colours already taken, and how the peaks are picked.
+ * @returns The spectra, in the same order.
+ */
+export function toMassSpectra(
+  loaded: readonly LoadedMassSpectrum[],
+  options: Pick<ToMassSpectrumOptions, 'taken' | 'analysis'> = {},
+): MassSpectrum[] {
+  const { taken = [], analysis } = options;
+  const colors = [...taken];
+  const spectra: MassSpectrum[] = [];
+  for (const entry of loaded) {
+    const spectrum = toMassSpectrum(entry, {
+      taken: colors,
+      ...(analysis === undefined ? {} : { analysis }),
+    });
+    colors.push(spectrum.color);
+    spectra.push(spectrum);
+  }
+  return spectra;
+}

package/src/mass/core/traceIcon.ts

@@ -0,0 +1,105 @@
+/**
+ * The three things one trace icon has to say, and what a click on it asks for.
+ *
+ * A spectrum row carries two of these icons, one for the continuous trace and
+ * one for the centroid sticks, and each of them answers two questions at once:
+ * is this trace on the chart, and is this the spectrum everything else is
+ * about. The second is not decoration — the selected spectrum is the one the
+ * peak labels are written on, the one the acquisition table describes and the
+ * one the peak list holds — so a plain visibility checkbox would either lose it
+ * or need a second control beside it in a row that has no room for one.
+ *
+ * The two icons are an **either/or**, not two checkboxes: a spectrum is drawn as
+ * its profile or as its sticks and never as both. Drawn together, the sticks
+ * stand inside the very peak shapes they were picked from, and the pair reads as
+ * two spectra laid over each other — a peak top that says one thing in the
+ * outline and another in the stick beside it. Which peaks the picking found is
+ * asked of the label toggle instead, which marks their tops over whichever trace
+ * is on screen.
+ *
+ * Hence the cycle: a hidden trace comes back drawn *and* selected and takes the
+ * other trace off, a trace drawn beside somebody else's selection takes the
+ * selection over, and only a click on a trace that already has both takes the
+ * spectrum off the chart. The rule lives here rather than in the row so it can
+ * be read in one place and tested without mounting anything.
+ */
+
+import type { SpectrumVisibility } from './massReducer.ts';
+
+/** Which of a spectrum's two traces an icon stands for. */
+export type MassTraceKind = 'profile' | 'centroid';
+
+/**
+ * What one trace icon currently says.
+ *
+ * `drawn` is the state a plain checkbox cannot tell from `selected`: the trace
+ * is on the chart, but the labels, the acquisition table and the peak list are
+ * about some other spectrum.
+ */
+export type TraceIconState = 'hidden' | 'drawn' | 'selected';
+
+/** What a click on a trace icon asks the viewer for. */
+export interface TraceIconClick {
+  /**
+   * The visibility to ask of the spectrum. It names **both** traces every time,
+   * because they are an either/or: picking one is also the gesture that puts the
+   * other away, and a change that mentioned only the trace clicked would leave
+   * the two drawn together for exactly as long as nobody clicked the other.
+   */
+  visibility: SpectrumVisibility;
+  /**
+   * Whether the spectrum becomes the one the panels act on. `false` means the
+   * selection is left exactly as it is rather than cleared: a spectrum whose
+   * last trace has just been hidden is still the one being worked on, and its
+   * acquisition table has no business emptying itself because of a click on an
+   * eye.
+   */
+  select: boolean;
+}
+
+/**
+ * What a click on a trace icon asks for, given what the icon was saying.
+ *
+ * The click that hides a trace is the same click that would otherwise select
+ * it, which is why `select` and the visibility asked for always agree: any
+ * click leaving the spectrum on the chart also makes it the one being looked at,
+ * and the only click that takes it off is one on a trace that already had the
+ * selection.
+ * @param kind - The trace the icon stands for.
+ * @param state - What the icon was saying before the click.
+ * @returns The visibility to ask for, and whether to take the selection.
+ * @example
+ * nextTraceIconClick('centroid', 'drawn'); // { visibility: { showProfile: false, showCentroid: true }, select: true }
+ */
+export function nextTraceIconClick(
+  kind: MassTraceKind,
+  state: TraceIconState,
+): TraceIconClick {
+  const show = state !== 'selected';
+  return {
+    visibility: {
+      showProfile: show && kind === 'profile',
+      showCentroid: show && kind === 'centroid',
+    },
+    select: show,
+  };
+}
+
+/**
+ * What a trace icon says about a spectrum as it stands.
+ *
+ * Selection belongs to the spectrum rather than to either trace, so the icon of
+ * the drawn trace of the selected spectrum says `selected` while the other says
+ * `hidden` — which is the honest picture: it is that spectrum, not one of its
+ * traces, that the rest of the viewer is about.
+ * @param shown - Whether that trace is drawn.
+ * @param isSelected - Whether the spectrum is the one the panels act on.
+ * @returns The state the icon draws itself in.
+ */
+export function traceIconState(
+  shown: boolean,
+  isSelected: boolean,
+): TraceIconState {
+  if (!shown) return 'hidden';
+  return isSelected ? 'selected' : 'drawn';
+}

package/src/mass/core/writtenResolution.ts

@@ -0,0 +1,81 @@
+/**
+ * The weakest evidence of resolution, and the only one a bare peak table has:
+ * how many decimals its masses were written with.
+ *
+ * Weak because the decimals say what the exporter wrote rather than what the
+ * instrument resolved — an ion trap that exports four decimals is read as high
+ * resolution by it, and nothing in the numbers can tell that apart. Whole
+ * numbers are the case it is sure of: a table of them is a nominal-mass table
+ * whatever wrote it.
+ */
+
+import type { MassResolution } from './massResolution.ts';
+import { MZ_DECIMALS } from './massResolution.ts';
+
+/**
+ * The most decimals a written mass is looked at for.
+ *
+ * Beyond six the digits are the noise of a binary fraction rather than anything
+ * an exporter wrote, and every mass computed rather than typed reaches it.
+ */
+export const MAXIMUM_WRITTEN_DECIMALS = 6;
+
+/**
+ * The resolution the written masses imply.
+ *
+ * Whole numbers are a nominal-mass table; one or two decimals are a coarse
+ * measurement; three or more are taken for a resolved one. The decimals the
+ * masses were written with are also how many they are shown with, up to four.
+ * @param masses - The m/z of every peak, as they were read.
+ * @returns The verdict, `nominal` for a spectrum holding no peak at all.
+ */
+export function writtenResolution(masses: Float64Array): MassResolution {
+  const written = writtenDecimals(masses);
+  const kind = written === 0 ? 'nominal' : written < 3 ? 'low' : 'high';
+  return {
+    kind,
+    resolvingPower: null,
+    basis: 'decimals',
+    decimals: Math.min(written, MZ_DECIMALS.high),
+  };
+}
+
+/**
+ * How many decimals the masses were written with, the most any of them needs.
+ *
+ * Tested against a tolerance rather than for equality, because a JCAMP scales
+ * every value by its `##XFACTOR=` on the way in and `1631 × 0.1` is
+ * `163.10000000000002` — one decimal written, sixteen in the double. The count
+ * only ever grows, so each mass is tested from the decimals already found.
+ * @param masses - The m/z of every peak.
+ * @returns The decimals, from 0 to `MAXIMUM_WRITTEN_DECIMALS`.
+ */
+export function writtenDecimals(masses: Float64Array): number {
+  let most = 0;
+  for (const mass of masses) {
+    if (!Number.isFinite(mass)) continue;
+    while (most < MAXIMUM_WRITTEN_DECIMALS && !isWrittenWith(mass, most)) {
+      most++;
+    }
+    if (most === MAXIMUM_WRITTEN_DECIMALS) break;
+  }
+  return most;
+}
+
+/**
+ * Whether a mass was written with no more than so many decimals.
+ * @param mass - The mass.
+ * @param decimals - How many decimals.
+ * @returns Whether rounding it there changes nothing an exporter wrote.
+ */
+function isWrittenWith(mass: number, decimals: number): boolean {
+  return Math.abs(mass - Number(mass.toFixed(decimals))) <= DECIMAL_EPSILON;
+}
+
+/**
+ * How far a mass may sit from its rounding and still be written that way.
+ *
+ * Far below the smallest step tested, a millionth, and far above the error a
+ * scaling by `##XFACTOR=` leaves in a double, which is around 1e-13 at m/z 1000.
+ */
+const DECIMAL_EPSILON = 1e-8;

package/src/mass/ui/MassAboutDialog.tsx

@@ -0,0 +1,89 @@
+import { Dialog, DialogBody } from '@blueprintjs/core';
+
+import { credits } from '../../credits/core/credits.ts';
+import { CreditsList } from '../../credits/ui/CreditsList.tsx';
+import { massCommands } from '../core/massCommands.ts';
+
+import { MassLogo } from './MassLogo.tsx';
+
+export interface MassAboutDialogProps {
+  /** Whether the dialog is open. */
+  isOpen: boolean;
+  /** Close it. */
+  onClose: () => void;
+}
+
+/**
+ * What the viewer is, what it stands on, and who is owed for it.
+ *
+ * The credits are read from the shared registry rather than written here, so
+ * every page of the family names each work the same way, licence included.
+ * @param props - Component props.
+ * @returns The dialog.
+ */
+export function MassAboutDialog(props: MassAboutDialogProps) {
+  const { isOpen, onClose } = props;
+
+  return (
+    <Dialog
+      isOpen={isOpen}
+      onClose={onClose}
+      title={massCommands.about.title}
+      icon={<MassLogo size={20} />}
+      style={dialogStyle}
+    >
+      <DialogBody>
+        <div style={brandStyle}>
+          <MassLogo size={64} />
+          <div>
+            <p style={leadStyle}>react-cheminfo/mass</p>
+            <p style={paragraphStyle}>
+              Draws mass spectra read from JCAMP-DX and text files, picks the
+              peaks of a profile, labels them as you zoom, and says whether each
+              spectrum is high resolution.
+            </p>
+          </div>
+        </div>
+
+        <h4 style={headingStyle}>Built on</h4>
+        <CreditsList entries={MASS_CREDITS} />
+        <p style={paragraphStyle}>
+          The <strong>colours</strong> are Okabe and Ito&apos;s colour-universal
+          palette, so two traces stay distinguishable for a reader with a colour
+          vision deficiency.
+        </p>
+      </DialogBody>
+    </Dialog>
+  );
+}
+
+/** Every work the viewer borrows, in the order it reads a file through them. */
+const MASS_CREDITS = credits([
+  'jcampconverter',
+  'xy-parser',
+  'ms-spectrum',
+  'ml-gsd',
+  'ml-spectra-processing',
+  'convert-to-jcamp',
+  'react-mf',
+  'react-science',
+  'blueprint',
+]);
+
+const dialogStyle = { width: 'min(680px, 92vw)' } as const;
+
+const brandStyle = {
+  display: 'flex',
+  alignItems: 'flex-start',
+  gap: 16,
+} as const;
+
+const leadStyle = {
+  margin: '0 0 4px',
+  fontWeight: 600,
+  fontSize: 16,
+} as const;
+
+const paragraphStyle = { margin: '0 0 6px' } as const;
+
+const headingStyle = { margin: '14px 0 4px' } as const;