xrdkit 0.1.0__py3-none-any.whl

xrdkit/io.py

@@ -0,0 +1,115 @@
+"""Readers for X-ray diffraction data files."""
+
+from __future__ import annotations
+
+import xml.etree.ElementTree as ET
+from dataclasses import dataclass
+from pathlib import Path
+
+import numpy as np
+
+__all__ = ["XRDScan", "read_xrdml"]
+
+
+@dataclass
+class XRDScan:
+    """A single powder diffraction scan."""
+
+    two_theta: np.ndarray
+    intensity: np.ndarray
+    wavelength: float
+    start_angle: float
+    end_angle: float
+    step_size: float
+    time_per_step: float
+    sample_id: str
+    source_path: str
+
+
+def _namespace(root: ET.Element) -> str:
+    """Return the default namespace of ``root`` as a ``{uri}`` prefix."""
+    if root.tag.startswith("{"):
+        return root.tag[: root.tag.index("}") + 1]
+    return ""
+
+
+def _text(element: ET.Element | None) -> str:
+    if element is None or element.text is None:
+        return ""
+    return element.text.strip()
+
+
+def read_xrdml(path: str | Path) -> XRDScan:
+    """Read a PANalytical ``.xrdml`` file into an :class:`XRDScan`.
+
+    Parameters
+    ----------
+    path
+        Path to the ``.xrdml`` file.
+
+    Raises
+    ------
+    ValueError
+        If the file contains no intensity data.
+    """
+    path = Path(path)
+    root = ET.parse(path).getroot()
+    ns = _namespace(root)
+
+    scan = root.find(f".//{ns}scan")
+    if scan is None:
+        raise ValueError(f"No scan found in {path}")
+
+    data_points = scan.find(f"{ns}dataPoints")
+    if data_points is None:
+        raise ValueError(f"No dataPoints element found in {path}")
+
+    # Intensities live in <counts> or <intensities> depending on the writer.
+    counts_element = data_points.find(f"{ns}counts")
+    if counts_element is None:
+        counts_element = data_points.find(f"{ns}intensities")
+    raw_counts = _text(counts_element)
+    if not raw_counts:
+        raise ValueError(f"No intensity data found in {path}")
+
+    intensity = np.array(raw_counts.split(), dtype=float)
+    if intensity.size == 0:
+        raise ValueError(f"No intensity data found in {path}")
+
+    two_theta_positions = None
+    for positions in data_points.findall(f"{ns}positions"):
+        if positions.get("axis") == "2Theta":
+            two_theta_positions = positions
+            break
+    if two_theta_positions is None:
+        raise ValueError(f"No 2Theta axis found in {path}")
+
+    start_angle = float(_text(two_theta_positions.find(f"{ns}startPosition")))
+    end_angle = float(_text(two_theta_positions.find(f"{ns}endPosition")))
+
+    n_points = intensity.size
+    two_theta = np.linspace(start_angle, end_angle, n_points)
+    step_size = (end_angle - start_angle) / (n_points - 1) if n_points > 1 else 0.0
+
+    common_time = _text(data_points.find(f"{ns}commonCountingTime"))
+    if common_time:
+        time_per_step = float(common_time)
+    else:
+        per_point = _text(data_points.find(f"{ns}countingTimes"))
+        time_per_step = float(per_point.split()[0]) if per_point else 0.0
+
+    wavelength = float(_text(root.find(f".//{ns}usedWavelength/{ns}kAlpha1")))
+
+    sample_id = _text(root.find(f".//{ns}sample/{ns}id"))
+
+    return XRDScan(
+        two_theta=two_theta,
+        intensity=intensity,
+        wavelength=wavelength,
+        start_angle=start_angle,
+        end_angle=end_angle,
+        step_size=step_size,
+        time_per_step=time_per_step,
+        sample_id=sample_id,
+        source_path=str(path),
+    )

xrdkit/lattice.py

