react-cheminfo 0.69.0 → 0.71.0

package/lib/mass/core/massDomain.js

@@ -0,0 +1,179 @@
+/**
+ * The window a chart opens on, worked out from the spectra it was handed.
+ *
+ * This is what "zoom to fit" and the first render both call, so it has to be
+ * right for a peak table of four rows and for a profile scan of half a million
+ * points alike, and it has to answer something usable when it is handed nothing
+ * at all — a chart with no data is still mounted, still measured, and still
+ * builds its scales.
+ */
+import { xMaxValue } from 'ml-spectra-processing';
+/**
+ * How much air is left either side of the outermost peak, as a fraction.
+ *
+ * A stick drawn exactly on the axis reads as a spectrum that was cut off there;
+ * two percent is enough to show that it was not.
+ */
+export const X_DOMAIN_PADDING = 0.02;
+/**
+ * How far above the tallest peak the intensity axis runs.
+ *
+ * The base peak carries the label nobody wants to lose — its m/z and its
+ * intensity, on two lines — and it is drawn above the stick. Twenty percent is
+ * the room those lines take at the top of a chart of any usual height.
+ */
+export const Y_DOMAIN_HEADROOM = 1.2;
+/**
+ * The window that shows everything currently drawn.
+ *
+ * A spectrum marked `excludeFromDomain` is left out of the extents, because it
+ * is a preview rather than data: a predicted pattern that appears and
+ * disappears with the pointer would throw away the zoom the user set every
+ * time it moved the axes. The exclusion is dropped when it would leave nothing
+ * at all — previewing into an empty chart has to show the preview, not an empty
+ * axis from 0 to 1.
+ *
+ * In mirror mode the negative half is the reflection of the positive one rather
+ * than its own extent. Two spectra compared head-to-head are only comparable if
+ * a peak of the same height means the same intensity in both halves; giving each
+ * half its own scale makes the weaker spectrum look as intense as the stronger,
+ * which is precisely the comparison the view exists to make.
+ * @param spectra - What the chart draws.
+ * @param mirror - Whether the chart reflects its spectra about zero. Defaults
+ * to `false`.
+ * @returns The window, in m/z and in intensity.
+ */
+export function fullDomain(spectra, mirror = false) {
+    const extent = traceExtent(spectra, false) ?? traceExtent(spectra, true);
+    if (extent === null)
+        return { x: [0, 1], y: [0, 1] };
+    const { xMinimum, xMaximum, yMaximum } = extent;
+    const padding = (xMaximum - xMinimum) * X_DOMAIN_PADDING;
+    // A single peak, or several at one m/z, has no width to take a fraction of.
+    const x = padding > 0
+        ? [xMinimum - padding, xMaximum + padding]
+        : [xMinimum - 1, xMaximum + 1];
+    const top = yMaximum > 0 ? yMaximum * Y_DOMAIN_HEADROOM : 1;
+    return { x, y: mirror ? [-top, top] : [0, top] };
+}
+/**
+ * What a fitted window was fitted *to*, as one string two renders can compare.
+ *
+ * The chart puts its window back to `fullDomain` when it is handed different
+ * data, and must not when the same data is merely drawn differently — so
+ * something has to tell the two apart. It is the identities that are compared
+ * and never the extents: a spectrum switched from its profile to its sticks
+ * moves the fitted window by a hair, and refitting on a hair throws away the
+ * zoom somebody set, which is the whole reason this exists. Loading a spectrum,
+ * closing one and reflecting the chart about zero are the changes that have to
+ * be shown, and every one of them shows up here.
+ *
+ * A spectrum kept out of the automatic domain is kept out of this too, for the
+ * reason it is kept out of the extents: a predicted pattern previewed under the
+ * pointer comes and goes with the pointer, and refitting on it would throw the
+ * zoom away every time a search result is read. The identities are joined by a
+ * character no identity holds, so `a b` and `a` then `b` are two fits.
+ * @param spectra - What the chart draws.
+ * @param mirror - Whether the chart reflects its spectra about zero. Defaults
+ * to `false`.
+ * @returns A string equal to itself exactly when a fit would be made to the
+ * same thing.
+ */
+export function fittedTo(spectra, mirror = false) {
+    let key = mirror ? 'mirror' : 'upward';
+    for (const spectrum of spectra) {
+        if (spectrum.excludeFromDomain)
+            continue;
+        key += `\u0000${spectrum.id}`;
+    }
+    return key;
+}
+/**
+ * The tallest intensity among the traces a set of spectra currently draws.
+ *
+ * What "how tall is this chart" comes to, in the units the spectra are in, with
+ * the headroom `fullDomain` adds left off — so it answers a question about the
+ * measurement rather than about the plot. A preview kept out of the extents is
+ * kept out of this too, and a chart holding nothing but a preview is measured
+ * by it rather than answering zero.
+ * @param spectra - The spectra to measure, drawn or not.
+ * @returns The tallest intensity drawn, or `0` when nothing is.
+ */
+export function basePeakOf(spectra) {
+    const extent = traceExtent(spectra, false) ?? traceExtent(spectra, true);
+    return extent === null ? 0 : extent.yMaximum;
+}
+/**
+ * How much of the axis framing a peak shows, either side of its mass.
+ *
+ * Wide enough to hold the isotopologue cluster of a singly charged ion, because
+ * a peak is read in its cluster and not alone: the M+1 says how much carbon it
+ * holds and the spacing says what charge it carries.
+ */
+export const MZ_FRAME_HALF_WIDTH = 2.5;
+/**
+ * The window that frames one mass, keeping the intensity axis where it was.
+ *
+ * The vertical extent is deliberately not recomputed from what falls inside the
+ * new window: a click is a request to look somewhere else along the m/z axis,
+ * and rescaling the height at the same time makes whatever was just clicked fill
+ * the plot, so every peak looks like the base peak and the one number the eye
+ * reads off a spectrum stops meaning anything. It is only worked out from the
+ * spectra when the chart has no window of its own to keep.
+ * @param mz - The mass to frame.
+ * @param spectra - What the chart is drawing, for the height it opens on.
+ * @param domain - The window the chart is showing, `null` when it is fitting.
+ * @param options - How wide a window, and whether the chart is mirrored.
+ * @returns The window to show.
+ */
+export function mzFrame(mz, spectra, domain, options = {}) {
+    const { halfWidth = MZ_FRAME_HALF_WIDTH, mirror = false } = options;
+    const y = domain?.y ?? fullDomain(spectra, mirror).y;
+    return { x: [mz - halfWidth, mz + halfWidth], y };
+}
+/**
+ * The extremes over every trace that is currently drawn.
+ * @param spectra - What the chart draws.
+ * @param includeExcluded - Whether to count the spectra kept out of the domain.
+ * @returns The extremes, or `null` when nothing is drawn.
+ */
+function traceExtent(spectra, includeExcluded) {
+    let extent = null;
+    for (const spectrum of spectra) {
+        if (!includeExcluded && spectrum.excludeFromDomain)
+            continue;
+        if (spectrum.showProfile && spectrum.profile !== null) {
+            extent = widen(extent, spectrum.profile);
+        }
+        if (spectrum.showCentroid)
+            extent = widen(extent, spectrum.centroid);
+    }
+    return extent;
+}
+/**
+ * Grow an extent to cover one more trace.
+ *
+ * The m/z ends are read off the first and last sample rather than searched for:
+ * `MassTrace.x` is increasing by construction, so a scan would walk several
+ * hundred thousand points of a profile to learn what index zero already says.
+ * @param extent - What has been covered so far, `null` for nothing.
+ * @param trace - The trace to cover as well.
+ * @returns The grown extent, unchanged when the trace holds no point.
+ */
+function widen(extent, trace) {
+    const { x, y } = trace;
+    if (x.length === 0 || y.length === 0)
+        return extent;
+    const first = x[0];
+    const last = x.at(-1);
+    const tallest = xMaxValue(y);
+    if (extent === null) {
+        return { xMinimum: first, xMaximum: last, yMaximum: tallest };
+    }
+    return {
+        xMinimum: Math.min(extent.xMinimum, first),
+        xMaximum: Math.max(extent.xMaximum, last),
+        yMaximum: Math.max(extent.yMaximum, tallest),
+    };
+}
+//# sourceMappingURL=massDomain.js.map

