nmr-processing 19.0.3 → 19.2.0

package/dist/nmr-processing.d.ts

@@ -41,7 +41,6 @@ import type { ForwardLP1DOptions } from '@zakodium/nmr-types';
 import type { ForwardLPOptions } from '@zakodium/nmr-types';
 import { FromTo } from 'cheminfo-types';
 import type { GaussianOptions } from '@zakodium/nmr-types';
-import { GeneralAssignment as GeneralAssignment_2 } from './utils/generalAssignment/buildAssignments.js';
 import type { GenerateSpectrumOptions } from 'spectrum-generator';
 import type { GroupedDiaID } from 'openchemlib-utils';
 import type { GSDOptions } from 'ml-gsd';
@@ -57,7 +56,6 @@ import type { JoinBroadPeaksOptions } from 'ml-gsd';
 import type { LevenbergMarquardtOptions } from 'ml-levenberg-marquardt';
 import type { LightLogger } from 'cheminfo-types';
 import type { Logger } from 'cheminfo-types';
-import { MatchingMultiplicity as MatchingMultiplicity_2 } from '../index.ts';
 import { Matrix } from 'ml-matrix';
 import type { MatrixOptions } from '@zakodium/nmr-types';
 import type { Molecule } from 'openchemlib';
@@ -68,13 +66,9 @@ import type { NmrData2DFt } from 'cheminfo-types';
 import type { NMRPeak1D } from '@zakodium/nmr-types';
 import { NMRRange } from '@zakodium/nmr-types';
 import type { NMRSignal1D } from '@zakodium/nmr-types';
-import { NMRZoneWithID as NMRZoneWithID_2 } from './xyzAutoZonesPicking.ts';
 import type { NumberArray } from 'cheminfo-types';
 import type { NUSDimension2Options } from '@zakodium/nmr-types';
 import type { OCLMolecule } from 'cheminfo-types';
-import { OneDimensionalAssignment as OneDimensionalAssignment_2 } from './utils/oneDimensionalAssignment/buildAssignments.js';
-import { OneDimensionalAssignment as OneDimensionalAssignment_3 } from '../index.js';
-import { OneLetterMultiplet as OneLetterMultiplet_2 } from './MultiplicityPatterns.js';
 import type { OptimizePeaksOptions } from 'ml-gsd';
 import type { OptionsSG1D } from 'spectrum-generator';
 import type { Peak1D } from '@zakodium/nmr-types';
@@ -100,7 +94,6 @@ import type { SineBellOptions } from '@zakodium/nmr-types';
 import type { SymmetrizeCosyLikeOptions } from '@zakodium/nmr-types';
 import type { TopicMolecule } from 'openchemlib-utils';
 import type { TrafOptions } from '@zakodium/nmr-types';
-import type { XDistributionStats } from 'ml-spectra-processing';
 import type { XRobustDistributionStats } from 'ml-spectra-processing';
 import type { XYNumber } from 'spectrum-generator';
 import type { ZeroFillingDimension1Options } from '@zakodium/nmr-types';
@@ -120,8 +113,8 @@ declare type ApodizationDimension2 = FilterFactory<Entry2D, Apodization2D2Option
 
 export declare function apodizationXReIm(data: Required<NmrData1D>, options: Apodization1DOptions): {
     x: Float64Array<ArrayBufferLike>;
-    re: Float64Array<ArrayBufferLike>;
-    im: Float64Array<ArrayBufferLike>;
+    re: Float64Array<ArrayBuffer>;
+    im: Float64Array<ArrayBuffer>;
 };
 
 /**
@@ -129,7 +122,7 @@ export declare function apodizationXReIm(data: Required<NmrData1D>, options: Apo
  * @param data
  * @param options
  */
-export declare function apodize(data: DoubleArray, options: ApplyWindowOptions): Float64Array<ArrayBufferLike>;
+export declare function apodize(data: DoubleArray, options: ApplyWindowOptions): Float64Array<ArrayBuffer>;
 
 declare function applyFilter(datum: Entry1D, filter: Filter1DOptions, logger?: Logger): void;
 
@@ -309,6 +302,21 @@ export declare interface CalculateDiffussionCoefficientOptions {
     timeCorrection: number;
 }
 
