✨ Feat: Add scripts, test, and example for bar plot (#26)

* ✨ Feat(schemas(bar.py): Create Pydantic schema of the bar plot

* ✨ Feat(vuecore/engines/plotly/bar.py): Create script with build function for bar plot

* ✨ Feat(vuecore/engines/plotly/theming.py): Add apply_bar_theme to the script, and include samll fixes on other bar plot scripts

* ✨ Feat(vuecore/engines/plotly/__init__.py): Register bar builder and add it to the PlotType StrEnum

* ✨ Feat(vuecore/plots/bar.py): Create script with the user-facing function for bar plot, and update docstrings from line and scatter

* ✨ Feat(docs/api_examples/bar_plot.ipynb): Create notebook api example for bar plot, and modify theming and bar plot scripts to correct small bugs

* 🎨 Rename variables and use Path insetad of os in all api example notebooks

* ✨ Feat(docs/api_examples/bar_plot.py): Create python script synced from notebook for bar plot and update the others

* 📝 Docs: update index.md to add bar plot exmaple

* ✨ Feat(tests/test_barplot.py): Create bar plot test

* 🐛 Fix(vuecore/engines/plotly/saver.py): Add JSON format to the possible outputs

* 🎨 Improve comments, docstrings, and type annotations of test scripts

* 🎨 Remove ploty renderer from api examples and improve var bnames on the scatter examples

* 🐛 Reformat scatter api examples to the main version to avoid merge conflicts

* 🐛 Aplly black format

* 🎨 Improve comments and var names of the sactter api example files

Author: sayalaruano

docs/api_examples/bar_plot.ipynb

@@ -0,0 +1,209 @@
+# ---
+# jupyter:
+#   jupytext:
+#     text_representation:
+#       extension: .py
+#       format_name: percent
+#       format_version: '1.3'
+#       jupytext_version: 1.17.2
+#   kernelspec:
+#     display_name: vuecore-dev
+#     language: python
+#     name: python3
+# ---
+
+# %% [markdown]
+# # Bar Plot
+#
+# ![VueCore logo][vuecore_logo]
+#
+# [![Open In Colab][colab_badge]][colab_link]
+#
+# [VueCore][vuecore_repo] is a Python package for creating interactive and static visualizations of multi-omics data.
+# It is part of a broader ecosystem of tools—including [ACore][acore_repo] for data processing and [VueGen][vuegen_repo] for automated reporting—that together enable end-to-end workflows for omics analysis.
+#
+# This notebook demonstrates how to generate bar plots using plotting functions from VueCore. We showcase basic and advanced plot configurations, highlighting key customization options such as grouping, color mapping, text annotations, and export to multiple file formats.
+#
+# ## Notebook structure
+#
+# First, we will set up the work environment by installing the necessary packages and importing the required libraries. Next, we will create basic and advanced bar plots.
+#
+# 0. [Work environment setup](#0-work-environment-setup)
+# 1. [Basic bar plot](#1-basic-bar-plot)
+# 2. [Advanced bar plot](#2-advanced-bar-plot)
+#
+# ## Credits and Contributors
+# - This notebook was created by Sebastián Ayala-Ruano under the supervision of Henry Webel and Alberto Santos, head of the [Multiomics Network Analytics Group (MoNA)][Mona] at the [Novo Nordisk Foundation Center for Biosustainability (DTU Biosustain)][Biosustain].
+# - You can find more details about the project in this [GitHub repository][vuecore_repo].
+#
+# [colab_badge]: https://colab.research.google.com/assets/colab-badge.svg
+# [colab_link]: https://colab.research.google.com/github/Multiomics-Analytics-Group/vuecore/blob/main/docs/api_examples/bar_plot.ipynb
+# [vuecore_logo]: https://raw.githubusercontent.com/Multiomics-Analytics-Group/vuecore/main/docs/images/logo/vuecore_logo.svg
+# [Mona]: https://multiomics-analytics-group.github.io/
+# [Biosustain]: https://www.biosustain.dtu.dk/
+# [vuecore_repo]: https://github.com/Multiomics-Analytics-Group/vuecore
+# [vuegen_repo]: https://github.com/Multiomics-Analytics-Group/vuegen
+# [acore_repo]: https://github.com/Multiomics-Analytics-Group/acore
+
+# %% [markdown]
+# ## 0. Work environment setup
+
+# %% [markdown]
+# ### 0.1. Installing libraries and creating global variables for platform and working directory
+#
+# To run this notebook locally, you should create a virtual environment with the required libraries. If you are running this notebook on Google Colab, everything should be set.
+
+# %% tags=["hide-output"]
+# VueCore library
+# %pip install vuecore
+
+# %% tags=["hide-cell"]
+import os
+
+IN_COLAB = "COLAB_GPU" in os.environ
+
+# %% tags=["hide-cell"]
+# Create a directory for outputs
+output_dir = "./outputs"
+os.makedirs(output_dir, exist_ok=True)
+
+# %% [markdown]
+# ### 0.2. Importing libraries
+
+# %%
+# Imports
+import pandas as pd
+import numpy as np
+from pathlib import Path
+
+from vuecore.plots.basic.bar import create_bar_plot
+
+# %% [markdown]
+# ### 0.3. Create sample data
+# We create a synthetic dataset representing the relative abundances of common bacterial genera across various environmental samples.
+
+# %%
+# Set a random seed for reproducibility of the synthetic data
+np.random.seed(42)
+
+# Sample types and bacterial genera
+sample_types = ["Soil", "Freshwater", "Ocean", "Sediment", "Wastewater"]
+genera = [
+    "Pseudomonas",
+    "Bacillus",
+    "Escherichia",
+    "Streptococcus",
+    "Lactobacillus",
+    "Bacteroides",
+    "Clostridium",
+    "Staphylococcus",
+    "Enterobacter",
+    "Klebsiella",
+    "Salmonella",
+    "Shigella",
+    "Vibrio",
+]
+
+
+def make_sample(sample: str, genera: list[str]) -> list[dict]:
+    """
+    Generate synthetic microbial abundance data for a single sample.
+
+    Parameters
+    ----------
+    sample : str
+        The sample type (e.g., 'Soil', 'Ocean', etc).
+    genera : list[str]
+        List of all possible bacterial genera.
+
+    Returns
+    -------
+    list[dict]
+        A list of dictionaries, each containing: Sample name, Genus,
+        Relative abundance, and Genera count.
+    """
+    # Randomly pick a subset of genera present in this sample
+    selected = np.random.choice(
+        genera, np.random.randint(5, len(genera) + 1), replace=False
+    )
+
+    # Generate random raw abundances (shifted by +0.1 to avoid zeros)
+    raw = np.random.rand(len(selected)) + 0.1
+
+    # Normalize abundances so they sum to exactly 100%
+    abundances = (raw / raw.sum()) * 100
+
+    # Count how many genera are present
+    genera_count = len(selected)
+
+    # Store results into list of dicts
+    return [
+        {
+            "Sample": sample,
+            "Genus": genus,
+            "Relative_Abundance": abund,
+            "Genera_Count": genera_count,
+        }
+        for genus, abund in zip(selected, abundances)
+    ]
+
+
+# Generate full dataset by combining all samples
+abund_df = pd.DataFrame(
+    [row for sample in sample_types for row in make_sample(sample, genera)]
+)
+abund_df.head()
+
+# %% [markdown]
+# ## 1. Basic Bar Plot
+# A basic bar plot can be created by simply providing the `x` and `y` columns from the DataFrame, along with style options like `title`.
+
+# %%
+# Create a df with unique samples and their genera counts
+bar_plot_basic_df = abund_df.drop_duplicates(subset="Sample")[
+    ["Sample", "Genera_Count"]
+]
+
+# Define output path for the basic png plot
+file_path_basic_png = Path(output_dir) / "bar_plot_basic.png"
+
+# Generate the basic bar plot
+bar_plot_basic = create_bar_plot(
+    data=bar_plot_basic_df,
+    x="Sample",
+    y="Genera_Count",
+    title="Genera Count by Sample Type",
+    file_path=file_path_basic_png,
+)
+
+bar_plot_basic.show()
+
+# %% [markdown]
+# ## 2. Advanced Bar Plot
+# Here is an example of an advanced `stacked bar plot` with more descriptive parameters, including `color grouping`, `text annotations`, `hover tooltips`, and export to `HTML`.
+
+# %%
+# Define the output file path for the HTML plot
+file_path_adv_html = Path(output_dir) / "bar_plot_advanced.html"
+
+# Generate the advanced stacked bar plot
+bar_plot_adv = create_bar_plot(
+    data=abund_df,
+    x="Sample",
+    y="Relative_Abundance",
+    color="Genus",
+    barmode="stack",
+    title="Taxonomic Profile of Environmental Samples",
+    subtitle="Relative Abundance of Bacterial Genera",
+    labels={
+        "Sample": "Environmental Sample Type",
+        "Relative_Abundance": "Relative Abundance (%)",
+        "Genus": "Genus",
+    },
+    hover_name="Genus",
+    hover_data=["Relative_Abundance"],
+    opacity=0.9,
+    file_path=file_path_adv_html,
+)
+
+bar_plot_adv.show()

docs/api_examples/bar_plot.py

@@ -74,13 +74,10 @@
 # %%
 # Imports
 import pandas as pd
-import plotly.io as pio
+from pathlib import Path
 
 from vuecore.plots.basic.line import create_line_plot
 
-# Set the Plotly renderer based on the environment
-pio.renderers.default = "notebook"
-
 # %% [markdown]
 # ### 0.3. Create sample data
 # We create a synthetic dataset showing measurements over five days for two experiments (A, B), each tested under Control and Treatment conditions, with associated measurement errors.
@@ -145,11 +142,11 @@
 # A basic line plot can be created by simply providing the `x`, `y`, and `color` columns from the DataFrame.
 
 # %%
-# Define output path
-file_path_basic_png = os.path.join(output_dir, "line_plot_basic.png")
+# Define output path for the basic png plot
+file_path_basic_png = Path(output_dir) / "line_plot_basic.png"
 
-# Generate basic plot
-fig = create_line_plot(
+# Generate the basic bar plot
+line_plot_basic = create_line_plot(
     data=sample_df,
     x="day",
     y="value",
@@ -158,18 +155,18 @@
     file_path=file_path_basic_png,
 )
 
-fig.show()
+line_plot_basic.show()
 
 # %% [markdown]
 # ## 2. Advanced Line Plot
-# Here is an example of an advanced line plot with more descriptive parameters, including error bars, line styles, markers, and custom colors.
+# Here is an example of an advanced line plot with more descriptive parameters, including `error bars`, `line styles`, `markers`, and `custom colors`.
 
 # %%
-# Define output path
-file_path_adv_html = os.path.join(output_dir, "line_plot_advanced.html")
+# Define output file path for the HTML plot
+file_path_adv_html = Path(output_dir) / "line_plot_advanced.html"
 
-# Generate advanced plot
-fig_advanced = create_line_plot(
+# Generate advanced line plot
+line_plot_adv = create_line_plot(
     data=sample_df,
     x="day",
     y="value",
@@ -191,4 +188,4 @@
     file_path=file_path_adv_html,
 )
 
-fig_advanced.show()
+line_plot_adv.show()

docs/api_examples/line_plot.ipynb

@@ -286,13 +286,14 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 3,
+   "execution_count": null,
    "id": "06dbf6a2",
    "metadata": {},
    "outputs": [],
    "source": [
     "# Imports\n",
     "import pandas as pd\n",
+    "from pathlib import Path\n",
     "\n",
     "from vuecore.plots.basic.scatter import create_scatter_plot"
    ]
@@ -480,7 +481,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 5,
+   "execution_count": null,
    "id": "d0d34455",
    "metadata": {},
    "outputs": [
@@ -4418,19 +4419,19 @@
     }
    ],
    "source": [
-    "# Define output path\n",
-    "file_path_png = os.path.join(output_dir, \"scatter_basic.png\")\n",
+    "# Define output path for the basic png plot\n",
+    "file_path_basic_png = Path(output_dir) / \"scatter_basic.png\"\n",
     "\n",
-    "# Generate basic plot\n",
-    "fig = create_scatter_plot(\n",
+    "# Generate the basic scatter plot\n",
+    "scatter_plot_basic = create_scatter_plot(\n",
     "    data=sample_df,\n",
     "    x=\"gene_expression\",\n",
     "    y=\"log_p_value\",\n",
     "    title=\"Basic Gene Expression Scatter Plot\",\n",
-    "    file_path=file_path_png,\n",
+    "    file_path=file_path_basic_png,\n",
     ")\n",
     "\n",
-    "fig.show()"
+    "scatter_plot_basic.show()"
    ]
   },
   {
@@ -4444,7 +4445,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 7,
+   "execution_count": null,
    "id": "f9307e85",
    "metadata": {},
    "outputs": [
@@ -4490,11 +4491,11 @@
     }
    ],
    "source": [
-    "# Define output path\n",
-    "file_path_adv_html = os.path.join(output_dir, \"scatter_advanced.html\")\n",
+    "# Define output file path for the HTML plot\n",
+    "file_path_adv_html = Path(output_dir) / \"scatter_advanced.html\"\n",
     "\n",
-    "# Generate advanced plot\n",
-    "fig_advanced = create_scatter_plot(\n",
+    "# Generate advanced line plot\n",
+    "scatter_plot_adv = create_scatter_plot(\n",
     "    data=sample_df,\n",
     "    x=\"gene_expression\",\n",
     "    y=\"log_p_value\",\n",
@@ -4519,7 +4520,7 @@
     "    file_path=file_path_adv_html,\n",
     ")\n",
     "\n",
-    "fig_advanced.show()"
+    "scatter_plot_adv.show()"
    ]
   }
  ],