Tasks#

Note

Use these tasks to create your own 3DXRD workflow.

If you are looking for an example workflow, see the Workflows page

Segmentation#

SegmentScan#

This task segments an entire scan folder, merges the peaks, and produces a 3D column file. The resulting 3D column peak file is saved.

Outputs:

sample_folder_info: A Config information about raw scan sample
segmented_peaks_url: A Nexus file data url path to segmented_3d_peaks data

Identifier:: ewoks3dxrd.tasks.segment_scan.SegmentScan
Task type:: class

Inputs:

overwrite : bool= False: Overwrite NXprocess group if it already exists
folder_config* : ewoks3dxrd.models.SegmenterFolderConfig
segmenter_algo_params* : ewoks3dxrd.models.GaussianPeakSearchConfig | ewoks3dxrd.models.LimaSegmenterAlgoConfig
correction_files* : ewoks3dxrd.models.SegmenterCorrectionFiles
monitor_name : str | None= None

Outputs:

sample_folder_info
segmented_peaks_url

Additional models#

SegmenterFolderConfig#

Fields:

omega_motor* : str: The name of the rotation motor
master_file* : str
scan_number* : int
detector* : str: The name of the detector
analyse_folder* : str

GaussianPeakSearchConfig#

Fields:

algorithm : Literal['gaussian_peak_search']= gaussian_peak_search: Gaussian Peak Search segmentation Algorithm
threshold* : int
smooth_sigma* : float
bgc* : float
min_px* : int
offset_threshold* : int
ratio_threshold* : int

LimaSegmenterAlgoConfig#

Fields:

algorithm : Literal['lima_segmenter']= lima_segmenter: Lima Peak Search Segmentation Algorithm
lower_bound_cut* : int
max_pixels_per_frame* : int
num_pixels_in_spot* : int

SegmenterCorrectionFiles#

Fields:

bg_file : str | None= None
mask_file : str | None= None
dark_file : str | None= None
flat_file : str | None= None

Data correction#

DetectorSpatialCorrection#

Does the detector spatial correction on the segmented 3d peaks and saves the corrected 3D column peak file

Outputs:

spatial_corrected_data_url: A Nexus file path along with data entry point to spatial_corrected_peaks data group

Identifier:: ewoks3dxrd.tasks.detector_spatial_correction.DetectorSpatialCorrection
Task type:: class

Inputs:

overwrite : bool= False

Overwrite NXprocess group if it already exists

segmented_peaks_url* : str

Path to the NXprocess group containing the segmeted peaks

correction_files* : Tuple[str, str] | str

two corrections are possible:

Spline correction: correction_files should be a string containing the path to the spline file
e2dx,e2dy correction: correction_files should be a tuple of 2 strings, the first one being the path to e2dx file, the second the path to the e2dy file
any other type will be treated as invalid input

Examples:

'eiger.spline'
('eiger.e2dx', 'eiger.e2dy')

Outputs:

spatial_corrected_data_url

GeometryTransformation#

This task performs the following operations:

Gathers geometry information from the geometry_tdxrd.par file.
Copy the geometry file in the directory structure: analysis_folder / dset_name / (dset_name + sample_name). i.e the parent folder of ‘detector_spatial_corrected_3d_peaks_file’
Applies the geometry correction to the 3D peaks column file using the ImageD11 dataset class.
Save the geometry corrected 3d peaks columnfile (output: geometry_updated_3d_peaks_file)

Identifier:: ewoks3dxrd.tasks.geometry_transformation.GeometryTransformation
Task type:: class

Inputs:

overwrite : bool= False: Overwrite NXprocess group if it already exists
spatial_corrected_data_url* : str: Path to the NXprocess group containing the detector spatial corrected 3D peaks
geometry_par_file* : str: Path to the .par file containing geometry parameters

Outputs:

geometry_updated_data_url
wavelength

Peak filtering#

FilterByIndexer#

Filter the 3D merged peaks using Indexer, to be used only to grid indexer for producing grains.

Outputs:

indexer_filtered_data_url (str): Data path to ‘NxProcess group data’ Grains that stores generated UBI

Identifier:: ewoks3dxrd.tasks.filter_by_index.FilterByIndexer
Task type:: class

Inputs:

overwrite : bool= False

Overwrite NXprocess group if it already exists

intensity_filtered_data_url* : str

Path to the NXprocess group containing the intensity filtered peaks

rings* : Sequence[int]

Ring indices

Examples:

(0, 1, 2)

process_group_name : str= indexer_filtered_peaks

NXprocess group name where to save the filtered peaks

wavelength* : float

wavelength used in the geometry transformation task

ds_tol : float= 0.025

distance tolerance used in the lattice based filtering task

lattice_file* : str

