-
Notifications
You must be signed in to change notification settings - Fork 10
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #45 from axelwalter/main
update README and main page
- Loading branch information
Showing
2 changed files
with
27 additions
and
65 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,73 +1,19 @@ | ||
# 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() | ||
``` | ||
|
||
|
||
## 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). | ||
|
||
## App layout | ||
|
||
- 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. | ||
- Packaged executables for Windows | ||
- framework for workflows with OpenMS TOPP tools | ||
- Deployment [with docker-compose](https://github.com/OpenMS/streamlit-deployment) | ||
|
||
## Modify the template to build your own app | ||
## Documentation | ||
|
||
- 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` | ||
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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters