Full Workflow Tutorial#

This tutorial mirrors the practical sequence TexTOM users follow on experimental data. It assumes you already installed TexTOM inside a dedicated Python environment (see the how-to guide).

1. Prepare the Sample Directory#

  1. Create or select a working directory per sample and copy the relevant data (detector masks, .poni, .cif files) into or alongside it. Raw data do not have to be transferred.

  2. Launch textom from inside that folder so every generated artifact (e.g., analysis/, data_integrated/) stays scoped to the sample.

  3. Run textom_config once if you have not already set thread counts or GPU defaults.

2. Integrate Raw Frames#

integrate()

  • Fill out the prompted configuration: overview HDF5 path, filename pattern, detector metadata datasets, azimuth/radial ranges, sampling density (npt_rad, npt_azi), and integration mode (TexTOM requires 2D; add 1D if desired).

  • Select parallel execution parameters (n_tasks, cores_per_task); leave both as 1 for GPU-based integration.

  • The command writes integrated datasets into data_integrated/ (and /data_integrated_1d/ when 1D output is requested).

3. Align Projections#

align_data()

  • Clean data_integrated/ by moving unwanted files elsewhere; the function consumes everything matching the filename filter. Revise present data and projection numbers using list_projections().

  • Provide a q_range (preferred) or q_index_range centred on representative peaks to stabilise the scalar alignment metric.

  • Edit the generated geometry.py to describe beam direction, rotation axes, scan mode, and detector flips. TexTOM caches it under analysis/geometry.py for reuse.

  • Review alignment diagnostics: alignment_result.h5, check_alignment_consistency(), check_alignment_projection(g), g referring to the projection number.

4. Build the Physical Model#

make_model()

  • Supply crystallographic metadata via crystal.py: CIF path, energy, q-range, harmonic order (HSH) or grid resolution.

  • Inspect the simulated powder pattern versus averaged data; adjust lattice parameters or cut-off values until peaks match.

  • Generate projectors after a valid alignment run. The interactive histogram helps you choose thresholds to mask background voxels, producing analysis/projectors.h5.

5. Pre-process Peaks#

preprocess_data()

  • Select q-intervals per peak, set detector masks, and pick a baseline subtraction strategy (linear, chebyshev, chebyshev_auto, none).

  • TexTOM stores your choices (mask/peak files) under analysis/, so repeated runs or similar samples can reuse them.

  • Use helpers like check_baselines() or mask_peak_regions() to iterate without re-running everything.

6. Optimise Orientation Distributions#

optimize()

  • Launch the gradient-based solver; progress writes into analysis/fits/<timestamp>/.

  • Interruptions with Ctrl+C still persist the latest iteration. Resume or compare runs using list_opt() and load_opt().

  • Health-check the fit using check_residuals(), check_projection_orientations(g), check_projection_residuals(g).

7. Analyse and Export Results#

  • Populate derived metrics via calculate_orientation_statistics(), calculate_segments(), or calculate_order_parameters().

  • Persist dictionaries with save_results() and reload later via load_results() / list_results_loaded().

  • Export grids for Paraview using export_paraview().

8. Visualise#

  • Scalar volumes: show_volume(), show_slice_directions().

  • Orientation tools: show_volume_ipf(), show_slice_ipf(), show_voxel_odf(), show_voxel_polefigure().

  • QC plots: show_histogram(), show_correlations(), plus save_images() for automation.

Next Steps#

  • Dive into the how-to guides for focused topics (environment setup, remote execution, troubleshooting).

  • Check the explanations section if you want the theory behind diffractlets, projectors, or optimisation strategies.