vuegen 0.2.1

Module to generate automatic web interface reports with visualizations

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

Information	Links
Package
Documentation
Build
Examples
Discuss on GitHub

Table of contents:

• About the project
• Installation
• Execution
• Case studies
• Web application deployment
• Credits and acknowledgements
• Contact

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 web applications.

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:

Installation

Vuegen is available on PyPI and can be installed using pip:

pip install vuegen

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

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.

Quarto installation

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.

Execution

Run VueGen using a directory with the following command:

vuegen --directory 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.

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

vuegen --config example_data/Earth_microbiome_vuegen_demo_notebook/Earth_microbiome_vuegen_demo_notebook_config.yaml --report_type streamlit

The current report types supported by VueGen are:

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

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.

🔗

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] An HTML report example of the current vuegen release is available here.

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.

Credits and acknowledgements

• Vuegen was developed by the Multiomics Network Analytics Group (MoNA) at the Novo Nordisk Foundation Center for Biosustainability (DTU Biosustain).
• 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.

Contact

If you have comments or suggestions about this project, you can open an issue in this repository.