Units, quantities, and masks

SpectroChemPy exposes selected Pint and NumPy objects unchanged so that unit-aware and masked data interoperate with their originating libraries. This page documents their role in the SpectroChemPy API. The units and masks guide provides verified examples of construction, conversion, masking, plotting, and raw-array access.

Units and quantities

scp.ur

The Pint unit registry configured and used by SpectroChemPy. It owns the units of public Quantity and Unit objects and includes SpectroChemPy definitions and formatters. Use the single public registry rather than constructing another registry for values intended to interact with NDDataset.

scp.Unit

The original Pint Unit class. A unit describes dimensionality and scale but carries no magnitude. scp.Unit("cm^-1") constructs a unit attached to scp.ur.

scp.Quantity

The Quantity class generated by scp.ur. It combines a magnitude with a unit. scp.Quantity(value, "cm") and value * scp.ur.cm are the recommended public constructions. A quantity does not carry NDDataset dimensions, coordinates, metadata, or history.

scp.DimensionalityError

The original Pint DimensionalityError, raised for incompatible unit operations and conversions. Keeping the exact class permits callers to catch errors raised by both SpectroChemPy and Pint.

SpectroChemPy does not wrap or subclass these objects for documentation. Their Python help() output therefore remains Pint’s documentation. The user guide above is the project-specific behavioral reference.

Masks and masked-array interoperability

scp.MASKED

The original NumPy masked sentinel. Assign it to a dataset selection to exclude those values without deleting their positions or coordinates.

scp.NOMASK

The original NumPy nomask sentinel returned by NDDataset.mask when no value is excluded. Use NDDataset.remove_masks() to clear an existing dataset mask through the public API.

scp.MaskedArray and scp.MaskedConstant

The original NumPy masked-array interoperability types. masked_data and NDDataset.to_array() may return MaskedArray objects, and scp.MASKED is a MaskedConstant. Normal spectroscopy workflows should retain NDDataset so that units, coordinates, metadata, and mask semantics stay together.

help() for these exact objects continues to show NumPy documentation. The SpectroChemPy-specific accessors and information retained by each conversion are documented in the units and masks guide.

Masks and definite integrals

NDDataset.trapezoid() and NDDataset.simpson() reduce one dimension. A masked point is a scientific exclusion, so SpectroChemPy does not publish an integral for a slice whose contribution is incomplete. Each output slice is treated as follows:

  • a slice built without any masked point is integrated normally and the corresponding output is not masked;

  • a slice that used at least one masked point, including a fully masked slice, produces a masked output whose raw value is numpy.nan. The area is explicitly unavailable; no estimate of the missing contribution is made, so masked points are never replaced by zero, removed, or interpolated;

  • the values hidden under the mask never reach the quadrature, so they cannot change a published result nor overflow the calculation;

  • the result mask is always compatible with the result shape. A 1D input yields a zero-dimensional result carrying a scalar mask, and an unmasked input yields the canonical scp.NOMASK mask.

Because only the affected slices are affected, a batch where a single spectrum contains a masked point keeps all the other valid areas. Use NDDataset.masked_data rather than NDDataset.data to read a result containing unavailable areas.

These rules are the SpectroChemPy policy for these two methods. They do not extend automatically to the other reductions, whose own mask behavior is unchanged.

External references