Differences

This shows you the differences between two versions of the page.

--- processing:compare-grain-orientations [2018/08/22 12:46]
smerkel
+++ processing:compare-grain-orientations [2019/12/03 13:39] (current)
jeff [Usage]
@@ Line 10: / Line 10: @@
 Here is the output of the help command
 <code>
 timelessGrainComparison --help
 usage: timelessGrainComparison [options] file1 file2
@@ Line 22: / Line 22: @@
   file2                 second grain file, matched against the previous file
                         (gff or GrainSpotter output file, based on extension)
-optional arguments:
-  -h, --help            show this help message and exit
   -c {1,2,3,4,5,6,7}, --crystal_system {1,2,3,4,5,6,7}
                         Crystal system. Can be one of the following 1:
                         Triclinic 2: Monoclinic 3: Orthorhombic 4: Tetragonal
 : Trigonal 6: Hexagonal 7: Cubic
+optional arguments:
+  -h, --help            show this help message and exit
   -o OUTPUT_STEM, --output_stem OUTPUT_STEM
                         Stem for output files. Default is comp
@@ Line 34: / Line 33: @@
                         Misorientation below which two grains are considered
                         identical, in degrees. Default is 2.0
+  -v VERBOSE, --verbose VERBOSE
+                        Create output file with verbose grain comparison. Can
+                        be True or False. Default is Default is False
 </code>
 ===== Example =====
