MaD GUI is a basis for graphical annotation and computational analysis of time series data.

Overview

MaD GUI

Machine Learning and Data Analytics Graphical User Interface

Test and Lint CodeFactor Documentation Status PyPI version shields.io

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.

⚠️ WARNING ⚠️
This is still an early version. Things might not work as expected.
Experiencing issues? Report a bug here!

click to enlarge the image

click to show videos on YouTube
(open video descriptions on YouTube for chapters)

Quickstart for developers

In a python 3.7 environment, execute the following commands or use the section Development installation:

pip install mad_gui
mad-gui

You can download our example data to test our built-in exemplary importer, exemplary algorithms and exemplary label. To see how to open our example data within the GUI, please refer to our section about the User Interface.

Contents of this readme

General Information Development Additional Information
  • Why and what?
  • Download / Installation
  • Example data
  • User Interface (Videos & Shortcuts)
  • Load / display data of any format
  • Use a custom algorithm
  • Terminology
  • Development installation
  • Developing Plugins
  • Communicating with the user
  • Adjusting Constants
  • Changing the theme


  • Support & Contributing
  • Background





  • Why and what?

    Existing graphical user interfaces (GUIs), that deal with time series data, usually do not allow support of annotation by algorithms, although such algorithms exist. If they do, the algorithm and the GUI are tightly coupled, such that reusing it becomes hard.

    Furthermore, algorithms that were developed to analyze time series data, can usually not be used by researchers, who do not have programming experience, although the algorithms were developed for their research area. This is for example the case in the area of gait analysis, where algorithms are provided by computer scientists and need to be used by clinical researchers.

    The MaD GUI can be used as a framework to incorporate algorithms for supporting time series annotation and for using algorithms for analyzing time series data even without having programming experience. You can read about this in more detail in our Background section.

    Download / Installation

    Plugin Developers

    Please see the section Development installation.

    GUI user: Standalone executable

    You do not need to install anything. Simply download the file from the table below for your regarding operating system. Afterwards you can start the GUI as described in the rightmost column of the table.

    When downloading a file from the table, your browser may warn you that this is a potentially dangerous file. You will only be able to use our GUI by selecting "Keep anyway / download anyway / ...". In the case of Microsoft Edge, this possibility is hidden, but you can select it after downloading as explained here.

    Operating system File to download What to do
    Windows Windows (64 bit) Download the file on the left. Then open the downloaded file and read about example data in the section below this table.

    Note: If prompted with a dialog Windows protected your PC, click More info and then select Run anyway.
    Ubuntu Ubuntu (64 bit) Download the file on the left. Then, in your terminal, navigate to the file loaction and then: chmod +x ./mad_gui_ubuntu and then ./mad_gui_ubuntu.

    Note: you might need to install some additional packages. You can use this script to do so. Just right click the link, save it on your machine and execute it.
    Mac OS Mac OS (64 bit)
  • Download the file on the left and extract it, for example to a folder called mad_gui.
  • Right click on the folder mad_gui and choose "New Terminal at Folder"
  • In the terminal, type sudo -xvf mad_gui.tgz and press return.
  • Close the terminal.
  • Right click on the file mad_gui_mac, select "Open", and confirm that you want to open the file.
  • Wait about half a minute until the GUI opens
  • You can read about example data to load in the GUI in the section below this table.


  • Note: If your Mac does not allow you to open this file, perform the actions for "If you want to open an app that hasn’t been notarized or is from an unidentified developer" on the Apple Support Page. Afterwards, try to open it again as described above.
    other Supplied upon request Contact us

    Example Data

    You can download our example data and extract the .csv file. After starting MaD GUI, you can open the previously downloaded example data as shown in 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

    User Interface

    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 Download / Installation. There you will find information on how to download our GUI and our exemplary data.

    Shortcuts

    Please watch the videos linked above, if you want to learn more about the different actions.

    Shortcut Mode Action
    a, e, r, s, Esc all Switch between modes Add label, Edit label, Remove label, Synchronize data
    Left Mouse Click Add label Set start/end of a label
    Space Add label Can be used instead of Left Mouse Click
    1, 2, 3,... TAB Add label Navigate in the pop-up window
    Shift + Left Mouse Click Add label Start a new label directly when setting the end of a label
    Ctrl + Left Mouse Click Add label Add a single event

    Load and display data of any format

    This will need someone who is familiar with Python, who has to develop a plugin of the type Importer. For more information on how to create plugins, please refer to Developing Plugins. You do not have experience with python but still want to load data from a specific system? Contact us!

    Use a custom algorithm

    This will need someone who is familiar with Python, who has to develop a plugin of the type Algorithm. For more information on how to create plugins, please refer to Developing Plugins. You do not have experience with python but still want to load data from a specific system? Contact us!

    Terminology

    Word Meaning
    Annotation An annotation has a start and a stop value, e.g. it goes from second 1 to second 2 of the time series data. Furthermore, it can have a description, such as "walking" or "running".
    Label An annotation is always of a certain type, for example "Activity". These types are called labels. A Label keeps the possible descriptions of an annotation, e.g. "walk" or "run". Furthermore, it keeps information about where the label should be plotted, e.g. lowest 20% of the plot.
    User Someone who performs actions in the GUI.
    Developer Someone who creates plugins for the GUI, for example to load a specific data format or to use a specific algorithm.

    Development

    In case you experience issues, please try to find a solution in our documentation regarding Troubleshooting.

    Development installation

    Info: We recommend to use pip install mad_gui in a clean python 3.7 conda environment, or if you know what you are doing in a python venv / .

    pip install mad_gui
    

    Then, from your command line simply call:

    mad-gui
    

    Alternatively, within a python script use our start_gui function:

    from mad_gui import start_gui
    start_gui()
    

    If you want to see an example, download our example data and extract the .csv. Afterwards, you can open the previously downloaded example data as shown in 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 and Use a custom algorithm.

    Developing plugins

    The MaD GUI package is a framework, which can be extended with different kinds of plugins and labels. The user can access your plugins within the GUI using dropdowns, after clicking "Load data" or "Use algorithm". However, this is only possible if your plugin was passed to the GUI at startup, as we show it for an importer in this GIF, or as shown in this code snippet:

    from mad_gui import start_gui
    from my_importer import MyImporter
    from my_algorithm import MyAlgorithm
    from my_labels import MyFirstLabel, MySecondLabel
    
    # only passing plugins
    start_gui(plugins=[MyImporter, MyAlgorithm])
    
    # passing plugins and labels
    start_gui(plugis=[MyImporter], labels=[MyFirstLabel, MySecondLabel])

    In the sections in the following list we describe how you can develop your own plugins and labels, which must inherit one of our base plugins or BaseRegionLabel. Each of these sections keeps working example to get you started as quick as possible:

    Communicating with the user

    Pop-up

    If - at any point - you want to send a message to the user of the GUI, you create a message box with an OK button like this:

    from mad_gui.components.dialogs.user_information import UserInformation
    
    UserInformation.inform_user("Your message")
    
    # will return PySide2.QtWidgets.QMessageBox.Yes or PySide2.QtWidgets.QMessageBox.No
    yes_no = UserInformation().ask_user("Yes or No?") 

    Tooltip of labels

    You can display results of your algorithms for example by putting the results into the label's description as shown in our section about custom algorithms.

    Adjusting Constants

    You can create your own settings by creating a class, which inherits from our BaseSettings. The following example makes use of the BaseSettings and simply overrides some properties:

    from mad_gui.config import BaseSettings
    from mad_gui import start_gui
       
    class MySettings(BaseSettings):
        # decide which axes/channels should be plotted by default
        # Note that this will result in an error if the passed data does not have those axes
        CHANNELS_TO_PLOT = ["acc_x", "acc_z"]
        
        # used if a label has `snap_to_min = True` or `snap_to_max = True`
        SNAP_AXIS = "acc_x"
        SNAP_RANGE_S = 0.2
        
        # in all your labels you can add an event by using `Ctrl` as modifier when in `Add label` mode
        # when adding an event the user will be prompted to select one of these two strings as a
        # `description` for the event
        EVENTS = ["important event", "other type of important event"]
        
        # Set the width of IMU plot to this, when hitting the play button for the video.
        PLOT_WIDTH_PLAYING_VIDEO = 20  # in seconds
        
        # If plotting large datasets, this speeds up plotting, however might result in inaccurate
        # representation of the data
        AUTO_DOWNSAMPLE = True
    
    start_gui(
    settings=MySettings,
    )

    Changing the theme

    You can easily change the two dominating colors by passing your own theme to the GUI.

       from mad_gui import start_gui
       from mad_gui.config import BaseTheme
       from PySide2.QtGui import QColor
    
       class MyTheme(BaseTheme):
          COLOR_DARK = QColor(0, 255, 100)
          COLOR_LIGHT = QColor(255, 255, 255)
    
       start_gui(
        theme=MyTheme,
       )

    Support & Contributing

    You can find some help in our section about troubleshooting. In case you can not solve an issue using that section, please get in touch.

    Background

    User perspective

    The challenge

    New algorithms for analyzing time series data are published frequently. However, the developed algorithms can hardly be used if the area of application is outside of computer science. For example in clinical research, the user likely will lack necessary programming expertise.

    Best available solutions

    Many graphical user interfaces exist, that allow interaction with time series data without programming expertise. Usually they can be used to annotate sequences of a signal, resulting in information like "from timestamp x to timestamp y, z happend" or "at timestamp x, z happened". In case they need a more detailed analysis using a specific kind of algorithm, usually the data has to be sent to the developer of the specific algorithm, who has to process it and send back the results.

    Limitations of available solutions

    If available graphical user interfaces contain algorithms, these tools are often not open-source and/or require the user to install software on their machine. The latter is not always easily possible due to restrictions of an institution's security policy. In case an algorithm is not incorporated into a graphical user interface, the user interested in using this algorithm would have to send data to developers of the specific algorithm. This may be undesirable for several reasons. Among others, data protection laws and the created overhead are important aspects.

    As a result, many algorithms are developed to support research fields outside of computer science, as for example clinical research, but can hardly be used.

    Our solution

    The MaD GUI offers an easy way of accessing algorithms for the analysis of time series data. This enables researchers to make use of state-of-the-art-algorithms for time series analysis in their respective research area even if they do not have programming expertise.

    Developer perspective

    The challenge

    Researching algorithms for time series data in many cases requires annotation of data. To accomplish the task of annotation, developers usually need some kind of graphical user interface.

    Best available solutions

    While many graphical user interface exist for annotating time series data, they usually do not incorporate algorithms, which could support the developer with labelling the data - and they do not offer an interface to add algorithms. However, many algorithms exist for such kind of support.

    Limitations of avaialable solutions

    In case a graphical user interface incorporates algorithms to support labelling, these are often very specific to the use-case. This results in each developer building their own graphical user interface, which usually is not developed with the aim of being modular or to be used in other projects. Therefore, there is a lot of work done over and over again.

    Our solution

    The MaD GUI offers a basis for such scenarios. It can be extended by developers to load their specific data format. Furthermore, developers can easily inject their algorithms to support labelling or analyze time series data as a plugin. In addition, developers can specify the labels to be used - it could be one layer (= one label from top to bottom) or an arbitrary amount of layers, (e.g. use one kind of label in the upper part of the plot and another kind of label in the lower part of the plot). During annotation, each label can easily be assigned an additional description to add details to the specific annotation.

    Comments
    • [BUG]

      [BUG]

      Describe the bug We had a bug on window in mad_gui/windows/main.py line 69:

      if platform.system() == "Windows" and int(platform.release()) >= 8:

      platform.release() returns a string, and int(str) throws and error. We solved it by: int(float(platform.release())).

      opened by Aksei 3
    • [BUG] Video synchronization does not work for some videos

      [BUG] Video synchronization does not work for some videos

      Describe the bug For some video files, the QMediaPlayer cannot read fps and therefore synchronizing video and data is not possible.

      To Reproduce

      1. Open sensor data and video (you may have to test several videos, as it is not yet clear for which it works and for which not)
      2. Click the synchronize button
      3. See that the line of the video_plot does not move

      Expected behavior If the fps cannot be obtained automatically, the user should be asked for the fps, e.g. in a pop-up window.

      Additional context See also pull request https://github.com/mad-lab-fau/mad-gui/pull/9

      opened by MalteOlle 0
    • [BUG] get_sync_file -> _get_sync_file

      [BUG] get_sync_file -> _get_sync_file

      AttributeError: 'ExampleImporter' object has no attribute 'get_sync_file' Der error tritt in load_data_dialog.py auf, wenn in Zeile 260 auf loader.get_sync_file aufgerufen wird.

      opened by MalteOlle 0
    • Make loading annotations generic

      Make loading annotations generic

      Currently the user has to specify either strides or activities

      https://github.com/mad-lab-fau/mad-gui/blob/main/mad_gui/components/dialogs/plugin_selection/load_data_dialog.py#L174

      opened by MalteOlle 0
    • Add main start gui command as a script to the pyproject.toml

      Add main start gui command as a script to the pyproject.toml

      https://python-poetry.org/docs/pyproject/#scripts

      This allows you to run the command without the "python -m" part and you can simply run mad-gui

      opened by AKuederle 0
    • [BUG] Syncing gets lost after executing an algorithm

      [BUG] Syncing gets lost after executing an algorithm

      Describe the bug The combination "Load Data+Video" and then "Use Algorithm" does not work, respectively the video is not synchronized with the sensor data afterward. Workaround for now: "Load data -> Use Algorithm -> export" and then "Reload data with annotations and video".

      To Reproduce Steps to reproduce the behavior:

      1. Select data and video to load
      2. Load it
      3. Use algorithm and execute an algorithm
      4. Sync is broken

      Expected behavior Sync should not be broken :)

      Workaround "Load data -> Use Algorithm -> export" and then "Reload data with annotations and video".

      opened by MalteOlle 1
    • Re-loading events

      Re-loading events

      If loading data from a .mad_gui file, the single added events are not restored. Events are currently only restored, if they are part of a BaseRegionLabel or a child of that.

      opened by MalteOlle 0
    Releases(v1.0.1-a1.1)
    • v1.0.1-a1.1(Jul 18, 2022)

    • v1.0.1(Jul 18, 2022)

    • v1.0.0(Jul 18, 2022)

      Project

      • Switch to Python 3.8 for faster dependency resolving
      • improve/fix README
      • extend documentation

      Code

      • make it possible to assign 'file types' to a loader, such that the user knows which file types can be opened using this loader
      • fix loading of PlotData objects from saved files
      • fix window not shown on macOS
      • add python-vlc to fix video plot (for synchronization) not showing up -> may have implications for standalone-builds
      • fix synchronization mode

      Pipeline

      • Remove individually installing astroid as prospector works fine again

      Full changelog : https://github.com/mad-lab-fau/mad-gui/compare/v0.2.1-beta4...v1.0.0

      Source code(tar.gz)
      Source code(zip)
    • v0.2.1-beta4(Oct 12, 2021)

      Potentially fix "pyside2-uic" not found on windows

      Full Changelog: https://github.com/mad-lab-fau/mad-gui/compare/v0.2.1-beta3...v0.2.1-beta4

      Source code(tar.gz)
      Source code(zip)
    • v0.2.1-beta3(Oct 8, 2021)

    • v0.2.1-beta.1(Oct 6, 2021)

      1. Bugs

      • Plugin selection dialog showed "Exporter to used" -> changed to "Plugin to use"
      • Fixed style of dropdowns
      • Previously the border of a RegionLabel could only be changed when first hovering over the label; now it works also if approaching the label "from outside"
      • Plotted channels are now the same before and after executing an algorithm

      2. Additions

      • Added example algorithm for analysis of existing labels
      • Added example exporter
      • Added BaseImporter.file_type to be able to give importer a preferred file name, such that only files of that type are shown when selecting data
      • Added typecheck for passing plugins and labels to MainWindow

      4. Readthedocs

      • improved, e.g. includes working examples
      Source code(tar.gz)
      Source code(zip)
      mad_gui.exe(63.90 MB)
      mad_gui_mac.zip(60.36 MB)
      mad_gui_ubuntu(168.75 MB)
    • v0.2.0-alpha.6(Sep 26, 2021)

      1. Labels

      • events snapped to a wrong position when added via mouse/keyboard, because sampling rate was not considered. It needs to be this way, since otherwise the positions are not correct when reloading events from a .mad_gui file.
      • event labels can now be passed to the gui. Press and hold ctrl to add events
      • region labels can be defined to include one or more event labels

      2. Bugs

      • fixed an issue with axis going off when having several monitors
      • enabled using openGL and autodownsampling (see config.settings), which gives a high performance boost in loading and moving large datasets
      Source code(tar.gz)
      Source code(zip)
    • v0.2.0-alpha.5(Sep 16, 2021)

      • Relax pandas dependency to ease dependency handling for developers who build using our GUI. If developers wanted to use our ExampleAlgrotihm and ExampleImporter, they now have to use the code from github and use poetry install or manually take care that the correct pandas version is installed.
      • Enable to load annotaions in custom format.
      • Give more feedback to users and developers if things go wrong.
      Source code(tar.gz)
      Source code(zip)
      mad_gui_mac.zip(60.36 MB)
      mad_gui_ubuntu(168.75 MB)
    • v0.2.0-alpha.3(Aug 4, 2021)

    • v0.2.0-alpha.2(Aug 4, 2021)

    Owner
    Machine Learning and Data Analytics Lab FAU
    Public projects of the Machine Learning and Data Analytics Lab at the Friedrich-Alexander-University Erlangen-Nürnberg
    Machine Learning and Data Analytics Lab FAU
    A statistical library designed to fill the void in Python's time series analysis capabilities, including the equivalent of R's auto.arima function.

    pmdarima Pmdarima (originally pyramid-arima, for the anagram of 'py' + 'arima') is a statistical library designed to fill the void in Python's time se

    alkaline-ml 1.3k Sep 29, 2022
    A data preprocessing package for time series data. Design for machine learning and deep learning.

    A data preprocessing package for time series data. Design for machine learning and deep learning.

    Allen Chiang 146 Sep 18, 2022
    STUMPY is a powerful and scalable Python library for computing a Matrix Profile, which can be used for a variety of time series data mining tasks

    STUMPY STUMPY is a powerful and scalable library that efficiently computes something called the matrix profile, which can be used for a variety of tim

    TD Ameritrade 2.4k Sep 29, 2022
    Automatically build ARIMA, SARIMAX, VAR, FB Prophet and XGBoost Models on Time Series data sets with a Single Line of Code. Now updated with Dask to handle millions of rows.

    Auto_TS: Auto_TimeSeries Automatically build multiple Time Series models using a Single Line of Code. Now updated with Dask. Auto_timeseries is a comp

    AutoViz and Auto_ViML 486 Sep 30, 2022
    A machine learning toolkit dedicated to time-series data

    tslearn The machine learning toolkit for time series analysis in Python Section Description Installation Installing the dependencies and tslearn Getti

    null 2.3k Sep 27, 2022
    Tool for producing high quality forecasts for time series data that has multiple seasonality with linear or non-linear growth.

    Prophet: Automatic Forecasting Procedure Prophet is a procedure for forecasting time series data based on an additive model where non-linear trends ar

    Facebook 15k Oct 1, 2022
    A machine learning toolkit dedicated to time-series data

    tslearn The machine learning toolkit for time series analysis in Python Section Description Installation Installing the dependencies and tslearn Getti

    null 2.2k Sep 23, 2022
    Visualize classified time series data with interactive Sankey plots in Google Earth Engine

    sankee Visualize changes in classified time series data with interactive Sankey plots in Google Earth Engine Contents Description Installation Using P

    Aaron Zuspan 74 Sep 7, 2022
    PyPOTS - A Python Toolbox for Data Mining on Partially-Observed Time Series

    A python toolbox/library for data mining on partially-observed time series, supporting tasks of forecasting/imputation/classification/clustering on incomplete multivariate time series with missing values.

    Wenjie Du 117 Sep 21, 2022
    A python library for easy manipulation and forecasting of time series.

    Time Series Made Easy in Python darts is a python library for easy manipulation and forecasting of time series. It contains a variety of models, from

    Unit8 4.7k Sep 23, 2022
    An open-source library of algorithms to analyse time series in GPU and CPU.

    An open-source library of algorithms to analyse time series in GPU and CPU.

    Shapelets 213 Sep 15, 2022
    A collection of Scikit-Learn compatible time series transformers and tools.

    tsfeast A collection of Scikit-Learn compatible time series transformers and tools. Installation Create a virtual environment and install: From PyPi p

    Chris Santiago 0 Mar 30, 2022
    Open source time series library for Python

    PyFlux PyFlux is an open source time series library for Python. The library has a good array of modern time series models, as well as a flexible array

    Ross Taylor 2k Sep 30, 2022
    Automatic extraction of relevant features from time series:

    tsfresh This repository contains the TSFRESH python package. The abbreviation stands for "Time Series Feature extraction based on scalable hypothesis

    Blue Yonder GmbH 6.7k Sep 30, 2022
    A unified framework for machine learning with time series

    Welcome to sktime A unified framework for machine learning with time series We provide specialized time series algorithms and scikit-learn compatible

    The Alan Turing Institute 5.7k Sep 27, 2022
    Probabilistic time series modeling in Python

    GluonTS - Probabilistic Time Series Modeling in Python GluonTS is a Python toolkit for probabilistic time series modeling, built around Apache MXNet (

    Amazon Web Services - Labs 3k Sep 25, 2022
    A Python package for time series classification

    pyts: a Python package for time series classification pyts is a Python package for time series classification. It aims to make time series classificat

    Johann Faouzi 1.3k Sep 22, 2022
    Time series forecasting with PyTorch

    Our article on Towards Data Science introduces the package and provides background information. Pytorch Forecasting aims to ease state-of-the-art time

    Jan Beitner 2.3k Oct 2, 2022
    Python module for machine learning time series:

    seglearn Seglearn is a python package for machine learning time series or sequences. It provides an integrated pipeline for segmentation, feature extr

    David Burns 527 Sep 12, 2022