VueGen is a Python package that automates the creation of scientific reports.

Information	Links
Package
Documentation
Build
Examples
Discuss on GitHub
Cite

Table of contents:

• About the project
• Installation
• Execution
• GUI
• Case studies
• Web application deployment
• Contributing
• Credits and acknowledgements
• Citation
• Contact and feedback

About the project

VueGen is a tool that automates the creation of reports from bioinformatics outputs, allowing researchers with minimal coding experience to communicate their results effectively. With VueGen, users can produce reports by simply specifying a directory containing output files, such as plots, tables, networks, Markdown text, HTML components, and API calls, along with the report format. Supported formats include documents (PDF, HTML, DOCX, ODT), presentations (PPTX, Reveal.js), Jupyter notebooks, and Streamlit web applications.

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.

An overview of the VueGen workflow is shown in the figure below:

Also, the class diagram for the project is presented below to illustrate the architecture and relationships between classes:

An extended version of the class diagram with attributes and methods is available here.

The VueGen documentation is available at vuegen.readthedocs.io, 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 and can be installed using pip:

pip install vuegen

You can also install the package for development by cloning this repository and running the following command:

pip install -e path/to/vuegen # specify location
pip install -e . # in case your pwd is in the vuegen directory

Conda

VueGen is also available on Bioconda and can be installed using conda:

conda install bioconda::vuegen

Dependencies

VueGen uses Quarto to generate various report types. The pip insallation includes quarto using the quarto-cli Python library. To test if quarto is installed in your computer, run the following command:

quarto check

Tip

If quarto is not installed, you can download the command-line interface from the Quarto website for your operating system.

For PDF reports, you need to have a LaTeX distribution installed. This can be done with quarto using the following command:

quarto install tinytex

Tip

Also, you can add the --quarto_checks argument to the VueGen command to check and install the required dependencies automatically.

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 for details on running VueGen with Docker. The official Docker images are available at quay.io/dtu_biosustain_dsp/vuegen. The Dockerfiles to build the images are available here.

Nextflow and nf-core

VueGen is also available as a nf-core module, customised for compatibility with the 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.

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.

Run VueGen using a directory with the following command:

vuegen --directory docs/example_data/Earth_microbiome_vuegen_demo_notebook --report_type streamlit

Note

By default, the streamlit_autorun argument is set to False, but you can use it in case you want to automatically run the streamlit app.

Folder structure

Your input directory must follow a nested folder structure, where first-level folders are treated as sections and second-level folders as subsections, containing the components (plots, tables, networks, Markdown text, and HTML files).

Here is an example layout:

report_folder/
├── section1/
│   └── subsection1/
│       ├── table.csv
│       ├── image1.png
│       └── chart.json
├── section2/
│   ├── subsection1/
│   │   ├── summary_table.xls
│   │   └── network_plot.graphml
│   └── subsection2/
│       ├── report.html
│       └── summary.md

Warning

VueGen currently requires each section to contain at least one subsection folder. Defining only sections (with no subsections) or using deeper nesting levels (i.e., sub-subsections) will result in errors. In upcoming releases, we plan to support more flexible directory structures.

The titles for sections, subsections, and components are extracted from the corresponding folder and file names, and afterward, users can add descriptions, captions, and other details to the configuration file. Component types are inferred from the file extensions and names. The order of sections, subsections, and components can be defined using numerical suffixes in folder and file names.

It's also possible to provide a configuration file instead of a directory:

vuegen --config docs/example_config_files/Earth_microbiome_vuegen_demo_notebook.yaml --report_type streamlit

If a configuration file is given, users can specify titles and descriptions for sections and subsections, as well as component paths and required attributes, such as file format and delimiter for dataframes, plot types, and other details.

The current report types supported by VueGen are:

• Streamlit
• HTML
• PDF
• DOCX
• ODT
• Reveal.js
• PPTX
• Jupyter

Running VueGen with Docker

Instead of installing VueGen locally, you can run it directly from a Docker container with the following command:

docker run --rm \
  -v "$(pwd)/docs/example_data/Earth_microbiome_vuegen_demo_notebook:/home/appuser/Earth_microbiome_vuegen_demo_notebook" \
  -v "$(pwd)/output_docker:/home/appuser/streamlit_report" \
  quay.io/dtu_biosustain_dsp/vuegen:v0.3.2-docker --directory /home/appuser/Earth_microbiome_vuegen_demo_notebook --report_type streamlit

GUI

Local GUI

We have a simple GUI for VueGen that can be run locally or through a standalone executable. For now you will need to have a copy of this repository.

pip install '.[gui]'
cd gui
python app.py

Bundled GUI

The bundle GUI with the VueGen package is available under the latest releases. You will need to unzip the file and run vuegen_gui in the unpacked main folder. Most dependencies are included into the bundle using PyInstaller.

Streamlit works out of the box as a purely Python based package. For html creation you will have to have a Python 3.12 installation with the jupyter package installed as quarto needs to start a kernel for execution. This is also true if you install quarto globally on your machine.

We recommend using miniforge to install Python and the conda package manager:

• conda-forge.org/download/

We continous our example assuming you have installed the miniforge distribution for your machine (MacOS with arm64/ apple silicon or x86_64/ intel or Windows x86_64). Also download the latest vuegen_gui bundle from the releases page according to your operating system.

conda create -n vuegen_gui -c conda-forge python=3.12 jupyter
conda info -e # find environment location

Find the vuegen_gui path for your local user.

On MacOS you need to add a bin to the path:

/Users/user/miniforge3/envs/vuegen_gui/bin

On Windows you can use the path as displayed by conda info -e:

Note: On Windows a base installation of miniforge with jupyter might work as well as the app can see your entire Path which is not the case on MacOS.

C:\Users\user\miniforge3\envs\vuegen_gui

More information regarding the app and builds can be found in the GUI README.

Case studies

VueGen’s functionality is demonstrated through two case studies:

1. Predefined Directory

This introductory case study uses a predefined directory with plots, dataframes, Markdown, and HTML components. Users can generate reports in different formats and modify the configuration file to customize the report structure.

🔗

Note

The configuration file is available in the docs/example_config_files folder, and the directory with example data is in the docs/example_data folder.

2. Earth Microbiome Project Data

This advanced case study demonstrates the application of VueGen in a real-world scenario using data from the Earth Microbiome Project (EMP). The EMP is an initiative to characterize global microbial taxonomic and functional diversity. The notebook process the EMP data, create plots, dataframes, and other components, and organize outputs within a directory to produce reports. Report content and structure can be adapted by modifying the configuration file. Each report consists of sections on exploratory data analysis, metagenomics, and network analysis.

🔗

Note

The EMP case study is available online as HTML and Streamlit reports. The configuration file is available in the docs/example_config_files folder, and the directory with example data is in the docs/example_data folder.

3. ChatBot Component

This case study highlights VueGen’s capability to embed a chatbot component into a report subsection, enabling interactive conversations inside the report.

Two API modes are supported:

• Ollama-style streaming chat completion If a model parameter is specified in the config file, VueGen assumes the chatbot is using Ollama’s /api/chat endpoint. Messages are handled as chat history, and the assistant responses are streamed in real time for a smooth and responsive experience. This mode supports LLMs such as llama3, deepsek, or mistral.

Tip

See Ollama’s website for more details.

• Standard prompt-response API If no model is provided, VueGen uses a simpler prompt-response flow. A single prompt is sent to an endpoint, and a structured JSON object is expected in return. Currently, the response can include:
  • text: the main textual reply
  • links: a list of source URLs (optional)
  • HTML content: an HTML snippet with a Pyvis network visualization (optional)

This response structure is currently customized for an internal knowledge graph assistant, but VueGen is being actively developed to support more flexible and general-purpose response formats in future releases.

Note

You can see a configuration file example for the chatbot component in the docs/example_config_files folder.

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, as demonstrated in the EMP VueGen 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.
• Standalone Executables: Convert your Streamlit application into a desktop app by packaging it as an executable file for different operating systems. A detailed explanation of this process can be found in this Streamlit forum post.
• Stlite: Run Streamlit apps directly in the browser with stlite, a WebAssembly port of Streamlit powered by Pyodide, eliminating the need for a server. It also allows packaging apps as standalone desktop executables using stlite desktop.

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 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) at the Novo Nordisk Foundation Center for Biosustainability (DTU Biosustain).
• VueGen relies on the work of numerous open-source projects like Streamlit, 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 for The Turing Way Community, which is shared under a CC-BY licence. The original image can be found at Zenodo.

Citation

If you use VueGen in your research or publications, please cite it as follows:

APA:

Ayala-Ruano, S., Webel, H., & Santos, A. (2025). VueGen: Automating the generation of scientific reports. bioRxiv. https://doi.org/10.1101/2025.03.05.641152

BibTeX:

@article{Ayala-Ruano2025VueGen,
  author  = {Ayala-Ruano, Sebastian and Webel, Henry and Santos, Alberto},
  title   = {VueGen: Automating the generation of scientific reports},
  journal = {bioRxiv},
  year    = {2025},
  doi     = {10.1101/2025.03.05.641152},
  publisher = {Cold Spring Harbor Laboratory},
  url     = {https://www.biorxiv.org/content/10.1101/2025.03.05.641152},
  eprint = {https://www.biorxiv.org/content/10.1101/2025.03.05.641152.full.pdf}
}

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 in this repository. Your input helps us make VueGen better for everyone.