Monochromatic energy reduction#

Use lauelab.energy to calculate mean intensity versus Q from one monochromatic image. See Plot intensity versus Q for an example, the algorithm for scientific conventions, and the file format for storage.

Compute and inspect#

lauelab.energy.q_distribution(frame, *, geometry, energy_kev=None, metadata=None, monochromatic=None, monochromatic_reason=None, detector_index=None, detector_id=None, start=(0, 0), group=(1, 1), depth=None, roi=None, mask=None, dark=None, dark_metadata=None, normalization='i0', q_first=None, q_last=None, q_points=None, max_bins=1000000)[source]#

Reduce one monochromatic image to mean intensity versus Q.

Parameters:

  • frame (numpy.ndarray or str or pathlib.Path or lauelab.indexing.ScanFrame) – One 2D real image. HDF5 uses the supported 34-ID-E image layout; ScanFrame selects exactly one stored reconstructed depth image.

  • geometry (lauelab.indexing.Geometry or str or pathlib.Path) – Calibrated detector geometry in the 34-ID-E conventions.

  • energy_kev (float or None) – Positive photon energy, overriding metadata and file energy.

  • metadata (lauelab.indexing.FrameMetadata or Mapping or None) – Explicit metadata overlays file values. Monitor data must be scalar or length one; longer vectors require a scalar override.

  • dark_metadata (lauelab.indexing.FrameMetadata or Mapping or None) – Explicit metadata overlays file values. Monitor data must be scalar or length one; longer vectors require a scalar override.

  • monochromatic (bool or None) – Explicit declaration when mode metadata is insufficient. Recorded white-beam metadata requires True and a nonempty monochromatic_reason.

  • monochromatic_reason (str or None) – Recorded reason for overriding white-beam metadata.

  • detector_index (int or str or None) – Physical geometry slot or exact ID. Metadata ID or a sole active detector can select automatically; conflicting selections error.

  • detector_id (int or str or None) – Physical geometry slot or exact ID. Metadata ID or a sole active detector can select automatically; conflicting selections error.

  • start (tuple of int) – Full-detector (x,y) origin and grouping. Stored values take precedence over call arguments.

  • group (tuple of int) – Full-detector (x,y) origin and grouping. Stored values take precedence over call arguments.

  • depth (float or None) – Sample depth in um; explicit values, including zero, override the file.

  • roi (tuple of int or None) – Half-open stored-image (y0,y1,x0,x1); None uses the full frame.

  • mask (numpy.ndarray or None) – Full-frame exclusion mask; nonzero excludes before arithmetic.

  • dark (numpy.ndarray or str or pathlib.Path or lauelab.indexing.ScanFrame or None) – Direct subtraction in matching stored coordinates, units and exposure. No automatic scaling/resampling; primary metadata supplies normalization.

  • normalization (str or None) – ‘i0’ (default): Igor exposure/I0 correction, including 1e5 scale. ‘exposure’: divide by exposure only. ‘none’ or None: no scalar correction.

  • q_first (float or None) – First/last Q sample centers in 1/nm, not edges. Supply together with q_points, or omit all three for Igor-style automatic spacing.

  • q_last (float or None) – First/last Q sample centers in 1/nm, not edges. Supply together with q_points, or omit all three for Igor-style automatic spacing.

  • q_points (int or None) – Number of uniform Q centers, at least two.

  • max_bins (int) – Allocation guard, default 1,000,000 centers. Raise explicitly for larger profiles. Neither automatic coarsening nor an image-size limit is used.

Returns:

QDistribution – Owned/read-only Q, corrected sums/means, occupancy/nonfinite counts and provenance. Empty means and contaminated means/sums are NaN.

Raises:

InputError – Invalid source, selection, beam qualification, correction metadata, geometry, grid or arithmetic overflow. No selected in-range pixels.

Return type:

QDistribution

Notes

Uses uniform centers and nearest-center rounding, half ties away from zero. All-zero and negative intensities are valid. Unmasked NaN/Inf contaminates its bin only. Counts are not statistical errors. No files are written. Distortion/flat-field/solid-angle/polarization/Lorentz corrections, background estimation and peak fitting are not performed. See the energy guide for input conventions, corrections, precision limits and validation evidence.

