Aaron: Created page with "{{DISPLAYTITLE:cctbx.xfel GUI/Unit Cell tab}} The '''Unit Cell tab''' plots histograms of the unit cell parameters of every indexed lattice in a trial, so that you can check that indexing is finding the expected cell, compare samples or conditions, spot polymorphs, and define unit cell clusters for the scaling stage of a dataset to filter on. The plot is redrawn every 15 seconds by the ''Unit Cell Sentinel'' while ''Auto update'' is ticked. Back to cctbx.xfel GUI...."

2026-10-09T22:19:35Z

Created page with "{{DISPLAYTITLE:cctbx.xfel GUI/Unit Cell tab}} The '''Unit Cell tab''' plots histograms of the unit cell parameters of every indexed lattice in a trial, so that you can check that indexing is finding the expected cell, compare samples or conditions, spot polymorphs, and define unit cell clusters for the scaling stage of a dataset to filter on. The plot is redrawn every 15 seconds by the ''Unit Cell Sentinel'' while ''Auto update'' is ticked. Back to cctbx.xfel GUI...."

New page

{{DISPLAYTITLE:cctbx.xfel GUI/Unit Cell tab}}
The '''Unit Cell tab''' plots histograms of the unit cell parameters of every indexed lattice in a trial, so that you can check that indexing is finding the expected cell, compare samples or conditions, spot polymorphs, and define unit cell clusters for the scaling stage of a dataset to filter on. The plot is redrawn every 15 seconds by the ''Unit Cell Sentinel'' while ''Auto update'' is ticked.

Back to [[cctbx.xfel GUI]].

== Selecting lattices by tag ==
The tab compares '''tag sets'''. Each tag set is a selection of runs from one trial, and each gets its own colour in the histograms.

# Choose the '''Trial'''. The ''Available tags'' list fills with the tags carried by that trial's runs.
# Tick one or more tags and choose '''union''' (runs carrying any of the tags) or '''intersection''' (runs carrying all of them). Ticking no tags selects every run in the trial (the set then shows as a blank entry in the list).
# Press '''Add selection'''. The set appears in ''Tag sets to display'', named after its tags with ''(u)'' or ''(i)'' for the mode when there is more than one tag.
# Repeat for further sets, for example one per sample. To drop a set, tick it and press '''Remove selection'''; '''Reset selections''' clears them all.

== Histogram mode ==
With ''Plot clusters'' unticked, the plot shows a histogram for each of a, b, c, α, β and γ for each tag set, with the legend giving the number of lattices and the mean and standard deviation of each parameter.

* '''Reject outliers''': drop lattices whose parameters fall outside 1.5 times the inter-quartile range before plotting, so that a few mis-indexed images do not stretch the axes.
* The matplotlib toolbar zooms and saves the figure, and ''Large text'' on the toolbar enlarges the labels.

== Cluster mode ==
With ''Plot clusters'' ticked (available only when the <code>uc_metrics</code> package is installed), the lattices of the '''first''' tag set are clustered with DBSCAN in the space of the independent cell parameters for the trial's space group (a, b, c for orthorhombic and lower; a, c for tetragonal, hexagonal and rhombohedral on hexagonal axes; a, α on rhombohedral axes; cubic cells cannot be clustered). The trial's space group comes from its indexing parameters, so set one in the trial for the clustering to use the right parameters.

* '''Cluster epsilon''' (default 0.8): the DBSCAN neighbourhood distance. Smaller values give tighter, more numerous clusters; press Enter to apply.
* ''Reject outliers'' controls whether the unclustered points are drawn.

Each clustering writes a covariance file, <code>cluster/cluster_<tag set name>.pickle</code> in the output folder, describing the Gaussian mixture components found (component 0 is the largest). The '''scaling stage''' of a dataset can filter lattices with this file (''Filter by unit-cell cluster'' in the [[cctbx.xfel GUI/Datasets tab#Scaling|Datasets tab]]), accepting only lattices within a chosen Mahalanobis distance of a chosen component. This is the way to merge only one polymorph when a sample indexes as a mixture.

== Tips ==
* A multi-modal histogram for a single sample usually means a mixture of crystal forms, or an indexing ambiguity producing permuted axes. Try cluster mode, or tighten the unit cell in the trial.
* Compare samples by adding one tag set per sample tag: differences in mean cell between conditions show up directly.
* Because the sentinel re-queries the database on every cycle, large trials can take a while to redraw; untick ''Auto update'' once the plot is as you want it.

Cctbx.xfel GUI/Unit Cell tab - Revision history