Merge branch 'main' into test_all_os

Author: enryH

.github/workflows/cdci.yml

@@ -19,6 +19,8 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - uses: psf/black@stable
+        with:
+          jupyter: true
       - uses: isort/isort-action@v1
       - name: Set up Python ${{ matrix.python-version }}
         uses: actions/setup-python@v5
@@ -122,3 +124,58 @@ jobs:
         run: python -m build
       - name: Publish package distributions to PyPI
         uses: pypa/gh-action-pypi-publish@release/v1
+
+  build-executable:
+    name: Build-exe-${{ matrix.os.label }}
+    runs-on: ${{ matrix.os.runner }}
+    needs:
+      - test
+      - other-reports
+    strategy:
+      matrix:
+        python-version: ["3.12"]
+        os:
+          # https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/running-variations-of-jobs-in-a-workflow#example-using-a-multi-dimension-matrix
+          - runner: "macos-13"
+            label: "macos-13-x64"
+          - runner: "macos-15"
+            label: "macos-15-arm64"
+          - runner: "windows-latest"
+            label: "windows-x64"
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install VueGen GUI and pyinstaller
+        run: |
+          python -m pip install ".[gui]" pyinstaller
+      - name: Install quarto tools
+        run: |
+          quarto install chromium
+          quarto install tinytex
+      - name: Build executable
+        run: |
+          cd gui
+          pyinstaller -n vuegen_gui --onefile --windowed --collect-all pyvis --collect-all streamlit --collect-all st_aggrid --collect-all customtkinter --collect-all quarto_cli --collect-all plotly --collect-all _plotly_utils --collect-all traitlets --collect-all referencing --collect-all rpds --collect-all tenacity --collect-all pyvis --collect-all pandas --collect-all numpy --collect-all matplotlib --collect-all openpyxl --collect-all xlrd --collect-all nbformat --collect-all nbclient --collect-all altair --collect-all itables --collect-all kaleido --collect-all pyarrow --collect-all dataframe_image --collect-all narwhals --collect-all PIL --collect-all vl_convert --add-data ../docs/example_data/Basic_example_vuegen_demo_notebook:example_data/Basic_example_vuegen_demo_notebook --add-data ../docs/images/vuegen_logo.png:. app.py
+        # --windowed only for mac, see:
+        # https://pyinstaller.org/en/stable/usage.html#building-macos-app-bundles
+        # 'Under macOS, PyInstaller always builds a UNIX executable in dist.'
+        # --onefile --windowed for Windows?
+        # --collect-all yaml --collect-all strenum --collect-all jinja2 --collect-all fastjsonschema --collect-all jsonschema --collect-all jsonschema_specifications
+        # replace by spec file once done...
+      - name: Upload executable
+        uses: actions/upload-artifact@v4
+        with:
+          name: vuegen_gui_${{ matrix.os.label }}
+          path: gui/dist/
+      - name: Upload Executable to a GitHub Release
+        if: startsWith(github.ref, 'refs/tags')
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          TAG_NAME=${GITHUB_REF#refs/tags/}
+          cp 
+          gh release upload "$TAG_NAME" gui/dist/vuegen_gui.*#vuegen_gui_${{ matrix.os.label }}
+        # https://cli.github.com/manual/gh_release_upload
+        # either .app or .exe depending on the OS

CONTRIBUTING.md

@@ -0,0 +1,71 @@
+# Contributing to VueGen
+
+[VueGen][vuegen-repo] is an open source project, and we welcome contributions of all 
+kinds via GitHub issues and pull requests: correct or improve our [documentation][vuegen-docs], report or fix bugs, propose changes, and implement new features. Please follow 
+these guidelines to make sure that your contribution is easily integrated into the project.
+
+## 1. Contributor Agreement
+
+By contributing, you agree that we may redistribute your work under [our
+license](LICENSE). In exchange, we will address your issues and/or assess
+your change proposal as promptly as we can, and help you become a member of our
+community.
+
+## 2. What to Contribute
+
+The easiest way to get started is by reporting an issue that needs to be fixed, 
+such as a bug in the code, unclear explanations, conceptual errors, or other details. 
+You can also  contribute by proposing new features or modules, improving existing 
+functionality, or suggesting other ideas that might be useful. If you’re looking for 
+inspiration, please check the [list of open issues][issues] in this repository.
+
+Feedback from beginners is especially valuable, as experienced users may overlook how 
+challenging certain aspects of the software can be for newcomers. Therefore, we encourage 
+you to share any suggestions or observations you have about this project.
+
+## 3. How to Contribute
+
+Here are the ways you can submit your suggestions and contribute to the project:
+
+1. **Reporting Issues or Suggesting Improvements:** If you have a  [GitHub][github] account 
+   (or are willing to [open one][github-join]) but are unfamiliar with Git, you can report 
+   bugs or suggest improvements by [creating an issue][new-issue]. This GitHub feature allows 
+   for discussion threads on reported issues and proposed enhancements.
+
+2. **Submitting Changes via Pull Requests:** If you are comfortable using Git and would like to
+   add or modify a functionality, you can submit a **pull request (PR)**. Instructions on how to contribute this way are provided in the next section.
+
+3. **Providing Feedback via Email:** If you don’t have a GitHub account and are
+   unfamiliar with Git, you can send feedback via email to [[email protected]][contact]. However, using GitHub is preferred, as it allows us to respond more quickly and track discussions openly.
+
+> [!NOTE]
+> The documentation for [Git][git-docs] and [GitHub][github-docs] are easy to follow, and you can learn the basics using their official guides.
+
+## 4. Creating a Pull Request
+
+If you choose to contribute via GitHub, you may want to look at [How to Contribute to an Open Source Project on GitHub][how-contribute]. In brief, we use [GitHub flow][github-flow] to manage changes:
+
+1. Create a new branch in your desktop copy of this repository for each significant change.
+2. Commit the change in that branch.
+3. Push that branch to your fork of this repository on GitHub.
+4. Submit a pull request from that branch to the [upstream repository][vuegen-repo].
+5. If you receive feedback, make changes on your desktop and push to your branch on GitHub: the 
+   pull request will update automatically.
+
+## 5. Credits
+
+This contribution guide was modified under the [Creative Commons Attribution 4.0 International License][ccby] from the [Software Carpentry guides][soft-cp-guides].
+
+[vuegen-repo]: https://github.com/Multiomics-Analytics-Group/vuegen
+[vuegen-docs]: https://vuegen.readthedocs.io/
+[issues]: https://github.com/Multiomics-Analytics-Group/vuegen/issues
+[new-issue]: https://github.com/Multiomics-Analytics-Group/vuegen/issues/new
+[github]: https://github.com
+[github-join]: https://github.com/join
+[contact]: mailto:[email protected]
+[git-docs]: https://git-scm.com/doc
+[github-docs]: https://guides.github.com/
+[how-contribute]: https://egghead.io/courses/how-to-contribute-to-an-open-source-project-on-github
+[github-flow]: https://guides.github.com/introduction/flow/
+[soft-cp-guides]: https://software-carpentry.org/lessons/
+[ccby]: https://creativecommons.org/licenses/by/4.0/

README.md

@@ -14,16 +14,19 @@
 | **Cite** | [![DOI:10.1101/2025.03.05.641152](https://img.shields.io/badge/DOI-10.1101/2025.03.05.641152-B31B1B.svg)][vuegen-preprint]|
 
 ## Table of contents:
+
 - [About the project](#about-the-project)
 - [Installation](#installation)
 - [Execution](#execution)
 - [Case studies](#case-studies)
 - [Web application deployment](#web-application-deployment)
+- [Contributing](#contributing)
 - [Credits and acknowledgements](#credits-and-acknowledgements)
 - [Citation](#citation)
 - [Contact and feedback](#contact-and-feedback)
 
 ## About the project
+
 VueGen automates the creation of reports based on a directory with plots, dataframes, and other files in different formats. A YAML configuration file is generated from the directory to define the structure of the report. Users can customize the report by modifying the configuration file, or they can create their own configuration file instead of passing a directory as input. 
 
 The configuration file specifies the structure of the report, including sections, subsections, and various components such as plots, dataframes, markdown, html, and API calls. Reports can be generated in various formats, including documents (PDF, HTML, DOCX, ODT), presentations (PPTX, Reveal.js), notebooks (Jupyter) or [Streamlit](streamlit) web applications.
@@ -38,10 +41,15 @@ Also, the class diagram for the project is presented below to illustrate the arc
 
 An extended version of the class diagram with attributes and methods is available [here][vuegen-class-diag-att].
 
-The VueGen documentation is available at [vuegen.readthedocs.io][vuegen-docs], where you can find detailed information of the package’s classes and functions, installation and execution instructions, and case studies to demonstrate its functionality. 
+The VueGen documentation is available at [vuegen.readthedocs.io][vuegen-docs], where you can find detailed information of the package’s classes and functions, installation and execution instructions, and case studies to demonstrate its functionality.
 
 ## Installation
+
+> [!TIP]
+> It is recommended to install VueGen inside a virtual environment to manage depenendencies and avoid conflicts with existing packages. You can use the virtual environment manager of your choice, such as `poetry`, `conda`, or `pipenv`.
+
 ### Pip
+
 VueGen is available on [PyPI][vuegen-pypi] and can be installed using pip:
 
 ```bash
@@ -55,17 +63,16 @@ pip install -e path/to/vuegen # specify location
 pip install -e . # in case your pwd is in the vuegen directory
 ```
 
-> [!TIP]
-> It is recommended to install VueGen inside a virtual environment to manage depenendencies and avoid conflicts with existing packages. You can use the virtual environment manager of your choice, such as `poetry`, `conda`, or `pipenv`.
-
 ### Conda
+
 VueGen is also available on [Bioconda][vuegen-conda] and can be installed using conda:
 
 ```bash
 conda install bioconda::vuegen
 ```
 
 ### Dependencies
+
 VueGen uses [Quarto][quarto] to generate various report types. The pip insallation includes quarto using the [quarto-cli Python library][quarto-cli-pypi]. To test if quarto is installed in your computer, run the following command:
 
 ```bash
@@ -76,12 +83,15 @@ quarto check
 > If quarto is not installed, you can download the command-line interface from the [Quarto website][quarto-cli] for your operating system.
 
 ### Docker
+
 If you prefer not to install VueGen on your system, a pre-configured Docker container is available. It includes all dependencies, ensuring a fully reproducible execution environment. See the [Execution section](#execution) for details on running VueGen with Docker. The official Docker image is available at [quay.io/dtu_biosustain_dsp/vuegen][vuegen-docker-quay]. 
 
 ### Nextflow and nf-core
+
 VueGen is also available as a [nf-core][nfcore] module, customised for compatibility with the [Nextflow][nextflow] environment. This module is designed to automate report generation from outputs produced by other modules, subworkflows, or pipelines. The code and documentation for the nf-core module are available in the [nf-VueGen repository][nf-vuegen].
 
 ## Execution
+
 > [!IMPORTANT]
 > Here we use the `Earth_microbiome_vuegen_demo_notebook` directory and the `Earth_microbiome_vuegen_demo_notebook.yaml` configuration file as examples, which are available in the `docs/example_data` and `docs/example_config_files` folders, respectively. Make sure to clone this reposiotry to access these contents, or use your own directory and configuration file.
 
@@ -111,6 +121,7 @@ The current report types supported by VueGen are:
 * Jupyter
 
 ### Running VueGen with Docker
+
 Instead of installing VueGen locally, you can run it directly from a Docker container with the following command:
 
 ```bash
@@ -120,7 +131,28 @@ docker run --rm \
   quay.io/dtu_biosustain_dsp/vuegen:docker --directory /home/appuser/Earth_microbiome_vuegen_demo_notebook --report_type streamlit
 ```
 
+## GUI
+
+We have a simple GUI for VueGen that can be run locally or through a standalone executable.
+
+```bash
+cd gui
+python app.py
+```
+
+The bundle GUI with the VueGen package is available under the releases. You will need to
+unzip the file and run `vuegen_gui` in the unpacked main folder. Most dependencies are included into
+the bundle under `_internals` using PyInstaller.
+
+Streamlit works out of the box as a purely Python based package. For `html` creation you will have to
+have a global Python installation with the `jupyter` package installed. `quarto` needs to start
+a kernel for execution. This is also true if you install `quarto` globally on your machine.
+
+More information can be found in the 
+[GUI README](https://github.com/Multiomics-Analytics-Group/vuegen/blob/os_installers/gui/README.md).
+
 ## Case studies
+
 VueGen’s functionality is demonstrated through two case studies:
 
 **1. Predefined Directory**
@@ -139,6 +171,7 @@ This advanced case study demonstrates the application of VueGen in a real-world
 > The EMP case study is available online as [HTML][emp-html-demo] and [Streamlit][emp-st-demo] reports.
 
 ## Web application deployment
+
 Once a Streamlit report is generated, it can be deployed as a web application to make it accessible online. There are multiple ways to achieve this:
 
 * **Streamlit Community Cloud**: Deploy your report easily using [Streamlit Cloud][st-cloud], as demonstrated in the [EMP VueGen Demo][emp-st-demo]. The process involves moving the necessary scripts, data, and a requirements.txt file into a GitHub repository. Then, the app can be deployed via the Streamlit Cloud interface. The deployment example is available in the `streamlit-report-example` branch.
@@ -147,12 +180,18 @@ Once a Streamlit report is generated, it can be deployed as a web application to
 
 These options provide flexibility depending on whether the goal is online accessibility, lightweight execution, or local application distribution.
 
+## Contributing
+
+VueGen is an open-source project, and we welcome contributions of all kinds via GitHub issues and pull requests. You can report bugs, suggest improvements, propose new features, or implement changes. Please follow the guidelines in the [CONTRIBUTING](CONTRIBUTING.md) file to ensure that your contribution is easily integrated into the project.
+
 ## Credits and acknowledgements
+
 - VueGen was developed by the [Multiomics Network Analytics Group (MoNA)][Mona] at the [Novo Nordisk Foundation Center for Biosustainability (DTU Biosustain)][Biosustain].
 - VueGen relies on the work of numerous open-source projects like [Streamlit](streamlit), [Quarto][quarto], and others. A big thank you to their authors for making this possible!
 - The vuegen logo was designed based on an image created by [Scriberia][scriberia] for The [Turing Way Community][turingway], which is shared under a CC-BY licence. The original image can be found at [Zenodo][zenodo-turingway].
 
 ## Citation
+
 If you use VueGen in your research or publications, please cite it as follows:
 
 **APA:**
@@ -175,6 +214,7 @@ Ayala-Ruano, S., Webel, H., & Santos, A. (2025). *VueGen: Automating the generat
 ```
 
 ## Contact and feedback
+
 We appreciate your feedback! If you have any comments, suggestions, or run into issues while using VueGen, feel free to [open an issue][new-issue] in this repository. Your input helps us make VueGen better for everyone. 
 
 [streamlit]: https://streamlit.io/