From 821d00d61fab4db6eceeae577c80b1532e89e3d0 Mon Sep 17 00:00:00 2001 From: rettigl Date: Wed, 23 Oct 2024 22:13:33 +0200 Subject: [PATCH] fix several docs issues --- docs/index.md | 16 +++------ docs/sed/dataset.rst | 36 ++++++------------- docs/sed/loader.rst | 1 + .../advanced_topics.md} | 9 +---- docs/user_guide/index.md | 9 +++-- tutorial/1_binning_fake_data.ipynb | 7 ++-- ...for_example_time-resolved_ARPES_data.ipynb | 12 +++++-- 7 files changed, 36 insertions(+), 54 deletions(-) rename docs/{advanced_topics/index.md => user_guide/advanced_topics.md} (50%) diff --git a/docs/index.md b/docs/index.md index 6b4cf732..1ba91d3c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -13,8 +13,12 @@ SED (Single Event Data Frame) is a collection of routines and utilities to handl It features lazy evaluation of dataframe processing using dask, numba-accelerated multi-dimensional binning, calibration and correction for trARPES (Time- and angle-resolved photoemission spectroscopy) datasets. The package ensures provenance and FAIR data through metadata tracking, usage of the community defined NeXus format. +## User guide + +We introduce different functionalities of the package by several step-by-step use guides: + ```{toctree} -:maxdepth: 2 +:maxdepth: 1 user_guide/index @@ -30,16 +34,6 @@ Several example notebooks to demonstrate the functionality of SED for end-to-end workflows/index ``` -## Advanced topics - -There are also further example notebooks showing more advanced topics not required in every-day analysis. - -```{toctree} -:maxdepth: 2 - -advanced_topics/index -``` - ## API ```{toctree} diff --git a/docs/sed/dataset.rst b/docs/sed/dataset.rst index 05bd94c0..b0147464 100644 --- a/docs/sed/dataset.rst +++ b/docs/sed/dataset.rst @@ -13,14 +13,12 @@ Getting datasets import os from sed.dataset import dataset -Get -~~~ +get() +^^^^^ The “get” just needs the data name, but another root_dir can be provided. -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Try to interrupt the download process and restart to see that it continues the download from where it stopped -''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' .. code:: python @@ -39,14 +37,12 @@ Try to interrupt the download process and restart to see that it continues the d Download complete. Not providing “remove_zip” at all will by default delete the zip file after extraction -'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' .. code:: python dataset.get("WSe2") Setting the “use_existing” keyword to False allows to download the data in another location. Default is to use existing data -'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' .. code:: python @@ -62,10 +58,8 @@ Setting the “use_existing” keyword to False allows to download the data in a Interrupting extraction has similar behavior to download and just continues from where it stopped. -'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' Or if user deletes the extracted documents, it re-extracts from zip file -''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' .. code:: python @@ -90,11 +84,12 @@ Or if user deletes the extracted documents, it re-extracts from zip file WSe2 data extracted successfully. +remove() +^^^^^^^^ + “remove” allows removal of some or all instances of existing data -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This would remove only one of the two existing paths -'''''''''''''''''''''''''''''''''''''''''''''''''''' .. code:: python @@ -105,7 +100,6 @@ This would remove only one of the two existing paths Removed /datasets/WSe2 This removes all instances, if any present -'''''''''''''''''''''''''''''''''''''''''' .. code:: python @@ -116,10 +110,9 @@ This removes all instances, if any present WSe2 data is not present. Attributes useful for user -~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^ All available datasets after looking at module, user and folder levels -'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' .. code:: python @@ -130,7 +123,6 @@ All available datasets after looking at module, user and folder levels ['WSe2', 'TaS2', 'Gd_W110'] The dir and subdirs where data is located -''''''''''''''''''''''''''''''''''''''''' .. code:: python @@ -150,7 +142,6 @@ The dir and subdirs where data is located '/datasets/WSe2/energycal_2019_01_08'] Existing locations where data is present -'''''''''''''''''''''''''''''''''''''''' .. code:: python @@ -164,11 +155,12 @@ Existing locations where data is present Example of adding custom datasets --------------------------------- +DatasetsManager +^^^^^^^^^^^^^^^ + Allows to add or remove datasets in json file at any level (module, user, folder). -'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' Looks at all levels to give the available datasets -'''''''''''''''''''''''''''''''''''''''''''''''''' .. code:: python @@ -176,10 +168,8 @@ Looks at all levels to give the available datasets from sed.dataset import DatasetsManager We add a new dataset to both folder and user levels -''''''''''''''''''''''''''''''''''''''''''''''''''' This dataset also has “rearrange_files” set to True, which takes all files in subfolders and puts them in the main dataset specific directory -''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' .. code:: python @@ -198,7 +188,6 @@ This dataset also has “rearrange_files” set to True, which takes all files i Added Example dataset to user datasets.json datasets.json should be available in execution folder after this -'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' .. code:: python @@ -210,7 +199,6 @@ datasets.json should be available in execution folder after this ['Example', 'WSe2', 'TaS2', 'Gd_W110'] This will remove the Example dataset from the user json file -'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' .. code:: python @@ -221,7 +209,6 @@ This will remove the Example dataset from the user json file Removed Example dataset from user datasets.json Adding dataset that already exists will give an error. Likewise, removing one that doesn’t exist -'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' .. code:: python @@ -234,7 +221,6 @@ Adding dataset that already exists will give an error. Likewise, removing one th Now that dataset.json with Example exists in current dir, lets try to fetch it -'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' .. code:: python @@ -272,7 +258,6 @@ Now that dataset.json with Example exists in current dir, lets try to fetch it [] lets download to another location -''''''''''''''''''''''''''''''''' .. code:: python @@ -300,7 +285,6 @@ lets download to another location Rearranging complete. we can remove one instance -'''''''''''''''''''''''''' .. code:: python @@ -332,7 +316,7 @@ we can remove one instance ['/datasets/Example'] Default datasets.json ------------------------- +--------------------- .. literalinclude:: ../../sed/dataset/datasets.json :language: json diff --git a/docs/sed/loader.rst b/docs/sed/loader.rst index 87fdebdb..468f34e4 100644 --- a/docs/sed/loader.rst +++ b/docs/sed/loader.rst @@ -10,6 +10,7 @@ Loader Interface :undoc-members: .. _base_loader: + Abstract BaseLoader ################################################### .. automodule:: sed.loader.base.loader diff --git a/docs/advanced_topics/index.md b/docs/user_guide/advanced_topics.md similarity index 50% rename from docs/advanced_topics/index.md rename to docs/user_guide/advanced_topics.md index 82a6d02c..ebd773c8 100644 --- a/docs/advanced_topics/index.md +++ b/docs/user_guide/advanced_topics.md @@ -1,12 +1,5 @@ ---- -myst: - html_meta: - "description lang=en": | - Advanced topics describing specific workflows and functionalities ---- -# Workflows - ```{toctree} +:maxdepth: 1 ../tutorial/6_binning_with_time-stamped_data ../tutorial/7_correcting_orthorhombic_symmetry ../tutorial/8_jittering_tutorial diff --git a/docs/user_guide/index.md b/docs/user_guide/index.md index 504782d9..e7b4e90a 100644 --- a/docs/user_guide/index.md +++ b/docs/user_guide/index.md @@ -2,7 +2,7 @@ myst: html_meta: "description lang=en": | - Documentation for beginner users. + Documentation for users. --- # User Guide @@ -14,12 +14,15 @@ installation ```{toctree} :caption: Basic concepts +:maxdepth: 1 ../tutorial/1_binning_fake_data ../tutorial/2_conversion_pipeline_for_example_time-resolved_ARPES_data ../tutorial/3_metadata_collection_and_export_to_NeXus +config ``` ```{toctree} -:caption: Advance -config +:maxdepth: 1 +:caption: Advanced Topics +advanced_topics ``` diff --git a/tutorial/1_binning_fake_data.ipynb b/tutorial/1_binning_fake_data.ipynb index 04370e8e..01e987ae 100644 --- a/tutorial/1_binning_fake_data.ipynb +++ b/tutorial/1_binning_fake_data.ipynb @@ -20,8 +20,6 @@ "metadata": {}, "outputs": [], "source": [ - "import sys\n", - "\n", "import dask\n", "import numpy as np\n", "import pandas as pd\n", @@ -29,8 +27,9 @@ "\n", "import matplotlib.pyplot as plt\n", "\n", - "sys.path.append(\"../\")\n", - "from sed.binning import bin_partition, bin_dataframe" + "from sed.binning import bin_partition, bin_dataframe\n", + "\n", + "%matplotlib widget" ] }, { diff --git a/tutorial/2_conversion_pipeline_for_example_time-resolved_ARPES_data.ipynb b/tutorial/2_conversion_pipeline_for_example_time-resolved_ARPES_data.ipynb index 7b9cb1e2..6ee3d7c1 100644 --- a/tutorial/2_conversion_pipeline_for_example_time-resolved_ARPES_data.ipynb +++ b/tutorial/2_conversion_pipeline_for_example_time-resolved_ARPES_data.ipynb @@ -315,13 +315,21 @@ "sp.apply_momentum_calibration()" ] }, + { + "cell_type": "markdown", + "id": "74e7ef75", + "metadata": {}, + "source": [ + "## Energy Correction and Calibration workflow" + ] + }, { "attachments": {}, "cell_type": "markdown", "id": "0bce2388", "metadata": {}, "source": [ - "## Energy Correction (optional)\n", + "### Energy Correction (optional)\n", "The purpose of the energy correction is to correct for any momentum-dependent distortion of the energy axis, e.g. from geometric effects in the flight tube, or from space charge" ] }, @@ -394,7 +402,7 @@ "id": "8b571b4c", "metadata": {}, "source": [ - "## 3. Energy calibration\n", + "### Energy calibration\n", "For calibrating the energy axis, a set of data taken at different bias voltages around the value where the measurement was taken is required." ] },