Merge pull request #59 from pudeIko/pyOS-EiC-checks

PyOS EiC checks
pudeIko · Jan 23, 2025 · 83a3255 · 83a3255
2 parents adaeaa5 + 5e1a21d
commit 83a3255
Show file tree

Hide file tree

Showing 40 changed files with 452 additions and 64 deletions.
diff --git a/dist/piva-0.0.1-py3-none-any.whl b/dist/piva-0.0.1-py3-none-any.whl
diff --git a/dist/piva-0.0.1.tar.gz b/dist/piva-0.0.1.tar.gz
diff --git a/docs/img/custom_widget.png → docs/img/custom/custom_widget.png b/docs/img/custom_widget.png → docs/img/custom/custom_widget.png
diff --git a/docs/img/db-labels.png → docs/img/db/db-labels.png b/docs/img/db-labels.png → docs/img/db/db-labels.png
diff --git a/docs/img/db.png → docs/img/db/db.png b/docs/img/db.png → docs/img/db/db.png
diff --git a/docs/img/dl-cdl.png → docs/img/dl/dl-cdl.png b/docs/img/dl-cdl.png → docs/img/dl/dl-cdl.png
diff --git a/docs/img/dl-scheme.png → docs/img/dl/dl-scheme.png b/docs/img/dl-scheme.png → docs/img/dl/dl-scheme.png
diff --git a/docs/img/dl/dl-test_spectrum.png b/docs/img/dl/dl-test_spectrum.png
diff --git a/docs/img/dv-2d-main.png → docs/img/dv/dv-2d-main.png b/docs/img/dv-2d-main.png → docs/img/dv/dv-2d-main.png
diff --git a/docs/img/dv-3d-main.png → docs/img/dv/dv-3d-main.png b/docs/img/dv-3d-main.png → docs/img/dv/dv-3d-main.png
diff --git a/docs/img/dv-4d-main.png → docs/img/dv/dv-4d-main.png b/docs/img/dv-4d-main.png → docs/img/dv/dv-4d-main.png
diff --git a/docs/img/dv-up-axes.png → docs/img/dv/dv-up-axes.png b/docs/img/dv-up-axes.png → docs/img/dv/dv-up-axes.png
diff --git a/docs/img/dv-up-file.png → docs/img/dv/dv-up-file.png b/docs/img/dv-up-file.png → docs/img/dv/dv-up-file.png
diff --git a/docs/img/dv-up-image.png → docs/img/dv/dv-up-image.png b/docs/img/dv-up-image.png → docs/img/dv/dv-up-image.png
diff --git a/docs/img/dv-up-orientate.png → docs/img/dv/dv-up-orientate.png b/docs/img/dv-up-orientate.png → docs/img/dv/dv-up-orientate.png
diff --git a/docs/img/dv-up-volume.png → docs/img/dv/dv-up-volume.png b/docs/img/dv-up-volume.png → docs/img/dv/dv-up-volume.png
diff --git a/docs/img/fitters-edc-main.png → ...img/fitters_plottool/fitters-edc-main.png b/docs/img/fitters-edc-main.png → ...img/fitters_plottool/fitters-edc-main.png
diff --git a/docs/img/fitters-mdc-fitting_tab.png → ...ters_plottool/fitters-mdc-fitting_tab.png b/docs/img/fitters-mdc-fitting_tab.png → ...ters_plottool/fitters-mdc-fitting_tab.png
diff --git a/docs/img/fitters-mdc-main.png → ...img/fitters_plottool/fitters-mdc-main.png b/docs/img/fitters-mdc-main.png → ...img/fitters_plottool/fitters-mdc-main.png
diff --git a/docs/img/plottool-main.png → docs/img/fitters_plottool/plottool-main.png b/docs/img/plottool-main.png → docs/img/fitters_plottool/plottool-main.png
diff --git a/docs/img/plottool-up-add_remove.png → ...tters_plottool/plottool-up-add_remove.png b/docs/img/plottool-up-add_remove.png → ...tters_plottool/plottool-up-add_remove.png
diff --git a/docs/img/plottool-up-annotate.png → ...fitters_plottool/plottool-up-annotate.png b/docs/img/plottool-up-annotate.png → ...fitters_plottool/plottool-up-annotate.png
diff --git a/docs/img/plottool-up-edit_curves.png → ...ters_plottool/plottool-up-edit_curves.png b/docs/img/plottool-up-edit_curves.png → ...ters_plottool/plottool-up-edit_curves.png
diff --git a/docs/img/plottool-up-edit_plot.png → ...itters_plottool/plottool-up-edit_plot.png b/docs/img/plottool-up-edit_plot.png → ...itters_plottool/plottool-up-edit_plot.png
diff --git a/docs/img/plottool-up-markers.png → .../fitters_plottool/plottool-up-markers.png b/docs/img/plottool-up-markers.png → .../fitters_plottool/plottool-up-markers.png
diff --git a/docs/misc/piva_dataloader_importer.py b/docs/misc/piva_dataloader_importer.py
@@ -1,6 +1,7 @@
 import numpy as np
 from piva.data_loaders import Dataloader, Dataset
 from piva.data_browser import DataBrowser
