Merge pull request #2846 from nem1234/jeol_pts_emimage

jeol.py:  Add lazy loading for spectrum image, and add loader for SEM/STEM image in pts file

doc/user_guide/io.rst

@@ -1840,28 +1840,47 @@ files automatically.
 Extra loading arguments
 ^^^^^^^^^^^^^^^^^^^^^^^
 
-- ``rebin_energy`` : Factor used to rebin the energy dimension. It must be a
-  multiple of the number of channels, typically 4096. (default 1)
-- ``sum_frames`` : If False, each individual frame (sweep in JEOL software jargon)
+- ``rebin_energy`` : int, default 1.
+  Factor used to rebin the energy dimension. It must be a
+  factor of the number of channels, typically 4096.
+- ``sum_frames`` : bool, default True.
+  If False, each individual frame (sweep in JEOL software jargon)
   is loaded. Be aware that loading each individual will use a lot of memory,
   however, it can be used in combination with ``rebin_energy``, ``cutoff_at_kV``
   and ``downsample`` to reduce memory usage.
-  (default True).
-- ``SI_dtype`` : set dtype of the eds dataset. Useful to adjust memory usage
-  and maximum number of X-rays per channel. (default np.unit8)
-- ``cutoff_at_kV`` : if set (can be int or float >= 0), use to crop the energy
-  range up the specified energy. If ``None``, the whole energy range is loaded.
-  Useful to reduce memory usage. (default None).
-- ``downsample`` : the downsample ratio of the navigation dimension of EDS
+- ``SI_dtype`` : dtype, default np.uint8.
+  set dtype of the eds dataset. Useful to adjust memory usage
+  and maximum number of X-rays per channel.
+- ``cutoff_at_kV`` : int, float, or None, default None.
+  if set (>= 0), use to crop the energy range up the specified energy.
+  If ``None``, the whole energy range is loaded.
+  Useful to reduce memory usage.
+- ``downsample`` : int, default 1.
+  the downsample ratio of the navigation dimension of EDS
   dataset, it can be integer or a tuple of length 2 to define ``x`` and ``y``
   separetely and it must be a mutiple of the size of the navigation dimension.
-  (default 1).
-- ``only_valid_data`` : for ``pts`` file only, ignore incomplete and partly
+- ``only_valid_data`` : bool, default True.
+  for ``pts`` file only, ignore incomplete and partly
   acquired last frame, which typically occurs when the acquisition was
   interrupted. When loading incomplete data (``only_valid_data=False``),
   the missing data are filled with zeros. If ``sum_frames=True``, this argument
-  will be ignored to enforce consistent sum over the mapped area.
-  (default True).
+  will be ignored to enforce consistent sum over the mapped area. 
+- ``read_em_image`` : bool, default False.
+  for ``pts`` file only, If ``read_em_image=True``,
+  read SEM/STEM image from pts file if available. In this case, both
+  spectrum Image and SEM/STEM Image will be returned as list.
+- ``frame_list`` : list of integer or None, default None
+  for ``pts`` file only, frames in frame_list will be loaded.
+  for example, ``frame_list=[1,3]`` means second and forth frame will be loaded.
+  If ``None``, all frames are loaded.
+- ``frame_shifts`` : list of [int, int], list of [int, int, int], or None, default None
+  for ``pts`` file only, each frame will be loaded with offset of
+  [dy, dx (, and optionary dEnergy)]. Units are pixels/channels.
+  The result of estimate_shift2D() can be used as a parameter of frame_shifts.
+  This is useful for express drift correction. Not suitable for accurate analysis.
+- ``lazy`` : bool, default False
+  for ``pts`` file only, spectrum image is loaded as a dask.array if lazy == true.
+  This is useful to reduce memory usage, with cost of cpu time for calculation.
 
 
 Example of loading data downsampled, and with energy range cropped with the