package/lib/mass/core/massDomain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"massDomain.js","sourceRoot":"","sources":["../../../src/mass/core/massDomain.ts"],"names":[],"mappings":"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"}

package/lib/mass/core/massEditorApi.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The handle a host drives the viewer through.
+ *
+ * A handle rather than props, for the reason NMRium uses one: "frame this peak"
+ * and "take these spectra" are *gestures*, and a gesture expressed as a prop has
+ * to change to be obeyed — so asking for the same window twice does nothing the
+ * second time, and a host ends up inventing a nonce to make it work.
+ */
+import type { MassDomain, MassSpectrum } from './massSpectrum.ts';
+/** How much room to leave either side of a mass a host asks to be framed. */
+export interface ZoomToMzOptions {
+    /**
+     * How much of the m/z axis to show either side of the mass.
+     * @default MZ_FRAME_HALF_WIDTH
+     */
+    halfWidth?: number;
+}
+/** What a host can ask of the viewer. */
+export interface MassEditorHandle {
+    /** The spectra that are open, in the order they were loaded. */
+    getSpectra: () => MassSpectrum[];
+    /** Draw these instead of what is open, and refit to them. */
+    setSpectra: (spectra: MassSpectrum[]) => void;
+    /** Draw these as well as what is open. */
+    addSpectra: (spectra: MassSpectrum[]) => void;
+    /**
+     * Read files the way a drop on the chart reads them, and add what they hold.
+     * Resolves once every file has been read; what could not be read is said in
+     * the status bar.
+     */
+    openFiles: (files: readonly File[]) => Promise<void>;
+    /** Close every spectrum. */
+    clear: () => void;
+    /** Show this window. */
+    setDomain: (domain: MassDomain) => void;
+    /** Show what fits. */
+    resetDomain: () => void;
+    /**
+     * Frame a mass, keeping the intensity axis as it is.
+     *
+     * The commonest thing a host wants: a peak named in a table beside the viewer
+     * is clicked, and the chart should go there.
+     */
+    zoomToMz: (mz: number, options?: ZoomToMzOptions) => void;
+    /** Point the panels at one spectrum, or at none. */
+    selectSpectrum: (id: string | null) => void;
+}
+/**
+ * A click on the plot, as the viewer tells its host about it.
+ *
+ * A click is a press let go over the plot without travelling: the end of a zoom
+ * drag is never one, and a click on the axis labels is not reported.
+ */
+export interface MassPlotClick {
+    /** Where it landed on the m/z axis. */
+    mz: number;
+    /**
+     * The m/z of the picked peak within reach of the click, `null` when it landed
+     * on none — an empty stretch of the plot is not a peak of zero.
+     */
+    peakMz: number | null;
+    /** Identity of the spectrum selected when it was made, `null` for none. */
+    spectrumId: string | null;
+}
+//# sourceMappingURL=massEditorApi.d.ts.map

