diff --git a/app.py b/app.py index 73801251..46b43607 100644 --- a/app.py +++ b/app.py @@ -6,7 +6,10 @@ if __name__ == '__main__': pages = { "FLASHApp" : [ - st.Page(Path("content", "quickstart.py"), title="Quickstart", icon="👋") + st.Page(Path("content", "quickstart.py"), title="Quickstart", icon="👋"), + #st.Page(Path("content", "user_guide.md").read_text(encoding="utf-8"), unsafe_allow_html=True), + st.Page(Path("content", "user_guide.py"), title="User Guide", icon="📖"), + ], "⚡️ FLASHDeconv" : [ st.Page(Path("content", "FLASHDeconv", "FLASHDeconvWorkflow.py"), title="Workflow", icon="⚙️"), diff --git a/content/FLASHTnT/img.png b/content/FLASHTnT/img.png new file mode 100644 index 00000000..6dd7a51f Binary files /dev/null and b/content/FLASHTnT/img.png differ diff --git a/content/FLASHTnT/img_1.png b/content/FLASHTnT/img_1.png new file mode 100644 index 00000000..6dd7a51f Binary files /dev/null and b/content/FLASHTnT/img_1.png differ diff --git a/content/FLASHTnT/img_2.png b/content/FLASHTnT/img_2.png new file mode 100644 index 00000000..6dd7a51f Binary files /dev/null and b/content/FLASHTnT/img_2.png differ diff --git a/content/TODO_Update/documentation.py b/content/TODO_Update/documentation.py deleted file mode 100644 index c308213b..00000000 --- a/content/TODO_Update/documentation.py +++ /dev/null @@ -1,109 +0,0 @@ -import streamlit as st -from src.common.common import page_setup -from pathlib import Path -from docs.toppframework import content as topp_framework_content - -page_setup() - - -st.title("Documentation") - -cols = st.columns(2) - -pages = [ - "User Guide", - "Installation", - "Developers Guide: How to build app based on this template", - "Developers Guide: TOPP Workflow Framework", - "Developer Guide: Windows Executables", - "Developers Guide: Deployment", -] -page = cols[0].selectbox( - "**Content**", - pages, -) - -############################################################################################# -# User Guide -############################################################################################# - -if page == pages[0]: - with open(Path("docs", "user_guide.md"), "r", encoding="utf-8") as f: - content = f.read() - st.markdown(content) - -############################################################################################# -# Installation -############################################################################################# - -if page == pages[1]: - 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", - ) - with open(Path("docs", "installation.md"), "r", encoding="utf-8") as f: - content = f.read() - st.markdown(content) - -############################################################################################# -# Developer Overview, how to build app based on Template -############################################################################################# - -if page == pages[2]: - with open(Path("docs", "build_app.md"), "r", encoding="utf-8") as f: - content = f.read() - st.markdown(content) - -############################################################################################# -# TOPP Workflow Framework -############################################################################################# - -if page == pages[3]: - topp_framework_content() - -############################################################################################# -# Windows Executables -############################################################################################# - -if page == pages[4]: - st.markdown( - """ -## 💻 How to package everything for Windows executables - -This guide explains how to package OpenMS apps into Windows executables using two different methods: -""" - ) - - tabs = ["**embeddable Python**", "**PyInstaller**"] - tabs = st.tabs(tabs) - - # window executable with embeddable python - with tabs[0]: - with open(Path("docs", "win_exe_with_embed_py.md"), "r", encoding="utf-8") as f: - content = f.read() - st.markdown(content) - - # window executable with pyinstaller - with tabs[1]: - with open(Path("docs", "win_exe_with_pyinstaller.md"), "r", encoding="utf-8") as f: - content = f.read() - st.markdown(content) - -############################################################################################# -# Deployment -############################################################################################# - -if page == pages[5]: - with open(Path("docs", "deployment.md"), "r", encoding="utf-8") as f: - content = f.read() - st.markdown(content) \ No newline at end of file diff --git a/content/user_guide.md b/content/user_guide.md new file mode 100644 index 00000000..30a61327 --- /dev/null +++ b/content/user_guide.md @@ -0,0 +1,249 @@ +# **FLASHDeconv & FLASHTnT User Guide** + +Welcome to the **FLASHDeconv & FLASHTnT User Guide**. This guide provides a step-by-step walkthrough on using **FLASHDeconv** and **FLASHTnT**, from uploading data to processing and viewing results. + +--- + +## **1️⃣ Uploading MS Data** + +1. Navigate to **FLASHDeconv > Workflow** in the sidebar. +2. Click **"File Upload"** to upload your `.mzML` file. +3. **Two options to add files:** + - **Drag and Drop** your file into the upload box. + - **Browse Files** to manually select the `.mzML` file. +4. Click **"Add MS Data"** to confirm the upload. + +![Upload](/static/images/flashdeconv_upload.png) + + +--- + +## **2️⃣ Configuring Parameters** + +1. Click the **"Configure"** tab. +2. Select your uploaded **mzML file** (should appear in the file list). +3. Adjust **parameters**: + - Set **threads** (recommended: 8). + - Choose **General Settings** (e.g., `keep_empty_out`, `write_detail`). + - Configure **FD settings** like `report_FDR`, `merging_method`, `min_mass`, `max_mass`, `min_charge`. + - Adjust **SD settings** for deconvolution accuracy. +4. If you want to know more about each parameter go to this link: https://openms.de/FLASHDeconv + + +![Configure Parameters](/static/images/flashdeconv_configure.png) + +--- + +## **3️⃣ Running the Workflow** + +1. Click on the **"Run"** tab. +2. Set **log details** to `minimal` (or another level as needed). +3. Click **"Start Workflow"** to begin the deconvolution process. +4. Monitor the **log output** to track progress. + + +![Run Workflow](/static/images/flashdeconv_run.png) + +--- + +## **4️⃣ Viewing Results** + +1. Once the workflow is finished, check the **log messages**. +2. Navigate to the **"Viewer"** tab in the sidebar to analyze the deconvoluted data. +3. If needed, **download results** by clicking **"Download Files"**. + (Will be explained later in step 7 and 8 in this guide) + +--- + +## **5️⃣ Manual Result Upload** + +1. Click on the **"Manual Result Upload"** tab. +2. Upload FLASHDeconv output files (`*_annotated.mzML` & `*_deconv.mzML`) or TSV files for ECDF Plot. +3. Browse files or **drag and drop** them into the upload section. +4. Click **"Add files to workspace"** to finalize. + + +![Manual Upload](/static/images/flashdeconv_manual_upload.png) + +--- + +## **6️⃣ Using Example Data** + +1. Click the **"Example Data"** tab. +2. Click **"Load Example Data"** to use the preloaded dataset. +3. The example data will appear in the uploaded experiments table. + + +![Example Data](/static/images/flashdeconv_example_data.png) + +--- + +## **7️⃣ Layout Manager** + +The **Layout Manager** allows users to customize the experiment display settings. + +1. Select the **number of experiments** to view at once. +2. Click **"Select..."** to choose components to add: + - **MS1 raw heatmap** - 2D heatmap of raw MS signals with m/z (y-axis), retention time (x-axis), and intensity as color gradient. + - **MS1 deconvolved heatmap** - Displays raw MS signals as a 2D heatmap with monoisotopic mass (y-axis), retention time (x-axis), and intensity as a color gradient. + - **Scan table** - Lists scan details (e.g., number, retention time, precursor mass). + - **Deconvolved spectrum** - Plots deconvolved spectrum for a scan (summed intensity vs. monoisotopic mass). + - **Raw spectrum** - Plots raw spectrum for a scan(intensity vs m/z). + - **Mass table** - Display deconvolved masses for a selected scan with properties. + - **3D S/N plot** - Visualizes S/N ratio of deconvolved masses in 3D. +3. Click **Save** to apply changes. + + +![Layout Manager](/static/images/flashdeconv_layout_manager.png) + +--- + +## **8️⃣ Viewing Results in FLASHViewer** + +1. Navigate to the **Viewer** tab. +2. Choose an experiment from the dropdown. +3. View the selected one from Layout manager: scan table, mass table, annotated spectrum, and deconvolved spectrum etc. + +![FLASHViewer](/static/images/flashdeconv_viewer.png) + +--- + +## **9️⃣ Downloading Results** + +1. Navigate to the **Download** tab. +2. Locate the experiment you want to download. +3. Click **"Prepare Download"** to generate the downloadable files. +4. To delete an experiment, click the **trash icon** next to the experiment name. + +![Download Results](/static/images/flashdeconv_download.png) + +--- + + + +# **FLASHTnT Guide** + +## **1️⃣ Uploading MS Data & Database** + +1. Navigate to **FLASHTnT > Workflow** in the sidebar. +2. Click **"File Upload"** to upload your `.mzML` file. + +![Download Results](/static/images/flashTnT_upload.png) + +3. Click the **"Database"** tab to upload the necessary **FASTA** database files. +4. Click **"Add Database"** to confirm the upload. + + +![Download Results](/static/images/flashTnT_databaseupload.png) +--- +## **2️⃣ Configuring Parameters** +1. Click the **"Configure"** tab. +2. Select your uploaded **mzML file**. +3. Choose the **FASTA database** file. +4. There are two sub-tabs for configuring parameters: **FLASHDeconv** and **FLASHTnT**. +5. Adjust FLASHTnT parameters: +Adjust **general settings** such as: + - **FDR settings** (prsm_fdr, pro_fdr) – Set thresholds for precursor and proteoform-level FDR (e.g., 1.00%). + - **Ion types** (ion_type) – Ion series to consider when generating tags (e.g., b, y). + - **Max modification count** (max_mod_count) – Maximum number of allowed modifications per protein. + + +5. Click **Save** to apply settings. + + +![Download Results](/static/images/flashtnt_configure.png) +![Download Results](/static/images/flashTnT_configure2.png) + + +--- + +## **3️⃣ Running the Workflow** + +1. Click on the **"Run"** tab. +2. Click **"Start Workflow"** to begin. +3. Monitor the progress in the log output. + +![Download Results](/static/images/flashtnt_run.png) + +--- + +## **4️⃣ Layout Manager** + +1. Navigate to Layout Manager. +2. Select how many experiments to display simultaneously (e.g., 1–5). +3. Choose **components** to add for each experiment: +- **Protein Table** – Lists proteins identified by FLASHTnT, including accession, modifications, and score. +- **Sequence View** – Annotates tags, PTMs, and fragments. Visualizes FLASHTnT results; for FLASHDeconv data must be user-supplied. +- **Internal Fragment Map** – Shows internal fragment ions from the selected scan +- **Tag Table** – Lists sequence tags with corresponding information. +- **Spectrum View** – Shows the annotated spectrum with matched peaks. + +![Download Results](/static/images/layoutmanager_tnt.png) + +--- + +## **5️⃣ Viewer** + +1. Choose the experiment. +2. View the selected one from Layout manager. + +![Download Results](/static/images/FlashTnT_Viewer.png) + +--- + +## **6️⃣ Manual Result Upload & Example Data** + +1. Click **"Manual Result Upload"** to upload manually processed data. +2. Click **"Example Data"** to load a sample dataset. + +![Download Results](/static/images/manual_result_upload.png) + +--- + +## **7️⃣ Downloading Results** + +1. Navigate to the **Download** tab. +2. Locate the experiment you want to download. +3. Click **"Prepare Download"** to generate the downloadable files. +4. To delete an experiment, click the **trash icon** next to the experiment name. + +![Download Results](/static/images/download_tnt.png) + +--- + + +## **📖 Need Help?** + +If you have any questions or need assistance, feel free to contact our support team. + +### **FLASHApp Support Contacts:** +- **Tom Müller**: [tom.mueller@uni-tuebingen.de](mailto:tom.mueller@uni-tuebingen.de) +- **Ayesha Feroz**: [ayesha.feroz@uni-tuebingen.de](mailto:ayesha.feroz@uni-tuebingen.de) + +--- + +## **📚 Relevant Publications** +For more information about the research behind FLASHDeconv & FLASHTnT, refer to the following publications: + +- **Jeong, K., Kim, J., Gaikwad, M., Hidayah, S. N., Heikaus, L., Schlüter, H., & Kohlbacher, O.** (2020). + *FLASHDeconv: Ultrafast, high-quality feature deconvolution for top-down proteomics.* + **Cell Systems, 10(2), 213-218.e6** + 📄 [Read the paper](https://doi.org/10.1016/j.cels.2020.01.003) + +- **Müller, T. D., Siraj, A., Walter, A., Kim, J., Wein, S., von Kleist, J., Feroz, A., Pilz, M., Jeong, K., Sing, J. C., Charkow, J., Röst, H. L., & Sachsenberg, T.** (2024, November 20). + *OpenMS webapps: Building user-friendly solutions for MS analysis.* + 📄 [Read the paper](https://pubs.acs.org/doi/10.1021/acs.jproteome.4c00872) + +- **Müller, T., Kim, J., Almaguer, A., et al.** (2025, April 17). + *FLASHApp: Interactive Data Analysis and Visualization for Top-Down Proteomics.* + 📄 [Read the paper](https://www.authorea.com/users/914240/articles/1287405-flashapp-interactive-data-analysis-and-visualization-for-top-down-proteomics?commit=1447908dbdd26d9a2312890c9c400d96f2b171f7) +--- + +🚀 **You're now ready to use FLASHDeconv & FLASHTnT!** + + + + + + + diff --git a/content/user_guide.py b/content/user_guide.py new file mode 100644 index 00000000..9d995900 --- /dev/null +++ b/content/user_guide.py @@ -0,0 +1,38 @@ +import streamlit as st +from pathlib import Path +from src.common.common import page_setup + +# Setup page +params = page_setup() +st.title("📖 User Guide") + +# Define paths +md_file = Path("content", "user_guide.md") +image_folder = Path("static", "Images") + +# Read the User Guide Markdown file +if md_file.exists(): + with open(md_file, "r", encoding="utf-8") as f: + content = f.readlines() +else: + st.error(f"🚨 Error: Could not find {md_file}") + content = [] + +# Process Markdown content and replace image references +for line in content: + + # Markdown-style image (e.g., ![alt text](path/to/image.png)) + if line.strip().startswith("!["): + start = line.find("(") + 1 + end = line.find(")") + image_name = line[start:end].split("/")[-1] + image_path = image_folder / image_name + + if image_path.exists(): + st.image(str(image_path), caption=image_name, width=800) + else: + st.warning(f"⚠️ Missing image: {image_name}") + + # Normal markdown text + else: + st.markdown(line) diff --git a/static/images/FlashTnT_Viewer.png b/static/images/FlashTnT_Viewer.png new file mode 100644 index 00000000..8fb45427 Binary files /dev/null and b/static/images/FlashTnT_Viewer.png differ diff --git a/static/images/download_tnt.png b/static/images/download_tnt.png new file mode 100644 index 00000000..08ca41c5 Binary files /dev/null and b/static/images/download_tnt.png differ diff --git a/static/images/flashTnT_configure2.png b/static/images/flashTnT_configure2.png new file mode 100644 index 00000000..f6cf0eff Binary files /dev/null and b/static/images/flashTnT_configure2.png differ diff --git a/static/images/flashTnT_databaseupload.png b/static/images/flashTnT_databaseupload.png new file mode 100644 index 00000000..ef1ffd75 Binary files /dev/null and b/static/images/flashTnT_databaseupload.png differ diff --git a/static/images/flashTnT_upload.png b/static/images/flashTnT_upload.png new file mode 100644 index 00000000..bebe3667 Binary files /dev/null and b/static/images/flashTnT_upload.png differ diff --git a/static/images/flashdeconv_configure.png b/static/images/flashdeconv_configure.png new file mode 100644 index 00000000..174ed38f Binary files /dev/null and b/static/images/flashdeconv_configure.png differ diff --git a/static/images/flashdeconv_download.png b/static/images/flashdeconv_download.png new file mode 100644 index 00000000..ccf35a90 Binary files /dev/null and b/static/images/flashdeconv_download.png differ diff --git a/static/images/flashdeconv_example_data.png b/static/images/flashdeconv_example_data.png new file mode 100644 index 00000000..d52e097f Binary files /dev/null and b/static/images/flashdeconv_example_data.png differ diff --git a/static/images/flashdeconv_layout_manager.png b/static/images/flashdeconv_layout_manager.png new file mode 100644 index 00000000..9a867db8 Binary files /dev/null and b/static/images/flashdeconv_layout_manager.png differ diff --git a/static/images/flashdeconv_manual_upload.png b/static/images/flashdeconv_manual_upload.png new file mode 100644 index 00000000..898251c6 Binary files /dev/null and b/static/images/flashdeconv_manual_upload.png differ diff --git a/static/images/flashdeconv_run.png b/static/images/flashdeconv_run.png new file mode 100644 index 00000000..efd63329 Binary files /dev/null and b/static/images/flashdeconv_run.png differ diff --git a/static/images/flashdeconv_upload.png b/static/images/flashdeconv_upload.png new file mode 100644 index 00000000..76dad1bd Binary files /dev/null and b/static/images/flashdeconv_upload.png differ diff --git a/static/images/flashdeconv_viewer.png b/static/images/flashdeconv_viewer.png new file mode 100644 index 00000000..de9ab0e0 Binary files /dev/null and b/static/images/flashdeconv_viewer.png differ diff --git a/static/images/flashtnt_configure.png b/static/images/flashtnt_configure.png new file mode 100644 index 00000000..41c77dd8 Binary files /dev/null and b/static/images/flashtnt_configure.png differ diff --git a/static/images/flashtnt_run.png b/static/images/flashtnt_run.png new file mode 100644 index 00000000..9fdca276 Binary files /dev/null and b/static/images/flashtnt_run.png differ diff --git a/static/images/layoutmanager_tnt.png b/static/images/layoutmanager_tnt.png new file mode 100644 index 00000000..3fea1fcb Binary files /dev/null and b/static/images/layoutmanager_tnt.png differ diff --git a/static/images/manual_result_upload.png b/static/images/manual_result_upload.png new file mode 100644 index 00000000..8c80c484 Binary files /dev/null and b/static/images/manual_result_upload.png differ