nmr-processing 19.1.0 → 19.3.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';
@@ -380,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: {
@@ -467,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;
@@ -484,8 +473,6 @@ export declare interface DatabaseNMREntry {
     signals?: NMRSignal1D[];
 }
 
-export declare type DataBaseStructure = DataBaseLevelStructure[];
-
 export declare interface DataResurrect {
     info: {
         solvent?: string;
@@ -701,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.
@@ -730,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
@@ -755,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>;
@@ -794,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[][];
@@ -926,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
@@ -1476,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 {
@@ -1649,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.
      */
@@ -1875,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 {
     /**
@@ -1883,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.
      */
@@ -1928,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;
 }
@@ -2791,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;
  })[];