package/lib/mass/core/massEditorApi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"massEditorApi.d.ts","sourceRoot":"","sources":["../../../src/mass/core/massEditorApi.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAElE,6EAA6E;AAC7E,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,yCAAyC;AACzC,MAAM,WAAW,gBAAgB;IAC/B,gEAAgE;IAChE,UAAU,EAAE,MAAM,YAAY,EAAE,CAAC;IACjC,6DAA6D;IAC7D,UAAU,EAAE,CAAC,OAAO,EAAE,YAAY,EAAE,KAAK,IAAI,CAAC;IAC9C,0CAA0C;IAC1C,UAAU,EAAE,CAAC,OAAO,EAAE,YAAY,EAAE,KAAK,IAAI,CAAC;IAC9C;;;;OAIG;IACH,SAAS,EAAE,CAAC,KAAK,EAAE,SAAS,IAAI,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD,4BAA4B;IAC5B,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,wBAAwB;IACxB,SAAS,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,IAAI,CAAC;IACxC,sBAAsB;IACtB,WAAW,EAAE,MAAM,IAAI,CAAC;IACxB;;;;;OAKG;IACH,QAAQ,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,KAAK,IAAI,CAAC;IAC1D,oDAAoD;IACpD,cAAc,EAAE,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;CAC7C;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,uCAAuC;IACvC,EAAE,EAAE,MAAM,CAAC;IACX;;;OAGG;IACH,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,2EAA2E;IAC3E,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B"}

package/lib/mass/core/massEditorApi.js

@@ -0,0 +1,10 @@
+/**
+ * The handle a host drives the viewer through.
+ *
+ * A handle rather than props, for the reason NMRium uses one: "frame this peak"
+ * and "take these spectra" are *gestures*, and a gesture expressed as a prop has
+ * to change to be obeyed — so asking for the same window twice does nothing the
+ * second time, and a host ends up inventing a nonce to make it work.
+ */
+export {};
+//# sourceMappingURL=massEditorApi.js.map

