Skip to main content

spectrochempy-nmr

NMR plugin for SpectroChemPy.

The plugin provides NMR-specific readers for vendor and exchange formats, validated 1D workflows, and processing for qualified 2D acquisitions. The 0.3 series stores paired 2D data as two ordinary complex channels. See the standalone NMR documentation for installation, readers, processing and supported acquisition profiles.

Installation

This plugin requires SpectroChemPy 1.1.0 or later (and remains restricted to SpectroChemPy versions below 2). Users who stay on SpectroChemPy 1.0.0 should keep an earlier compatible version of this plugin.

pip install "spectrochempy>=1.1.0,<2" "spectrochempy-nmr==0.3.0"

For an editable development install from this repository, see Development.

Usage

import spectrochempy as scp

dataset = scp.nmr.read("path/to/1/fid")
dataset = scp.nmr.read("path/to/1/pdata/1/1r")
dataset = scp.nmr.read("path/to/experiment", expno=1, procno=1)

experiment = scp.nmr.Experiment(dataset)
spectrum = experiment.process(apodization="em", lb=2.0, size=32768)

Use Experiment.process(replay="topspin") to replay supported TopSpin recipes explicitly. The 2D processing guide describes the qualified XFB workflow.

The current explicit apodization contract covers the public modes already exposed by Experiment.process(): em(lb=...), gm(lb=..., gb=...), and sp(ssb=..., pow=...).

The result of Experiment.process() also records the SpectroChemPy-owned processing trace in result.meta.nmr_processing["scp_processing"]. requested contains only the arguments explicitly provided by the user, whereas applied contains only the operations that were actually executed and the values they really consumed. This trace is attached to the result only: the source dataset is not mutated, the vendor procs profile remains purely descriptive, and phase="metadata" does not replay TopSpin PHC0/PHC1.

The NMR ppm/frequency unit context is also provided by this plugin:

from spectrochempy_nmr.units import set_nmr_context

set_nmr_context(104.3 * scp.ur.MHz)

The compatibility aliases scp.nmr.read_topspin(...) and scp.read_topspin(...) are kept for historical usage. TopSpin is a reader, so it is not exposed as dataset.read_topspin(...) or dataset.nmr.read_topspin(...).

Experimental Agilent NOESY States-TPPI

An opt-in prototype is available for explicitly annotated raw Agilent/Varian NOESY States data:

result = scp.nmr.process_agilent_noesy_states_tppi(
    raw_dataset,
    transport="none",  # or explicitly "var2pipe"
)

