diff --git a/README.md b/README.md index 0e4876b..a592a47 100644 --- a/README.md +++ b/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)](git@github.com:EIT-ALIVE/eit_dash) | -| (2/5) license | [![github license badge](https://img.shields.io/github/license/EIT-ALIVE/eit_dash)](git@github.com: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/.svg)](https://doi.org/) | -| (5/5) checklist | [![workflow cii badge](https://bestpractices.coreinfrastructure.org/projects//badge)](https://bestpractices.coreinfrastructure.org/projects/) | -| 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)](git@github.com:EIT-ALIVE/eit_dash) | +| license | [![github license badge](https://img.shields.io/github/license/EIT-ALIVE/eit_dash)](git@github.com: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 git@github.com: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) diff --git a/docs/images/load_data_preview.png b/docs/images/load_data_preview.png new file mode 100644 index 0000000..5cea052 Binary files /dev/null and b/docs/images/load_data_preview.png differ diff --git a/docs/images/load_entry_point.png b/docs/images/load_entry_point.png new file mode 100644 index 0000000..4463bfb Binary files /dev/null and b/docs/images/load_entry_point.png differ diff --git a/docs/images/preprocessing_add_selection.png b/docs/images/preprocessing_add_selection.png new file mode 100644 index 0000000..d215d87 Binary files /dev/null and b/docs/images/preprocessing_add_selection.png differ diff --git a/docs/images/preprocessing_filter.png b/docs/images/preprocessing_filter.png new file mode 100644 index 0000000..e2c97dd Binary files /dev/null and b/docs/images/preprocessing_filter.png differ diff --git a/docs/user_manual.md b/docs/user_manual.md new file mode 100644 index 0000000..3a451a4 --- /dev/null +++ b/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: + + + + + +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: + + + + + +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`. + + + + + +#### 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. + + + +