package/lib/mass/core/massEditorApi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"massEditorApi.js","sourceRoot":"","sources":["../../../src/mass/core/massEditorApi.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/lib/mass/core/massFormat.d.ts

@@ -0,0 +1,78 @@
+/**
+ * How every number about a mass spectrum is written, wherever it is written.
+ *
+ * An m/z is written to the decimals the spectra on screen resolve — four for a
+ * high-resolution measurement, none for a nominal-mass table, as
+ * `mzDecimalsOf` settles it for all of them at once — and an intensity follows
+ * it. Settled once here, so a table, an axis label and a tooltip never disagree
+ * about how wide one number is.
+ */
+import type { MassResolution } from './massResolution.ts';
+import type { MassFormat } from './massSpectrum.ts';
+/** Decimals an intensity is written with, on the 0–100 scale. */
+export declare const INTENSITY_DECIMALS = 2;
+/**
+ * An m/z as every table, axis label and tooltip writes it.
+ *
+ * Always a fixed number of decimals, never `toPrecision` and never the shortest
+ * form that round-trips: a column of masses is read by running an eye down it,
+ * and `163` above `162.9871` above `164.1` is unreadable in a way that
+ * `163.0000` above `162.9871` above `164.1000` is not.
+ * @param mz - The mass-to-charge ratio.
+ * @param decimals - How many decimals the spectra on screen resolve, as
+ * `mzDecimalsOf` decides. Defaults to the high-resolution four.
+ * @returns The number as it is written.
+ */
+export declare function formatMz(mz: number, decimals?: number): string;
+/**
+ * An intensity as every table and tooltip writes it, on the 0–100 scale.
+ *
+ * It follows the m/z rather than being decided on its own: a nominal-mass peak
+ * table quotes relative intensities as whole percentages too, and one column of
+ * the same table rounded and the other not looks like a bug. Past the chart's
+ * own `SCIENTIFIC_ABOVE`, and under a hundredth — where two decimals would write
+ * a zero that is not one — the intensity is written as a power of ten, which is
+ * how the axis beside it spells such numbers too.
+ * @param intensity - The intensity, normalised to a base peak of 100, or the
+ * counts themselves for a spectrum that kept them.
+ * @param mzDecimals - How many decimals the masses beside it are written with.
+ * Defaults to the high-resolution four.
+ * @returns The number as it is written.
+ */
+export declare function formatIntensity(intensity: number, mzDecimals?: number): string;
+/**
+ * A range of masses, low end first, as the list and the table write it.
+ * @param masses - The m/z of every peak, ascending.
+ * @param decimals - How many decimals to write them with.
+ * @returns `43.8490 – 223.6762`, or `''` for a spectrum holding no peak.
+ */
+export declare function formatMzRange(masses: Float64Array, decimals: number): string;
+/**
+ * A format as a chemist writes it rather than as the code spells it.
+ * @param format - The format the spectrum was read from.
+ * @returns Its name; a format this package does not read, as it was given.
+ */
+export declare function massFormatLabel(format: MassFormat): string;
+/**
+ * What a resolution verdict is called, in the words a status line uses.
+ * @param resolution - The verdict.
+ * @returns `high resolution`, `low resolution` or `nominal mass`.
+ */
+export declare function resolutionLabel(resolution: MassResolution): string;
+/**
+ * A resolving power as it is quoted: approximately, and to two figures.
+ *
+ * Two significant figures because that is all a median over a score of peaks
+ * can claim, and because `R ≈ 47,000` is how an instrument's resolution is
+ * quoted on its data sheet.
+ * @param resolvingPower - The resolving power `m / Δm`.
+ * @returns `R ≈ 47,000`.
+ */
+export declare function resolvingPowerLabel(resolvingPower: number): string;
+/**
+ * How a verdict was reached, said as a reader would want it said.
+ * @param resolution - The verdict.
+ * @returns The sentence fragment, e.g. `measured on the peak widths`.
+ */
+export declare function resolutionBasisLabel(resolution: MassResolution): string;
+//# sourceMappingURL=massFormat.d.ts.map

package/lib/mass/core/massFormat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"massFormat.d.ts","sourceRoot":"","sources":["../../../src/mass/core/massFormat.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAQH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,iEAAiE;AACjE,eAAO,MAAM,kBAAkB,IAAI,CAAC;AAEpC;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,SAAmB,GAAG,MAAM,CAExE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,MAAM,EACjB,UAAU,SAAmB,GAC5B,MAAM,CAQR;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAK5E;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAE1D;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,cAAc,GAAG,MAAM,CAElE;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CAElE;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,cAAc,GAAG,MAAM,CAEvE"}

package/lib/mass/core/massFormat.js

@@ -0,0 +1,168 @@
+/**
+ * How every number about a mass spectrum is written, wherever it is written.
+ *
+ * An m/z is written to the decimals the spectra on screen resolve — four for a
+ * high-resolution measurement, none for a nominal-mass table, as
+ * `mzDecimalsOf` settles it for all of them at once — and an intensity follows
+ * it. Settled once here, so a table, an axis label and a tooltip never disagree
+ * about how wide one number is.
+ */
+import { SCIENTIFIC_ABOVE, formatScientific, } from "../../chart/core/axisLabels.js";
+import { formatInteger } from "../../format/core/numbers.js";
+import { MZ_DECIMALS } from "./massResolution.js";
+/** Decimals an intensity is written with, on the 0–100 scale. */
+export const INTENSITY_DECIMALS = 2;
+/**
+ * An m/z as every table, axis label and tooltip writes it.
+ *
+ * Always a fixed number of decimals, never `toPrecision` and never the shortest
+ * form that round-trips: a column of masses is read by running an eye down it,
+ * and `163` above `162.9871` above `164.1` is unreadable in a way that
+ * `163.0000` above `162.9871` above `164.1000` is not.
+ * @param mz - The mass-to-charge ratio.
+ * @param decimals - How many decimals the spectra on screen resolve, as
+ * `mzDecimalsOf` decides. Defaults to the high-resolution four.
+ * @returns The number as it is written.
+ */
+export function formatMz(mz, decimals = MZ_DECIMALS.high) {
+    return mz.toFixed(decimals);
+}
+/**
+ * An intensity as every table and tooltip writes it, on the 0–100 scale.
+ *
+ * It follows the m/z rather than being decided on its own: a nominal-mass peak
+ * table quotes relative intensities as whole percentages too, and one column of
+ * the same table rounded and the other not looks like a bug. Past the chart's
+ * own `SCIENTIFIC_ABOVE`, and under a hundredth — where two decimals would write
+ * a zero that is not one — the intensity is written as a power of ten, which is
+ * how the axis beside it spells such numbers too.
+ * @param intensity - The intensity, normalised to a base peak of 100, or the
+ * counts themselves for a spectrum that kept them.
+ * @param mzDecimals - How many decimals the masses beside it are written with.
+ * Defaults to the high-resolution four.
+ * @returns The number as it is written.
+ */
+export function formatIntensity(intensity, mzDecimals = MZ_DECIMALS.high) {
+    const decimals = mzDecimals === 0 ? 0 : INTENSITY_DECIMALS;
+    if (intensity === 0)
+        return (0).toFixed(decimals);
+    const size = Math.abs(intensity);
+    if (size >= SCIENTIFIC_ABOVE || size < PLAIN_BELOW) {
+        return formatScientific(intensity, INTENSITY_DECIMALS);
+    }
+    return intensity.toFixed(decimals);
+}
+/**
+ * A range of masses, low end first, as the list and the table write it.
+ * @param masses - The m/z of every peak, ascending.
+ * @param decimals - How many decimals to write them with.
+ * @returns `43.8490 – 223.6762`, or `''` for a spectrum holding no peak.
+ */
+export function formatMzRange(masses, decimals) {
+    if (masses.length === 0)
+        return '';
+    const first = masses[0];
+    const last = masses.at(-1);
+    return `${formatMz(first, decimals)} – ${formatMz(last, decimals)}`;
+}
+/**
+ * A format as a chemist writes it rather than as the code spells it.
+ * @param format - The format the spectrum was read from.
+ * @returns Its name; a format this package does not read, as it was given.
+ */
+export function massFormatLabel(format) {
+    return FORMAT_LABELS.get(format) ?? format;
+}
+/**
+ * What a resolution verdict is called, in the words a status line uses.
+ * @param resolution - The verdict.
+ * @returns `high resolution`, `low resolution` or `nominal mass`.
+ */
+export function resolutionLabel(resolution) {
+    return RESOLUTION_LABELS[resolution.kind];
+}
+/**
+ * A resolving power as it is quoted: approximately, and to two figures.
+ *
+ * Two significant figures because that is all a median over a score of peaks
+ * can claim, and because `R ≈ 47,000` is how an instrument's resolution is
+ * quoted on its data sheet.
+ * @param resolvingPower - The resolving power `m / Δm`.
+ * @returns `R ≈ 47,000`.
+ */
+export function resolvingPowerLabel(resolvingPower) {
+    return `R ≈ ${formatInteger(Number(resolvingPower.toPrecision(2)))}`;
+}
+/**
+ * How a verdict was reached, said as a reader would want it said.
+ * @param resolution - The verdict.
+ * @returns The sentence fragment, e.g. `measured on the peak widths`.
+ */
+export function resolutionBasisLabel(resolution) {
+    return BASIS_LABELS[resolution.basis];
+}
+/**
+ * The intensity below which two decimals have nothing left to say it in.
+ *
+ * A hundredth, which is exactly where `INTENSITY_DECIMALS` runs out: `0.01` is
+ * the smallest number two decimals can write, and everything under it rounds to
+ * a zero that is not one.
+ */
+const PLAIN_BELOW = 1e-2;
+/**
+ * How each format is spelled where it is shown: `mzML` and `netCDF` are the
+ * names of the standards, capitals and all, and a table that showed `mzml`
+ * would read as a typo in a panel whose whole purpose is to quote the file
+ * faithfully. Every format a reader of the family hands spectra over in, the
+ * vendor ones included, since a host reading them hands the format over too.
+ */
+const FORMAT_LABELS = new Map([
+    ['jcamp', 'JCAMP-DX'],
+    ['text', 'Text, two columns'],
+    ['calculated', 'Calculated'],
+    ['mzml', 'mzML'],
+    ['mzxml', 'mzXML'],
+    ['mzdata', 'mzData'],
+    ['imzml', 'imzML'],
+    ['mzmlb', 'mzMLb'],
+    ['netcdf', 'netCDF'],
+    ['mgf', 'MGF'],
+    ['msp', 'MSP library'],
+    ['msn', 'MS1/MS2 text'],
+    ['dta', 'Sequest DTA'],
+    ['pkl', 'Micromass peak list'],
+    ['asm', 'Allotrope ASM'],
+    ['thermo', 'Thermo RAW'],
+    ['uep', 'Waters UNIFI package'],
+    ['watersraw', 'Waters RAW'],
+    ['wiff', 'SCIEX WIFF'],
+    ['wiff2', 'SCIEX WIFF2'],
+    ['wiffscan', 'SCIEX WIFF scan file'],
+    ['shimadzu', 'Shimadzu'],
+    ['chemstationms', 'Agilent ChemStation MS'],
+    ['chemstationch', 'Agilent ChemStation trace'],
+    ['chemstationuv', 'Agilent ChemStation UV'],
+    ['agilentdad', 'Agilent MassHunter device'],
+    ['masshunter', 'Agilent MassHunter'],
+    ['brukerflex', 'Bruker flex'],
+    ['brukertsf', 'Bruker timsTOF (TSF)'],
+    ['brukertdf', 'Bruker timsTOF (TDF)'],
+    ['penx', 'PerkinElmer TotalChrom'],
+    ['varian', 'Varian Saturn'],
+    ['spc', 'Galactic SPC'],
+    ['wdf', 'Renishaw WDF'],
+    ['targetraster', 'AP-MALDI target raster'],
+]);
+/** How each kind of resolution is named. */
+const RESOLUTION_LABELS = {
+    high: 'high resolution',
+    low: 'low resolution',
+    nominal: 'nominal mass',
+};
+/** How each basis of a verdict is said. */
+const BASIS_LABELS = {
+    peakWidth: 'measured on the peak widths',
+    instrument: 'stated by the file',
+    decimals: 'read off the decimals written',
+};
+//# sourceMappingURL=massFormat.js.map

package/lib/mass/core/massFormat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"massFormat.js","sourceRoot":"","sources":["../../../src/mass/core/massFormat.ts"],"names":[],"mappings":"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"}

