====== Merge GrainSpotter output files ======

If you run GrainSpotter multiple times on the same dataset, you will want to merge the different output files into one and end up with a single collection of unique grains.

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


===== Objectives =====

Let's say you ran GrainSpotter 3 times, with the following output files: ''grainsIndexed1.log'', ''grainsIndexed2.log'', and ''grainsIndexed3.log''. You will run the code as follow
<code>
timelessGrainSpotterMerge -c 3 grainsIndexed1.log grainsIndexed2.log grainsIndexed3.log
</code>

It will compare grains in the 3 output files. Grains are considered equal if their relative orientation is below a threshold misorientation, 2° by default. The script will keep the indexing with the largest number of assigned peak. The script also counts the number of times a grain with indexed (i.e. the number of times the same grain appears in a GrainSpotter output file).

New GrainSpotter output files are generated, 
  *  a file with a list of unique grains,
  *  a file with the grains that were indexed only once,
  *  a file with the grains that were indexed twice,
  *  a file with the grains that were indexed three times,
  *  etc


===== Usage =====

Here is the output of the help command
<code>
timelessGrainSpotterMerge  -h
Using AVX codes
usage: timelessGrainSpotterMerge [options] file1 file2 ... fileN

Merges grains from multiple GrainSpotter indexings This is part of the
TIMEleSS project http://timeless.texture.rocks

positional arguments:
  files                 grainSpotter output files

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
                        5: Trigonal 6: Hexagonal 7: Cubic
  -o OUTPUT_STEM, --output_stem OUTPUT_STEM
                        Stem for output files. Default is merge
  -m MISORIENTATION, --misorientation MISORIENTATION
                        Misorientation below which two grains are considered
                        identical, in degrees. Default is 2.0
  -s SKIPBOGUS, --skipbogus SKIPBOGUS
                        Skip bogus grains in GrainSpotter output.
                        Default is False
</code>


===== Terminal output ===== 

Here is an example of a terminal output

<code>
Parsed grainsIndexed1.log, found 7 grains
Parsed grainsIndexed2.log, found 6 grains
Parsed grainsIndexed3.log, found 7 grains

Misorientation below which the two grains are considered identical, in degrees: 2.0

Looking for unique grains
- grain 0 and 7 are identical
- grain 0 and 17 are identical
- grain 1 and 10 are identical
- grain 1 and 19 are identical
- grain 3 and 9 are identical
- grain 3 and 13 are identical
- grain 4 and 8 are identical
- grain 4 and 14 are identical
- grain 5 and 11 are identical
- grain 5 and 16 are identical
- grain 6 and 12 are identical
- grain 6 and 18 are identical
- grain 7 and 17 are identical
- grain 8 and 14 are identical
- grain 9 and 13 are identical
- grain 10 and 19 are identical
- grain 11 and 16 are identical
- grain 12 and 18 are identical
Found 12 grains indexed twice
New number of grains: 8

Indexing statistics
- 6 grains were indexed 3 times
- 2 grains were indexed 1 times

Saving unique grains
- all 8 unique grains saved in merge-grains.log
- 6 grains indexed 3 times saved in merge-grains-3.log
- 2 grains indexed 1 times saved in merge-grains-1.log
</code>