TIMEleSS Multigrain Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Compare grain orientations ======

Sometimes, you might want to compare the orientations of grains between two collections, to make sure that they are the same, for instance.

A typical case when you perform this operation is during training. If you [[processing:synthetic_dataset|generated a synthetic dataset]] and indexed this data, you will want to make sure that the grains you indexed actually existed at start.

This operation is performed using the ''timelessGrainComparison'' script, which is part of the [[software:timelesstools|TIMEleSS tools]].

===== Usage =====

Here is the output of the help command
<code>
timelessGrainComparison --help
usage: timelessGrainComparison [options] file1 file2

Compare grains between 2 files This is part of the TIMEleSS project
http://timeless.texture.rocks

positional arguments:
  file1                 first grain file, used as a reference (gff or
                        GrainSpotter output file, based on extension)
  file2                 second grain file, matched against the previous file
                        (gff or GrainSpotter output file, based on extension)
  -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
                        5: 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
  -m MISORIENTATION, --misorientation MISORIENTATION
                        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 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>
3 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.

1.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.