package/lib/mass/core/massMeta.d.ts

@@ -0,0 +1,85 @@
+/**
+ * What the file says about how the spectrum was acquired, made displayable.
+ *
+ * A JCAMP written by a Thermo instrument carries the answer to every question a
+ * chemist asks of a spectrum — which analyser, which polarity, which collision
+ * energy — but carries it in whichever of two record bags the exporting
+ * software felt like using, and leaves half of them blank. A JCAMP of the older
+ * MS dialect states the same facts under standard records of its own,
+ * `##.SPECTROMETER TYPE=` and `##.IONIZATION MODE=`. So each field names the
+ * records it may live in, in the order they are worth trying, and anything
+ * still blank falls back to the instrument's own scan description.
+ *
+ * A field that is absent or empty is left out entirely rather than shown as a
+ * dash, which is what keeps the table short enough to read at a glance: every
+ * line in it is a fact the file actually stated.
+ */
+import type { MassMeta } from './massSpectrum.ts';
+/**
+ * The two record bags a JCAMP reader offers.
+ *
+ * `jcampconverter` splits the records in two — `##ORIGIN=` and the other
+ * standard labels into `info`, keyed without their spaces, and the
+ * `$`-prefixed user-defined ones into `meta` with the `$` stripped — and a
+ * record belongs to one bag or the other, never both.
+ */
+export interface MassMetaSource {
+    /**
+     * The standard records, keyed without their `##` and without spaces.
+     * @default undefined
+     */
+    info?: Record<string, unknown>;
+    /**
+     * The `$`-prefixed user-defined records, keyed without their `##$`.
+     * @default undefined
+     */
+    meta?: Record<string, unknown>;
+    /**
+     * The title, when the reader kept it apart from the records.
+     * @default undefined
+     */
+    title?: string;
+}
+/** One record a row of the table can be read from, and written back to. */
+export interface MassMetaRecord {
+    /** The record's label as the reader keys it, without its `##` or its `$`. */
+    key: string;
+    /** Whether it is a standard record rather than a `$`-prefixed one. */
+    info: boolean;
+}
+/**
+ * Read the acquisition metadata a file carries.
+ *
+ * Returns `null` rather than an empty table when the file said nothing at all,
+ * so the panel can leave the section out instead of drawing a heading over
+ * nothing — the normal outcome for a pasted peak list.
+ * @param source - The record bags the reader recovered.
+ * @returns The metadata, or `null` when the file carries none.
+ */
+export declare function buildMassMeta(source: MassMetaSource): MassMeta | null;
+/**
+ * The record a row of the table is written back to.
+ *
+ * The inverse of the table below, and it lives beside it for that reason: a
+ * writer holding a second list of record names is a writer whose `MSLEVEL`
+ * becomes `MS_LEVEL` the day a spelling is added here, and the round trip then
+ * loses the field without anything going wrong loudly. Only the first of each
+ * row's records is offered — the others exist to read what other exporters
+ * wrote, and writing our own file is not the place to imitate them.
+ * @param label - The row's label, as the table displays it.
+ * @returns The record, or `null` when the label is not one of the table's rows.
+ */
+export declare function metaRecord(label: string): MassMetaRecord | null;
+/**
+ * A record's value as a trimmed string, whatever dynamic typing made of it.
+ *
+ * `jcampconverter` reads `##$SCANS=1` as the number `1` and a record written
+ * twice as an array of both values, so a row that is only ever shown has to
+ * accept all three shapes. A repeated record shows its first occurrence, which
+ * is the one the exporter wrote for the acquisition rather than for a later
+ * reprocessing of it.
+ * @param value - The record, as dynamic typing left it.
+ * @returns The value as text, `''` when there is none.
+ */
+export declare function recordText(value: unknown): string;
+//# sourceMappingURL=massMeta.d.ts.map

package/lib/mass/core/massMeta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"massMeta.d.ts","sourceRoot":"","sources":["../../../src/mass/core/massMeta.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAiB,MAAM,mBAAmB,CAAC;AAGjE;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,2EAA2E;AAC3E,MAAM,WAAW,cAAc;IAC7B,6EAA6E;IAC7E,GAAG,EAAE,MAAM,CAAC;IACZ,sEAAsE;IACtE,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,cAAc,GAAG,QAAQ,GAAG,IAAI,CAkBrE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAK/D;AAwHD;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAOjD"}