+/**
+ * Calculates the frequencies (in MHz) for a pair of nuclei based on the observed spectrometer frequency.
+ *
+ * - The first element of the `nucleus` array is the observed nucleus.
+ * - The second element is the indirect nucleus.
+ * - Returns an array: [frequency of observed nucleus, frequency of indirect nucleus].
+ *
+ * @param nucleus - Array of two nuclei (e.g., ['1H', '13C']).
+ *   - The first element is the observed nucleus.
+ *   - The second element is the indirect nucleus.
+ * @param frequency - The spectrometer frequency (in MHz) of the observed nucleus (first element of the nucleus array).
+ * @returns Array of frequencies in MHz: [frequency of observed nucleus, frequency of indirect nucleus].
+ */
+export declare function calculateRelativeFrequency(nucleus: string[], frequency: number): number[];
+
 declare interface CalculateT1Options {
     optimization?: CalculateT1OptionsOptimization;
 }
@@ -365,7 +373,7 @@ declare interface CouplingInput {
     s: [ID, ID];
 }
 
-export declare const couplingPatterns: OneLetterMultiplet_2[];
+export declare const couplingPatterns: OneLetterMultiplet[];
 
 export declare function createApodizationWindowData(options: {
     windowOptions: {
@@ -452,10 +460,6 @@ declare interface CTSignal {
     atoms: number[];
 }
 
-export declare type DataBaseLevelEntry = number | [number] | [number, number, number, number | null, number] | undefined | XDistributionStats;
-
-export declare type DataBaseLevelStructure = Record<string, DataBaseLevelEntry>;
-
 export declare interface DatabaseNMREntry {
     id: string;
     ocl?: OCLMolecule;
@@ -469,8 +473,6 @@ export declare interface DatabaseNMREntry {
     signals?: NMRSignal1D[];
 }
 
-export declare type DataBaseStructure = DataBaseLevelStructure[];
-
 export declare interface DataResurrect {
     info: {
         solvent?: string;
@@ -686,7 +688,7 @@ declare type FilterSymbols = (typeof Filters)[keyof typeof Filters];
  * Look for a multiplet based on the pattern name or abbreviation.
  * @param name - pattern name or abbreviation.
  */
-export declare function findMultiplet(name: string): MatchingMultiplicity_2 | undefined;
+export declare function findMultiplet(name: string): MatchingMultiplicity | undefined;
 
 /**
  * Finds a peak that can serve as a pivot point within specified boundaries.
@@ -715,9 +717,41 @@ export declare interface GeneralAssignment {
     assignment: SpectraDataWithIds[];
 }
 
-export declare function get13CAssignments(ranges: NMRRange[], molecule: Molecule, options?: Get13CAssignmentsOptions): Promise<OneDimensionalAssignment_3[]>;
+/**
+ * Generate possible 13C assignments for the provided 1D ranges using
+ * predicted carbon shifts for the given molecule. It is based on the paper
+ * Fully automatic assignment of small molecules' NMR spectra without relying
+ * on chemical shift predictions {@link https://doi.org/10.1002/mrc.4272}
+ *
+ * The function:
+ * - Predicts 13C spectra for the provided molecule.
+ * - Ensures signals include atoms, diaIDs and nbAtoms (throws otherwise).
+ * - Normalizes range integrations (missing integration values become 0).
+ * - Builds assignments using buildAssignments and the provided options.
+ *
+ * @param ranges - Array of NMR ranges to assign. Missing integration values are set to 0.
+ * @param molecule - openchemlib Molecule used for shift prediction.
+ * @param {Get13CAssignmentsOptions} options - to control assignment behavior.
+ * @returns Promise resolving to the assignment results produced by buildAssignments.
+ *
+ * @throws If predicted signals do not include required atoms/diaIDs/nbAtoms properties.
+ */
+export declare function get13CAssignments(ranges: NMRRange[], molecule: Molecule, options?: Get13CAssignmentsOptions): Promise<OneDimensionalAssignment[]>;
 
+/**
+ * Options for get13CAssignments.
+ *
+ * restrictionByCS: Partial restrictions applied to chemical-shift matching when building assignments.
+ * minScore: Minimum score to accept an assignment (default: 1).
+ * maxSolutions: Maximum number of assignment solutions to return (default: 10).
+ * nbAllowedUnAssigned: Number of allowed unassigned signals in a solution (default: 0).
+ * timeout: Time limit in milliseconds to finish the assignment procedure (default: 6000).
+ * predictionOptions: Options forwarded to the carbon prediction routine.
+ */
 export declare interface Get13CAssignmentsOptions {
+    /**
+     * Partial restrictions applied to chemical-shift matching.
+     */
     restrictionByCS?: Partial<RestrictionByCS1D>;
     /**
      * min score to accept an assignment
@@ -740,14 +774,33 @@ export declare interface Get13CAssignmentsOptions {
      */
     timeout?: number;
     /**
-     * prediction options
+     * prediction options forwarded to the carbon prediction.
      */
     predictionOptions?: PredictCarbonOptions;
 }
 
 export declare function get1DErrorFactor(spectrum: Entry1D): number;
 
-export declare function get1HAssignments(ranges: NMRRange[], molecule: Molecule, options?: Get1HAssignmentsOptions): Promise<OneDimensionalAssignment_2[]>;
+/**
+ * Generate possible 1H assignments for the provided 1D ranges using
+ * predicted proton shifts and integration values for the given molecule. It is based on the paper
+ * Fully automatic assignment of small molecules' NMR spectra without relying
+ * on chemical shift predictions {@link https://doi.org/10.1002/mrc.4272}
+ *
+ * The function:
+ * - Predicts 1H spectra for the provided molecule.
+ * - Ensures signals include atoms, diaIDs and nbAtoms (throws otherwise).
+ * - Normalizes range integrations (missing integration values become 0).
+ * - Builds assignments using buildAssignments and the provided options.
+ *
+ * @param ranges - Array of NMR ranges to assign. Missing integration values are set to 0.
+ * @param molecule - openchemlib Molecule used for shift prediction.
+ * @param {Get1HAssignmentsOptions} options - to control assignment behavior.
+ * @returns Promise resolving to the assignment results produced by buildAssignments.
+ *
+ * @throws If predicted signals do not include required atoms/diaIDs/nbAtoms properties.
+ */
+export declare function get1HAssignments(ranges: NMRRange[], molecule: Molecule, options?: Get1HAssignmentsOptions): Promise<OneDimensionalAssignment[]>;
 
 export declare interface Get1HAssignmentsOptions {
     restrictionByCS?: Partial<RestrictionByCS1D>;
@@ -779,7 +832,7 @@ export declare interface Get1HAssignmentsOptions {
 
 export declare function get2DErrorFactor(spectrum: Entry2D): Zone2DError;
 
-export declare function getAssignments(input: GetAutoAssignmentInput, options?: GetAssignmentsOptions): Promise<GeneralAssignment_2[]>;
+export declare function getAssignments(input: GetAutoAssignmentInput, options?: GetAssignmentsOptions): Promise<GeneralAssignment[]>;
 
 export declare interface GetAssignmentsOptions {
     justAssign?: AtomTypes[][];
@@ -891,15 +944,9 @@ export declare function getDatabase(url?: string, options?: {
 declare function getDiaIDs(range: Range): string[];
 
 /**
- * calculate the frequency of a nucleus with respect to a reference nucleus
- * @param nucleus
- * @param observedNucleusData
- */
-export declare function getFrequency(
-/**
- * nucleus to calculate the frequency
+ * @deprecated use getRelativeFrequency instead
  */
-nucleus: string, observedNucleusData: ObservedNucleusData): number;
+export declare const getFrequency: typeof getRelativeFrequency;
 
 declare interface GetKernelOptions {
     sigma?: number;
@@ -917,6 +964,7 @@ export declare function getPeakDelta(peak: Peak1D | NMRPeak1D, shiftTarget: Shif
 };
 
 export declare interface GetPeakListOptions extends GSDOptions, OptimizePeaksOptions, JoinBroadPeaksOptions {
+    smoothedY: NumberArray;
     /**
      * If it is true, the peaks parameters will be optimized.
      * @default false
@@ -935,6 +983,17 @@ export declare interface GetPeakListOptions extends GSDOptions, OptimizePeaksOpt
 
 declare function getPopulations(p: PopulationInput[]): PopulationOutput[];
 
+/**
+ * calculate the frequency of a nucleus with respect to a reference nucleus
+ * @param nucleus
+ * @param observedNucleusData
+ */
+export declare function getRelativeFrequency(
+/**
+ * nucleus to calculate the frequency
+ */
+nucleus: string, observedNucleusData: ObservedNucleusData): number;
+
 declare function getShiftGroups(sg: ShiftGroupEntry[]): {
     id: string;
     parentID: string;
@@ -1456,6 +1515,13 @@ export declare interface OptionsXYAutoPeaksPicking extends Partial<GetPeakListOp
      * frequency used to convert width and fwhm to Hz
      */
     frequency: number;
+    /**
+     * Controls the degree of baseline smoothing applied to the data before peak picking.
+     * Higher values (closer to 100) mean less smoothing, while lower values (closer to 1) increase smoothing.
+     * Useful for reducing noise and improving peak detection in spectra with varying baseline quality.
+     * @default 100
+     */
+    sensitivity?: number;
 }
 
 declare interface OptionsXYAutoRangesPicking {
@@ -1629,21 +1695,15 @@ declare interface PredictAllSpectraOptions {
 
 export declare interface PredictCarbonOptions {
     /**
-     * Custom database. Each entry in the levels should have
-     * an array as value [median] or [median, mean, sd, min, max, nb] for statistic purpose.
-     */
-    database?: DataBaseStructure;
-    /**
-     * Max level to take into account in the query. If is not specified
-     * the max level in the database will be used.
-     * @default 'maximum level in the database'
-     */
-    maxSphereSize?: number;
-    /**
-     * Predictor function that will use by default: 'https://nmr-prediction.service.zakodium.com/v1/predict/carbon'
+     * Predictor function. Will use by default webservice: https://nmr-prediction.service.zakodium.com/v1/predict/carbon
      * @default defaultCarbonPredictor
      */
     predictor?: PredictorFn;
+    /**
+     * Options to pass to the predictor function.
+     * @default {}
+     */
+    predictorOptions?: Record<string, unknown>;
     /**
      * Prediction cache handler.
      */
@@ -1855,7 +1915,7 @@ export declare interface PredictionOptionsByExperiment {
 /**
  * A function that should make a prediction for the given molecule and return the result.
  */
-declare type PredictorFn = (topicMolecule: TopicMolecule) => Promise<PredictionBase1D> | PredictionBase1D;
+declare type PredictorFn = (topicMolecule: TopicMolecule, options?: Record<string, unknown>) => Promise<PredictionBase1D> | PredictionBase1D;
 
 export declare interface PredictProtonOptions {
     /**
@@ -1863,6 +1923,11 @@ export declare interface PredictProtonOptions {
      * @default defaultProtonPredictor
      */
     predictor?: PredictorFn;
+    /**
+     * Options to pass to the predictor function.
+     * @default {}
+     */
+    predictorOptions?: Record<string, unknown>;
     /**
      * Prediction cache handler.
      */
@@ -1871,7 +1936,7 @@ export declare interface PredictProtonOptions {
 
 export declare function predictSpectra(molecule: Molecule, options?: PredictAllSpectraOptions): Promise<PredictSpectraResult>;
 
-declare interface PredictSpectraResult {
+export declare interface PredictSpectraResult {
     spectra: Array<PredictedSpectrum1D | PredictedSpectrum2D>;
     molecules: Array<{
         molfile: string;
@@ -1908,37 +1973,67 @@ export declare function rangesToACS(ranges: NMRRange[], options?: RangesToACSOpt
 
 export declare interface RangesToACSOptions {
     /**
-     * nucleus
+     * Nucleus type for the NMR experiment (e.g., '1H', '13C', '19F').
+     * Determines default formatting and frequency values.
      * @default '1H'
      */
     nucleus?: string;
     /**
-     * Sort the chemical shift values in ascending order
+     * If true, sorts the chemical shift values in ascending order (low to high ppm).
+     * If false, sorts in descending order (high to low ppm).
      * @default false
      */
     ascending?: boolean;
+    /**
+     * Specifies which types of information to include for each range or signal in the ACS string output.
+     * Each character in the string represents a data type:
+     *
+     * - 'I': Integral value (e.g., number of protons or integration value)
+     * - 'M': Multiplicity (e.g., singlet, doublet, triplet)
+     * - 'J': Coupling constants (J values in Hz)
+     * - 'A': Assignment (atom or group assignment)
+     *
+     * The order of characters determines the order of information in the output. Any combination or subset is allowed, e.g.:
+     *   'IMJ' (integral, multiplicity, coupling constants)
+     *   'MA' (multiplicity, assignment)
+     *   'I' (only integral)
+     *
+     * Example: 'IMJA' includes all available information in the order: Integral, Multiplicity, Assignment, Coupling constants.
+     *
+     * @default 'IMJA'
+     */
     format?: string;
     /**
-     * default value depends of nucleus
-     * @default '0.00'
+     * Format string for chemical shift (delta) values, using [numeral.js](https://numeraljs.com/) syntax.
+     * The default value depends on the nucleus type:
+     *   - '1H' and '19F': '0.00'
+     *   - '13C': '0.0'
+     * @default '0.00' for '1H' and '19F', '0.0' for '13C'
      */
     deltaFormat?: string;
     /**
-     * Number of decimals to round the scalar coupling value
+     * Format string for scalar coupling constants (J values), using [numeral.js](https://numeraljs.com/) syntax.
+     * Controls the number of decimals for J values in Hz.
      * @default '0.0'
      */
     couplingFormat?: string;
     /**
-     * default value depends of nucleus
-     * @default 400|100
+     * Observed frequency of the NMR experiment in MHz.
+     * The default value depends on the nucleus type:
+     *   - '1H' and '19F': 400
+     *   - '13C': 100
+     * @default 400 for '1H' and '19F', 100 for '13C'
      */
     observedFrequency?: number;
     /**
+     * If true, filters out ranges or signals with kind 'impurity' or 'solvent'.
+     * If false, includes all ranges and signals.
      * @default true
      */
     filter?: boolean;
     /**
-     * solvent name
+     * Name of the solvent used in the NMR experiment (e.g., 'CDCl3', 'DMSO').
+     * If provided, it will be included in the ACS string output.
      */
     solvent?: string;
 }
@@ -1946,7 +2041,7 @@ export declare interface RangesToACSOptions {
 export declare function rangesToTSV(ranges: NMRRange[]): string;
 
 export declare function rangesToXY(ranges: NMRRange[], options?: RangesToXYOptions): {
-    x: Float64Array<ArrayBufferLike>;
+    x: Float64Array<ArrayBuffer>;
     y: Float64Array<ArrayBuffer>;
 };
 
@@ -2171,7 +2266,7 @@ export declare function signals2DToZ(signals: NMRSignal2D[], options?: Signals2D
     maxY: number;
     minZ: number;
     maxZ: number;
-    z: Float64Array<ArrayBufferLike>[];
+    z: Float64Array<ArrayBuffer>[];
 };
 
 declare interface Signals2DToZOptions {
@@ -2488,10 +2583,28 @@ declare interface Traf<ShapeOption = TrafOptions> {
  */
 export declare function translateMultiplet(name: string): string;
 
+/**
+ * Options for specifying the region and resolution of the 2D spectrum
+ */
 declare interface TwoDOptions {
-    from: PointXY;
-    to: PointXY;
+    /**
+     * Defines the chemical shift range for proton and carbon axes
+     */
+    fromTo: {
+        proton: FromTo;
+        carbon: FromTo;
+    };
+    /**
+     * Number of points in each dimension (x and y)
+     */
     nbPoints: PointXY;
+    /**
+     * Optional peak width in each dimension (x and y), in Hz
+     */
+    width?: {
+        x: number;
+        y: number;
+    };
 }
 
 declare function unlink(range: Range, options?: UnlinkOptions): Range;
@@ -2753,7 +2866,7 @@ declare function unlink(range: Range, options?: UnlinkOptions): Range;
      kernel?: GetKernelOptions;
  }
 
- export declare function xyzJResAnalyzer(signals: NMRSignal2D[], options?: XYZJResAnalyzerOptions): NMRZoneWithID_2[] | (NMRSignal2D<Peak2D> & {
+ export declare function xyzJResAnalyzer(signals: NMRSignal2D[], options?: XYZJResAnalyzerOptions): NMRZoneWithID[] | (NMRSignal2D<Peak2D> & {
      id: string;
  })[];