pyextal.jaxMultipole.data¶

Observed structure factors: refined LARBED Ug, joint refinements, tables.

Sources¶

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.
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.
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¶

`Observations`	A set of observed structure factors.
`ScanValue`	One refined structure factor of one run, already mapped to its family.

Functions¶

`merge`(*parts)	Concatenates observation sets (e.g. LARBED Ug and X-ray F).
`read_scan_values`(files, crystal[, run, notes, layer, ...])	Refined Ug of one run per dataset file, mapped to canonical families.
`robust_location`(x[, clip, iterations])	Median and MAD-based sigma with iterative rejection.
`from_scan_runs`(files, crystal[, run, notes, layer, ...])	Combines per-scan refinements into one value and sigma per family.
`from_joint_json`(path, crystal[, layer, sigma_from, ...])	Shared structure factors of a jaxJoint run.
`from_table`(path[, kind, crystal])	Reads `h k l value sigma [imag]` rows (CSV or whitespace; `#` comments).
`friis2004_table1`([column, corrected])	Friis et al. (2004) Table 1 as observations of kind `'xray_static'`.

Module Contents¶

class pyextal.jaxMultipole.data.Observations¶

A set of observed structure factors.

Variables:

hkl (np.ndarray) – (n, 3) canonical keys.
value (np.ndarray) – Complex values (Ug in Angstrom^-2, or F in e).
sigma (np.ndarray) – Standard uncertainties of the real (and, where used, imaginary) parts.
kind (np.ndarray) – 'electron', 'xray' or 'xray_static'.
use_imag (np.ndarray) – Fit the imaginary part as well.
n (np.ndarray) – Measurements behind each value.
spread (np.ndarray) – Their sample standard deviation (NaN for n = 1).
absorption (np.ndarray) – Mean refined U’ where known (complex), else NaN.
sign_agreement (np.ndarray) – Fraction of measurements whose real part has the sign of the mean.
source (list[str]) – Provenance per value.

hkl: numpy.ndarray¶

value: numpy.ndarray¶

sigma: numpy.ndarray¶

kind: numpy.ndarray¶

use_imag: numpy.ndarray¶

n: numpy.ndarray¶

spread: numpy.ndarray¶

absorption: numpy.ndarray¶

sign_agreement: numpy.ndarray¶

source: list = []¶

__len__()¶

select(mask)¶: Subset by boolean mask or index array.

without(keys)¶: Drops the given families (any member’s index works with crystal-free keys).

keys()¶

table(crystal=None)¶: A printable summary, sorted by s when a crystal is given.

pyextal.jaxMultipole.data.merge(*parts)¶: Concatenates observation sets (e.g. LARBED Ug and X-ray F).

class pyextal.jaxMultipole.data.ScanValue¶

One refined structure factor of one run, already mapped to its family.

h5: str¶

run: str¶

notes: str¶

local: tuple¶

key: tuple¶

U: complex¶

Uabs: complex¶

kv: float¶

pyextal.jaxMultipole.data.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.

Parameters:

files (list) – HDF5 dataset files, or (h5, run) pairs.
crystal (Crystal) – Defines the families, the reference cell and voltage.
run (str) – 'latest' – the newest run whose notes start with notes – or an explicit run key.
notes (str | None) – Notes prefix: 'geo' selects per-scan jaxGeo runs, 'joint' joint ones; None accepts any.
layer (int) – Layer to read for multi-layer runs (-1, the last).
dat (path, optional) – Crystal file to check the cell and voltage against, for every file; otherwise each file’s /paths dat (relative to base) is read.
check_cell (bool) – Refuse values refined with another cell.

Returns:

list[ScanValue]

pyextal.jaxMultipole.data.robust_location(x, clip=4.0, iterations=5)¶

Median and MAD-based sigma with iterative rejection.

Parameters:

x (array-like) – Real values.
clip (float) – Reject values more than clip sigma from the median; None or inf disables rejection.
iterations (int) – Rejection passes.

Returns:

(centre, sigma, keep_mask); sigma is NaN below 3 values.

Return type:

tuple

pyextal.jaxMultipole.data.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.

Parameters:

files – see read_scan_values.
crystal – see read_scan_values.
run – see read_scan_values.
notes – see read_scan_values.
layer – see read_scan_values.
dat – see read_scan_values.
check_cell – see read_scan_values.
method (str) – '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.
sigma (str) – '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.
clip (float) – Rejection threshold for 'robust'.
floor (tuple) – (absolute, relative) lower bound on sigma.
min_n (int) – Drop families with fewer surviving measurements; with one or two there is no scatter to take a sigma from.
use_imag (bool) – Mark the imaginary parts as observed (non-centric data).
report (list, optional) – Receives (key, ScanValue) of every rejected measurement.

Returns:

Observations

pyextal.jaxMultipole.data.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.

Parameters:

path (path-like) – joint_<stamp>.json.
crystal (Crystal) – Model crystal; keys are re-canonicalised against it.
layer (int) – Which layer’s values.
sigma_from (Observations, optional) – Take each family’s sigma (and n) from this scan-based set; families it lacks are dropped.
sigma (float, optional) – A constant sigma instead.
kv (float, optional) – Voltage of the joint run; the first dataset’s .dat hv when None, else the model’s.

Returns:

Observations

pyextal.jaxMultipole.data.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.

pyextal.jaxMultipole.data.friis2004_table1(column='cbed', corrected=True)¶

Friis et al. (2004) Table 1 as observations of kind 'xray_static'.

Parameters:

column (str) – 'cbed' (this experiment), 'xray' (Abramov et al.), 'dft' or 'iam' (no sigmas for the last two: 0.01 is used).
corrected (bool) – Replace the misprinted 110 IAM value.