diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index ec8245a..e787663 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -35,10 +35,11 @@ jobs: run: | cd docs sphinx-build -n --keep-going -b html ./ ./_build/ + # --- HTML example deployment --- - name: Rename entry point of report to index.html run: | mv docs/quarto_report/quarto_report.html docs/quarto_report/index.html - - name: Publish html report to github pages + - name: Publish HTML report to GitHub Pages (gh-pages branch) # Only publish a new static report upon a new release -> can be changed. if: startsWith(github.ref, 'refs/tags') uses: peaceiris/actions-gh-pages@v4 @@ -50,3 +51,14 @@ jobs: # with: # name: Sphinx_${{ matrix.python-version }} # path: docs/_build/ + + # --- Streamlit example deployment --- + - name: Fix Absolute Paths in Streamlit Scripts + run: | + find docs/streamlit_report/sections -type f -name "*.py" -exec sed -i 's|/home/runner/work/vuegen/vuegen/docs/||g' {} + + - name: Publish Streamlit report to streamlit-example branch + uses: peaceiris/actions-gh-pages@v4 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: docs/ + publish_branch: streamlit-report-example \ No newline at end of file diff --git a/README.md b/README.md index bb83be3..150ea02 100644 --- a/README.md +++ b/README.md @@ -1,25 +1,24 @@ - ![VueGen Logo](https://raw.githubusercontent.com/Multiomics-Analytics-Group/vuegen/main/docs/images/vuegen_logo.svg) -----------------

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

