Commit 2e2117d7 authored by eric pellegrini's avatar eric pellegrini
Browse files

replaced README.md by README.rst

updated docstrings and rst files accordingly
parent 129db380
Overview
========
**hdfviewer** is a python3 package for inspecting HDF files in the context of **Jupyter Lab** notebook.
.. overview-begin
It represents each group found in the HDF file as an accordion made of the following subitems:
- **attributes**: contains the HDF attributes of this group
......@@ -30,12 +32,37 @@ In case of **2D** and **3D** datasets, the matrix view is made of a 2D image of
- go the +n (n can be > 9) frame by pressing *n* number followed by the **down** or the **right** keys
- go the -n (n can be > 9) frame by pressing *n* number followed by the **up** or the **left** keys
.. overview-end
Usage in a notebook
===================
.. usage-begin
.. code-block:: python
:caption: Usage in a notebook
%matplotlib ipympl
import h5py
from hdfviewer.widgets.HDFViewer import HDFViewer
from hdfviewer.widgets.PathSelector import PathSelector
path = PathSelector(extensions=[".hdf",".h5",".nxs"])
path.widget
if path.file:
hdf5 = h5py.File(path.file,"r")
display(HDFViewer(hdf5))
.. usage-end
Prerequesites
=============
- python3 + pip
Installation
=============
============
see [here](https://github.com/jupyter-widgets/ipywidgets/tree/master/packages/jupyterlab-manager) for complementary info
- `cd` to the directory where lies the `setup.py` file
......@@ -54,24 +81,4 @@ If none or only one of these extensions are mentionned, please run the following
- `jupyter labextension install @jupyter-widgets/jupyterlab-manager`
- `jupyter labextension install jupyter-matplotlib`
Usage in a notebook
===================
```
%matplotlib ipympl
import h5py
from hdfviewer.widgets.HDFViewer import HDFViewer
from hdfviewer.widgets.PathSelector import PathSelector
path = PathSelector(extensions=[".hdf",".h5",".nxs"])
path.widget
if path.file:
hdf5 = h5py.File(path.file,"r")
display(HDFViewer(hdf5))
```
......@@ -42,8 +42,7 @@ extensions = [
'sphinx.ext.intersphinx',
'sphinx.ext.todo',
'sphinx.ext.coverage',
'sphinx.ext.imgmath',
'm2r'
'sphinx.ext.imgmath'
]
# Add any paths that contain templates here, relative to this directory.
......@@ -52,8 +51,7 @@ templates_path = ['_templates']
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
# source_suffix = ['.rst', '.md']
source_suffix = '.rst'
source_suffix = {'.rst' : 'restructuredtext', '.md' : 'markdown'}
# The master toctree document.
master_doc = 'index'
......@@ -194,3 +192,4 @@ intersphinx_mapping = {'python' : ('https://docs.python.org/3', None),
todo_include_todos = True
autodoc_default_flags = ['members', 'undoc-members', 'private-members', 'show-inheritance']
......@@ -3,7 +3,9 @@
Welcome to hdfviewer's documentation!
=====================================
.. mdinclude:: ../README.md
.. toctree::
readme_link
================
Package contents
......
.. include:: ../README.rst
......@@ -21,49 +21,13 @@ class HDFViewerError(Exception):
class HDFViewer(widgets.Accordion):
"""This class allows to inspect HDF data in the context of **Jupyter Lab**
It represents each group found in the HDF file as an accordion made of the following subitems:
.. include:: ../README.rst
:start-after: overview-begin
:end-before: overview-end
- **attributes**: contains the HDF attributes of this group
- **groups**: contains the HDF subgroups of this group
- **datasets**: contains the HDF datasets of this group
If one of these subitems is empty (e.g. no attributes defined for a given group) the corresponding subitem is omitted.
When one reaches a HDF dataset, informations about the dataset are collected (dimensionality, numeric type, attributes ...) and displayed in a Jupyter output widget. In case of 1D, 2D or 3D dataset, a view of the dataset is also displayed. Depending on the dimensionality of the dataset the display will consist in:
- **1D**: simple MatPlotLib 1D plot
- **2D**: matrix view of the dataset
- **3D**: matrix view of the dataset
In case of **2D** and **3D** datasets, the matrix view is made of a 2D image of the selected frame of the dataset (always `0` for 2D datasets) with a 1D column-projection view of the dataset on its top and a 1D row-projection view of the dataset on its right. The matrix view is interactive with the following interactions:
- **2D**:
- toggle between cross and integration 1D potting mode. In cross plot mode, the 1D projection views represents resp. the row and column of the matrix image point left-clicked by the user. In integration plot mode, the 1D projection views represents the sum over resp. the row and column of the image. To switch between those two modes, press the **i** key.
- **3D**:
- toggle between cross and integration 1D potting mode. See above.
- go to the last frame by pressing the **pgdn** key.
- go to the first frame by pressing the **pgup** key.
- go to the next frame by pressing the **down** or the **right** keys or wheeling **down** the mouse wheel
- go to the previous frame by pressing the **up** or the **left** keys or wheeling **up** the mouse down
- go the +n (n can be > 9) frame by pressing *n* number followed by the **down** or the **right** keys
- go the -n (n can be > 9) frame by pressing *n* number followed by the **up** or the **left** keys
.. code-block:: python
:caption: Usage in a Jupyter Lab notebook
%matplotlib ipympl
import h5py
from hdfviewer.widgets.HDFViewer import HDFViewer
from hdfviewer.widgets.PathSelector import PathSelector
path = PathSelector(extensions=[".hdf",".h5",".nxs"])
path.widget
if path.file:
hdf5 = h5py.File(path.file,"r")
display(HDFViewer(hdf5))
.. include:: ../README.rst
:start-after: usage-begin
:end-before: usage-end
:param hdf: the hdf Data to be inspected.
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment