You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+9-8Lines changed: 9 additions & 8 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -27,16 +27,17 @@ you to share any suggestions or observations you have about this project.
27
27
28
28
Here are the ways you can submit your suggestions and contribute to the project:
29
29
30
-
1.**Reporting Issues or Suggesting Improvements:** If you have a [GitHub][github] account
31
-
(or are willing to [open one][github-join]) but are unfamiliar with Git, you can report
32
-
bugs or suggest improvements by [creating an issue][new-issue]. This GitHub feature allows
33
-
for discussion threads on reported issues and proposed enhancements.
30
+
### 1. Reporting Issues or Suggesting Improvements
34
31
35
-
2.**Submitting Changes via Pull Requests:** If you are comfortable using Git and would like to
36
-
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.
32
+
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.
37
33
38
-
3.**Providing Feedback via Email:** If you don’t have a GitHub account and are
39
-
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.
34
+
### 2. Submitting Changes via Pull Requests
35
+
36
+
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.
37
+
38
+
### 3. Providing Feedback via Email
39
+
40
+
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.
40
41
41
42
> [!NOTE]
42
43
> The documentation for [Git][git-docs] and [GitHub][github-docs] are easy to follow, and you can learn the basics using their official guides.
|**Discuss on GitHub**|[][issues][][pulls]|
@@ -98,7 +98,7 @@ If you prefer not to install VueGen on your system, a pre-configured Docker cont
98
98
99
99
### Nextflow and nf-core
100
100
101
-
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].
101
+
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. You can read the offical documentation for the nf-core module[here](nf-vuegen-nf-core). Also, the source code and detailed documentation are available in the [nf-VueGen repository][nf-vuegen].
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).
120
120
121
121
Here is an example layout:
122
+
122
123
```
123
124
report_folder/
124
125
├── section1/
@@ -138,7 +139,7 @@ report_folder/
138
139
> [!WARNING]
139
140
> 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.
140
141
141
-
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.
142
+
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.
142
143
The order of sections, subsections, and components can be defined using numerical suffixes in folder and file names.
143
144
144
145
It's also possible to provide a configuration file instead of a directory:
@@ -206,6 +207,10 @@ from the releases page according to your operating system.
# in case you have errors, install vuegen addtionally
211
+
conda activate vuegen_gui
212
+
pip install vuegen
213
+
# list all conda environments to find the location of the environment
209
214
conda info -e # find environment location
210
215
```
211
216
@@ -233,7 +238,7 @@ More information regarding the app and builds can be found in the
233
238
234
239
VueGen’s functionality is demonstrated through two case studies:
235
240
236
-
**1. Predefined Directory**
241
+
### 1. Predefined Directory
237
242
238
243
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.
239
244
@@ -242,7 +247,7 @@ This introductory case study uses a predefined directory with plots, dataframes,
242
247
> [!NOTE]
243
248
> The [configuration file][predef-dir-config] is available in the `docs/example_config_files` folder, and the [directory][predef-dir] with example data is in the `docs/example_data` folder.
244
249
245
-
**2. Earth Microbiome Project Data**
250
+
### 2. Earth Microbiome Project Data
246
251
247
252
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.
248
253
@@ -252,30 +257,32 @@ This advanced case study demonstrates the application of VueGen in a real-world
252
257
> The EMP case study is available online as [HTML][emp-html-demo] and [Streamlit][emp-st-demo] reports.
253
258
> The [configuration file][emp-config] is available in the `docs/example_config_files` folder, and the [directory][emp-dir] with example data is in the `docs/example_data` folder.
254
259
255
-
**3. ChatBot Component**
260
+
### 3. ChatBot Component
256
261
257
262
This case study highlights VueGen’s capability to embed a chatbot component into a report subsection,
258
-
enabling interactive conversations inside the report.
263
+
enabling interactive conversations inside the report. This component is streamlit-specific and is not
264
+
available for other report types.
265
+
259
266
260
267
Two API modes are supported:
261
268
262
269
-**Ollama-style streaming chat completion**
263
-
If a `model` parameter is specified in the config file, VueGen assumes the chatbot is using Ollama’s [/api/chat endpoint][ollama_chat].
264
-
Messages are handled as chat history, and the assistant responses are streamed in real time for a smooth and responsive experience.
265
-
This mode supports LLMs such as `llama3`, `deepsek`, or `mistral`.
270
+
If a `model` parameter is specified in the config file, VueGen assumes the chatbot is using Ollama’s [/api/chat endpoint][ollama_chat].
271
+
Messages are handled as chat history, and the assistant responses are streamed in real time for a smooth and responsive experience.
272
+
This mode supports LLMs such as `llama3`, `deepsek`, or `mistral`.
266
273
267
274
> [!TIP]
268
275
> See [Ollama’s website][ollama] for more details.
269
276
270
277
-**Standard prompt-response API**
271
-
If no `model` is provided, VueGen uses a simpler prompt-response flow.
272
-
A single prompt is sent to an endpoint, and a structured JSON object is expected in return.
273
-
Currently, the response can include:
278
+
If no `model` is provided, VueGen uses a simpler prompt-response flow.
279
+
A single prompt is sent to an endpoint, and a structured JSON object is expected in return.
280
+
Currently, the response can include:
274
281
-`text`: the main textual reply
275
282
-`links`: a list of source URLs (optional)
276
283
-`HTML content`: an HTML snippet with a Pyvis network visualization (optional)
277
284
278
-
This response structure is currently customized for an internal knowledge graph assistant, but VueGen is being actively developed
285
+
This response structure is currently customized for an internal knowledge graph assistant, but VueGen is being actively developed
279
286
to support more flexible and general-purpose response formats in future releases.
280
287
281
288
> [!NOTE]
@@ -285,9 +292,17 @@ to support more flexible and general-purpose response formats in future releases
285
292
286
293
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:
287
294
288
-
-**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.
289
-
-**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].
290
-
-**Stlite**: Run Streamlit apps directly in the browser with [stlite][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.
295
+
### Streamlit Community Cloud
296
+
297
+
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.
298
+
299
+
### Standalone Executables
300
+
301
+
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].
302
+
303
+
### Stlite
304
+
305
+
Run Streamlit apps directly in the browser with [stlite][stlite_repo], 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.
291
306
292
307
These options provide flexibility depending on whether the goal is online accessibility, lightweight execution, or local application distribution.
293
308
@@ -352,6 +367,7 @@ We appreciate your feedback! If you have any comments, suggestions, or run into
0 commit comments