Merge pull request #40 from EIT-ALIVE/035_implement_filtering_wbaccin…

…elli

035 implement filtering wbaccinelli

README.md

@@ -1,64 +1,83 @@
-## Badges
+## EIT Dashboard
 
-(Customize these badges with your own links, and check https://shields.io/ or https://badgen.net/ to see which other badges are available.)
+Visualize and manipulate EIT in a code free way using the open source
+[eitprocessing](https://github.com/EIT-ALIVE/eitprocessing) software.
 
-| fair-software.eu recommendations | |
-| :-- | :--  |
-| (1/5) code repository              | [![github repo badge](https://img.shields.io/badge/github-repo-000.svg?logo=github&labelColor=gray&color=blue)]([email protected]:EIT-ALIVE/eit_dash) |
-| (2/5) license                      | [![github license badge](https://img.shields.io/github/license/EIT-ALIVE/eit_dash)]([email protected]:EIT-ALIVE/eit_dash) |
-| (3/5) community registry           | [![RSD](https://img.shields.io/badge/rsd-eit_dash-00a3e3.svg)](https://www.research-software.nl/software/eit_dash) [![workflow pypi badge](https://img.shields.io/pypi/v/eit_dash.svg?colorB=blue)](https://pypi.python.org/project/eit_dash/) |
-| (4/5) citation                     | [![DOI](https://zenodo.org/badge/DOI/<replace-with-created-DOI>.svg)](https://doi.org/<replace-with-created-DOI>) |
-| (5/5) checklist                    | [![workflow cii badge](https://bestpractices.coreinfrastructure.org/projects/<replace-with-created-project-identifier>/badge)](https://bestpractices.coreinfrastructure.org/projects/<replace-with-created-project-identifier>) |
-| howfairis                          | [![fair-software badge](https://img.shields.io/badge/fair--software.eu-%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8B-yellow)](https://fair-software.eu) |
-| Documentation                      | [![Documentation Status](https://readthedocs.org/projects/eit_dash/badge/?version=latest)](https://eit_dash.readthedocs.io/en/latest/?badge=latest) |
+**Important:** While the software code is open source, your data may not be. Once the dashboard is downloaded (and/or
+updated) on your local machine, no online interaction is needed. Your data remains local and is not shared or uploaded by
+this software.
 
+| Badges             |                                                                                                                                                                                                                                                |
+| :----------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| code repository    | [![github repo badge](https://img.shields.io/badge/github-repo-000.svg?logo=github&labelColor=gray&color=blue)]([email protected]:EIT-ALIVE/eit_dash)                                                                                             |
+| license            | [![github license badge](https://img.shields.io/github/license/EIT-ALIVE/eit_dash)]([email protected]:EIT-ALIVE/eit_dash)                                                                                                                         |
+| community registry | [![RSD](https://img.shields.io/badge/rsd-eit_dash-00a3e3.svg)](https://www.research-software.nl/software/eit_dash) [![workflow pypi badge](https://img.shields.io/pypi/v/eit_dash.svg?colorB=blue)](https://pypi.python.org/project/eit_dash/) |
+| howfairis          | [![fair-software badge](https://img.shields.io/badge/fair--software.eu-%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8B-yellow)](https://fair-software.eu)                                                                |
+| Documentation      | [![Documentation Status](https://readthedocs.org/projects/eit_dash/badge/?version=latest)](https://eit_dash.readthedocs.io/en/latest/?badge=latest)                                                                                            |
 
-## Mockup
-
-[mockup](https://github.com/EIT-ALIVE/eitprocessing/files/11480259/Proposal.GUI.mockup.pptx)
+## Getting started
 
-## How to use eit_dash
+### 1. Installation
 
-GUI to load and analyze image data from electrical impedance tomography (EIT)
+##### Install Poetry
 
-The project setup is documented in [project_setup.md](project_setup.md). Feel free to remove this document (and/or the link to this document) if you don't need it.
+EIT Dashboard uses of [poetry](https://python-poetry.org/) to easily manage the needed packages.
+Poetry can be installed as follows. Please refer to the [official installation instructions](https://python-poetry.org/docs/#installation) if problems arise:
 
-## Getting started
+In Linux (and WSL) or macOS
 
-### Installing Poetry
+```console
+curl -sSL https://install.python-poetry.org | python3 -
+```
 
-EIT Dashboard makes use of [poetry](https://python-poetry.org/) to easily manage the needed packages. 
-`Poetry` can be installed both at system level following the [installation instructions](https://python-poetry.org/docs/#installation):
+Alternatively, you can use Homebrew in macOS:
 
-In Linux, macOS, Windows (WSL)
 ```console
-curl -sSL https://install.python-poetry.org | python3 -
+brew install poetry
 ```
 
-In Windows (PowerShell)
+In Windows (using PowerShell)
+
 ```console
 (Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -
 ```
 
-Alternatively, Poetry can also be installed [using pip](https://pypi.org/project/poetry/). 
+Alternatively, poetry can also be installed [using pip](https://pypi.org/project/poetry/) or [conda](https://anaconda.org/conda-forge/poetry) in a virtual environment of choice.
 
-### Creating the virtual environment 
+##### Install EIT Dashboard
 
-The first time that the dashboard is used, the repository needs to be cloned and the needed dependencies have to be installed by running:
+The first time that the dashboard is used, the repository needs to be cloned and the needed dependencies have to be
+installed by navigating to the path where it should be installed and running:
 
 ```console
 git clone [email protected]:EIT-ALIVE/eit_dash.git
+cd eit_dash
 poetry install
 ```
 
-### Running the dashboard
+### 2. Running EIT Dashboard
 
-Once the environment has been created, the dashboard can be run through:
+##### Stay up to date
+
+To ensure you are using the newest version, including any updates since you last used it, navigate to the folder where
+the dashboard is installed and run:
 
 ```console
-poetry run python eit_dash/main.py
+git pull
+poetry install
 ```
 
+Please see our [user manual](docs/user_manual.md) for instructions on how to use the dashboard.
+
+##### Run dashboard
+
+Run the command below and and open the resulting link in a browser (often something like `http://127.0.0.1:8050/`).
+Note that while the dashboard should work on any browser, if you are experiencing issues we recommend switching to
+Chrome or Firefox, as these are the browser where we do most of the testing.
+
+```console
+poetry run python eit_dash/main.py
+```
 
 ## Documentation
 
@@ -72,3 +91,7 @@ have a look at the [contribution guidelines](CONTRIBUTING.md).
 ## Credits
 
 This package was created with [Cookiecutter](https://github.com/audreyr/cookiecutter) and the [NLeSC/python-template](https://github.com/NLeSC/python-template).
+
+## License
+
+This source code is licensed using a standard [Apache 2.0 License](LICENSE)

docs/user_manual.md

@@ -0,0 +1,74 @@
+# User manual for EIT dashboard
+
+Note 1: If you have not installed the dashboard yet, please refer to our [README](../README.md) on instructions how to do
+that.
+
+Note 2: While the dashboard is rendered in a browser window, you are not working online. All data that you load into the
+dashboard remains local on your machine.
+
+Note 3: The Dashboard, this manual, and the (back end) software it is built around are works in progress. The images and
+interaction procedures may be slightly off. Please bear with us.
+
+## LOAD page
+
+The dashboard should open on the **LOAD** page, but in case this does not happen, navigate there by clicking **LOAD** at
+the top of the page. You should see something like this:
+
+<kbd>
+<img src=images/load_entry_point.png width="1200px">
+</kbd>
+
+Click on the dropdown menu to select the format of data to load, then click on the `Select Files` button. From here you
+can navigate to the data and select it. Hit `Confirm` to pre-load and pre-view the selected data.
+
+Note that supported files currently are:
+
+- Dräger: `*.bin` files exported from the PV500 software
+- Timpel: `*.txt` files exported using the Timpel File Converter
+- Sentec: `*.zri` files
+
+It could look something like this:
+
+<kbd>
+<img src=images/load_data_preview.png width="800px">
+</kbd>
+
+From here one or more pre-selection(s), termed "Datasets" in the software, of a portion of the data can be made by
+selecting a time window from preview and clicking `Confirm`. Note that a number of additional signals can be co-loaded
+with the data using the check boxes above the Pre selection window. If you want to use these in the following steps,
+they _must_ be selected here already.
+
+Note that on the following page more precise time selections can be made. This page is just intended to make a rough
+pre-selection. Also, pre-selections cannot be undone at this point, but do not need to be used for further processing.
+
+When all pre-selections are made, Click **`PRE-PROCESSING`** at the top of the page to proceed to the next stage.
+
+## PRE-PROCESSING page
+
+Currently the only pre-processing steps available are period selection and filtering. We plan to add other
+pre-processing steps in the future, including ROI selection, resampling, etc.
+
+#### Select data range(s).
+
+First click on `Select data range(s)` and from the "Periods selection method", select `Manual` (we will add automated
+selection methods, e.g. "Stabe period selection", in the future).
+
+You can now select which periods to actually use from within each Dataset, and add them to your analysis list by
+clicking on `Add selection`. Multiple selections from one or more preselected data ranges. These are termed "Periods" in
+the software.
+
+All Periods will appear in a darker shade. When you have finished selecting periods, close the "Periods slection" window by hitting the `X`.
+
+<kbd>
+<img src=images/preprocessing_add_selection.png width="800px">
+</kbd>
+
+#### Filter data
+
+Click `Filter Data` and choose your favorite filter settings and then `Apply`. You can now select the period you want to
+apply it to to preview the result. You can change settings or periods in this window and each time you click `Apply`,
+the preview will update. When you are happy with a particular setting/selection, click `Confirm` to add it to your list.
+
+<kbd>
+<img src=images/preprocessing_filter.png width="800px" style="border: 1px solid black">
+</kbd>