---
title: Full Workflow Tutorial
---

# 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

```python
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

```python
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

```python
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

```python
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

```python
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.