API Reference

This page references the public classes and functions that define the dp5.nmr_processing workflow.

Orchestration

Processing Entrypoints

dp5.nmr_processing.proton.process.proton_processing(total_spectral_ydata, uc, solvent)

Process a proton FID into assignment-ready multiplets.

The proton pipeline implements the most complete DP4-AI processing path: spectral correction, derivative-based peak picking, BIC-guided peak-model pruning, solvent removal, and region simulation for later integration.

Parameters:

  • total_spectral_ydata (numpy.ndarray) – Complex frequency-domain proton spectrum.

  • uc (object) – nmrglue unit-conversion object for converting point indices into ppm and Hz.

  • solvent (str) – Solvent identifier used for solvent detection and referencing.

Returns:

PPM axis, processed spectrum, final peak regions, grouped peaks, fitted peak indices, combined fit parameters, and simulated regions for downstream integration.

Return type:

tuple

Assignment Algorithms

dp5.nmr_processing.proton.assign.iterative_assignment(mol, exp_peaks, calculated_shifts, H_labels, rounded_integrals)

Assign calculated proton shifts to processed multiplet centres.

The implementation mirrors the DP4-AI proton assignment strategy described in the paper and ESI. A first pass uses external scaling, methyl groups are assigned as integral-constrained bundles, the remaining protons are matched with a Hungarian optimisation over a probability matrix, and the assignment is repeated after internal scaling until it converges.

Parameters:

  • mol (object) – RDKit molecule used to identify methyl groups from connectivity.

  • exp_peaks (numpy.ndarray) – Experimental multiplet centres in ppm, expanded according to the rounded integrals so that peaks can be assigned multiple times.

  • calculated_shifts (numpy.ndarray) – Calculated proton shifts from DFT or a surrogate model.

  • H_labels (numpy.ndarray) – Proton labels corresponding to calculated_shifts.

  • rounded_integrals (numpy.ndarray) – Integer-like multiplet integrals derived from the deconvolved proton spectrum.

Returns:

Assigned calculated shifts, assigned experimental peaks, assigned labels, and the final scaled shifts used internally.

Return type:

tuple[list, list, list, numpy.ndarray]

Peak Modelling and Manual Inputs

dp5.nmr_processing.proton.bic_minimisation.BIC_minimisation_region_full(ind1, uc, peak_regions, grouped_peaks, total_spectral_ydata, corr_distance, std)

Fit and prune a Pearson-VII model for a single proton region.

The routine constructs an initial multi-peak model from the candidate peaks in one region, relaxes the Pearson-VII parameters with lmfit, and then removes peaks one at a time whenever doing so lowers the Bayesian Information Criterion by more than a fixed threshold.

Parameters:

  • ind1 (int) – Region index within peak_regions.

  • uc (object) – nmrglue unit-conversion object.

  • peak_regions (sequence) – Regions of the spectrum identified as containing proton signal.

  • grouped_peaks (sequence) – Candidate peak indices grouped by region.

  • total_spectral_ydata (numpy.ndarray) – Processed proton spectrum intensities.

  • corr_distance (int) – Correlation distance used to constrain peak widths and movement during fitting.

  • std (float) – Estimated noise level.

Returns:

Surviving fitted peaks, fitted parameters, and the simulated line shape for the region.

Return type:

tuple[list, lmfit.Parameters, numpy.ndarray]

dp5.nmr_processing.proton.bic_minimisation.multiproc_BIC_minimisation(peak_regions, grouped_peaks, total_spectral_ydata, corr_distance, uc, std)

Fit all proton regions in parallel and rebuild the final multiplets.

This wrapper dispatches BIC_minimisation_region_full() over all preliminary proton regions, collects the per-region peak models, and then rebuilds the final region boundaries after splitting fitted groups that are more than 20 Hz apart.

Parameters:

  • peak_regions (sequence) – Preliminary proton signal regions.

  • grouped_peaks (sequence) – Candidate peak indices grouped by preliminary region.

  • total_spectral_ydata (numpy.ndarray) – Processed proton spectrum intensities.

  • corr_distance (int) – Correlation distance estimated during spectral processing.

  • uc (object) – nmrglue unit-conversion object.

  • std (float) – Estimated noise level.

Returns:

Final picked peaks, grouped peaks, region boundaries, simulated global fit, and the combined fitted parameters.

Return type:

tuple