+import h5py
 
 
 class DataloaderImporter:
@@ -26,20 +27,20 @@ def add_dataloader1(self) -> None:
         """
 
         loader = CustomDataloader
-        dl_label = 'Custom Dataloader - {}'.format(loader.name)
+        dl_label = '{}'.format(loader.name)
 
         self.db.dp_dl_picker.addItem(dl_label)
         self.db.add_dataloader_to_record(dl_label, loader)
 
-        print('\t', loader.name, dl_label)
+        print('\t', dl_label)
 
 
 class CustomDataloader(Dataloader):
     """
     Simple example of a custom Dataloader.
     """
 
-    name = 'Custom1'
+    name = 'Custom_Dataloader'
 
     def __init__(self) -> None:
         super(CustomDataloader, self).__init__()
@@ -57,7 +58,7 @@ def load_data(self, filename: str, metadata: bool = False) -> Dataset:
         :return: loaded dataset with available metadata
         """
 
-        # dummy if condition to make the example work. One should remove
+        # dummy *if* condition to make the example work. One should remove
         # 'isinstance' part and change extension in 'endswith'
         if filename.endswith('h5') or isinstance(filename, str):
             self.custom_loading_method(filename, metadata=metadata)
@@ -67,11 +68,69 @@ def load_data(self, filename: str, metadata: bool = False) -> Dataset:
         self.ds.add_org_file_entry(filename, self.name)
         return self.ds
 
-    # function to implement. It supposed to read the file, extract data and
-    # metadata from it and pass them into Dataset object.
-    def custom_loading_method(self, filename, metadata=False):
-        n = 100
-        self.ds.data = np.random.random((n, n, n))
-        self.ds.xscale = np.arange(n)
-        self.ds.yscale = np.arange(n)
-        self.ds.zscale = np.arange(n)
+    def custom_loading_method(self, filename: str, metadata: bool = False):
+        """
+        This method is intended to read a file, extract its data and metadata,
+        and pass them into a :class:`Dataset` object.
+
+        Its content is designed to work with a simulated test file available
+        on the documentation website but can be freely replaced as needed.
+
+        :param filename: absolute path to the file
+        :param metadata: if :py:obj:`True`, read only metadata and size of the
+                         dataset. Not used here, but required to mach format
+                         of other **Dataloaders**. See :meth:`load_ses_zip`
+                         for more info.
+        """
+
+        # Extract the dataset and some metadata
+        datfile = h5py.File(filename, 'r')
+        h5_data = datfile['spectrum']
+        yscale = datfile['dimensions'].attrs['momentum']
+        zscale = datfile['dimensions'].attrs['energy']
+
+        # Convert to array and make 3D if necessary
+        shape = h5_data.shape
+        if metadata:
+            data = np.zeros(shape)
+        else:
+            data = np.array(h5_data)
+
+        data = data.T
+        if len(shape) == 2:
+            ny = shape[1]
+            nz = shape[0]
+            # Make data 3D
+            data = data.reshape((1, ny, nz))
+            xscale = np.array([1])
+            scan_type = 'cut'
+        else:
+            # adjust if scan has higher dimensionality
+            pass
+
+        # Extract available metadata
+        meta = datfile['metadata'].attrs
+        x_pos = meta['x']
+        y_pos = meta['y']
+        z_pos = meta['z']
+        temp = meta['temp']
+        pressure = meta['pres']
+        hv = meta['hv']
+        polarization = meta['polar']
+        DT = meta['DT']
+
+        self.ds.data = data
+        self.ds.xscale = xscale
+        self.ds.yscale = yscale
+        self.ds.zscale = zscale
+        self.ds.x = x_pos
+        self.ds.y = y_pos
+        self.ds.z = z_pos
+        self.ds.temp = temp
+        self.ds.pressure = pressure
+        self.ds.hv = hv
+        self.ds.polarization = polarization
+        self.ds.scan_type = scan_type
+        self.ds.DT = DT
+
+        h5py.File.close(datfile)
diff --git a/docs/misc/simulated_spectrum.h5 b/docs/misc/simulated_spectrum.h5
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,3 +1,5 @@
 sphinx
 sphinx_rtd_theme
 piva
