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.pyowns the normalized NDDataset contract, the two core FFT calls and channel/component views;processing/quadrature.pyowns the single validatedstates-tppireconstruction equation;adapters/agilent_noesy.pyowns 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.