Execution

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 the VueGen’s GitHub 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. You can also specify the output directory with the --output_directory argumument, which defaults to the current working directory. See all available arguments with the --help option.

Folder structure#

Your input directory should 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). If the component files are in the first-level folders, an overview subsection will be created automatically.

Here is an example layout:

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

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.

Configuration file#

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 component paths in the configuration file can be absolute or relative to the execution directory. In the examples, we assume that the working directory is the docs folder, so the paths are relative to it. If you run VueGen from another directory, you need to adjust the paths accordingly.

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

Running VueGen with Nextflow and nf-core#

To run VueGen as a nf-core module, you should create a Nextflow pipeline and include the VueGen module in your workflow. Here is a main.nf example:

#!/usr/bin/env nextflow
include { VUEGEN } from './modules/nf-core/vuegen/'

workflow {
    // Create a channel for the report type
    report_type_ch = Channel.value(params.report_type)

    // Handle configuration file and directory inputs
    if (params.config) {
        file_ch = Channel.fromPath(params.config)
        input_type_ch = Channel.value('config')
        output_ch = VUEGEN(input_type_ch, file_ch, report_type_ch)

    } else if (params.directory) {
        dir_ch = Channel.fromPath(params.directory, type: 'dir', followLinks: true)
        input_type_ch = Channel.value('directory')
        output_ch = VUEGEN(input_type_ch, dir_ch, report_type_ch)

    }
}

You can run the pipeline with the following command:

nextflow run main.nf --directory docs/example_data/Basic_example_vuegen_demo_notebook --report_type html

Note

You can read the offical documentation for the nf-core module here. Also, the source code and additional details are available in the nf-VueGen repository.

Contents