The input must declare seqfil='NOESY', phase=(1, 2), ni, np and arraydim, with a matching complex (arraydim, np // 2) matrix. The prototype performs two ordinary complex FFTs and returns two complex channels in the explicitly declared mathematical (RR, RI, IR, II) order. These labels are not a claim that the physical Agilent quadrature convention has been validated. It does not perform apodization, phasing, linear prediction, or universal vendor interpretation. Other Agilent sequences and encodings are rejected. This is experimental and is not part of the validated public processing workflow. The input must also declare ntraces=1; returned coordinates are provisional index coordinates and are not a calibrated physical frequency claim. Raw acquisition values are retained under raw_acquisition.

The returned native channels have an explicit component view:

channels = scp.nmr.process_agilent_noesy_states_tppi(raw_dataset)
components = scp.nmr.extract_noesy_components(channels)

channels is a standard complex NDDataset with dimensions ("c", "y", "x") and channel labels S_R, S_I. The c axis is mathematical and non-physical. The component mapping is explicit: RR=Re(S_R), RI=Re(S_I), IR=Im(S_R), and II=Im(S_I). This path uses ordinary core FFTs and does not use quaternion storage. Time-domain input must be unmasked; masks may be applied to the final spectrum and are retained by component extraction and native NDDataset persistence. The Agilent metadata and transport operation are an adapter boundary; the common channel engine receives only the normalized 3D dataset and an explicit reconstruction profile.

States-TPPI is the indirect-dimension acquisition mode; NOESY is only the first experimentally validated sequence using this adapter. The common engine does not select its calculation from the sequence or vendor identity. The normalized contract records quadrature_mode="states-tppi", explicit E1/E2 branch order, the validated f1coef, TPPI alternation state, normalization state and F2 transform convention. Other sequences are not thereby claimed to be experimentally validated.

The implementation is split into three layers:

  • processing/complex_channels.py owns the normalized NDDataset contract, the two core FFT calls and channel/component views;
  • processing/quadrature.py owns the single validated states-tppi reconstruction equation;
  • adapters/agilent_noesy.py owns the provisional Agilent metadata validation, transport conversion and branch demultiplexing.

The Agilent adapter is transitional. The common engine does not import readers, vendor adapters or spectrochempy_hypercomplex; future nmrglue-ng normalization will feed it through the same normalized-channel boundary.

Experimental neutral interop conversion

The plugin also exposes a generic converter for a validated normalized acquisition supplied by nmrglue.interop:

dataset = scp.nmr.from_interop(normalized_acquisition)

The first supported profile is a storage-normalized complex 1D FID. The converter accepts the neutral contract rather than a vendor or sequence name, preserves axes, provenance, acquisition metadata and applied operations, and does not perform FFT, scaling, conjugation, phasing or merging. A descriptive ReadResult is rejected until a profile-specific normalization step has established its guarantees. Existing read_agilent, read_topspin and merge behavior are unchanged in this experimental bridge.

Experimental Agilent interop facade

The complete normalized 1D path can be exercised without replacing the public reader:

dataset = scp.nmr.read_agilent_interop("experiment/", merge=False)
stacked = scp.nmr.read_agilent_interop(
    "experiment_01/", "experiment_02/", merge=True
)

The facade accepts acquisition directories or direct fid paths, delegates decoding and normalization to nmrglue-ng, returns a ScpObjectList for multiple acquisitions with merge=False, and uses the existing core stack() only after compatibility checks for merge=True. It does not replace read_agilent(), discover arbitrary recursive directories, or interpret the stacked axis as spectral F1. Its role is acquisition_index unless a validated experimental parameter is supplied by a future extension. Pseudo-2D acquisition is not implemented here. Stacked output retains the shared normalization contract and each acquisition's individual provenance, operation history, diagnostics, axis references and encoding.

Development

See CHANGELOG.rst for plugin release notes, including the unreleased development changes. The plugin maintains its own changelog; SpectroChemPy release notes can link to a specific published plugin version.

Install and run the standalone development hooks before submitting changes:

python -m pip install pre-commit
pre-commit install
pre-commit run --all-files

Hook revisions match the core's existing hygiene, spelling and Ruff hooks. The plugin configuration does not run core requirement, lazy-stub, version or release-note generators. Adapted third-party parsers and binary test fixtures are excluded from these mechanical checks. Ruff starts with its default lint rules rather than imposing the core's broader lint policy on the extracted package.

The experimental complex-channel processing path stores two complex channels in an ordinary NDDataset with shape (2, nF1, nF2) and dimensions ("c", "y", "x"). It uses the existing core complex FFTs and does not require spectrochempy-hypercomplex or numpy-quaternion. Native channel paths require a core exposing FFT_PREVALIDATION_API >= 1; they refuse to start on published cores 1.1.0/1.1.4, which retain ordinary 1D and interop support. The read-only prevalidation hook rejects unsupported FFT/IFFT requests before in-place changes. All readers and processing paths use ordinary numeric arrays. The optional hypercomplex extra and the legacy quaternion phasing handler have been removed. The former _channels NOESY function is consolidated into process_agilent_noesy_states_tppi.

CI covers ordinary numeric/1D and interop support on released cores 1.1.0 and 1.1.4 without a representation plugin. Native reader profiles, in-place refusal regressions, channel processing and persistence also run against the exact companion core commit with FFT prevalidation. Synthetic numerical agreement does not validate the physical quadrature of an uncharacterized acquisition or provide calibrated 2D frequency axes.

From the plugin directory, install the plugin against an installed compatible core (or install the desired core wheel first):

python -m pip install -e . pytest
python -m pytest tests/ -v

Tests and examples can run outside the monorepo. Real-data tests still use scp.preferences.datadir and its sibling testdata-extra; unavailable fixtures may cause skips. A scientific baseline must record which datasets were available and must not treat skipped cases as validated.

Build source and wheel distributions from this directory:

python -m pip install build
python -m build

Both distributions include LICENSE (CeCILL-B) and NMRGLUE_LICENSE.rst (the notice for the remaining adapted parsers). The plugin depends on nmrglue-ng for qualified Bruker processed 2D spectra. SpectroChemPy core does not require the NMR plugin or nmrglue-ng.

Metadata

Release files for spectrochempy-nmr 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for spectrochempy-nmr 0.3.0
File Size Uploaded Provenance Actions
spectrochempy_nmr-0.3.0.tar.gz 197.1 kB With provenance Details for spectrochempy_nmr-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for spectrochempy-nmr 0.3.0
File Interpreter ABI Platform Actions
spectrochempy_nmr-0.3.0-py3-none-any.whl Python 3 none any Details for spectrochempy_nmr-0.3.0-py3-none-any.whl

Total release size: 317.1 kB

Release files / spectrochempy_nmr-0.3.0.tar.gz

Download URL spectrochempy_nmr-0.3.0.tar.gz
Size 197.1 kB
Tags Source
SHA-256 checksum
How to use checksums
0e87b6e2ef1de11541093a478b97a0ce0d708317b2e68a44dcc2bdbf1ef3a1c9
BLAKE2b-256 checksum
How to use checksums
b9387c2a1e71340a258d62f6f11ad616d69c366d7c902d5d03e85e4d3f5291f8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

Release files / spectrochempy_nmr-0.3.0-py3-none-any.whl

Download URL spectrochempy_nmr-0.3.0-py3-none-any.whl
Size 120.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7be4c965692f6d869834992c96620e09c53c1f395e92bfd529bae02c56694bef
BLAKE2b-256 checksum
How to use checksums
b562e222a280ccd5bc3d4d018f7932f5554b0cae7ae2cde4427e2b267986a68e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

Security for spectrochempy-nmr 0.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for spectrochempy_nmr-0.3.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page