API Reference

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

Orchestration

class dp5.nmr_processing.nmr_ai.NMRData(nmr_source: List[str], solvent: str, output_folder: Path = PosixPath('/home/rk582/DP5'))

Container for processed experimental NMR data.

The class mirrors the DP4-AI workflow described in the 2020 Chemical Science paper: it accepts raw FID data or a pre-written description file, performs automated processing where possible, and stores the processed proton and carbon data required for the downstream assignment step.

Parameters:

nmr_source (list[str]) – Sequence of Bruker directories, JCAMP-DX files, or DP4-style description files.
solvent (str) – Solvent identifier used for solvent suppression and for aligning the NMR workflow with the DFT solvent model.
output_folder (pathlib.Path) – Folder used to cache processed spectra and write assignment plots.

assign(mol)

Assign processed experimental peaks to a candidate molecule.

The method selects the automated proton and carbon assignment routines when processed FID data are available. If the input came from a manual description file, it falls back to the simpler matching utilities used by legacy DP4 workflows.

Parameters:: mol (object) – Molecule object containing RDKit connectivity together with calculated shift arrays and atom labels.
Returns:: Two arrays containing experimental carbon shifts and experimental proton shifts in the same order as the calculated shifts stored on mol.
Return type:: tuple[list, list]

process_carbon()

Run the automated carbon processing pipeline.

The results are cached in output_folder / "carbondata" and include the processed spectrum, the final picked peaks, and bookkeeping about solvent peaks removed during referencing.

Returns:: None. The processed data are stored in carbondata.
Return type:: None

process_description(file)

Parse a manual DP4-style NMR description file.

Parameters:: file (pathlib.Path) – Path to a text file containing carbon shifts, proton shifts, equivalence groups, and optional omitted atoms.
Returns:: None. Parsed labels, shifts, and constraints are stored on the instance.
Return type:: None

process_proton()

Run the automated proton processing pipeline.

The results are cached in output_folder / "protondata" so that the expensive peak-model fitting stage does not have to be repeated across runs.

Returns:: None. The processed data are stored in protondata.
Return type:: None

search_files()

Inspect the provided inputs and dispatch them by format.

Bruker directories and JCAMP-DX files are parsed into frequency-domain data together with an nmrglue unit-conversion object. Plain text files are treated as manual NMR descriptions and parsed with dp5.nmr_processing.description_files.process_description().

Returns:: None. The method populates self.proton_fid, self.carbon_fid, or the manual description attributes in-place.
Return type:: None

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

dp5.nmr_processing.carbon.process.carbon_processing(total_spectral_ydata, uc, solvent)

Process a carbon FID into the peak list used by DP5 assignment.

The carbon pipeline follows the DP4-AI design more loosely than the proton path. It performs spectral correction, removes edge artefacts, iteratively fits strong peaks to suppress noise, removes solvent signals, and returns the experimental peak positions required by the carbon assignment algorithm.

Parameters:

total_spectral_ydata (numpy.ndarray) – Complex frequency-domain spectrum.
uc (object) – nmrglue unit-conversion object for converting point indices into ppm.
solvent (str) – Solvent identifier used by the solvent-removal routine.

Returns:

PPM axis, processed spectrum, picked peak indices, simulated spectrum used during iterative picking, and indices removed as solvent.

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]

dp5.nmr_processing.carbon.assign.iterative_assignment(picked_peaks, spectral_xdata_ppm, total_spectral_ydata, calculated_shifts, C_labels)

Assign calculated carbon shifts to experimental carbon peaks.

The carbon workflow implements the three-stage logic from DP4-AI: an initial assignment with external scaling, a second assignment after internal scaling, and a final bias-driven reassignment pass that promotes intense nearby peaks when the first optimisation appears to have preferred weak local noise.

Compared with the proton algorithm, the carbon routine also handles the case where a single experimental peak can represent multiple equivalent carbons by horizontally duplicating the assignment matrix and progressively penalising repeat use of the same peak.

Parameters:

picked_peaks (array-like) – Experimental peak indices returned by the carbon peak picking stage.
spectral_xdata_ppm (numpy.ndarray) – PPM axis for the processed spectrum.
total_spectral_ydata (numpy.ndarray) – Processed carbon spectrum intensities.
calculated_shifts (array-like) – Calculated carbon shifts.
C_labels (array-like) – Carbon labels corresponding to calculated_shifts.

Returns:

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

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

dp5.nmr_processing.description_files.process_description(nmr_source)

Parse a legacy DP4 description file.

The text format stores carbon shifts on the first line, proton shifts on the third line, and optional equivalence or omission directives below. This parser preserves the loose syntax used by historical DP4 workflows so that the modern package can still consume manually curated descriptions when raw FID data are not available.

Parameters:: nmr_source (str or pathlib.Path) – Path to the description file.
Returns:: Carbon labels, carbon shifts, proton labels, proton shifts, equivalence groups, and omitted labels.
Return type:: tuple[list, list, list, list, list, list]