From 09b3d00c9c2cf365f2cf7c278f86459823032c36 Mon Sep 17 00:00:00 2001 From: Thomas White Date: Sat, 25 Sep 2010 22:51:29 +0200 Subject: Add .txt to documentation files Let's not make life difficult just for the sake of it. --- doc/geometry | 52 ---------------------------------- doc/geometry.txt | 52 ++++++++++++++++++++++++++++++++++ doc/indexamajig | 80 ----------------------------------------------------- doc/indexamajig.txt | 80 +++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/pattern_sim | 0 doc/pattern_sim.txt | 0 doc/process_hkl | 6 ---- doc/process_hkl.txt | 6 ++++ doc/symmetry | 61 ---------------------------------------- doc/symmetry.txt | 61 ++++++++++++++++++++++++++++++++++++++++ 10 files changed, 199 insertions(+), 199 deletions(-) delete mode 100644 doc/geometry create mode 100644 doc/geometry.txt delete mode 100644 doc/indexamajig create mode 100644 doc/indexamajig.txt delete mode 100644 doc/pattern_sim create mode 100644 doc/pattern_sim.txt delete mode 100644 doc/process_hkl create mode 100644 doc/process_hkl.txt delete mode 100644 doc/symmetry create mode 100644 doc/symmetry.txt (limited to 'doc') diff --git a/doc/geometry b/doc/geometry deleted file mode 100644 index d4fcdb79..00000000 --- a/doc/geometry +++ /dev/null @@ -1,52 +0,0 @@ -CrystFEL detector geometry files --------------------------------- - -The detector geometry is taken from a text file rather than hardcoded into the -program. Programs which care about the geometry (indexamajig, pattern_sim and -powder_plot) take an argument "--geometry=" (or "-g "), where -contains the geometry. CrystFEL's representation of a detector is broken down -into one or more "panels", each of which has its own location for the centre of -the panel (i.e. the location of the central beam), its own camera length, -resolution and so on. Each panel fits into the overall image taken from the -HDF5 file, defined by minimum and maximum coordinates in x and y. The -coordinates are specified inclusively, meaning that a minimum of 0 and a maximum -of 9 results in ten items. Counting begins from zero. All pixels in the image -must be assigned to a panel. - -See "A note on data orientation" in the top level README file for important -information about how CrystFEL defines the axes. All coordinates (including the -centre coordinates for each panel) are measured according to these axes: there -is no coordinate system local to a panel. - -The syntax for a simple geometry might be as follows: - -; The number of panels -n_panels = 1 - -; "0/" specifies the first (and only) panel. If we had more panels, there would -; be a copy of the following lines but prefixes with "1/", "2/" and so on. - -; The region of the image which belongs to this panel: -0/min_x = 0 -0/max_x = 1023 -0/min_y = 512 -0/max_y = 1023 - -; The coordinates of the central beam which should be -; used for pixels in this panel: -0/cx = 491.9 -0/cy = 440.7 - -; The camera length (in metres) for this panel -0/clen = 67.8e-3 - -; The resolution (in pixels per metre) for this panel -0/res = 13333.3 ; 75 micron pixel size - -; The readout direction (x or y). If more than three peaks are found in -; the same readout region, they are all discarded. This helps to avoid -; problems due to streaks appearing along the readout direction. -0/badrow_direction = y - - -See the "examples" folder for some examples. diff --git a/doc/geometry.txt b/doc/geometry.txt new file mode 100644 index 00000000..d4fcdb79 --- /dev/null +++ b/doc/geometry.txt @@ -0,0 +1,52 @@ +CrystFEL detector geometry files +-------------------------------- + +The detector geometry is taken from a text file rather than hardcoded into the +program. Programs which care about the geometry (indexamajig, pattern_sim and +powder_plot) take an argument "--geometry=" (or "-g "), where +contains the geometry. CrystFEL's representation of a detector is broken down +into one or more "panels", each of which has its own location for the centre of +the panel (i.e. the location of the central beam), its own camera length, +resolution and so on. Each panel fits into the overall image taken from the +HDF5 file, defined by minimum and maximum coordinates in x and y. The +coordinates are specified inclusively, meaning that a minimum of 0 and a maximum +of 9 results in ten items. Counting begins from zero. All pixels in the image +must be assigned to a panel. + +See "A note on data orientation" in the top level README file for important +information about how CrystFEL defines the axes. All coordinates (including the +centre coordinates for each panel) are measured according to these axes: there +is no coordinate system local to a panel. + +The syntax for a simple geometry might be as follows: + +; The number of panels +n_panels = 1 + +; "0/" specifies the first (and only) panel. If we had more panels, there would +; be a copy of the following lines but prefixes with "1/", "2/" and so on. + +; The region of the image which belongs to this panel: +0/min_x = 0 +0/max_x = 1023 +0/min_y = 512 +0/max_y = 1023 + +; The coordinates of the central beam which should be +; used for pixels in this panel: +0/cx = 491.9 +0/cy = 440.7 + +; The camera length (in metres) for this panel +0/clen = 67.8e-3 + +; The resolution (in pixels per metre) for this panel +0/res = 13333.3 ; 75 micron pixel size + +; The readout direction (x or y). If more than three peaks are found in +; the same readout region, they are all discarded. This helps to avoid +; problems due to streaks appearing along the readout direction. +0/badrow_direction = y + + +See the "examples" folder for some examples. diff --git a/doc/indexamajig b/doc/indexamajig deleted file mode 100644 index 42f63771..00000000 --- a/doc/indexamajig +++ /dev/null @@ -1,80 +0,0 @@ -indexmajig - bulk indexing and data reduction program ------------------------------------------------------ - -The indexamajig program takes as input a list of diffraction image files, -currently in HDF5 format. For each image, it attempts to find peaks and then -index the pattern. If successful, it will measure the intensities of the peaks -at Bragg locations and produce a list in the form "h k l I", with some extra -information about the locations of the peaks. - -For minimal basic use, you need to provide the list of diffraction patterns, -the method which will be used to index (currently there is only one available -method), a file describing the geometry of the detector, a PDB file which -contains the unit cell which will be used for the indexing, and that you'd like -the program to output a list of intensities for each successfully indexed -pattern. You should redirect the output (stdout, but not stderr) of the program -to a file for later analysis. Here is what the minimal use looks like on the -command line, with each argument shown on a separate line. In practice, you'd -put this all on one line: - -indexamajig --i mypatternlist.lst ---indexing=dirax ---geometry mygeometry.geom --p mystructure.pdb ---near-bragg -> myoutputfile.txt - -More typical use includes all the above, but might also include a noise or -common mode filter (--filter-noise or --filter-cm respectively) if detector -noise causes problems for the peak detection. The HDF5 files might be in some -folder a long way from the current directory, so you might want to specify a -full pathname to be added in front of each filename. You'll probably want to -run more than one indexing job at a time (-j ), and you might want to correct -the intensities of saturated peaks according to a list stored elsewhere in the -HDF5 file: - -indexamajig --i mypatternlist.lst ---indexing=dirax ---geometry mygeometry.geom --p mystructure.pdb ---near-bragg ---filter-noise ---prefix=/some/horribly/long/pathname/ending/in/a/slash/ --j 16 ---sat-corr -> myoutputfile.txt - -The table of saturation values for --sat-corr should be located in the HDF5 file -as follows: /processing/hitfinder/peakinfo_saturated. It should be an n*3 two -dimensional array, where the first two columns contain x and y coordinates and -the third contains the value which should belong in a peak at location x,y. The -value will be divided by 5 and spread in a small cross centred on that location. - -See doc/geometry for information about how to create a geometry description -file. - - -Unconventional Use ------------------- - -There are some less often used options, for example "--dump-peaks" to dump the -peak locations found by the peak search (in turn presented to the indexer). -This might be useful if you want to check the performance of the peak finder. -If you run a large dataset with bot --dump-peaks and --near-bragg enabled, -you'll generate a large amount of data. To separate the peaks from the -indexed peaks, use scripts/stream-split as follows: - -scripts/stream-split myoutputfile.txt indexed.txt peaks.txt - -.. to generate both indexed.txt and peaks.txt. One of the last two arguments -can be "/dev/null" if you're only interested in the other. - - -"Gotchas" ---------- - -Don't run more than one indexamajig jobs simultaneously in the same working -directory - they'll overwrite each other's DirAx files, causing subtle problems -which can't easily be detected. diff --git a/doc/indexamajig.txt b/doc/indexamajig.txt new file mode 100644 index 00000000..42f63771 --- /dev/null +++ b/doc/indexamajig.txt @@ -0,0 +1,80 @@ +indexmajig - bulk indexing and data reduction program +----------------------------------------------------- + +The indexamajig program takes as input a list of diffraction image files, +currently in HDF5 format. For each image, it attempts to find peaks and then +index the pattern. If successful, it will measure the intensities of the peaks +at Bragg locations and produce a list in the form "h k l I", with some extra +information about the locations of the peaks. + +For minimal basic use, you need to provide the list of diffraction patterns, +the method which will be used to index (currently there is only one available +method), a file describing the geometry of the detector, a PDB file which +contains the unit cell which will be used for the indexing, and that you'd like +the program to output a list of intensities for each successfully indexed +pattern. You should redirect the output (stdout, but not stderr) of the program +to a file for later analysis. Here is what the minimal use looks like on the +command line, with each argument shown on a separate line. In practice, you'd +put this all on one line: + +indexamajig +-i mypatternlist.lst +--indexing=dirax +--geometry mygeometry.geom +-p mystructure.pdb +--near-bragg +> myoutputfile.txt + +More typical use includes all the above, but might also include a noise or +common mode filter (--filter-noise or --filter-cm respectively) if detector +noise causes problems for the peak detection. The HDF5 files might be in some +folder a long way from the current directory, so you might want to specify a +full pathname to be added in front of each filename. You'll probably want to +run more than one indexing job at a time (-j ), and you might want to correct +the intensities of saturated peaks according to a list stored elsewhere in the +HDF5 file: + +indexamajig +-i mypatternlist.lst +--indexing=dirax +--geometry mygeometry.geom +-p mystructure.pdb +--near-bragg +--filter-noise +--prefix=/some/horribly/long/pathname/ending/in/a/slash/ +-j 16 +--sat-corr +> myoutputfile.txt + +The table of saturation values for --sat-corr should be located in the HDF5 file +as follows: /processing/hitfinder/peakinfo_saturated. It should be an n*3 two +dimensional array, where the first two columns contain x and y coordinates and +the third contains the value which should belong in a peak at location x,y. The +value will be divided by 5 and spread in a small cross centred on that location. + +See doc/geometry for information about how to create a geometry description +file. + + +Unconventional Use +------------------ + +There are some less often used options, for example "--dump-peaks" to dump the +peak locations found by the peak search (in turn presented to the indexer). +This might be useful if you want to check the performance of the peak finder. +If you run a large dataset with bot --dump-peaks and --near-bragg enabled, +you'll generate a large amount of data. To separate the peaks from the +indexed peaks, use scripts/stream-split as follows: + +scripts/stream-split myoutputfile.txt indexed.txt peaks.txt + +.. to generate both indexed.txt and peaks.txt. One of the last two arguments +can be "/dev/null" if you're only interested in the other. + + +"Gotchas" +--------- + +Don't run more than one indexamajig jobs simultaneously in the same working +directory - they'll overwrite each other's DirAx files, causing subtle problems +which can't easily be detected. diff --git a/doc/pattern_sim b/doc/pattern_sim deleted file mode 100644 index e69de29b..00000000 diff --git a/doc/pattern_sim.txt b/doc/pattern_sim.txt new file mode 100644 index 00000000..e69de29b diff --git a/doc/process_hkl b/doc/process_hkl deleted file mode 100644 index b6411285..00000000 --- a/doc/process_hkl +++ /dev/null @@ -1,6 +0,0 @@ -process_hkl - data scaling and merging program ----------------------------------------------- - -This program takes as input the data stream from "indexamajig". It merges the -many individual intensities together to form a single list of reflection -intensities which are useful for crystallography. diff --git a/doc/process_hkl.txt b/doc/process_hkl.txt new file mode 100644 index 00000000..b6411285 --- /dev/null +++ b/doc/process_hkl.txt @@ -0,0 +1,6 @@ +process_hkl - data scaling and merging program +---------------------------------------------- + +This program takes as input the data stream from "indexamajig". It merges the +many individual intensities together to form a single list of reflection +intensities which are useful for crystallography. diff --git a/doc/symmetry b/doc/symmetry deleted file mode 100644 index 3b3ee124..00000000 --- a/doc/symmetry +++ /dev/null @@ -1,61 +0,0 @@ -How CrystFEL handles symmetry ------------------------------ - -Currently, only process_hkl and render_hkl understand symmetry (and render_hkl -only understands it when plotting a zone axis pattern). - -Symmetry definitions are included in src/symmetry.c. Point group definitions -are required for merging and the display of merged results, but space groups are -not taken into account since merging does not care about systematic absences - -as far as process_hkl is concerned, systematic absences are just measurements -which happen to have values of zero. Each space group belongs to exactly one -point group, which you can look up in the International Tables for X-Ray -Crystallography. - -Please read doc/process_hkl for important information on how symmetry is used -during the indexing and merging procedures. - - -Adding a new point group ------------------------- - -Point groups are being added here as they are required, so it's likely that the -exact one you want hasn't been added yet. Here's how to add a new one by -editing src/symmetry.c. - -First, expand the check_cond() function to include a description of the -asymmetric reciprocal unit cell for the point group. Every reflection in the -whole of reciprocal space must map onto exactly one reflection in the asymmetric -unit cell so defined. The asymmetric cell is usually defined with positive h, k -and l, but it doesn't really matter. Working out the required condition means -visualising the cell and taking care to properly handle situations such as the -(000) reflection. Get this right, otherwise you'll go crazy when it breaks in -weird ways. - -Next, expand the num_general_equivs() function. Given a point group, this -function must return the number of equivalent reflections for a general -reflection, including the input reflection. High-symmetry reflections (usually -ones with zeroes in their indices) have fewer equivalents, but the num_equivs() -function will work this out for you. - -Finally, add the new point group to the get_general_equiv() function. This -function takes a set of Miller indices, a point group and an index "n", and -returns (by reference) the indices of the "n"th equivalent reflection. You just -have to worry about the general position, because get_equiv() will work out the -special positions for you. get_general_equiv() must return the original indices -when idx=0. - - -The symmetry of the molecular model (the space group) ------------------------------------------------------ - -get_hkl does not currently understand symmetry, which means you'll have to -expand any molecular model (the PDB) out to P1 to get the correct results. You -can achieve that, for example, by loading it into Mercury, turning on "Packing" -and re-saving. Alternatively, you can do this using CCP4 with a command like: - -$ echo symgen P63 | pdbset xyzin model.pdb xyzout model-P1.pdb - -While on this subject, you might also want to include hydrogens in the model -using something like: -$ echo HYDROGENS APPEND | hgen xyzin model.pdb xyzout model-with-H.pdb diff --git a/doc/symmetry.txt b/doc/symmetry.txt new file mode 100644 index 00000000..3b3ee124 --- /dev/null +++ b/doc/symmetry.txt @@ -0,0 +1,61 @@ +How CrystFEL handles symmetry +----------------------------- + +Currently, only process_hkl and render_hkl understand symmetry (and render_hkl +only understands it when plotting a zone axis pattern). + +Symmetry definitions are included in src/symmetry.c. Point group definitions +are required for merging and the display of merged results, but space groups are +not taken into account since merging does not care about systematic absences - +as far as process_hkl is concerned, systematic absences are just measurements +which happen to have values of zero. Each space group belongs to exactly one +point group, which you can look up in the International Tables for X-Ray +Crystallography. + +Please read doc/process_hkl for important information on how symmetry is used +during the indexing and merging procedures. + + +Adding a new point group +------------------------ + +Point groups are being added here as they are required, so it's likely that the +exact one you want hasn't been added yet. Here's how to add a new one by +editing src/symmetry.c. + +First, expand the check_cond() function to include a description of the +asymmetric reciprocal unit cell for the point group. Every reflection in the +whole of reciprocal space must map onto exactly one reflection in the asymmetric +unit cell so defined. The asymmetric cell is usually defined with positive h, k +and l, but it doesn't really matter. Working out the required condition means +visualising the cell and taking care to properly handle situations such as the +(000) reflection. Get this right, otherwise you'll go crazy when it breaks in +weird ways. + +Next, expand the num_general_equivs() function. Given a point group, this +function must return the number of equivalent reflections for a general +reflection, including the input reflection. High-symmetry reflections (usually +ones with zeroes in their indices) have fewer equivalents, but the num_equivs() +function will work this out for you. + +Finally, add the new point group to the get_general_equiv() function. This +function takes a set of Miller indices, a point group and an index "n", and +returns (by reference) the indices of the "n"th equivalent reflection. You just +have to worry about the general position, because get_equiv() will work out the +special positions for you. get_general_equiv() must return the original indices +when idx=0. + + +The symmetry of the molecular model (the space group) +----------------------------------------------------- + +get_hkl does not currently understand symmetry, which means you'll have to +expand any molecular model (the PDB) out to P1 to get the correct results. You +can achieve that, for example, by loading it into Mercury, turning on "Packing" +and re-saving. Alternatively, you can do this using CCP4 with a command like: + +$ echo symgen P63 | pdbset xyzin model.pdb xyzout model-P1.pdb + +While on this subject, you might also want to include hydrogens in the model +using something like: +$ echo HYDROGENS APPEND | hgen xyzin model.pdb xyzout model-with-H.pdb -- cgit v1.2.3