Merge branch 'main' into refresh_bug

.github/workflows/build-windows-executable-app.yaml

@@ -63,12 +63,16 @@ jobs:
         key: ${{ runner.os }}-contrib3
 
     - name: Load contrib build
-      if: steps.cache-contrib-win.outputs.cache-hit != 'true'
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       run: |
-          cd OpenMS/contrib
-          curl -o contribbld.tar.gz https://abibuilder.cs.uni-tuebingen.de/archive/openms/contrib/windows/x64/msvc-14.2/contrib_build.tar.gz
-          tar -xzf contribbld.tar.gz
-          rm contribbld.tar.gz
+        cd OpenMS/contrib
+        # Download the file using the URL fetched from GitHub
+        gh release download -R OpenMS/contrib --pattern 'contrib_build-Windows.tar.gz'
+        # Extract the archive
+        7z x -so contrib_build-Windows.tar.gz | 7z x -si -ttar
+        rm contrib_build-Windows.tar.gz
+        ls
 
     - name: Setup ccache cache
       uses: actions/cache@v3

README.md

@@ -1,73 +1,27 @@
-# OpenMS streamlit template [![Open Template!](https://static.streamlit.io/badges/streamlit_badge_black_white.svg)](https://abi-services.cs.uni-tuebingen.de/streamlit-template/)
+# OpenMS streamlit template 
 