-As an illustration, will will work with synthetic data on stishovite. The following [[processing:example:stishovitegff|file]]
+As an illustration, will will work with synthetic data on stishovite. The following file, {{ :processing:example:simu_stishovite_10grain2.gff | simu_stishovite_10grain2.gff }}, is the result of a [[processing:synthetic_dataset|PolyXSim simulation]] for stishovite. It includes the orientations of 10 stishovite grains, randomly oriented.
+The author ran a GrainSpotter indexing and generated a GrainSpotter log file: {{ :processing:example:stishovite_10grain2.log | stishovite_10grain2.log}}.
+We want to make sure that the grains indexed by GrainSpotter are the same than those we had in the simulation. In other words, we want to test that our indexing makes sense.
+==== Comparing grains ====
+The grain comparison is run as follow
+<code>
+timelessGrainComparison -c 4 -o test-stish simu_stishovite_10grain2.gff stishovite_10grain2.log
+</code>
+We use a tetragonal symmetry (c is set to 4), output files will start with ''test-stish'', the reference grains are found in ''simu_stishovite_10grain2.gff'' and we are checking whether the grains in ''stishovite_10grain2.log'' are correct.
+timelessGrainComparison can read gff or GrainSpotter log files. What matters is the order in which you provide the files. The first file is the reference, the second file will be checked.
+==== Terminal output ====
+You should get the following output in your terminal. In this case, the user did an excellent job. He indexed the 10 grains, with no erroneous grains. All grains are indexed with an orientation error of 0.01° or less. This is not always true! Your should be careful and train yourself with complex examples...
+<code>
+output files will be generated:
+- test-stish-log.dat,
+- test-stish-matching-grains.dat,
+- test-stish-erroneous-grains.dat
+Parsed simu_stishovite_10grain2.gff, found 10 grains
+Parsed stishovite_10grain2.log, found 10 grains
+Misorientation below which the two grains are considered identical, in degrees: 2.0
+Check for doubles in simu_stishovite_10grain2.gff
+Found 0 grains indexed twice
+New number of grains: 10
+Check for doubles in stishovite_10grain2.log
+Found 0 grains indexed twice
+New number of grains: 10
+Trying to match grains between the 2 collections...
+- Grain Grain-1 of simu_stishovite_10grain2.gff matches Grain-1 of stishovite_10grain2.log with a misorientation of 0.00°
+- Grain Grain-9 of simu_stishovite_10grain2.gff matches Grain-2 of stishovite_10grain2.log with a misorientation of 0.01°
+- Grain Grain-6 of simu_stishovite_10grain2.gff matches Grain-3 of stishovite_10grain2.log with a misorientation of 0.01°
+- Grain Grain-7 of simu_stishovite_10grain2.gff matches Grain-4 of stishovite_10grain2.log with a misorientation of 0.00°
+- Grain Grain-10 of simu_stishovite_10grain2.gff matches Grain-5 of stishovite_10grain2.log with a misorientation of 0.00°
+- Grain Grain-4 of simu_stishovite_10grain2.gff matches Grain-6 of stishovite_10grain2.log with a misorientation of 0.00°
+- Grain Grain-8 of simu_stishovite_10grain2.gff matches Grain-7 of stishovite_10grain2.log with a misorientation of 0.01°
+- Grain Grain-2 of simu_stishovite_10grain2.gff matches Grain-8 of stishovite_10grain2.log with a misorientation of 0.00°
+- Grain Grain-5 of simu_stishovite_10grain2.gff matches Grain-9 of stishovite_10grain2.log with a misorientation of 0.00°
+- Grain Grain-3 of simu_stishovite_10grain2.gff matches Grain-1 of stishovite_10grain2.log with a misorientation of 0.01°
+End of run
+N. of grains in simu_stishovite_10grain2.gff: 10
+N. of unique grains in simu_stishovite_10grain2.gff: 10
+N. of grains in stishovite_10grain2.log: 10
+N. of unique grains in stishovite_10grain2.log: 10
+N. of unique grains found in both simu_stishovite_10grain2.gff and stishovite_10grain2.log: 10
+N. of unique grains found only in stishovite_10grain2.log: 0
+N. of unique grains found in simu_stishovite_10grain2.gff but not in stishovite_10grain2.log: 0
+Indexing capability
+- 100.0 pc of simu_stishovite_10grain2.gff grains indexed
+- 0.0 pc of simu_stishovite_10grain2.gff grains not indexed
+- 0.0 pc of erroneous grains in stishovite_10grain2.log
+</code>
+==== Text file output ====
+There are several text files that can be used for further processing. From the previous examples, the output files are
+  * {{ :processing:example:test-stish-log.dat |test-stish-log.dat}}: a summary of the run,
+  * {{ :processing:example:test-stish-matching-grains.dat | test-stish-matching-grains.dat}}: information on matching grains (grains that were in the original list and were indexed, actually,
+  * {{ :processing:example:test-stish-erroneous-grains.dat | test-stish-erroneous-grains.dat }}: information on erroneous grains (grains that were indexed but should not have been there).
+In addition, the ''verbose'' option allows you to save a large file in which all grains from files 1 and 2 are compared to each other.
+===== Known issues =====
+==== Error: Found more than 1 pair for grain xy. Something is wrong ====
+Before it actually compares the two lists of grains, the script checks whether there are multiples within the same list (e.g. a certain grain appears more than once in the same list) and removes the multiple. So whenever the script finds a multiple in a later step it throws an error and stops because it assumes there must be something wrong.
+=== Cause of the issue ===
+However, this may actually happen, even if there is nothing wrong. Here is an example how this is possible:
+Let's assume our script considers grains identical if they have a misorientation of less than 2.0°. Going through the lists before the actual comparison throws out two lists of 100 grains each. Let's assume grain 44 and grain 66 of list A have a misorientation of 3.4°. This means they are not considered identical. Let's further assume there is a grain in list B (grain 20) which has a misorientation to grain 44 (list A) of 1.6° and also a misorientation of 1.9° to grain 66 (list A). This can actually happen if grain 20 lies roughly (or exactly) on the half-way rotation between grain 44 and 66.
+.7° is less than 2.0° so the script considers grain 20 (list A) and grain 44 (list B) identical. It also considers grain 20 (list A) and grain 66 (list B) identical. But at the beginning it considered grain 44 and grain 66 as NOT identical. The script is confused, throws the error ''Found more than 1 pair for grain 20. Something is wrong'' and stops.
+=== How to solve it ===
+Possibility 1: Delete the grain(s) with the issue from the list. (This is not a nice thing to do though.)
+Possibility 2: Decrease the maximum misorientation. (This is a better way.)\\
+The default value is 2.0°. Decrease it a bit and try again. In this example, decreasing it to 1.8° would already be enough:
+  * Grain 44 and grain 66 would still be considered not identical (misorientation = 3.4°).
+  * Grain 20 and grain 44 would still be considered identical (misorientation = 1.6°).
+  * But grain 20 and grain 66 would not be considered identical anymore because their misorientation of 1.9° is now above the threshold.
+During this process, you might lose other grains which were matching before but do not match anymore because of the decreased misorientation threshold.

TIMEleSS Multigrain Wiki

User Tools

Site Tools

Differences

Page Tools