class lauelab.energy.QDistribution(q_nm_inv, intensity_mean, intensity_sum, pixel_count, nonfinite_pixel_count, provenance)[source]#

Owned numerical profile and a snapshot of its scientific provenance.

Parameters:

  • q_nm_inv (numpy.ndarray) – Float64 Q centers in 1/nm, mean intensity, and corrected intensity sums, all shape (n,) with n >= 2. Q centers are uniformly spaced. Empty means and contaminated means/sums are NaN; empty sums are zero.

  • intensity_mean (numpy.ndarray) – Float64 Q centers in 1/nm, mean intensity, and corrected intensity sums, all shape (n,) with n >= 2. Q centers are uniformly spaced. Empty means and contaminated means/sums are NaN; empty sums are zero.

  • intensity_sum (numpy.ndarray) – Float64 Q centers in 1/nm, mean intensity, and corrected intensity sums, all shape (n,) with n >= 2. Q centers are uniformly spaced. Empty means and contaminated means/sums are NaN; empty sums are zero.

  • pixel_count (numpy.ndarray) – Nonnegative integer occupancy and nonfinite-intensity counts, shape (n,). Occupancy includes assigned nonfinite pixels.

  • nonfinite_pixel_count (numpy.ndarray) – Nonnegative integer occupancy and nonfinite-intensity counts, shape (n,). Occupancy includes assigned nonfinite pixels.

  • provenance (Mapping) – Settings, identities and metadata. A snapshot is taken as JSON; the provenance property returns a fresh mapping on each access.

Notes

Arrays are copied and marked read-only. Negative intensities are valid. Counts are diagnostics, not statistical uncertainties. Units and correction mode are recorded by q_distribution() in the provenance.

property provenance: dict#

Return a fresh copy of settings, source identities and metadata.

property intensity_label: str#

Intensity-axis label identifying the scalar correction mode.

property intensity_units: str#

Known raw/exposure units, or ‘unspecified’ for I0-relative intensity.

The five read-only arrays have the same shape (n,): q_nm_inv, intensity_mean, intensity_sum, pixel_count, and nonfinite_pixel_count. Floating-point arrays use numpy.float64; count arrays use numpy.int64. Mean intensity is NaN in empty bins. Bins containing nonfinite intensities have NaN sums and means. Use pixel_count and nonfinite_pixel_count to distinguish these cases.

Save, load and export#

lauelab.energy.save_q_distribution(result, path, *, overwrite=False)[source]#

Save a standalone versioned HDF5 profile and its complete provenance.

Files contain profile arrays, dimensioned settings, geometry and provenance, not source/dark/mask pixels. A closed, validated temporary file is published in the destination directory. Existing files require overwrite=True.

lauelab.energy.load_q_distribution(path, *, max_bins=1000000)[source]#

Load a validated standalone profile, with owned/read-only arrays.

No original frame or geometry file is opened. max_bins is checked before loading arrays; explicitly raise it to read larger profiles.

lauelab.energy.validate_q_distribution_file(path, *, max_bins=1000000)[source]#

Validate format, units, settings and scientific arrays with bounded reads.

The allocation guard is checked before reading profile arrays. Unknown fields are ignored. Validation failures raise InputError; opening failures raise OSError. The validator does not open source image files.

lauelab.energy.export_q_distribution_csv(result, path, *, overwrite=False)[source]#

Export five numeric columns with a comment header for units/corrections.

Skip lines starting with ‘#’ when reading the CSV. NaN denotes empty or contaminated means. Use counts to distinguish these cases. Save as HDF5 for complete provenance. An existing destination requires overwrite=True.

The validator checks arrays in bounded slices. Computation and validation raise InputError for invalid requests or malformed profile content. Opening a saved file can raise OSError. Saving a manually constructed result requires complete provenance in the schema produced by q_distribution.

Plot#

Use plot_q_distribution() to plot a computed or loaded result. The function does not read source files, recalculate the profile or write a file. Customize the returned Plotly figure with layout_update or per-role trace_update options.