Path to the file (.par or .cif) containing lattice parameters and space group information forwarded by lattice filter task

Outputs:

indexer_filtered_data_url
indexer_log

FilterByLattice#

Performs Lattice/Phase-based filtering on a geometry-transformed 3D peaks file.

This process applies filtering based on ‘reciprocal distance’ and ‘lattice’ rings ds criteria to extract relevant peaks.

Steps:

Initial Filtering:
- Copies the input geometry-transformed 3D peaks file.
- Reads the ds column and removes rows where ds exceeds the specified reciprocal_dist_max value.
Lattice-Based Filtering:
- Computes ideal lattice ring ds values (reciprocal distances from the origin).
- Further filters peaks based on these values, using the tolerance defined by reciprocal_dist_tol.
File Storage:
- Saves the lattice-filtered 3D peaks file as {Lattice_name}_{reciprocal_dist_max_tag}_filtered_3d_peaks.h5,flt in the parent directory of the input file (‘geometry_trans_3d_peaks_file’).

Additionally, if the specified lattice_file is not present in the sample analysis path, it is copied to "par_folder/{lattice_file}".

Outputs

lattice_filtered_data_url (str): Data path to the lattice filtered ‘NxProcess group data’ peaks
copied_lattice_file (str): Path to the copied lattice parameter file stored within the analysis folder.
ds_tol (float): Forwarding the value of reciprocal_dist_tol for the future tasks

Identifier:: ewoks3dxrd.tasks.filter_by_lattice.FilterByLattice
Task type:: class

Inputs:

overwrite : bool= False: Overwrite NXprocess group if it already exists
geometry_updated_data_url* : str: Path to the NXprocess group containing containing the geometry-transformed peaks
lattice_file* : str: Path to the .par file containing lattice parameters and space group information.
reciprocal_dist_tol* : float: Tolerance for peak inclusion near lattice rings
reciprocal_dist_max : float | None= None: Maximum reciprocal distance for filtering. If None or not provided, the maximum value in the ds column from input file will be used.
process_group_name : str= lattice_filtered_peaks: NXprocess group name where to save the filtered peaks

Outputs:

copied_lattice_file
ds_tol
lattice_filtered_data_url

FilterByIntensity#

Does the Intensity based peaks filter, computes intensity metric based on sum_intensity, ds (reciprocal distance) columns from the input file normalize with the maximum value of intensity metric, only keeps the rows whose value is above the given input ‘intensity_frac’ and save them in .h5 format.

Outputs:

intensity_filtered_data_url (str): Data path to the intensity filtered ‘NxProcess group data’ peaks

Identifier:: ewoks3dxrd.tasks.filter_by_intensity.FilterByIntensity
Task type:: class

Inputs:

overwrite : bool= False: Overwrite NXprocess group if it already exists
lattice_filtered_data_url* : str: Path to the NXprocess group containing the peaks corrected for geometry and detector
intensity_frac* : float: Filter peaks whose intensity is below this value
thermal_factor : float= 0.2: Thermal Factor in computing correction intensity from sum intensity
process_group_name : str= intensity_filtered_peaks: NXprocess group name where to save the filtered peaks

Outputs:

intensity_filtered_data_url

Indexing#

GridIndexGrains#

From 3D peaks, finds grains’ UBI matrices and stores them in NeXus (.h5) format.

Warning

This task is still experimental and may break or change without notice.

Outputs:

grid_indexed_grain_data_url (str): Data path to ‘NxProcess group data’ grains that stores generated UBI

Identifier:: ewoks3dxrd.tasks.grid_index_grains.GridIndexGrains
Task type:: class

Inputs:

overwrite : bool= False

Overwrite NXprocess group if it already exists

indexer_filtered_data_url* : str

Path to NXprocess group containing the filtered (be it by index, lattice or intensity) peaks

grid_index_parameters* : ewoks3dxrd.models.GridIndexParameters

dict of following parameters:

NPKS (int) : number of peaks
DSTOL (float) : reciprocal distance tolerance
RING1 (Sequence[int]) : default (1, 0)
RING2 (Sequence[int]) : default (0,)
NUL (bool) : default True
FITPOS (bool) : default True
tolangle (float) : default 0.50
toldist (float) : default 100.0
NPROC (int) : default None, but ImageD11 will set it to maximum available cores on the server
NTHREAD (int) : default 1
COSTOL (float) : default None (from model) if default provided then here will set it to np.cos(np.radians(90 - 2 * omega_slop))
OMEGAFLOAT (float) : default None (from model) if default provided then here will set it to omega_slop Note: omega_slop is related to wobble of the instrument,
TOLSEQ (Tuple[float, …]) : default (0.02, 0.015, 0.01)
SYMMETRY (str) : default cubic

