docs: update io documentation

kmnhan · Apr 10, 2024 · b0d2d01 · b0d2d01
1 parent 007bb3b
commit b0d2d01
Show file tree

Hide file tree

Showing 3 changed files with 80 additions and 4 deletions.
diff --git a/docs/source/images/flowchart_multiple.pdf b/docs/source/images/flowchart_multiple.pdf
diff --git a/docs/source/images/flowchart_single.pdf b/docs/source/images/flowchart_single.pdf
diff --git a/docs/source/user-guide/io.ipynb b/docs/source/user-guide/io.ipynb
@@ -143,12 +143,88 @@
     "tags": []
    },
    "source": [
-    "It is easy to add new loaders to the framework; see\n",
-    ":doc:`../generated/erlab.io.dataloader` for more information. The implementation\n",
-    "of existing loaders in the :mod:`erlab.io.plugins` module is a good starting\n",
-    "point; see the `source code on github\n",
+    "Advanced: implementing a data loader plugin\n",
+    "-------------------------------------------\n",
+    "\n",
+    "It is easy to add new loaders to the framework. Any class that subclasses\n",
+    ":class:`LoaderBase <erlab.io.dataloader.LoaderBase>` is automatically registered\n",
+    "as a loader upon its definition. The class must have a valid ``name`` attribute,\n",
+    "which is used to access the loader.\n",
+    "\n",
+    "If the ``name`` attribute is prefixed with an underscore, the loader is not\n",
+    "registered as a loader. This is useful for abstract classes that are not meant\n",
+    "to be used directly. One example is :class:`DA30Loader\n",
+    "<erlab.io.plugins.da30.DA30Loader>`, which serves as a base class for\n",
+    "implementing loaders for setups using the Scienta Omicron DA30 hemispherical\n",
+    "analyzer with ``SES.exe``.\n",
+    "\n",
+    "ARPES data from a single experiment are usually stored in one folder, with files\n",
+    "that look like ``file_0001.h5``, ``file_0002.h5``, etc. If the naming scheme\n",
+    "does not deviate from this pattern, only two methods need to be implemented:\n",
+    ":meth:`identify <erlab.io.dataloader.LoaderBase.identify>` and\n",
+    ":meth:`load_single <erlab.io.dataloader.LoaderBase.load_single>`. The following\n",
+    "flowchart shows the process of loading data from a single scan, given either a\n",
+    "file path or a sequence number:\n",
+    "\n",
+    ".. image:: ../images/flowchart_single.pdf\n",
+    "   :align9: center\n",
+    "\n",
+    "However, there are some setups where data for a single scan is saved over\n",
+    "multiple files. In this case, the files will look like ``file_0001_0001.h5``,\n",
+    "``file_0001_0002.h5``, etc. For these kinds of setups, an additional method\n",
+    ":meth:`infer_index <erlab.io.dataloader.LoaderBase.infer_index>` must be\n",
+    "implemented. The following flowchart shows the process of loading data from\n",
+    "multiple files:\n",
+    "\n",
+    ".. image:: ../images/flowchart_multiple.pdf\n",
+    "   :align: center\n",
+    "\n",
+    "See :doc:`../generated/erlab.io.dataloader` for more information. The\n",
+    "implementation of existing loaders in the :mod:`erlab.io.plugins` module is a\n",
+    "good starting point; see the `source code on github\n",
     "<https://github.com/kmnhan/erlabpy/tree/main/src/erlab/io/plugins>`_."
    ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/html": [
+       "<table><thead><tr><th style='text-align:left;'><b>Name</b></th><th style='text-align:left;'><b>Aliases</b></th><th style='text-align:left;'><b>Loader class</b></th></tr></thead><tbody><tr><td style='text-align:left;'>kriss</td><td style='text-align:left;'>KRISS</td><td style='text-align:left;'>erlab.io.plugins.kriss.KRISSLoader</td></tr><tr><td style='text-align:left;'>merlin</td><td style='text-align:left;'>ALS_BL4, als_bl4, BL403, bl403</td><td style='text-align:left;'>erlab.io.plugins.merlin.BL403Loader</td></tr><tr><td style='text-align:left;'>ssrl</td><td style='text-align:left;'>ssrl52, bl5-2</td><td style='text-align:left;'>erlab.io.plugins.ssrl52.SSRL52Loader</td></tr></tbody></table>"
+      ],
+      "text/plain": [
+       "Registered data loaders\n",
+       "=======================\n",
+       "\n",
+       "Loaders\n",
+       "-------\n",
+       "kriss: <class 'erlab.io.plugins.kriss.KRISSLoader'>\n",
+       "merlin: <erlab.io.plugins.merlin.BL403Loader object at 0x1216a5790>\n",
+       "ssrl: <erlab.io.plugins.ssrl52.SSRL52Loader object at 0x1238c30d0>\n",
+       "\n",
+       "Aliases\n",
+       "-------\n",
+       "kriss: ['KRISS']\n",
+       "merlin: ['ALS_BL4', 'als_bl4', 'BL403', 'bl403']\n",
+       "ssrl: ['ssrl52', 'bl5-2']"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    }
+   ],
+   "source": [
+    "from erlab.io.dataloader import LoaderBase\n",
+    "\n",
+    "class MyLoader(LoaderBase):\n",
+    "    name = 'my_loader'\n",
+    "\n",
+    "    skip_validate = True\n",
+    "\n"
+   ]
   }
  ],
  "metadata": {