Parameters#

PeakParams controls peak detection and fitting. IndexParams controls orientation indexing. Both are immutable dataclasses that the Indexer validates during construction.

Start with the defaults#

Use default values for an initial API check, but do not assume that they are appropriate for every detector, exposure, or material.

from lauelab.indexing import Indexer, IndexParams, PeakParams

indexer = Indexer(
    "geometry.xml",
    "crystal.xml",
    peak_params=PeakParams(),
    index_params=IndexParams(),
)

Record the complete parameter objects with analysis output. A result alone does not contain every setting needed to reproduce processing.

Peak-search parameters#

Parameter	Default	Units	Effect and constraint
`boxsize`	`5`	px	Half-width of the square fitting region. Must be positive.
`max_rfactor`	`2.0`	dimensionless	Maximum accepted fit residual factor. Must be positive.
`min_size`	`3`	px	Minimum accepted peak size. Must be positive.
`min_separation`	`10`	px	Minimum separation between accepted peaks. Must be positive.
`threshold`	`100.0`	detector counts	Absolute detection threshold. Use `None` for an automatically derived threshold.
`threshold_ratio`	`None`	dimensionless	Scale applied to the frame standard deviation for automatic thresholding. `None` resolves to the native default, `4.0`.
`peak_shape`	`"Lorentzian"`	none	Fit model. Exactly `"Lorentzian"` or `"Gaussian"`.
`max_peaks`	`50`	peaks	Maximum number of returned peaks. Must be positive.
`smooth`	`False`	none	Applies native image smoothing before detection and fitting. Frame sums continue to describe the raw input image; an automatically derived threshold is computed from the smoothed image.

When threshold is not None, threshold_ratio does not determine the threshold. When threshold is None, the native stage calculates the threshold from frame statistics and the resolved threshold_ratio. XML provenance records the resolved value (4.0 when configured as None).

Indexing parameters#

Parameter	Default	Units	Effect and constraint
`kev_max_calc`	`30.0`	keV	Maximum energy used to calculate candidate reflections. Must be positive.
`kev_max_test`	`35.0`	keV	Maximum energy used when testing candidate reflections. Must be positive.
`angle_tolerance_deg`	`0.12`	deg	Angular matching tolerance. Must be positive.
`cone_deg`	`72.0`	deg	Search-cone angle. Must be positive.
`hkl_prefer`	`(0, 0, 1)`	Miller indices	Preferred direction. Must contain exactly three integers.
`max_data`	`250`	peaks	Maximum detected peaks supplied to orientation indexing. Must be at least two.

These fields configure the native orientation search. Their scientifically appropriate values depend on the experiment and crystal. This guide does not prescribe universal tuning values.

Derive a configuration#

Use dataclasses.replace() instead of mutating a parameter object:

from dataclasses import replace

base_peaks = PeakParams()
automatic_threshold = replace(
    base_peaks,
    threshold=None,
    threshold_ratio=4.0,
    max_peaks=200,
)

Construct a new indexer or use Indexer.replace() to validate changed settings:

updated = indexer.replace(peak_params=automatic_threshold)

Indexer.replace() constructs independent native geometry and crystal state for the new instance.

Parameter interactions#

Several interactions follow directly from processing behavior:

threshold selects absolute or automatic thresholding.
threshold_ratio affects automatic thresholding only.
max_peaks limits the output of peak search.
max_data limits how many detected peaks enter orientation indexing.
Orientation indexing runs only when a crystal is present and at least two peaks were detected.
start, group, and depth affect pixel-to-q conversion rather than peak fitting.
A mask changes which frame pixels peak search can use.

Changes to peak acceptance can change the scattering vectors available to indexing. Compare the intermediate peak count and fit fields before attributing a changed pattern result only to IndexParams.

A conservative tuning workflow#

Save the original frame, geometry, crystal description, and parameter objects.
Run peak search with a fixed configuration.
Inspect threshold_used, n_peaks, fitted positions, widths, residuals, and masked regions.
Change one peak-search parameter at a time.
Hold the accepted peak set fixed before comparing indexing parameters.
Compare pattern count, assignments, and angular errors across runs.
Record the chosen values and the reason for each change.

This process isolates parameter effects. Numerical thresholds and acceptance criteria still require experiment-specific review.

Performance and reproducibility#

Do not infer speed from elapsed_seconds alone. It sums recorded peak-search and orientation-indexing time but excludes pixel-to-q conversion and Python setup.

For a reproducible comparison, record:

Package version or Git commit
Frame identifier and checksum when possible
Geometry and crystal file versions
Detector selection
start, group, and depth
Mask identity
Complete PeakParams and IndexParams
Hardware and process configuration for timing comparisons

Invalid configurations#

The Indexer raises InputError for invalid parameter ranges, unsupported peak models, malformed hkl_prefer, and max_data below two. See Configuration for exact field definitions.