+nbsphinx
+myst-nb
diff --git a/docs/source/_static/showcase.mp4 b/docs/source/_static/showcase.mp4
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -21,7 +21,7 @@
 # -- Project information -----------------------------------------------------
 
 project = 'piva'
-copyright = '2024, Wojtek Pudelko'
+copyright = '2025, Wojtek Pudelko'
 author = 'Wojtek Pudelko'
 
 
@@ -30,6 +30,9 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
+    'nbsphinx',
+    'myst_nb',
+    'sphinx.ext.mathjax',  # Optional, for LaTeX rendering
     'sphinx_rtd_theme',
     'sphinx.ext.viewcode',
     'sphinx.ext.intersphinx',
@@ -89,3 +92,12 @@ def setup(app):
 
 # Don't show class signature with the class' name.
 autodoc_class_signature = "separated"
+
+
+# including jupyter notebook
+nbsphinx_allow_errors = True  # Allow notebooks with errors to render
+nbsphinx_execute = 'never'  # Always execute notebooks during the build
+nb_execution_mode = 'off'
+nb_render_text_lexer = 'python'  # Syntax highlighting for code cells
+# nb_ipywidgets_js = True          # Support for Jupyter widgets (optional)
+
diff --git a/docs/source/custom_plugins.rst b/docs/source/custom_plugins.rst
@@ -33,7 +33,7 @@ The most basic implementation of the :class:`PluginImporter` and an example
 This example creates a simple window (shown below) that can be opened
 from the menu bar.
 
-.. figure:: ../img/custom_widget.png
+.. figure:: ../img/custom/custom_widget.png
     :alt: Image not found.
 
 

diff --git a/docs/source/dataloaders.rst b/docs/source/dataloaders.rst
@@ -17,7 +17,7 @@ specific **Dataloader** dedicated to various ARPES beamlines around the world
 Principles of the data import in :mod:`piva` are presented on a simple scheme
 below.
 
-.. figure:: ../img/dl-scheme.png
+.. figure:: ../img/dl/dl-scheme.png
     :alt: Image not found.
 
 If the file format is not yet supported, one needs to implement a custom
@@ -89,8 +89,8 @@ Description below shows step by step how to achieve both.
 
    The :class:`~data_loaders.Dataloader` class offers an interface for that.
    In order to write a custom dataloader, let's call it
-   :class:`CustomDataloader` for the sake of the following example, one needs
-   to start by creating a subclass of :class:`~data_loader.Dataloader`::
+   :class:`CustomDataloader`, one needs to start by creating a subclass of
+   :class:`~data_loader.Dataloader`::
 
     from piva.data_loaders import Dataloader
 
@@ -116,14 +116,18 @@ Description below shows step by step how to achieve both.
            - ``metadata``, :obj:`bool`, determine whether method should load
              entire dataset or just its metadata
 
-        have to be arguments of the ``load_data()`` method. See *e.g*
+        have to be arguments of the ``load_data()`` method. See
         :meth:`~data_loaders.DataloaderPickle.load_data` for more details.
 
 
    .. note::
-        Above example describes most basic implementation necessary to work.
-        It is recommended to use prepared template, which can be downloaded
-        from :download:`here <../misc/custom_data_loaders.py>`.
+        The above example describes the most basic implementation necessary to
+        work. It is recommended to use prepared template, which can be
+        downloaded from :download:`here <../misc/custom_data_loaders.py>`.
+
+   .. seealso::
+      See :meth:`~data_browser.DataBrowser.load_custom_data_loaders` for more
+      details.
 
 2. Making **CustomDataloader** visible for :mod:`piva` is accomplished through
    :class:`DataloaderImporter` object. Its proper configuration requires
@@ -136,21 +140,12 @@ Description below shows step by step how to achieve both.
       it on any operating system can be found `here <https://stackoverflow.com/
       questions/10738919/how-do-i-add-a-path-to-pythonpath-in-virtualenv>`_.
 
-   At the beginning of the session :mod:`piva` will search for the
+   At the beginning of the session, :mod:`piva` will search for the
    :class:`DataloaderImporter` class and execute whatever code it contains.
