pyextal.hdf5io
==============

.. py:module:: pyextal.hdf5io

.. autoapi-nested-parse::

   HDF5-based I/O for pre-refinement data.

   Replaces the per-stage .npy file family with a single HDF5 file per dataset.

   Layout
   ------
   {sample}.h5
   ├── attrs:  crystal_dat, acquisition_prefix, date
   ├── raw/          dp, variance, g_vectors
   └── pre_refinement/
       ├── attrs:    thickness, scale, background, gl, rotation, grid_shape
       ├── simgrid   (n_rows, n_cols, 3)
       ├── templates (n_beams, n_rows, n_cols)
       ├── variance  (n_beams, n_rows, n_cols)
       ├── roi_regions (n_regions, 4, 2)
       ├── g_include   (n_beams, 3)
       └── allshift    (n_shifts, 2)



Classes
-------

.. autoapisummary::

   pyextal.hdf5io.PreRefinementResult


Functions
---------

.. autoapisummary::

   pyextal.hdf5io.save_raw
   pyextal.hdf5io.save_pre_refinement
   pyextal.hdf5io.load_pre_refinement
   pyextal.hdf5io._replace


Module Contents
---------------

.. py:class:: PreRefinementResult

   Bases: :py:obj:`tuple`


   .. py:attribute:: simgrid


   .. py:attribute:: templates


   .. py:attribute:: variance


   .. py:attribute:: roi_regions


   .. py:attribute:: geometry


   .. py:attribute:: g_include


   .. py:attribute:: grid_shape


.. py:function:: save_raw(h5path, dp, variance, g_vectors, *, prefix='', crystal_dat='', date='')

   Write raw LARBED measurement into /raw of an HDF5 file.

   :param h5path:
   :type h5path: path-like
   :param dp:
   :type dp: (n_beams, ny, nx) array
   :param variance:
   :type variance: (n_beams, ny, nx) array
   :param g_vectors:
   :type g_vectors: (n_beams, 3) int array  — Miller indices
   :param prefix:
   :type prefix: optional provenance strings
   :param crystal_dat:
   :type crystal_dat: optional provenance strings
   :param date:
   :type date: optional provenance strings


.. py:function:: save_pre_refinement(h5path, roi, fine, g_include)

   Write pre-refinement outputs from a LARBEDROI + FineOptimize run to HDF5.

   Replaces the 6 np.save calls in the notebook export cell.  The arrays are
   stored in 2D spatial form (n_rows, n_cols) so the file is self-describing.

   :param h5path:
   :type h5path: path-like
   :param roi:
   :type roi: LARBEDROI  (must have had selectROI called — simGrid, templates, variance present)
   :param fine:
   :type fine: FineOptimize  (must have been run — fine.thickness, fine.errorFunc.scale/.background)
   :param g_include:
   :type g_include: list of (h,k,l) tuples — the reflections included in the ROI


.. py:function:: load_pre_refinement(h5path)

   Load pre-refinement outputs.

   :returns: simgrid     (n_rows, n_cols, 3)
             templates   (n_beams, n_rows, n_cols)
             variance    (n_beams, n_rows, n_cols)
             roi_regions (n_regions, 4, 2)
             geometry    dict — thickness, scale, background, gl, rotation, allshift
             g_include   (n_beams, 3) int array
             grid_shape  (n_rows, n_cols)
   :rtype: PreRefinementResult namedtuple with fields


.. py:function:: _replace(grp, name, data)

   Write (or overwrite) a compressed dataset inside an HDF5 group.