diff --git a/README.md b/README.md index bf9dcbd..04b623f 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ MaD GUI is a basis for graphical annotation and computational analysis of time series data. It gives easy access to plotted data / annotations and handles interaction with annotations for you in the background. -Developers must create plugins and inject them into the GUI to read data of their format or use their algorithm. +**Developers must create plugins and inject them into the GUI to read data of their format or use their algorithm.**
@@ -27,7 +27,8 @@ Experiencing issues? [Report a bug here!](https://github.com/mad-lab-fau/mad-gui [](https://mad-gui.readthedocs.io/en/latest/_static/images/MaD-GUI.png) -click to show videos on YouTube +click to show videos on YouTube
+(open video descriptions on YouTube for chapters) [](https://www.youtube.com/watch?v=cSFFSTUM4e0 "MaD GUI - Loading data and navigating in the plot") [](https://www.youtube.com/watch?v=n96eO7TAItg "MaD GUI - Labelling data manually or using an algorithm") @@ -37,7 +38,7 @@ Experiencing issues? [Report a bug here!](https://github.com/mad-lab-fau/mad-gui ## Quickstart for developers -In a python 3.7 environment, execute the following commands: +In a python 3.7 environment, execute the following commands or use the section [Development installation](#development-installation): ``` pip install mad_gui mad-gui @@ -51,7 +52,7 @@ To see how to open our example data within the GUI, please refer to our section |General Information | Development | Additional Information | |---------------------|-----------|-------------------------| -|
  • [Why and what?](#why-and-what)
  • [Download / Installation](#download--installation)
  • [Example data](#example-data)
  • [User Interface (Videos & Shortcuts)](#user-interface)
  • [Load / display data of any format](#load-and-display-data-of-any-format)
  • [Use a custom algorithm](#use-a-custom-algorithm)
  • [Terminology](#terminology)
    • |
  • [Development installation](#development-installation)
  • [Developing Plugins](#developing-plugins)
  • [Communicating with the user](#communicating-with-the-user)
  • [Adjusting Constants](#adjusting-constants)
  • [Changing the theme](#changing-the-theme)


    • |
  • [Support & Contributing](#support-contributing)
  • [Background](#background)





    • | +|
  • [Why and what?](#why-and-what)
  • [Download / Installation](#download-installation)
  • [Example data](#example-data)
  • [User Interface (Videos & Shortcuts)](#user-interface)
  • [Load / display data of any format](#load-and-display-data-of-any-format)
  • [Use a custom algorithm](#use-a-custom-algorithm)
  • [Terminology](#terminology)
    • |
  • [Development installation](#development-installation)
  • [Developing Plugins](#developing-plugins)
  • [Communicating with the user](#communicating-with-the-user)
  • [Adjusting Constants](#adjusting-constants)
  • [Changing the theme](#changing-the-theme)


    • |
  • [Support & Contributing](#support-contributing)
  • [Background](#background)





    • | ## Why and what? @@ -97,7 +98,7 @@ and extract the .csv file. After starting MaD GUI, you can open the previously d [User Interface](#user-interface). You want to load / display data of a specific format/system or want to use a specific algorithm? -In this case please refer to [Load and display data of a certain data type](#load-and-display-data-of-a-certain-data-type) +In this case please refer to [Load and display data of a certain data type](#load-and-display-data-of-any-format) ## User Interface @@ -105,7 +106,7 @@ In this case please refer to [Load and display data of a certain data type](#loa ### Videos By clicking on the images below, you will be redirected to YouTube. In case you want to follow along on your own -machine, check out the section [Installation](#installation). +machine, check out the section [Download / Installation](#download-installation). There you will find information on how to download our GUI and our exemplary data. [](https://www.youtube.com/watch?v=cSFFSTUM4e0 "MaD GUI - Loading data and navigating in the plot") @@ -150,8 +151,8 @@ You do not have experience with python but still want to load data from a specif ### Development installation Info: We recommend to use `pip install mad_gui` in a -clean python 3.7 [virtual environment](https://docs.python.org/3/library/venv.html#creating-virtual-environments) / -[conda environment](https://mad-gui.readthedocs.io/en/latest/preparation.html#installing-necessary-software). +clean python 3.7 [conda environment](https://mad-gui.readthedocs.io/en/latest/preparation.html#installing-necessary-software), or if you know what you are doing in a [python venv](https://docs.python.org/3/library/venv.html#creating-virtual-environments) / +. ``` pip install mad_gui @@ -175,7 +176,7 @@ extract the .csv. Afterwards, you can open the previously downloaded example dat [User Interface](#user-interface). You want to load data of a specific format/system or want to use a specific algorithm? In this case please refer to the sections -[Load and display data of a certain data type](#load-and-display-data-of-a-certain-data-type) +[Load and display data of a certain data type](#load-and-display-data-of-any-format) and [Use a custom algorithm](#use-a-custom-algorithm). ### Developing plugins @@ -208,8 +209,8 @@ In the sections in the following list we describe how you can develop your own p - Algorithm: [Create annotations for plotted data](https://mad-gui.readthedocs.io/en/latest/plugin_algorithm.html#algorithm) - Algorithm: [Calculate features for existing annotations](https://mad-gui.readthedocs.io/en/latest/plugin_algorithm.html#algorithm) - Exporter: [Export displayed annotations](https://mad-gui.readthedocs.io/en/latest/plugin_exporter.html) - - Labels: [Create one or several custom label classes](file:///D:/mad-gui/docs/_build/html/labels.html#labels) - - For supplementary basic information please refer to [Preparation](file:///D:/mad-gui/docs/_build/html/preparation.html). + - Labels: [Create one or several custom label classes](https://mad-gui.readthedocs.io/en/latest/labels.html) + - For supplementary basic information please refer to [Preparation](https://mad-gui.readthedocs.io/en/latest/preparation.html). ## Communicating with the user diff --git a/docs/plugin_algorithm.rst b/docs/plugin_algorithm.rst index 20e9c0d..8f23cb2 100644 --- a/docs/plugin_algorithm.rst +++ b/docs/plugin_algorithm.rst @@ -22,12 +22,12 @@ Overview - 1.2 Algorithm, which creates annotations to be plotted: - - see what that means `in a video `_ (01:47 to 02:03) + - see what that means `in a video `_ (02:04 to 02:20) - use the :ref:`code example ` - 1.3 Algorithm, which calculates features for existing annotations: - - see what that means `in a video `_ (02:03 to 01:32) + - see what that means `in a video `_ (02:21 to 02:39) - use the :ref:`code example ` .. admonition:: Using the working example @@ -39,7 +39,7 @@ Overview - copy one of the code snippets containing the `MyAlgorithm` class to the file (section 1.2 or 1.3) - download our `example CSV `_ - in a separate file execute the following code snippet and then apply the algorithm as shown in our - `exemplary video `_: + `exemplary video `_: .. code-block:: python @@ -57,8 +57,8 @@ Algorithm, which creates annotations to be plotted A plugin like this can be used to create annotations which span a region between to samples. Your algorithm may for example be able to find regions where the sensor was not moving. The GUI will plot the annotations automatically after it returns from your algorithm's `process_data` method. -You can see an example in `this GIF <_static/gifs/algorithm_label.gif>`_ or `this video from 01:47 to 02:03 -`_. +You can see an example in `this GIF <_static/gifs/algorithm_label.gif>`_ or `this video from 02:04 to 02:20 +`_. .. admonition:: Adapting the working example :class: tip @@ -93,6 +93,9 @@ You can see an example in `this GIF <_static/gifs/algorithm_label.gif>`_ or `thi # Use the currently plotted data to create annotations annotations = self.create_annotations(sensor_plot.data, sensor_plot.sampling_rate_hz) UserInformation.inform(f"Found {len(annotations)} annotations for {plot_name}.") + if not all(col in annotations.columns for col in ["start", "end"]): + raise KeyError("Please make sure the dataframe returned from create_annotations has the columns " + "'start' and 'end'.") sensor_plot.annotations["Activity"].data = annotations @staticmethod @@ -132,8 +135,8 @@ For example the user might have created annotations manually or by using an algo Now, you might want to know the mean value of the sensor signal in each of the annotated regions. For this task you can create an algorithm as we describe it in this section. After execution of the algorithm, the GUI will take care for showing the results as soon as the user hovers of the -annotation with the mouse, as you can see in `this GIF <_static/gifs/algorithm_feature.gif>`_ or `this video from 02:04 to 02:20 -`_. +annotation with the mouse, as you can see in `this GIF <_static/gifs/algorithm_feature.gif>`_ or `this video from 02:21 to 02:39 +`_. .. admonition:: Adapting the working example :class: tip diff --git a/docs/plugin_importer.rst b/docs/plugin_importer.rst index 7728f38..1cb2b4e 100644 --- a/docs/plugin_importer.rst +++ b/docs/plugin_importer.rst @@ -16,16 +16,14 @@ Overview This enables our GUI to load and display your specific type of data, as shown in `this video `_ form 0:06 to 0:16. -Please additionally take a look at `this GIF <_static/gifs/importer.gif>`_, which shows you how your plugin gets into the GUI. -First of all you have to create a file, that will only keep your importer class, as shown in -`this image <_static/images/development/importer_create_file.png>`_. +Please additionally take a look at `this GIF `_, which shows you how your plugin gets into the GUI. .. admonition:: Using the working example :class: tip The subsection below shows a working example, which you can adapt to your case. To run it: - - create a file as shown in `this image <_static/images/development/importer_create_file.png>`_ + - create a file as shown in `this image `_ - copy the code snippet containing `CustomImporter` class to the file (see long code snippet in section :ref:`develop custom importer`) - download our `example CSV `_ - in a separate file execute the following code snippet and then load data as shown in our @@ -101,14 +99,14 @@ The name will show up in the dropdown menu in the GUI's pop up when the user cli warnings.warn("Please load the sampling frequency from your source in Hz" " Afterwards, remove this warning.") - sampling_rate_hz = 1 / df["time"].diff().mean() + sampling_rate_hz = 1 / sensor_data["time"].diff().mean() ############################################################## ### CAUTION ### ### If you only want to have one plot you do not need to ### ### change the following lines! If you want several plots, ### ### just add another sensor like "IMU foot" to the `data` ### - ### dictionary, which again keeps the files sensor_data ### + ### dictionary, which again hase keys sensor_data and ### ### and sampling_rate_hz for that plot. ### ############################################################## data = { @@ -123,7 +121,7 @@ The name will show up in the dropdown menu in the GUI's pop up when the user cli .. warning:: You need to pass your importer to our GUI like this as it is also shown in - `this image `_: + `this image `_: .. code-block:: python diff --git a/docs/preparation.rst b/docs/preparation.rst index 8eaa08d..7c4d7a9 100644 --- a/docs/preparation.rst +++ b/docs/preparation.rst @@ -44,10 +44,10 @@ Installing MaD GUI You have two possibilities for installing the dependencies: -Recommended: Assuming you want to build on top of the MaD GUI and do things that are described in :ref:`customization`, installation +Recommended: Assuming you want to build on top of the MaD GUI and do things that are described in `Developing plugins `_, installation can be done as described in :ref:`Installation for Customization (recommended) `. -In case you want to change parts at the core of the GUI, which go beyond the parts described in :ref:`customization`, +In case you want to change parts at the core of the GUI, which go beyond the parts described in `Developing plugins `_, you should use poetry as described in :ref:`Installation for Contributing ` .. _install via pip: