PROCESS_HKL(1)

📦
version 0.13.0 · 2 versions
, in nixpkgs unstable

💅 PROCESS_HKL(1) — like, the merging era ✨

okay so bestie, welcome to the process_hkl glow-up page 💖 this is from the General Commands Manual, and it's genuinely one of the most iconic little tools in the CrystFEL friend group. grab a strawberry drink 🍓 and let's get into it.

🌸 NAME 🌸

process_hkl — Monte Carlo merging of Bragg intensities. that's it, that's the vibe, she merges, she slays ✨

🦋 SYNOPSIS 🦋

process_hkl -i mypatterns.stream -o mydata.hkl -y pointgroup [options]
...
process_hkl --help

so the [options] there is doing so much heavy lifting, and the ... is basically the manpage saying "you know the drill, babe" 🎀

👑 DESCRIPTION 👑

process_hkl takes a data stream — like, the kind indexamajig hands you — and merges all those many individual intensities together into one single list of reflection intensities that's actually useful for crystallography. like taking a chaotic group chat and turning it into one clean, quotable summary 💅

and how does she merge? by the Monte Carlo method, which is the fancy way of saying, and I quote the manpage here, "taking the mean of the individual values." lowkey obsessed with that level of honesty, ngl 🫶

✨ OPTIONS ✨

every single one, bestie, no skipping, no cap 🔥

  • -i filename, --input=filename — give the name of the input stream. and heads up, --input=- means use stdin. iconic behavior honestly.
  • -o filename, --output=filename — give the name of the output file. default is --output=processed.hkl.
  • -y pointgroup, --symmetry=pointgroup — merge according to symmetry pointgroup.
  • -g h,k,l, --histogram=h,k,l — calculate a histogram of intensities for h,k,l, which gets written as histogram.dat in the current directory. cute little side quest 🎀
  • -z min,max,nbins, --hist-parameters=min,max,nbins — set the minimum and maximum values, and the number of bins, to min, max and nbins, respectively.
  • --start-after=n — ignore the first n crystals in the input. default is --start-after=0, i.e. start at the beginning, main character from page one 🧚
  • --stop-after=n — stop processing after n crystals have been successfully merged. default is --stop-after=0, which means process all the patterns from the start point to the end of the input (see --start-after).
  • --even-only — merge only the even-numbered crystals in the stream. "even-numbered" is defined simply according to position in the stream, i.e. not according to any serial number. see also --odd-only. she's picky, we respect it 💅
  • --odd-only — merge only the odd-numbered crystals in the stream. "odd-numbered" is defined simply according to position in the stream, i.e. not according to any serial number. see also --even-only. the other half of the duo ✨
  • --scale — perform a second pass through the input, scaling each crystal's intensities to best fit the initial model. and a little note from the page itself: use partialator if you need more advanced merging techniques. ok so partialator is the older sister, got it 👑
  • --polarisation=type — specify the polarisation of the incident radiation. type can be horiz or vert to indicate 100% polarisation of the electric field in the horizontal plane or vertical plane respectively. setting type to none completely disables the polarisation correction (see the note below, it's important 👀). alternatively, type can be a direction followed by a percentage polarisation fraction. for example, 45deg90 means that 90% of the radiation is polarised with its electric field in a direction 45 degrees from horizontal, and 10deg100 means that all the radiation is polarised at 10 degrees from horizontal. the angle is specified clockwise from horizontal as viewed along the beam direction, i.e. as shown by the CrystFEL GUI. the beam is unpolarised when the fraction is 50% (equal parts of the radiation have their electric field in the specified plane). if the polarisation fraction is 100%, it can be omitted. for example 10deg or horiz. the default is --polarisation=horiz.
🚨 okay the note, because it matters: --polarisation=none is not the same as, for example, --polarisation=vert50. in the first case, the polarisation correction will be completely disabled. in the other case, the incident beam will be unpolarised, but the polarisation of the diffracted radiation will still be corrected for (the factor of (1+cos^2(2theta))/2 or, equivalently, (2-sin^2(2theta))/2). like, these are two different things bestie, don't mix them up 😭
  • --no-polarisation — synonym for --polarisation=none. same energy, shorter spelling 🫶
  • --min-measurements=n — include a reflection in the output only if it appears at least n times. the default is --min-measurements=2. (and yeah, the original page says "least least", we're keeping the whole vibe intact, it's endearing 💀)
  • --min-snr=n — use a particular individual reflection intensity measurement only if it exceeds its estimated standard error by at least n. the default is -infinity, i.e. no cutoff.
⚠️ WARNING: think very carefully before using this option. it will bias reflections towards more positive values, even where no signal exists, leading to a data set dominated by the background. this can invalidate some of the figures of merit for the merit for data quality while severely compromising the actual quality. like... fr fr, be so careful, this one is not a cute casual flag 🙈
  • --max-adu=n — include reflections only if their peak values were less than n. that means n is the saturation value of the detector. the default is infinity, i.e. no cutoff.
  • --min-res=n — merge crystals only if they diffract to beyond n Angstroms resolution. the default is infinity, i.e. all crystals are included. the resolution is taken from the diffraction_resolution_limit line in the stream.
  • --push-res=n — merge reflections which are up to n nm^-1 higher than the apparent resolution limit of each individual crystal. n can be negative to merge lower than the apparent resolution limit. the default is --push-res=inf, which means no resolution cutoff at all.
  • --min-cc=n — perform a second pass through the input, merging crystals only if their correlation with the initial model is at least n.
  • --stat=filename — perform a second pass through the input and, for each crystal merged, write a line to filename containing the filename, scale factor and correlation coefficient with the initial model. the scale factors will all be 1 unless --scale is also used. receipts, but make them data ✨

🌈 CHOICE OF POINT GROUP FOR MERGING 🌈

okay so this part is genuinely iconic crystal lore 👑

one of the main features of serial crystallography is that the orientations of individual crystals are random. that means the orientation of each crystal must be determined independently, with no information about its relationship to the orientation of crystals in other patterns. every crystal is on its own solo journey, no notes 🦋

some symmetry classes are merohedral, which means that they have lower symmetry than their lattices. this means that the orientation determined by indexing will have an ambiguity. in such cases, you will need to merge according to corresponding holohedral point group. to determine what this is, consult the tables in twin-calculator.pdf. like, actually consult them, don't guess 💅

🎀 AUTHOR 🎀

this page was written by Thomas White. thank you king 🫶

💀 REPORTING BUGS 💀

report bugs to <taw@physics.org>, or visit <http://www.desy.de/~twhite/crystfel>. they want to hear from you, bestie, that's how the glow-up happens 🌸

Copyright © 2012-2021 Deutsches Elektronen-Synchrotron DESY, a research centre of the Helmholtz Association.

process_hkl, 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/>.

⭐ SEE ALSO ⭐

crystfel(7), indexamajig(5), compare_hkl(1), check_hkl(1), render_hkl(1), ambigator(1), partialator(1) — the whole squad, go say hi 👑

okay that's the page!! sending you off with a lil sign-off: this was process_hkl(1) from the CrystFEL manual, brought to you by General Commands Manual energy, copyright © 2012-2021 Deutsches Elektronen-Synchrotron DESY 💖 go merge something gorgeous, bestie. slay. periodt. 🎀✨

📦 where this page comes from