-   Users are in complete liberty of implementing the object according to
-   their preferences, but they might benefit from the example code provided
-   :download:`here <../misc/piva_dataloader_importer.py>`, that contains most
-   basic solution.
-
-   .. seealso::
-      See :meth:`~data_browser.DataBrowser.load_custom_data_loaders` for more
-      details.
-
-   Correctly loaded **CustomDataloader** should appear in **DataBrowser**
+   Correctly loaded **CustomDataloader** should appear in **DataBrowser's**
    drop-down menu:
 
-.. figure:: ../img/dl-cdl.png
+.. figure:: ../img/dl/dl-cdl.png
     :width: 276
     :height: 256
     :align: center
@@ -163,6 +158,33 @@ Description below shows step by step how to achieve both.
     the loader will be automatically imported at the beginning of each
     :mod:`piva` session and available to the user immediately.
 
+
+
+.. _sec-custom-dl-example:
+
+Example
+-------
+Users are free to implement custom data loaders according to their
+preferences. However, they may find the provided template
+:download:`here <../misc/piva_dataloader_importer.py>` helpful.
+The template offers a basic implementation of the :class:`DataloaderImporter`
+and :class:`CustomDataloader` classes.
+
+Additionally, the template can be used to test the configuration with an
+example :download:`spectrum file <../misc/simulated_spectrum.h5>`, which
+contains a simulated 2D spectrum:
+
+.. figure:: ../img/dl/dl-test_spectrum.png
+    :width: 414
+    :height: 440
+    :align: center
+    :alt: Image not found.
+
+
+
+Contributing
+------------
+
 We encourage everyone to share their tested, self-written data loaders with
 the community by adding them to :mod:`piva`'s source code. This can be done
 ideally `directly through GitHub <https://github.com/pudeIko/piva>`_ or

diff --git a/docs/source/db.rst b/docs/source/db.rst
@@ -12,7 +12,7 @@ simply run::
 in the terminal. This will start a :mod:`piva` session and open the following
 window:
 
-.. figure:: ../img/db-labels.png
+.. figure:: ../img/db/db-labels.png
     :alt: Image not found.
 
 - The left-hand side of the window provides a **tree-view** of the filesystem,

diff --git a/docs/source/fitters.rst b/docs/source/fitters.rst
@@ -25,7 +25,7 @@ selected fitting range.
 
 Its layout is shown and described below.
 
-.. figure:: ../img/fitters-mdc-main.png
+.. figure:: ../img/fitters_plottool/fitters-mdc-main.png
    :alt: Image not found.
 
 =====   =======================================================================
@@ -58,7 +58,7 @@ Fitting tab
 
 Contains all widgets useful for interactive fitting of MDCs.
 
-.. figure:: ../img/fitters-mdc-fitting_tab.png
+.. figure:: ../img/fitters_plottool/fitters-mdc-fitting_tab.png
    :alt: Image not found.
 
 =======================     ===================================================
@@ -97,7 +97,7 @@ perform gap analysis.
 
 Its layout is shown and described below.
 
-.. figure:: ../img/fitters-edc-main.png
+.. figure:: ../img/fitters_plottool/fitters-edc-main.png
    :alt: Image not found.
 
 =====   =======================================================================

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -15,6 +15,14 @@ Welcome to piva - Photoemission Interface for Visualization and Analysis!
    installation
 
 
+.. toctree::
+   :maxdepth: 2
+   :caption: Data formats
+
+   dataset
+   dataloaders
+
+
 .. toctree::
    :maxdepth: 2
    :caption: GUI
@@ -28,10 +36,9 @@ Welcome to piva - Photoemission Interface for Visualization and Analysis!
 
 .. toctree::
    :maxdepth: 2
-   :caption: Data formats
+   :caption: Analysis
 
-   dataset
-   dataloaders
+   Data Ingestion and Analysis <notebooks/analysis>
 
 
 .. toctree::

diff --git a/docs/source/intro.rst b/docs/source/intro.rst
@@ -22,6 +22,21 @@ exploration of large image-like datasets. While it can generally display any
 multidimensional data, most of its functionalities are tailored for users
 performing Angle-Resolved Photoemission Spectroscopy (ARPES) experiments.
 
+The showcase video presented below offers a demonstration of the GUI's layout
+and overall user experience, while also highlighting its core functionalities
+and key features in action.
+
+.. raw:: html
+
+   <div style="text-align: center;">
+       <video width="600" controls>
+           <source src="_static/showcase.mp4" type="video/mp4">
+           Your browser does not support the video tag.
+       </video>
+   </div>
+   <br><br><br>
+
+
 The package allows for live investigation of various datasets individually, as
 well as linking separate datasets for simultaneous browsing. Interactive
 sliders enable the display of multidimensional data across all available