| Information | Links | | :--- | :--- | -| **Package** |[ ![PyPI Latest Release](https://img.shields.io/pypi/v/vuegen.svg)](https://pypi.org/project/vuegen/) [![Supported versions](https://img.shields.io/pypi/pyversions/vuegen.svg)](https://pypi.org/project/vuegen/)| -| **Documentation** | [![Docs](https://readthedocs.org/projects/vuegen/badge/?style=flat)](https://vuegen.readthedocs.io/)| -| **Build** | [![CI](https://github.com/Multiomics-Analytics-Group/vuegen/actions/workflows/cdci.yml/badge.svg)](https://github.com/Multiomics-Analytics-Group/vuegen/actions/workflows/cdci.yml) [![Docs](https://github.com/Multiomics-Analytics-Group/vuegen/actions/workflows/docs.yml/badge.svg)](https://github.com/Multiomics-Analytics-Group/vuegen/actions/workflows/docs.yml)| -| **Examples** | [![HTML5](https://img.shields.io/badge/html5-%23E34F26.svg?style=for-the-badge&logo=html5&logoColor=white)](https://multiomics-analytics-group.github.io/vuegen/) [![Streamlit](https://img.shields.io/badge/Streamlit-%23FE4B4B.svg?style=for-the-badge&logo=streamlit&logoColor=white)](https://multiomics-analytics-group.github.io/vuegen/)| -| **Discuss on GitHub** | [![GitHub issues](https://img.shields.io/github/issues/Multiomics-Analytics-Group/vuegen)](https://github.com/Multiomics-Analytics-Group/vuegen/issues) [![GitHub pull requests](https://img.shields.io/github/issues-pr/Multiomics-Analytics-Group/vuegen)](https://github.com/Multiomics-Analytics-Group/vuegen/pulls) | +| **Package** |[ ![PyPI Latest Release](https://img.shields.io/pypi/v/vuegen.svg)][vuegen-pypi] [![Supported versions](https://img.shields.io/pypi/pyversions/vuegen.svg)][vuegen-pypi]| +| **Documentation** | [![Docs](https://readthedocs.org/projects/vuegen/badge/?style=flat)][vuegen-docs]| +| **Build** | [![CI](https://github.com/Multiomics-Analytics-Group/vuegen/actions/workflows/cdci.yml/badge.svg)][ci-gh-action] [![Docs](https://github.com/Multiomics-Analytics-Group/vuegen/actions/workflows/docs.yml/badge.svg)][ci-docs]| +| **Examples** | [![HTML5](https://img.shields.io/badge/html5-%23E34F26.svg?style=for-the-badge&logo=html5&logoColor=white)][emp-html-demo] [![Streamlit](https://img.shields.io/badge/Streamlit-%23FE4B4B.svg?style=for-the-badge&logo=streamlit&logoColor=white)][emp-st-demo]| +| **Discuss on GitHub** | [![GitHub issues](https://img.shields.io/github/issues/Multiomics-Analytics-Group/vuegen)][issues] [![GitHub pull requests](https://img.shields.io/github/issues-pr/Multiomics-Analytics-Group/vuegen)][pulls]| ## Table of contents: - [About the project](#about-the-project) - [Installation](#installation) - [Execution](#execution) -- [Acknowledgements](#acknowledgements) +- [Case studies](#case-studies) +- [Web application deployment](#web-application-deployment) +- [Credits and acknowledgements](#credits-and-acknowledgements) - [Contact](#contact) ## About the project @@ -29,25 +28,13 @@ The configuration file specifies the structure of the report, including sections An overview of the VueGen workflow is shown in the figure below: - ![VueGen Abstract](https://raw.githubusercontent.com/Multiomics-Analytics-Group/vuegen/main/docs/images/vuegen_graph_abstract.png) Also, the class diagram for the project is presented below to illustrate the architecture and relationships between classes: - - ![VueGen Class Diagram](https://raw.githubusercontent.com/Multiomics-Analytics-Group/vuegen/main/docs/images/vuegen_classdiagram_noattmeth.png) ## Installation - Vuegen is available on [PyPI][vuegen-pypi] and can be installed using pip: ```bash @@ -61,28 +48,28 @@ pip install -e path/to/vuegen # specify location pip install -e . # in case your pwd is in the vuegen directory ``` -### Quarto 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`. +### Quarto installation 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 quarto check ``` -If quarto is not installed, you can download the command-line interface from the [Quarto website][quarto-cli] for your operating system. +> [!TIP] +> If quarto is not installed, you can download the command-line interface from the [Quarto website][quarto-cli] for your operating system. ## Execution - Run VueGen using a directory with the following command: ```bash -cd docs vuegen --directory example_data/Earth_microbiome_vuegen_demo_notebook --report_type streamlit ``` -> ๐Ÿ’ก If `vuegen` does not work, try `python -m vuegen` instead. - -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. +> [!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: @@ -100,8 +87,34 @@ The current report types supported by VueGen are: * PPTX * Jupyter -## Acknowledgements +## 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. + +๐Ÿ”— [![Open in Colab][colab_badge]][colab_link_intro_demo] + +**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)][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. + +๐Ÿ”— [![Open in Colab][colab_badge]][colab_link_emp_demo] + +> [!NOTE] +> An HTML report example of the current vuegen release is available [here][emp-html-demo]. + +## 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. +* **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][st-forum-exe]. +* [Stlite][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)][Mona] at the [Novo Nordisk Foundation Center for Biosustainability (DTU Biosustain)][Biosustain]. - 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]. @@ -110,14 +123,28 @@ If you have comments or suggestions about this project, you can [open an issue][ [streamlit]: https://streamlit.io/ [vuegen-pypi]: https://pypi.org/project/vuegen/ +[vuegen-docs]: https://vuegen.readthedocs.io/ +[ci-gh-action]: https://github.com/Multiomics-Analytics-Group/vuegen/actions/workflows/cdci.yml +[ci-docs]: https://github.com/Multiomics-Analytics-Group/vuegen/actions/workflows/docs.yml +[emp-html-demo]: https://multiomics-analytics-group.github.io/vuegen/ +[emp-st-demo]: https://earth-microbiome-vuegen-demo.streamlit.app/ +[issues]: https://github.com/Multiomics-Analytics-Group/vuegen/issues +[pulls]: https://github.com/Multiomics-Analytics-Group/vuegen/pulls [quarto]: https://quarto.org/ [quarto-cli-pypi]: https://pypi.org/project/quarto-cli/ [quarto-cli]: https://quarto.org/docs/get-started/ +[colab_badge]: https://colab.research.google.com/assets/colab-badge.svg +[colab_link_intro_demo]: https://colab.research.google.com/github/Multiomics-Analytics-Group/vuegen/blob/main/docs/vuegen_basic_case_study.ipynb +[colab_link_emp_demo]: https://colab.research.google.com/github/Multiomics-Analytics-Group/vuegen/blob/main/docs/vuegen_case_study_earth_microbiome.ipynb +[emp]: https://earthmicrobiome.org/ +[st-cloud]: https://streamlit.io/cloud +[stlite]: https://github.com/whitphx/stlite +[st-forum-exe]: https://discuss.streamlit.io/t/streamlit-deployment-as-an-executable-file-exe-for-windows-macos-and-android/6812 [Mona]: https://multiomics-analytics-group.github.io/ [Biosustain]: https://www.biosustain.dtu.dk/ [scriberia]: https://www.scriberia.co.uk/ [turingway]: https://github.com/the-turing-way/the-turing-way [zenodo-turingway]: https://zenodo.org/records/3695300 -[issues]: https://github.com/Multiomics-Analytics-Group/vuegen/issues/new +[new-issue]: https://github.com/Multiomics-Analytics-Group/vuegen/issues/new diff --git a/docs/images/vuegen_logo.png b/docs/images/vuegen_logo.png index 5fdc22b..17abb65 100644 Binary files a/docs/images/vuegen_logo.png and b/docs/images/vuegen_logo.png differ diff --git a/docs/images/vuegen_logo.svg b/docs/images/vuegen_logo.svg index dbb3316..76e2964 100644 --- a/docs/images/vuegen_logo.svg +++ b/docs/images/vuegen_logo.svg @@ -11,8 +11,8 @@ sodipodi:docname="vuegen_logo.svg" inkscape:version="1.3.2 (091e20e, 2023-11-25)" inkscape:export-filename="vuegen_logo.png" - inkscape:export-xdpi="192" - inkscape:export-ydpi="192" + inkscape:export-xdpi="278.23743" + inkscape:export-ydpi="278.23743" width="350" height="300" xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" @@ -28,14 +28,14 @@ inkscape:pageopacity="0.0" inkscape:pagecheckerboard="0" inkscape:deskcolor="#d1d1d1" - inkscape:zoom="1.2685346" - inkscape:cx="217.17973" - inkscape:cy="131.25381" - inkscape:window-width="1200" - inkscape:window-height="932" - inkscape:window-x="1200" + inkscape:zoom="3.5879577" + inkscape:cx="220.18097" + inkscape:cy="229.3784" + inkscape:window-width="1920" + inkscape:window-height="1027" + inkscape:window-x="1440" inkscape:window-y="25" - inkscape:window-maximized="0" + inkscape:window-maximized="1" inkscape:current-layer="g7" showgrid="true" inkscape:document-units="mm">VueGen