@@ -0,0 +1,233 @@
+"""Lattice parameter refinement against indexed peaks, with systematic errors."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+from scipy import optimize
+
+from xrdkit.indexing import IndexedPeak, TetragonalCell
+
+__all__ = ["LatticeFit", "lattice_fit_to_dict", "refine_lattice"]
+
+# A peak needs this many more than the parameters before a fit means anything.
+MIN_EXTRA_PEAKS = 3
+
+# Keeps the arcsine in range while the optimiser tries a cell that cannot
+# diffract at all; the residual there is large either way.
+MAX_SIN_THETA = 1.0 - 1e-9
+
+# Order of the parameter vector the model is written in.
+PARAMETER_NAMES = ("a", "c", "zero", "displacement")
+
+
+@dataclass
+class LatticeFit:
+    """The outcome of a lattice parameter refinement.
+
+    ``zero`` is the zero point error in degrees, added to every calculated
+    position. ``displacement`` is the specimen displacement in millimetres,
+    positive below the focusing circle, or ``None`` when it was not refined.
+    An estimated standard deviation of a parameter that was held fixed is
+    ``None``.
+    """
+
+    a: float
+    c: float
+    esd_a: float
+    esd_c: float
+    zero: float
+    esd_zero: float | None
+    displacement: float | None
+    esd_displacement: float | None
+    radius_mm: float | None
+    n_peaks: int
+    rms_two_theta: float
+    residuals: np.ndarray
+    hkl: list[tuple[int, int, int]]
+    converged: bool
+
+    @property
+    def cell(self) -> TetragonalCell:
+        """The refined cell."""
+        return TetragonalCell(a=self.a, c=self.c)
+
+
+def _two_theta(
+    a: float, c: float, hkl: np.ndarray, wavelength: float
+) -> tuple[np.ndarray, np.ndarray]:
+    """Return the Bragg 2theta of ``hkl`` for a tetragonal cell, and its theta.
+
+    Both in degrees and radians respectively, from 1/d^2 = (h^2+k^2)/a^2 +
+    l^2/c^2 and sin(theta) = lambda / 2d.
+    """
+    hk, ll = hkl[:, 0] ** 2 + hkl[:, 1] ** 2, hkl[:, 2] ** 2
+    inverse_squared = hk / a**2 + ll / c**2
+    d_spacing = 1.0 / np.sqrt(inverse_squared)
+    sin_theta = np.clip(wavelength / (2.0 * d_spacing), -MAX_SIN_THETA, MAX_SIN_THETA)
+    theta = np.arcsin(sin_theta)
+    return 2.0 * np.degrees(theta), theta
+
+
+def _model(
+    parameters: np.ndarray, hkl: np.ndarray, wavelength: float, radius_mm: float | None
+) -> np.ndarray:
+    """Calculated 2theta for ``parameters`` = (a, c, zero, displacement).
+
+    The specimen displacement shifts a reflection by -2 s cos(theta) / R
+    radians, which is the usual flat plate term: a specimen sitting below the
+    focusing circle moves every peak to low angle, most of all at low angle.
+    """
+    a, c, zero, displacement = parameters
+    calculated, theta = _two_theta(a, c, hkl, wavelength)
+    shift = zero
+    if radius_mm is not None:
+        shift = shift + np.degrees(-2.0 * displacement * np.cos(theta) / radius_mm)
+    return calculated + shift
+
+
+def refine_lattice(
+    indexed: list[IndexedPeak],
+    wavelength: float,
+    start_cell: TetragonalCell,
+    fit_zero: bool = True,
+    fit_displacement: bool = False,
+    radius_mm: float | None = None,
+    start_zero: float = 0.0,
+) -> LatticeFit:
+    """Refine a tetragonal cell, and its systematic errors, by least squares.
+
+    Each peak is modelled as its Bragg position for the cell plus a zero point
+    error plus a specimen displacement term, and the observed positions are
+    taken as measured: ``peak.two_theta``, not ``corrected_two_theta``, since
+    the zero point is what is being refined rather than assumed.
+
+    Only peaks that matched exactly one reflection are used, so an assignment
+    that was a choice between rivals cannot pull the cell.
+
+    A zero point error and a specimen displacement are not independent over a
+    short angular range, since one is constant and the other follows
+    cos(theta); refining both needs peaks spread widely enough in 2theta to
+    tell them apart.
+
+    Parameters
+    ----------
+    indexed
+        Result of :func:`~xrdkit.indexing.index_peaks`, or the first element of
+        :func:`~xrdkit.indexing.index_and_refine`.
+    wavelength
+        Radiation wavelength in angstroms.
+    start_cell
+        Cell to start from.
+    fit_zero
+        Refine the zero point error. Held at zero when ``False``.
+    fit_displacement
+        Refine the specimen displacement. Held at zero when ``False``.
+    radius_mm
+        Goniometer radius in millimetres. Needed only to refine a displacement.
+    start_zero
+        Zero point error to start from, in degrees. Only a starting value: it
+        is refined like any other when ``fit_zero``, and held there when not.
+
+    Returns
+    -------
+    LatticeFit
+        The refined parameters, their estimated standard deviations, and the
+        residuals of the peaks used.
+
+    Raises
+    ------
+    ValueError
+        If ``fit_displacement`` is asked for without a ``radius_mm``, or fewer
+        than three peaks more than there are parameters are available.
+    """
+    if fit_displacement and radius_mm is None:
+        raise ValueError(
+            "refine_lattice needs radius_mm to refine a specimen displacement"
+        )
+
+    used = [
+        entry for entry in indexed if entry.is_indexed and len(entry.candidates) == 1
+    ]
+
+    free = np.array([True, True, bool(fit_zero), bool(fit_displacement)])
+    n_parameters = int(free.sum())
+    if len(used) < n_parameters + MIN_EXTRA_PEAKS:
+        raise ValueError(
+            f"Need at least {n_parameters + MIN_EXTRA_PEAKS} peaks with a single "
+            f"candidate to refine {n_parameters} parameters, got {len(used)}"
+        )
+
+    observed = np.array([entry.peak.two_theta for entry in used], dtype=float)
+    hkl = np.array([entry.reflection.hkl for entry in used], dtype=float)
+    hkl_tuples = [entry.reflection.hkl for entry in used]
+
+    # The whole vector is carried about so the model stays readable; only the
+    # free entries are handed to the optimiser.
+    start = np.array([start_cell.a, start_cell.c, start_zero, 0.0], dtype=float)
+    # A displacement term of zero leaves the model unchanged, so the radius is
+    # only consulted when one is being refined.
+    radius = radius_mm if fit_displacement else None
+
+    def residual(varying: np.ndarray) -> np.ndarray:
+        parameters = start.copy()
+        parameters[free] = varying
+        return observed - _model(parameters, hkl, wavelength, radius)
+
+    result = optimize.least_squares(residual, start[free])
+
+    parameters = start.copy()
+    parameters[free] = result.x
+    a, c, zero, displacement = parameters
+
+    residuals = np.asarray(result.fun, dtype=float)
+    degrees_of_freedom = len(used) - n_parameters
+    # Scaling by the reduced chi squared turns the curvature of the surface
+    # into an error bar that reflects how well the model actually fits.
+    reduced_chi_squared = float(np.sum(residuals**2) / degrees_of_freedom)
+    jacobian = np.asarray(result.jac, dtype=float)
+    covariance = np.linalg.pinv(jacobian.T @ jacobian) * reduced_chi_squared
+    deviations = np.sqrt(np.abs(np.diag(covariance)))
+
+    esd = dict(zip(np.array(PARAMETER_NAMES)[free], deviations))
+
+    return LatticeFit(
+        a=float(a),
+        c=float(c),
+        esd_a=float(esd["a"]),
+        esd_c=float(esd["c"]),
+        zero=float(zero),
+        esd_zero=float(esd["zero"]) if fit_zero else None,
+        displacement=float(displacement) if fit_displacement else None,
+        esd_displacement=float(esd["displacement"]) if fit_displacement else None,
+        radius_mm=radius_mm,
+        n_peaks=len(used),
+        rms_two_theta=float(np.sqrt(np.mean(residuals**2))),
+        residuals=residuals,
+        hkl=hkl_tuples,
+        converged=bool(result.success),
+    )
+
+
+def lattice_fit_to_dict(fit: LatticeFit) -> dict[str, float | int | bool | None]:
+    """Flatten ``fit`` to the scalar fields, ready for a CSV row.
+
+    The residuals and the hkl are left out, being one row each rather than one
+    value.
+    """
+    return {
+        "a": fit.a,
+        "esd_a": fit.esd_a,
+        "c": fit.c,
+        "esd_c": fit.esd_c,
+        "c_over_a": fit.c / fit.a,
+        "zero": fit.zero,
+        "esd_zero": fit.esd_zero,
+        "displacement": fit.displacement,
+        "esd_displacement": fit.esd_displacement,
+        "radius_mm": fit.radius_mm,
+        "n_peaks": fit.n_peaks,
+        "rms_two_theta": fit.rms_two_theta,
+        "converged": fit.converged,
+    }

xrdkit/peaks.py

@@ -0,0 +1,340 @@
+"""Peak finding for X-ray diffraction patterns."""
+
+from __future__ import annotations
+
+import csv
+from dataclasses import asdict, dataclass, replace
+from pathlib import Path
+
+import numpy as np
+from scipy import signal
+
+from xrdkit.io import XRDScan
+
+__all__ = [
+    "Peak",
+    "exclude_kalpha2",
+    "find_peaks",
+    "flag_kalpha2",
+    "peaks_to_csv",
+]
+
+# Minimum peak prominence, as a fraction of the strongest intensity in range.
+DEFAULT_MIN_PROMINENCE = 0.02
+
+# Minimum separation between peaks, in degrees.
+DEFAULT_MIN_DISTANCE = 0.15
+
+# scipy measures the width at this fraction of the prominence below the peak,
+# so 0.5 gives the full width at half maximum.
+HALF_PROMINENCE = 0.5
+
+# Copper K alpha 1 and K alpha 2 wavelengths, in angstroms. A satellite
+# diffracts at the same d spacing as its parent, so Bragg's law puts it at
+# 2theta_2 = 2 arcsin(KALPHA2_RATIO sin(theta_1)), always to high angle.
+KALPHA1_WAVELENGTH = 1.54056
+KALPHA2_WAVELENGTH = 1.54439
+KALPHA2_RATIO = KALPHA2_WAVELENGTH / KALPHA1_WAVELENGTH
+
+# Largest gap between a peak and the satellite position predicted for it, in
+# degrees.
+DEFAULT_KALPHA2_TOLERANCE = 0.03
+
+# A K alpha 2 satellite carries about half the intensity of its parent, but a
+# satellite resolved on the tail of its parent measures well above that, so the
+# ceiling is set high enough to admit the partly overlapped ones.
+DEFAULT_KALPHA2_INTENSITY_RATIO = (0.25, 0.90)
+
+CSV_COLUMNS = (
+    "two_theta",
+    "intensity",
+    "prominence",
+    "fwhm",
+    "d_spacing",
+    "relative_intensity",
+    "kalpha2_of",
+)
+
+# Decimal places per column when writing CSV; counts keep one place.
+CSV_DECIMALS = {
+    "two_theta": 3,
+    "intensity": 1,
+    "prominence": 1,
+    "fwhm": 3,
+    "d_spacing": 4,
+    "relative_intensity": 2,
+}
+
+
+@dataclass
+class Peak:
+    """A single reflection located in a diffraction pattern."""
+
+    two_theta: float
+    intensity: float
+    prominence: float
+    fwhm: float
+    d_spacing: float
+    relative_intensity: float
+    # Index in the peak list of the K alpha 1 parent this peak is a satellite
+    # of, or None if it is not judged to be one.
+    kalpha2_of: int | None = None
+
+
+def _step_size(scan: XRDScan) -> float:
+    """Return the 2theta step of ``scan``, falling back to the axis spacing."""
+    if scan.step_size > 0.0:
+        return float(scan.step_size)
+    if scan.two_theta.size > 1:
+        return float(np.median(np.diff(scan.two_theta)))
+    raise ValueError("Cannot determine the 2theta step of a single point scan")
+
+
+def _d_spacing(two_theta: float, wavelength: float) -> float:
+    """Return the d spacing in angstroms from Bragg's law."""
+    theta = np.radians(two_theta / 2.0)
+    sin_theta = float(np.sin(theta))
+    if sin_theta <= 0.0:
+        return float("nan")
+    return wavelength / (2.0 * sin_theta)
+
+
+def _refine_position(
+    two_theta: np.ndarray, intensity: np.ndarray, index: int, step: float
+) -> float:
+    """Refine a peak position by the vertex of a parabola through three points.
+
+    Falls back to the grid position when the peak sits on the first or last
+    point, when the three points are collinear, or when the vertex lands outside
+    the neighbouring points, since none of those give a meaningful vertex.
+    """
+    grid_position = float(two_theta[index])
+    if index <= 0 or index >= intensity.size - 1:
+        return grid_position
+
+    left, centre, right = (float(value) for value in intensity[index - 1 : index + 2])
+    curvature = left - 2.0 * centre + right
+    if curvature == 0.0:
+        return grid_position
+
+    shift = 0.5 * (left - right) / curvature
+    if not -1.0 < shift < 1.0:
+        return grid_position
+    return grid_position + shift * step
+
+
+def find_peaks(
+    scan: XRDScan,
+    min_prominence: float = DEFAULT_MIN_PROMINENCE,
+    min_distance: float = DEFAULT_MIN_DISTANCE,
+    two_theta_range: tuple[float, float] | None = None,
+    flag_satellites: bool = True,
+) -> list[Peak]:
+    """Locate reflections in ``scan``, sorted by 2theta.
+
+    Parameters
+    ----------
+    scan
+        The scan to search.
+    min_prominence
+        Minimum prominence a peak must have, as a fraction of the strongest
+        intensity within the searched range.
+    min_distance
+        Minimum separation between peaks, in degrees.
+    two_theta_range
+        Optional ``(low, high)`` window, in degrees, to restrict the search to.
+    flag_satellites
+        Whether to run :func:`flag_kalpha2` over the result, which sets
+        ``kalpha2_of`` on the peaks that look like K alpha 2 satellites.
+
+    Returns
+    -------
+    list[Peak]
+        Peaks ordered by 2theta. ``relative_intensity`` is a percentage of the
+        strongest peak found, which is therefore always 100. Satellites are
+        still returned; they are flagged rather than dropped, so that
+        :func:`exclude_kalpha2` can be applied when it suits.
+
+    Raises
+    ------
+    ValueError
+        If ``two_theta_range`` selects no data, or the step cannot be determined.
+    """
+    two_theta = np.asarray(scan.two_theta, dtype=float)
+    intensity = np.asarray(scan.intensity, dtype=float)
+
+    if two_theta_range is not None:
+        low, high = two_theta_range
+        selected = (two_theta >= low) & (two_theta <= high)
+        if not np.any(selected):
+            raise ValueError(
+                f"two_theta_range {two_theta_range} selects no points of "
+                f"{two_theta[0]:.3f}-{two_theta[-1]:.3f} degrees"
+            )
+        two_theta = two_theta[selected]
+        intensity = intensity[selected]
+
+    if intensity.size == 0:
+        return []
+
+    step = _step_size(scan)
+    prominence = min_prominence * float(np.max(intensity))
+    # scipy counts separation in points, and needs at least one.
+    distance = max(1, round(min_distance / step))
+
+    indices, properties = signal.find_peaks(
+        intensity, prominence=prominence, distance=distance
+    )
+    if indices.size == 0:
+        return []
+
+    widths = signal.peak_widths(intensity, indices, rel_height=HALF_PROMINENCE)[0]
+
+    heights = intensity[indices]
+    strongest = float(np.max(heights))
+
+    peaks = []
+    for index, height, peak_prominence, width in zip(
+        indices, heights, properties["prominences"], widths
+    ):
+        position = _refine_position(two_theta, intensity, int(index), step)
+        peaks.append(
+            Peak(
+                two_theta=position,
+                intensity=float(height),
+                prominence=float(peak_prominence),
+                fwhm=float(width) * step,
+                d_spacing=_d_spacing(position, scan.wavelength),
+                relative_intensity=100.0 * float(height) / strongest,
+            )
+        )
+    peaks.sort(key=lambda peak: peak.two_theta)
+    if flag_satellites:
+        flag_kalpha2(peaks)
+    return peaks
+
+
+def _satellite_position(two_theta: float, wavelength_ratio: float) -> float:
+    """Return where the K alpha 2 satellite of a peak at ``two_theta`` falls.
+
+    ``nan`` when the scaled sine passes 1, which is beyond the reach of the
+    longer wavelength and so has no satellite.
+    """
+    sin_theta = wavelength_ratio * np.sin(np.radians(two_theta / 2.0))
+    if sin_theta > 1.0:
+        return float("nan")
+    return 2.0 * float(np.degrees(np.arcsin(sin_theta)))
+
+
+def flag_kalpha2(
+    peaks: list[Peak],
+    tolerance: float = DEFAULT_KALPHA2_TOLERANCE,
+    intensity_ratio: tuple[float, float] = DEFAULT_KALPHA2_INTENSITY_RATIO,
+    wavelength_ratio: float = KALPHA2_RATIO,
+) -> list[Peak]:
+    """Flag the peaks that look like K alpha 2 satellites, in place.
+
+    A satellite sits at the position the parent's d spacing would give at the
+    longer K alpha 2 wavelength, and carries roughly half the parent's
+    intensity. Every stronger peak is tested as a possible parent and the
+    closest one that satisfies both conditions wins, so a peak that happens to
+    fall near two predicted positions is attributed to the better match.
+
+    Only resolved satellites can be caught this way. Below about 50 degrees the
+    pair is not separated enough for the peak finder to report two peaks, so
+    there is nothing to flag. A satellite that is only just resolved, still
+    sitting on the tail of its parent, measures high because its height is taken
+    above a baseline the parent has raised, which is why the default ceiling on
+    the intensity ratio is well above the half that clean separation would give.
+
+    Parameters
+    ----------
+    peaks
+        Peaks to flag, as returned by :func:`find_peaks`. Modified in place.
+    tolerance
+        Largest allowed gap between a peak and a predicted satellite position,
+        in degrees.
+    intensity_ratio
+        Allowed ``(low, high)`` range of the peak's intensity over its parent's.
+    wavelength_ratio
+        K alpha 2 over K alpha 1, 1.002486 for copper.
+
+    Returns
+    -------
+    list[Peak]
+        The same list, for chaining.
+
+    Raises
+    ------
+    ValueError
+        If ``intensity_ratio`` is not a rising pair of positive numbers.
+    """
+    low, high = intensity_ratio
+    if not 0.0 < low < high:
+        raise ValueError(
+            f"Need 0 < low < high for intensity_ratio, got {intensity_ratio}"
+        )
+
+    # Predicting once per peak keeps this a single pass over the pairs.
+    predicted = [
+        _satellite_position(peak.two_theta, wavelength_ratio) for peak in peaks
+    ]
+
+    for index, peak in enumerate(peaks):
+        best_parent = None
+        best_gap = float("inf")
+        for parent_index, parent in enumerate(peaks):
+            if parent_index == index or parent.intensity <= peak.intensity:
+                continue
+            if not low <= peak.intensity / parent.intensity <= high:
+                continue
+            gap = abs(peak.two_theta - predicted[parent_index])
+            # A tie keeps the earlier parent, which is the lower angle one.
+            if gap <= tolerance and gap < best_gap:
+                best_parent = parent_index
+                best_gap = gap
+        peak.kalpha2_of = best_parent
+
+    return peaks
+
+
+def exclude_kalpha2(peaks: list[Peak]) -> list[Peak]:
+    """Return a new list without the flagged satellites.
+
+    The survivors are copied, not shared, and their ``relative_intensity`` is
+    recomputed against the strongest of them, so it again reaches 100.
+    """
+    kept = [replace(peak) for peak in peaks if peak.kalpha2_of is None]
+    if not kept:
+        return []
+
+    strongest = max(peak.intensity for peak in kept)
+    for peak in kept:
+        peak.relative_intensity = 100.0 * peak.intensity / strongest
+    return kept
+
+
+def peaks_to_csv(peaks: list[Peak], path: str | Path) -> Path:
+    """Write ``peaks`` to ``path`` as CSV with a header, returning the path.
+
+    Positions and widths are written to 3 decimal places and d spacings to 4;
+    counts keep one place and relative intensities two. ``kalpha2_of`` is the
+    parent's index, or blank for a peak that is not a satellite.
+    """
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    with path.open("w", newline="", encoding="utf-8") as handle:
+        writer = csv.writer(handle)
+        writer.writerow(CSV_COLUMNS)
+        for peak in peaks:
+            values = asdict(peak)
+            writer.writerow(
+                [
+                    f"{values[column]:.{CSV_DECIMALS[column]}f}"
+                    if column in CSV_DECIMALS
+                    else ("" if values[column] is None else values[column])
+                    for column in CSV_COLUMNS
+                ]
+            )
+    return path