Merge pull request #764 from donald-e-boyce/GrainData-doc

added GrainData.rst file

docs/source/users/GrainData.rst

@@ -0,0 +1,91 @@
+GrainData Class
+================
+
+The `GrainData` class loads the grain data output files, either
+`grains.out` or `grains.npz`. The intent of the class is to simplify
+post-processing by making it easy to load and save the grain data files
+and providing commonly used data attributes.
+
+
+Loading and Saving
+-----------------------
+You can load the newer `grains.npz` file using the `load` method, or you
+can load the `grains.out` file directly using the `from_grains_out`
+method. For example:
+
+.. code-block::
+
+   from hexrd.fitgrains import GrainData
+
+   # Load an npz file.
+   gd = GrainData.load("graindata.npz")
+
+   # Or load the standard `grains.out` file.
+   gd = GrainData.from_grains_out("grains.out")
+
+You can also write a new `.npz` file or a `.out` file.
+
+.. code-block::
+
+   gd.save("new-grains.npz")
+   gd.write_grains_out("new-grains.out")
+
+
+
+Working With Grain Data
+------------------------
+
+After loading data you have access to the following attributes. Notice that
+the shape of orientation arrays (`expmap`, `rotation_matrices`, `quaterions`)
+is different from core hexrd and more pythonic in that each orientation
+occupies a contiguous section of memory.
+
+num_grains
+    the number of grains
+
+id
+    *array(num_grains)*, grain ID in original output file
+
+completeness
+    *array(num_grains)*, completeness value for each grain
+
+chisq
+    *array(num_grains)*, goodness of fit values
+
+expmap
+    *array(num_grains, 3)*, exponential map parameters for orientations
+
+centroid
+    *array(num_grains), 3*, grain centroid values
+
+inv_Vs
+    *array(num_grains, 6)*, inverse of symmetric left stretch tensor
+
+ln_Vs
+    *array(num_grains, 6)*, matrix logarithm of symmetric left stretch tensor
+
+rotation_matrices
+    *array(num_grains, 3)*, rotation matrices for orientations
+
+quaternions
+    *array(num_grains, 4)*, unit quaternions for orientations
+
+strain
+    *array(num_grains, 6)*, convenience function for `ln_Vs`
+
+You are also able to select a subset of grains based on completeness or
+goodness of fit using the `select()` method. It returns a new `GrainData`
+instance with all arrays filtered by the selected IDs. Note that the
+new `id` attribute shows the original IDs and will no longer be contiguous.
+Here is an example of usage:
+
+.. code-block::
+
+   # Select grains at 80% completeness or better.
+   gd_new = gd.select(min_completeness=0.8)
+
+   # Select grains with chi-squared at most 0.5.
+   gd_new = gd.select(max_chisq=0.5)
+
+   # Or both.
+   gd_new = gd.select(min_completeness=0.8, max_chisq=0.5)