pyextal.jaxMultipole.data ========================= .. py:module:: pyextal.jaxMultipole.data .. autoapi-nested-parse:: Observed structure factors: refined LARBED Ug, joint refinements, tables. Sources ------- :func:`from_scan_runs` The per-scan refinements (`jaxGeo` runs, notes starting ``geo``) of a set of LARBED datasets. Each dataset labels a family by whichever member its zone shows, so every value is mapped to the family's canonical key with ``U(key) = U(local) / c`` (`jaxMultipole.symmetry.link_phase`), scaled to the model's voltage (``U ~ gamma``) and then averaged. The scatter between scans is the uncertainty -- the refinements carry none of their own -- as in Friis et al. (2004), eqs. (1)-(2), with equal weights. :func:`from_joint_json` The shared structure factors of a `jaxJoint` refinement (one value per canonical key), with sigmas taken from a scan set or given. :func:`from_table` Any other data: CSV or whitespace columns ``h k l value sigma [imag]``, kind ``'electron'`` (Ug, Angstrom^-2), ``'xray'`` (F, electrons, thermally averaged) or ``'xray_static'`` (F with the ADPs removed, as theory and Friis's Table 1 give them). Cell and voltage checks ----------------------- ``U ~ gamma / Omega``. Values refined at another voltage are rescaled by ``gamma_model / gamma_run``; values refined with another *cell* are refused, since the multipole model would then be fitted to a different lattice (Friis used a = 3.899 Angstrom, the STO_001 ``.dat`` files have 3.905). Classes ------- .. autoapisummary:: pyextal.jaxMultipole.data.Observations pyextal.jaxMultipole.data.ScanValue Functions --------- .. autoapisummary:: pyextal.jaxMultipole.data.merge pyextal.jaxMultipole.data.read_scan_values pyextal.jaxMultipole.data.robust_location pyextal.jaxMultipole.data.from_scan_runs pyextal.jaxMultipole.data.from_joint_json pyextal.jaxMultipole.data.from_table pyextal.jaxMultipole.data.friis2004_table1 Module Contents --------------- .. py:class:: Observations A set of observed structure factors. :ivar hkl: ``(n, 3)`` canonical keys. :vartype hkl: np.ndarray :ivar value: Complex values (Ug in Angstrom^-2, or F in e). :vartype value: np.ndarray :ivar sigma: Standard uncertainties of the real (and, where used, imaginary) parts. :vartype sigma: np.ndarray :ivar kind: ``'electron'``, ``'xray'`` or ``'xray_static'``. :vartype kind: np.ndarray :ivar use_imag: Fit the imaginary part as well. :vartype use_imag: np.ndarray :ivar n: Measurements behind each value. :vartype n: np.ndarray :ivar spread: Their sample standard deviation (NaN for n = 1). :vartype spread: np.ndarray :ivar absorption: Mean refined U' where known (complex), else NaN. :vartype absorption: np.ndarray :ivar sign_agreement: Fraction of measurements whose real part has the sign of the mean. :vartype sign_agreement: np.ndarray :ivar source: Provenance per value. :vartype source: list[str] .. py:attribute:: hkl :type: numpy.ndarray .. py:attribute:: value :type: numpy.ndarray .. py:attribute:: sigma :type: numpy.ndarray .. py:attribute:: kind :type: numpy.ndarray .. py:attribute:: use_imag :type: numpy.ndarray .. py:attribute:: n :type: numpy.ndarray .. py:attribute:: spread :type: numpy.ndarray .. py:attribute:: absorption :type: numpy.ndarray .. py:attribute:: sign_agreement :type: numpy.ndarray .. py:attribute:: source :type: list :value: [] .. py:method:: __len__() .. py:method:: select(mask) Subset by boolean mask or index array. .. py:method:: without(keys) Drops the given families (any member's index works with ``crystal``-free keys). .. py:method:: keys() .. py:method:: table(crystal=None) A printable summary, sorted by s when a crystal is given. .. py:function:: merge(*parts) Concatenates observation sets (e.g. LARBED Ug and X-ray F). .. py:class:: ScanValue One refined structure factor of one run, already mapped to its family. .. py:attribute:: h5 :type: str .. py:attribute:: run :type: str .. py:attribute:: notes :type: str .. py:attribute:: local :type: tuple .. py:attribute:: key :type: tuple .. py:attribute:: U :type: complex .. py:attribute:: Uabs :type: complex .. py:attribute:: kv :type: float .. py:function:: read_scan_values(files, crystal, run='latest', notes='geo', layer=-1, dat=None, check_cell=True, rtol_cell=0.0001) Refined Ug of one run per dataset file, mapped to canonical families. :param files: HDF5 dataset files, or ``(h5, run)`` pairs. :type files: list :param crystal: Defines the families, the reference cell and voltage. :type crystal: Crystal :param run: ``'latest'`` -- the newest run whose notes start with ``notes`` -- or an explicit run key. :type run: str :param notes: Notes prefix: ``'geo'`` selects per-scan `jaxGeo` runs, ``'joint'`` joint ones; None accepts any. :type notes: str | None :param layer: Layer to read for multi-layer runs (-1, the last). :type layer: int :param dat: Crystal file to check the cell and voltage against, for every file; otherwise each file's ``/paths`` ``dat`` (relative to ``base``) is read. :type dat: path, optional :param check_cell: Refuse values refined with another cell. :type check_cell: bool :returns: list[ScanValue] .. py:function:: robust_location(x, clip=4.0, iterations=5) Median and MAD-based sigma with iterative rejection. :param x: Real values. :type x: array-like :param clip: Reject values more than ``clip`` sigma from the median; ``None`` or ``inf`` disables rejection. :type clip: float :param iterations: Rejection passes. :type iterations: int :returns: ``(centre, sigma, keep_mask)``; sigma is NaN below 3 values. :rtype: tuple .. py:function:: from_scan_runs(files, crystal, run='latest', notes='geo', layer=-1, dat=None, method='robust', sigma='std', clip=4.0, floor=(2e-05, 0.0), min_n=3, use_imag=False, check_cell=True, report=None) Combines per-scan refinements into one value and sigma per family. :param files: see `read_scan_values`. :param crystal: see `read_scan_values`. :param run: see `read_scan_values`. :param notes: see `read_scan_values`. :param layer: see `read_scan_values`. :param dat: see `read_scan_values`. :param check_cell: see `read_scan_values`. :param method: ``'robust'`` (default) -- median, ``1.4826 MAD`` and rejection of values more than ``clip`` sigma out, then mean and standard deviation of the survivors; ``'mean'`` -- plain mean and standard deviation of everything. On the STO_001 scans a handful of large-tilt refinements return values that are plainly failed for some reflections (the sign of 220 flipped, U' of -0.07 on 110), and those dominate a plain standard deviation. :type method: str :param sigma: ``'std'`` -- the scatter of one measurement (Friis eq. (2) with equal weights); ``'sem'`` -- that over sqrt(n), only right if the scans' errors are independent, which systematic ones are not. :type sigma: str :param clip: Rejection threshold for ``'robust'``. :type clip: float :param floor: ``(absolute, relative)`` lower bound on sigma. :type floor: tuple :param min_n: Drop families with fewer surviving measurements; with one or two there is no scatter to take a sigma from. :type min_n: int :param use_imag: Mark the imaginary parts as observed (non-centric data). :type use_imag: bool :param report: Receives ``(key, ScanValue)`` of every rejected measurement. :type report: list, optional :returns: Observations .. py:function:: from_joint_json(path, crystal, layer=-1, sigma_from=None, sigma=None, kv=None, floor=(2e-05, 0.0)) Shared structure factors of a `jaxJoint` run. :param path: ``joint_.json``. :type path: path-like :param crystal: Model crystal; keys are re-canonicalised against it. :type crystal: Crystal :param layer: Which layer's values. :type layer: int :param sigma_from: Take each family's sigma (and n) from this scan-based set; families it lacks are dropped. :type sigma_from: Observations, optional :param sigma: A constant sigma instead. :type sigma: float, optional :param kv: Voltage of the joint run; the first dataset's ``.dat`` ``hv`` when None, else the model's. :type kv: float, optional :returns: Observations .. py:function:: from_table(path, kind='electron', crystal=None) Reads ``h k l value sigma [imag]`` rows (CSV or whitespace; ``#`` comments). Keys are canonicalised against ``crystal`` when given. .. py:function:: friis2004_table1(column='cbed', corrected=True) Friis et al. (2004) Table 1 as observations of kind ``'xray_static'``. :param column: ``'cbed'`` (this experiment), ``'xray'`` (Abramov et al.), ``'dft'`` or ``'iam'`` (no sigmas for the last two: 0.01 is used). :type column: str :param corrected: Replace the misprinted 110 IAM value. :type corrected: bool