analyse_folder : str | pathlib.Path | None= None

grid_abs_x_limit : int= 600

X limit of the 3D space to search translation positions of grains.

grid_abs_y_limit : int= 600

Y limit of the 3D space to search translation positions of grains.

grid_abs_z_limit : int= 200

Z limit of the 3D space to search translation positions of grains.

grid_step : int= 100

Step size of the 3D space to search translation positions of grains.

seed : int | None= 42

Seed for translation shuffling. Pass None to disable translation shuffling

sample_config : ewoks3dxrd.models.SampleConfig | None= None

Override the sample config. If not provided, it will be retrieved from the segmentation step

process_group_name : str= grid_indexed_grains

NXprocess group name where to save the grid indexed grains

Outputs:

grid_indexed_grain_data_url

Additional models#

GridIndexParameters#

Fields:

NPKS* : int
DSTOL : float= 0.004
RING1 : Sequence[int]= (1, 0)
RING2 : Sequence[int]= (0,)
NUL : bool= True
FITPOS : bool= True
tolangle : float= 0.5
toldist : float= 100.0
NPROC : int | None= None
NTHREAD : int= 1
COSTOL : float | None= None
OMEGAFLOAT : float | None= None
TOLSEQ : Tuple[float, ...]= (0.02, 0.015, 0.01)
SYMMETRY : str= cubic

SampleConfig#

Fields:

omega_motor* : str: The name of the rotation motor
master_file* : str
scan_number* : int

IndexGrains#

From 3D peaks, finds grains’ UBI matrices and stores them in both ASCII format and NeXus (.h5) format.

Outputs:

indexed_grain_data_url (str): Data path to ‘NxProcess group data’ Grains that stores generated UBI

Identifier:: ewoks3dxrd.tasks.index_grains.IndexGrains
Task type:: class

Inputs:

overwrite : bool= False

Overwrite NXprocess group if it already exists

intensity_filtered_data_url* : str

Path to NXprocess group containing the intensity filtered peaks

rings* : Sequence[int]

Indices of rings used for generating UBI. Two are usually enough, three in some rare cases.

Examples:

(0, 1)

scoring_rings* : Sequence[int]

Indices of the rings used for scoring. These must contain the indices used for indexing.

Examples:

(0, 1, 2)

max_grains : int | None= None

Limits the number of found grains.

reciprocal_dist_tol : float | None= None

Reciprocal distance tolerance value.

hkl_tols : Sequence[float] | None= None

Miller indices tolerances.

Examples:

(0.01, 0.02, 0.03, 0.04)

min_pks_frac : Sequence[float] | None= None

Minimal peaks fraction to iterate over.

cosine_tol : float | None= None

tolerance value used in the Indexer convergence scheme for finding pairs of peaks to make an orientation

lattice_file* : str

Path to the file (.par or .cif) containing lattice parameters and space group information forwarded by lattice filter task

wavelength* : float

wavelength used in the geometry transformation task

process_group_name : str= indexed_grains

NXprocess group name where to save the indexed grains

Outputs:

indexed_grain_data_url

Grain mapping#

MakeGrainMap#

Does an iterative refinement based on hkl_tols followed by a fine refinement on the indexed grains

Outputs:

ascii_grain_map_file: file where the refined grains are saved

Identifier:: ewoks3dxrd.tasks.make_grain_map.MakeGrainMap
Task type:: class

Inputs:

overwrite : bool= False

Overwrite NXprocess group if it already exists

folder_file_config* : ewoks3dxrd.models.SampleConfig

indexed_grain_data_url* : str

Path to NXprocess group containing the indexed grains

intensity_filtered_data_url* : str

Path to NXprocess group containing the filtered peaks used for the indexing

hkl_tols* : Sequence[float]

Decreasing sequence of hkl tolerances. Will be used for iterative refinement (one after the other).

Examples:

(0.3, 0.2, 0.1)

minpks* : int

Minimal number of peaks for the grain to be kept after iterative refinement.

intensity_fine_filtered_data_url : str | None= None

Path to NXprocess group containing the peaks to use to refine the grains finely at the end of the iterative refinement

intensity_two_theta_range : Tuple[float, float]= (0.0, 180.0)

Range of two theta to use when refining

symmetry : str= cubic

Lattice symmetry used to further refine grains

analyse_folder : str | pathlib.Path | None= None

lattice_file* : str

Path to the file (.par or .cif) containing lattice parameters and space group information forwarded by lattice filter task

process_group_name : str= make_map_grains

NXprocess group name where to save the make grains map

Outputs:

make_map_data_url

Additional models#

SampleConfig#

Fields:

omega_motor* : str: The name of the rotation motor
master_file* : str
scan_number* : int