-This is a template app for OpenMS workflows in a web application.
+[![Open Template!](https://static.streamlit.io/badges/streamlit_badge_black_white.svg)](https://abi-services.cs.uni-tuebingen.de/streamlit-template/)
 
-## Requires
-
-Python <= 3.10
+This repository contains a template app for OpenMS workflows in a web application using the **streamlit** framework. It serves as a foundation for apps ranging from simple workflows with **pyOpenMS** to complex workflows utilizing **OpenMS TOPP tools** with parallel execution. It includes solutions for handling user data and parameters in workspaces as well as deployment with docker-compose.
 
 ## Features
 
 - Workspaces for user data with unique shareable IDs
+- Persistent parameters and input files within a workspace
+- local and online mode
 - Captcha control
-- Deployment with Docker
-- Packaged executables for Windows (built via GitHub action)
-- Automatic removal of unused workspaces
-- Parameters persist within a workspace
-
-## Key concepts
-
-**Workspaces** 
-
-Directories where all data generated and uploaded can be stored as well as a workspace specific parameter file.
-
-**Run the app locally and online**
-
-Launching the app with the `local` argument let's the user create/remove workspaces. In the online the user gets a workspace with a specific ID.
-
-**Parameters**
-
-Parameters (defaults in `assets/default-params.json`) store changing parameters for each workspace. Parameters are loaded via the page_setup function at the start of each page. To track a widget variable via parameters simply give them a key and add a matching entry in the default parameters file. Initialize a widget value from the params dictionary.
-
-```python
-params = page_setup()
-
-st.number_input(label="x dimension", min_value=1, max_value=20,
-value=params["example-y-dimension"], step=1, key="example-y-dimension")
-
-save_params()
-```
+- Packaged executables for Windows
+- framework for workflows with OpenMS TOPP tools
+- Deployment [with docker-compose](https://github.com/OpenMS/streamlit-deployment)
 
+## Documentation
 
-## Code structure
+Documentation for **users** and **developers** is included as pages in [this template app](https://abi-services.cs.uni-tuebingen.de/streamlit-template/), indicated by the 📖 icon.
 
-- **Pages** must be placed in the `pages` directory.
-- It is recommended to use a separate file for defining functions per page in the `src` directory.
-- The `src/common.py` file contains a set of useful functions for common use (e.g. rendering a table with download button).
+## References
 
-## App layout
+- Pfeuffer, J., Bielow, C., Wein, S. et al. OpenMS 3 enables reproducible analysis of large-scale mass spectrometry data. Nat Methods 21, 365–367 (2024). [https://doi.org/10.1038/s41592-024-02197-7](https://doi.org/10.1038/s41592-024-02197-7)
 
-- Main page contains explanatory text on how to use the app and a workspace selector.
-- Sidebar contains the OpenMS logo, settings panel and a workspace indicator. The main page contains a workspace selector as well.
-- See pages in the template app for example use cases. The content of this app serves as a documentation.
+- Röst HL, Schmitt U, Aebersold R, Malmström L. pyOpenMS: a Python-based interface to the OpenMS mass-spectrometry algorithm library. Proteomics. 2014 Jan;14(1):74-7. [https://doi.org/10.1002/pmic.201300246](https://doi.org/10.1002/pmic.201300246). PMID: [24420968](https://pubmed.ncbi.nlm.nih.gov/24420968/).
 
-## Modify the template to build your own app
 
-- in `src/common.py` update the name of your app and the repository name
-- in `clean-up-workspaces.py` update the name of the workspaces directory to `/workspaces-<your-repository-name>`
-    - e.g. for the streamlit template it's "/workspaces-streamlit-template"
-- chose one of the Dockerfiles depending on your use case:
-    - `Dockerfile` build OpenMS including TOPP tools
-    - `Dockerfile_simple` uses pyOpenMS only
-- update the Dockerfile:
-    - with the `GITHUB_USER` owning the streamlit app repository
-    - with the `GITHUB_REPO` name of the streamlit app repository
-    - if your main streamlit file is not called `app.py` modfify the following line
-        - `RUN echo "mamba run --no-capture-output -n streamlit-env streamlit run app.py" >> /app/entrypoint.sh`
-- update Python package dependency files:
-    - `requirements.txt` if using `Dockerfile_simple`
-    - `environment.yml` if using `Dockerfile`
-- update `README.md`
-- for the Windows executable package:
-    - update `datas` in `run_app_temp.spec` with the Python packages required for your app
-    - update main streamlit file name to run in `run_app.py`

app.py

@@ -33,10 +33,24 @@ def main():
     """
     Display main page content.
     """
-    st.title("Template App")
-    st.markdown("## A template for an OpenMS streamlit app.")
+    st.title("OpenMS Streamlit Template App")
+    st.info("""
+This repository contains a template app for OpenMS workflows in a web application using the **streamlit** framework. It serves as a foundation for apps ranging from simple workflows with **pyOpenMS** to complex workflows utilizing **OpenMS TOPP tools** with parallel execution. It includes solutions for handling user data and parameters in workspaces as well as deployment with docker-compose.
+""")
+    st.subheader("Features")
+    st.markdown("""
+- Workspaces for user data with unique shareable IDs
+- Persistent parameters and input files within a workspace
+- Captcha control
+- Packaged executables for Windows
+- framework for workflows with OpenMS TOPP tools
+- Deployment [with docker-compose](https://github.com/OpenMS/streamlit-deployment)
+""")
+    st.subheader("Quick Start")
     if Path("OpenMS-App.zip").exists():
-        st.markdown("## Installation")
+        st.markdow("""
+Download the latest version for Windows here by clicking the button below.
+""")
         with open("OpenMS-App.zip", "rb") as file:
             st.download_button(
                 label="Download for Windows",
@@ -45,6 +59,14 @@ def main():
                 mime="archive/zip",
                 type="primary",
             )
+        st.markdown("""
+Extract the zip file and run the executable (.exe) file to launch the app. Since every dependency is compressed and packacked the app will take a while to launch (up to one minute).
+""")
+    st.markdown("""
+Check out the documentation for **users** and **developers** is included as pages indicated by the 📖 icon
+
+Try the example pages **📁 mzML file upload**, **👀 visualization** and **example workflows**.
+""")
     save_params(params)
 
 

pages/0_📖_Installation.py

@@ -0,0 +1,61 @@
+import streamlit as st 
+from pathlib import Path
+from src.common import page_setup
+
+page_setup()
+
+if Path("OpenMS-App.zip").exists():
+    st.markdown("""
+Download the latest version for **Windows** here clicking the button below.
+""")
+    with open("OpenMS-App.zip", "rb") as file:
+        st.download_button(
+            label="Download for Windows",
+            data=file,
+            file_name="OpenMS-App.zip",
+            mime="archive/zip",
+            type="primary",
+        )
+
+st.markdown("""
+# Installation
+
+## Windows
+
+The app is available as pre-packaged Windows executable, including all dependencies.
+
+The windows executable is built by a GitHub action and can be downloaded [here](https://github.com/OpenMS/streamlit-template/actions/workflows/build-windows-executable-app.yaml).
+Select the latest successfull run and download the zip file from the artifacts section, while signed in to GitHub.
+
+## Python
+
+Clone the [streamlit-template repository](https://github.com/OpenMS/streamlit-template). It includes files to install dependencies via pip or conda.
+
+### via pip in an existing Python environment
+
+To install all required depdencies via pip in an already existing Python environment, run the following command in the terminal:
+
+`pip install -r requirements.txt`
+
+### create new environment via conda/mamba
+
+Create and activate the conda environment:
+
+`conda env create -f environment.yml`
+
+`conda activate streamlit-env`
+
+### run the app
+
+Run the app via streamlit command in the terminal with or without *local* mode (default is *online* mode). Learn more about *local* and *online* mode in the documentation page 📖 **OpenMS Template App**.
+
+`streamlit run app.py [local]`
+
+## Docker
+
+This repository contains two Dockerfiles.
+
+1. `Dockerfile`: This Dockerfile builds all dependencies for the app including Python packages and the OpenMS TOPP tools. Recommended for more complex workflows where you want to use the OpenMS TOPP tools for instance with the **TOPP Workflow Framework**.
+2. `Dockerfile_simple`: This Dockerfile builds only the Python packages. Recommended for simple apps using pyOpenMS only.
+
+""")

pages/3_Workflow_with_mzML_files.py → pages/15_Workflow_with_mzML_files.py

@@ -5,7 +5,7 @@
 from pathlib import Path
 
 from src.common import page_setup, save_params, show_fig, show_table
-from src import complexworkflow
+from src import mzmlfileworkflow
 from src.captcha_ import captcha_control
 
 
@@ -48,7 +48,7 @@
 if run_workflow_button:
     params = save_params(params)
     if params["example-workflow-selected-mzML-files"]:
-        complexworkflow.run_workflow(params, result_dir)
+        mzmlfileworkflow.run_workflow(params, result_dir)
     else:
         st.warning("Select some mzML files.")
 

pages/1_📖_User_Guide.py

@@ -0,0 +1,52 @@
+import streamlit as st
+from src.common import page_setup
+
+page_setup()
+
+st.markdown("""
+# User Guide
+
+Welcome to the OpenMS Streamlit Web Application! This guide will help you understand how to use our tools effectively.
+
+## Advantages of OpenMS Web Apps
+
+OpenMS web applications provide a user-friendly interface for accessing the powerful features of OpenMS. Here are a few advantages:
+- **Accessibility**: Access powerful OpenMS algorithms and TOPP tools from any device with a web browser.
+- **Ease of Use**: Simplified user interface makes it easy for both beginners and experts to perform complex analyses.
+- **No Installation Required**: Use the tools without the need to install OpenMS locally, saving time and system resources.
+
+## Workspaces
+
+In the OpenMS web application, workspaces are designed to keep your analysis organized:
+- **Workspace Specific Parameters and Files**: Each workspace stores parameters and files (uploaded input files and results from workflows).
+- **Persistence**: Your workspaces and parameters are saved, so you can return to your analysis anytime and pick up where you left off.
+
+## Online and Local Mode Differences
+
+There are a few key differences between operating in online and local modes:
+- **File Uploads**:
+  - *Online Mode*: You can upload only one file at a time. This helps manage server load and optimizes performance.
+  - *Local Mode*: Multiple file uploads are supported, giving you flexibility when working with large datasets.
+- **Workspace Access**:
+  - In online mode, workspaces are stored temporarily and will be cleared after seven days of inactivity.
+  - In local mode, workspaces are saved on your local machine, allowing for persistent storage.
+
+## Downloading Results
+
+You can download the results of your analyses, including figures and tables, directly from the application:
+- **Figures**: Click the camera icon button, appearing while hovering on the top right corner of the figure. Set the desired image format in the settings panel in the side bar.
+- **Tables**: Use the download button to save tables in *csv* format, appearing while hovering on the top right corner of the table.
+
+## Getting Started
+
+To get started:
+1. Select or create a new workspace.
+2. Upload your data file.
+3. Set the necessary parameters for your analysis.
+4. Run the analysis.
+5. View and download your results.
+
+For more detailed information on each step, refer to the specific sections of this guide.
+""")
+
+

pages/2_📖_Build_App.py

@@ -0,0 +1,83 @@
+import streamlit as st 
+
+from src.common import page_setup
+
+page_setup()
+
+st.markdown("""
+# Build your own app based on this template
+
+## App layout
+
+- *Main page* contains explanatory text on how to use the app and a workspace selector. `app.py`
+- *Pages* can be navigated via *Sidebar*. Sidebar also contains the OpenMS logo, settings panel and a workspace indicator. The *main page* contains a workspace selector as well.
+- See *pages* in the template app for example use cases. The content of this app serves as a documentation.
+
+## Key concepts
+
+- **Workspaces**
+: Directories where all data is generated and uploaded can be stored as well as a workspace specific parameter file.
+- **Run the app locally and online**
+: Launching the app with the `local` argument lets the user create/remove workspaces. In the online the user gets a workspace with a specific ID.
+- **Parameters**
+: Parameters (defaults in `assets/default-params.json`) store changing parameters for each workspace. Parameters are loaded via the page_setup function at the start of each page. To track a widget variable via parameters simply give them a key and add a matching entry in the default parameters file. Initialize a widget value from the params dictionary.
+
+```python
+params = page_setup()
+
+st.number_input(label="x dimension", min_value=1, max_value=20,
+value=params["example-y-dimension"], step=1, key="example-y-dimension")
+
+save_params()
+```
+
+## Code structure
+
+- **Pages** must be placed in the `pages` directory.
+- It is recommended to use a separate file for defining functions per page in the `src` directory.
+- The `src/common.py` file contains a set of useful functions for common use (e.g. rendering a table with download button).
+
+## Modify the template to build your own app
+
+1. In `src/common.py`, update the name of your app and the repository name
+    ```python
+    APP_NAME = "OpenMS Streamlit App"
+    REPOSITORY_NAME = "streamlit-template"
+    ```
+2. In `clean-up-workspaces.py`, update the name of the workspaces directory to `/workspaces-<your-repository-name>`
+    ```python
+    workspaces_directory = Path("/workspaces-streamlit-template")
+    ```
+3. Update `README.md` accordingly
+
+
+**Dockerfile-related**
+1. Choose one of the Dockerfiles depending on your use case:
+    - `Dockerfile` builds OpenMS including TOPP tools
+    - `Dockerfile_simple` uses pyOpenMS only
+2. Update the Dockerfile:
+    - with the `GITHUB_USER` owning the Streamlit app repository
+    - with the `GITHUB_REPO` name of the Streamlit app repository
+    - if your main page Python file is not called `app.py`, modify the following line
+        ```dockerfile
+        RUN echo "mamba run --no-capture-output -n streamlit-env streamlit run app.py" >> /app/entrypoint.sh
+        ```
+3. Update Python package dependency files:
+    - `requirements.txt` if using `Dockerfile_simple`
+    - `environment.yml` if using `Dockerfile`
+
+**for the Windows executable package**
+1. Update `datas` in `run_app_temp.spec` with the Python packages required for your app
+2. Update main Streamlit file name to run in `run_app.py`
+    
+## How to build a workflow
+
+### Simple workflow using pyOpenMS
+
+Take a look at the example pages `Simple Workflow` or `Workflow with mzML files` for examples (on the *sidebar*). Put Streamlit logic inside the pages and call the functions with workflow logic from from the `src` directory (for our examples `src/simple_workflow.py` and `src/mzmlfileworkflow.py`).
+
+### Complex workflow using TOPP tools
+
+This template app features a module in `src/workflow` that allows for complex and long workflows to be built very efficiently. Check out the `TOPP Workflow Framework` page for more information (on the *sidebar*).
+""")
+