3DXRD tasks#

How to use

These tasks come from ewoks3dxrd. It can be installed with

pip install ewoks3dxrd

ℹ️ These tasks are used at the following ESRF beamlines: ID03, ID11

DetectorSpatialCorrection#

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

Inputs:

  • segmented_peaks_url: a segmented 3d peaks data group data url

  • correction_files: 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

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

Required inputs:

correction_files, segmented_peaks_url

Optional inputs:

overwrite

Outputs:

spatial_corrected_data_url

FilterByIndexer#

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

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

  • use_rings_for_index_filter (tuple[int,…]): Tuple of int indicating the index of the ring, ex: (0,1,2)

Optional Inputs:

  • overwrite (Bool): OverWrite permission if output nexus process group already exists.

  • process_group_name (str): ‘Nexus group data name’ to save the index filtered peaks, default: indexer_filtered_peaks

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

Required inputs:

intensity_filtered_data_url, use_rings_for_index_filter

Optional inputs:

overwrite, process_group_name

Outputs:

indexer_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 ascii (.flt) and .h5 format.

Inputs:

  • lattice_filtered_data_url: a 3d peaks data group, it is must be corrected for geometry and detector

  • intensity_frac: float value to remove the peaks row whose intensity metric below than this value.

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

Required inputs:

intensity_frac, lattice_filtered_data_url

Optional inputs:

overwrite, process_group_name

Outputs:

intensity_filtered_data_url

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:

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

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

  3. 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_par_file is not present in the sample analysis path, it is copied to "par_folder/{lattice_par_file}".

Inputs

  • geometry_updated_data_url (str): Data Path to the geometry-transformed NxProcess group data peaks.

  • lattice_par_file (str): Path to the .par file containing lattice parameters and space group information.

  • reciprocal_dist_max (float): Maximum reciprocal distance for filtering (an Optional Value) If it is not provided, then maximum value in the ds column from input file will be used.

  • reciprocal_dist_tol (float): Tolerance for peak inclusion near lattice rings.

  • process_group_name (str): Optional Nexus process group name. Default: “phase_filtered_peaks.”

Outputs

  • lattice_filtered_data_url (str): Data path to the lattice filtered ‘NxProcess group data’ peaks

  • copied_lattice_par_file (str): Path to the copied lattice parameter file stored within the analysis folder.

Identifier:

ewoks3dxrd.tasks.filter_by_lattice.FilterByLattice

Task type:

class

Required inputs:

geometry_updated_data_url, lattice_par_file, reciprocal_dist_tol

Optional inputs:

overwrite, process_group_name, reciprocal_dist_max

Outputs:

copied_lattice_par_file, lattice_filtered_data_url

GeometryTransformation#

Does the geometry Transformation on the detector spatial corrected 3d peaks and geometry parameter (.par) file, Inputs: ‘spatial_corrected_data_url’ a detector spatial corrected 3d peaks nexus data group path and geometry file path a .par file This task performs the following operations:

  1. Gathers geometry information from the geometry_tdxrd.par file.

  2. 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’

  3. Applies the geometry correction to the 3D peaks column file using the ImageD11 dataset class.

  4. Save the geometry corrected 3d peaks columnfile (output: geometry_updated_3d_peaks_file)

Identifier:

ewoks3dxrd.tasks.geometry_transformation.GeometryTransformation

Task type:

class

Required inputs:

geometry_par_file, spatial_corrected_data_url

Optional inputs:

overwrite

Outputs:

geometry_updated_data_url

IndexGrains#

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

Inputs:

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

  • gen_rings_from_idx (Tuple): Indices of rings used for generating UBI. Two are usually enough, three in some rare cases.

  • score_rings_from_idx (Tuple): Indices of the rings used for scoring. These must contain the indices used for indexing.

Optional Inputs:

  • max_grains (int): To limit the maximum number of grains (UBI matrices).

  • reciprocal_dist_tol (float): reciprocal distance tolerance value.

  • hkl_tols (Tuple): hkl tolerance, (hkl are integers, while doing convergence, had to do discretization on processed values)

  • min_pks_frac (Tuple): min peaks fraction to iterate over

  • cosine_tol (float): a tolerance value used in the Indexer convergence scheme for finding pairs of peaks to make an orientation

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

Required inputs:

gen_rings_from_idx, intensity_filtered_data_url, score_rings_from_idx

Optional inputs:

cosine_tol, hkl_tols, max_grains, min_pks_frac, overwrite, reciprocal_dist_tol

Outputs:

indexed_grain_data_url

MakeGrainMap#

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

Inputs:

  • folder_file_config: Output from Init Folder File Config Task as input here.

  • indexed_grain_ubi_file: indexed Grains ascii file path.

  • intensity_filtered_data_url: Filtered peaks data group path that were used for the indexing

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

  • minpks: To filter grains that are not associated with at least #minpks peaks after iterative refinement.

  • lattice_name: Use lattice parameter value from lattice par file referred by ‘lattice_name’.par.

Optional Inputs:

  • intensity_fine_filtered_data_url: Peaks used to refine the grains finely at the end of the iterative refinement. Default: intensity_filtered_data_url.

  • intensity_two_theta_range: tuple of two floats, giving two theta min and max when refining. Default: (0., 180.).

  • symmetry (str): Lattice symmetry used to further refine grains. Default: cubic.

Outputs:

  • ascii_grain_map_file: file where the refined grains are saved

Identifier:

ewoks3dxrd.tasks.make_grain_map.MakeGrainMap

Task type:

class

Required inputs:

folder_file_config, hkl_tols, indexed_grain_data_url, intensity_filtered_data_url, minpks

Optional inputs:

analyse_folder, intensity_fine_filtered_data_url, intensity_two_theta_range, overwrite, symmetry

Outputs:

make_map_data_url

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:

  • segmented_3d_peaks_file: A segmented 3d peaks for the given scan folder is saved in this path.

  • 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

Required inputs:

correction_files, folder_config, segmenter_algo_params

Optional inputs:

monitor_name, overwrite

Outputs:

sample_folder_info, segmented_peaks_url