1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
|
.\"
.\" ambigator man page
.\"
.\" Copyright © 2012-2018 Deutsches Elektronen-Synchrotron DESY,
.\" a research centre of the Helmholtz Association.
.\"
.\" Part of CrystFEL - crystallography with a FEL
.\"
.TH AMBIGATOR 1
.SH NAME
ambigator \- Resolve indexing ambiguities
.SH SYNOPSIS
.PP
.B ambigator \fIinput.stream\fR \fB[-o\fR \fIoutput.stream\fR\fB] [options]
.B ambigator --help
.SH DESCRIPTION
This program resolves indexing ambiguities using a simplified variant of the clustering algorithm described by Brehm and Diederichs, Acta Crystallographica D70 (2013) p101.
The algorithm starts by making a random indexing assignment to each crystal. The indexing assignment is a flag which indicates whether the crystal should be re-indexed according to the ambiguity operator.
The algorithm proceeds by calculating the individual correlation coefficients between the intensities from one crystal and those from each of the other crystals in turn. The mean correlation coefficient, \fIf\fR, is taken over all crystals which have the same indexing assignment as the current pattern. Separately the mean correlation coefficient \fIg\fR is taken over all crystals which have indexing assignments opposite to the current crystal. The indexing assignment for the current crystal is changed if \fIg\fR > \fIf\fR. Every crystal is visited once in turn, and the pass over all the crystals repeated several times.
Only one indexing ambiguity can be resolved at a time. In other words, each crystal is considered to be indexable in one of only two ways. If the true indexing ambiguity has more possibilities than this, the resolution must be performed by running \fBambigator\fR multiple times with a different ambiguity operator each time.
If the ambiguity operator is known (or, equivalently, the actual and apparent symmetries are both known), then the algorithm can be enhanced by including in \fIf\fR the correlation coefficients of all the crystals with the opposite indexing assignment to the current one, but after reindexing the other crystal first. Likewise, \fIg\fR includes the correlation coefficients of the crystals with the same indexing assignment after reindexing. This enhances the algorithm to an extent roughly equivalent to doubling the number of crystals.
The default behaviour is to compare each crystal to every other crystal. This leads to a computational complexity proportional to the square of the number of crystals. If the number of crystals is large, the number of comparisons can be limited without compromising the algorithm much. In this case, the crystals to correlate against will be selected randomly.
.SH OPTIONS
.PD 0
.IP "\fB-o\fR \fIfilename\fR"
.IP \fB--output=\fR\fIfilename\fR
.PD
Write a re-indexed version of the input stream to \fIfilename\fR. This stream can then be merged normally using \fBprocess_hkl\fR or \fBpartialator\fR, but using the actual symmetry instead of the apparent one.
.IP
\fBWARNING\fR: There is no default filename. The default behaviour is not to output any reindexed stream!
.PD 0
.IP "\fB-y\fR \fIpg\fR"
.IP \fB--symmetry=\fR\fIpg\fR
.PD
Set the actual symmetry of the crystals. If you're not sure, set this to the highest symmetry which you want to assume, which might be \fB-1\fR to assume Friedel's Law alone or \fB1\fR (the default) for no symmetry at all. The algorithm will work significantly better if you can use a higher symmetry here.
.PD 0
.IP "\fB-w\fR \fIpg\fR"
.PD
Set the apparent symmetry of the crystals. The ambiguity operator will be determined by comparing this to the actual symmetry.
.IP
If you prefer (or the scenario demands it), you can specify the ambiguity operator directly using \fB--operator\fR.
.IP
Using this option (or \fB--operator\fR) improves the algorithm to an extent roughly equivalent to doubling the number of crystals.
.PD 0
.IP \fB--operator=\fR\fIop\fR
.PD
Specify the indexing ambiguity operator. Example: \fB--operator=k,h,-l\fR.
.IP
If you prefer, you can specify the ambiguity operator by specifying the apparent symmetry using \fB-w\fR.
.IP
Using this option (or \fB-w\fR) improves the algorithm to an extent roughly equivalent to doubling the number of crystals.
.PD 0
.IP "\fB-n\fR \fIn\fR"
.IP \fB--iterations=\fR\fIn\fR
The number of passes through the data to make. Extra iterations are not expensive once the initial correlation calculation has been performed, so set this value quite high. Two or three iterations are normally sufficient unless the number of correlations (see \fB--ncorr\fR) is small compared to the number of crystals. The default is \fB--iterations=6\fR.
.PD 0
.IP "\fB-j\fR \fIn\fR"
Number of threads to use for the CC calculation.
.PD 0
.IP \fB--highres=\fR\fId\fR
High resolution cutoff in Angstroms.
.PD 0
.IP \fB--lowres=\fR\fId\fR
Low resolution cutoff in Angstroms.
.PD 0
.IP \fB--start-assignments=\fR\fIfilename\fR
Read the starting assignments to \fIfilename\fR. The file must be a list of 0 or 1, one value per line, in the same order as the crystals appear in the input stream. 1 means that the pattern should be reindexed according to the ambiguity operator. The length of the file must be at least equal to the number of crystals in the input stream.
.PD 0
.IP \fB--end-assignments=\fR\fIfilename\fR
Write the end assignments to \fIfilename\fR. The file will be a list of 0 or 1, one value per line, in the same order as the crystals appear in the input stream. 1 means that the pattern should be reindexed according to the ambiguity operator.
.PD 0
.IP \fB--fg-graph=\fR\fIfilename\fR
Write f and g values to \fIfilename\fR, one line per crystal, repeating all crystals as they are visited by the algorithm. Plot these using \fBfg-graph\fR from the CrystFEL script folder to evaluate the ambiguity resolution.
.PD 0
.IP \fB--ncorr=\fR\fIn\fR
Use \fIn\fR correlations per crystal. The default is to correlate against every crystal. If the CC calculation is too slow, try \fB--ncorr=1000\fR. Note that this option sets the maximum number of correlations, and some crystals might not have enough common reflections to correlate to the number requested. The mean number of actual correlations per crystal will be output by the program after the CC calculation, and if this number is much smaller than \fIn\fR then this option will not have a significant effect.
.PD 0
.IP \fB--really-random\fR
Be non-deterministic by seeding the random number generator (used to make the initial indexing assignments and select patterns to correlate against) from /dev/urandom. Otherwise, with single-threaded operation (\fB-j 1\fR) on the same data, the results from this program should be the same if it is re-run. Using more than one thread already introduces some non-deterministic behaviour.
.PD 0
.IP \fB--corr-matrix=\fR\fIfilename\fR
Write the the correlation matrices in HDF5 format to \fIfilename\fR. The file will contain two datasets: \fBcorrelation_matrix\fR and \fBcorrelation_matrix_reindexed\fR. They contain, respectively, the correlation matrix with all crystals in their original orientations and all crystals in the reindexed orientations. If the ambiguity operator is unknown (i.e. neither \fB--operator\fR nor \fB-w\fR were used), then the latter will be zero everywhere.
.SH AUTHOR
This page was written by Thomas White.
.SH REPORTING BUGS
Report bugs to <taw@physics.org>, or visit <http://www.desy.de/~twhite/crystfel>.
.SH COPYRIGHT AND DISCLAIMER
Copyright © 2014-2018 Deutsches Elektronen-Synchrotron DESY, a research centre of the Helmholtz Association.
ambigator, and this manual, are part of CrystFEL.
CrystFEL is free software: you can redistribute it and/or modify it under the
terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
CrystFEL is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with CrystFEL. If not, see <http://www.gnu.org/licenses/>.
.SH SEE ALSO
.BR crystfel (7),
.BR indexamajig (1).
|
