♻️ Refactor vuecore library with an initial example for scatter plot

This structure would enable the support of various backend engines and separate the validation, style, and building logic for the plots.

Here is a diagram of the proposed project structure:

```
vuecore/
├── __init__.py
├── constants.py         # Defines global enums and constants (e.g., plot types)
├── engines/             # Manages all plotting backends
│   ├── __init__.py      # Engine registry and loading logic
│   ├── plotly/             
│   │   ├── __init__.py  # Registers Plotly engine components
│   │   ├── saver.py     # Functions to save Plotly figures
│   │   ├── theming.py   # Applies styles and themes to Plotly figures
│   │   ├── scatter.py   # Generates plotly scatter plots from data and config
│   │   └── ... 
├── plots/               # User-facing API
│   ├── basic/       
│   │   ├── scatter.py   # Creates scatter plots using schemas and engines
│   │   └── ...
│   ├── .../        
├── schemas/             # Pydantic models for validating plot configurations
│   ├── distribution/          
│   │   ├── scatter.py  
│   │   └── ...
├── utils/               # Helper functions shared across the project
│   ├── statistics.py           
│   ├── validation.py    # Custom validation logic beyond Pydantic 
└── ...
tests/
├── test_scatter.py      # Unit and integration tests for scatter plot generation
└── ...
```

Also, here is the workflow:

```
User Code
    │
    ▼
plots/distribution/scatter.py             # "Create scatter plot"
    │
    │ Uses
    ├──► schemas/distribution/scatter.py  # Pydantic validation
    │                        │
    │                        └──► utils/validation.py    # Custom validation
    │
    │ Uses
    ├──► constants.py                     # Access plot types, engine types, etc.
    │
    │ Selects engine:
    ▼
engines/plotly/scatter.py       # Generate Plotly scatter plot from data + config
    │
    │ Uses
    ├──► engines/plotly/theming.py        # Apply theming
    │
    │ Uses
    ├──► utils/statistics.py              # Support for transformations, etc
    │
    │ Uses
    ▼
engines/plotly/saver.py              # Save plot (e.g., as PNG/HTML/JSON)
```

Author: sayalaruano

.gitignore

@@ -161,3 +161,8 @@ cython_debug/
 
 # VSCode
 *DS_Store
+
+# Tests
+test_results/
+docs/api_examples/outputs/
+docs/api_examples/iframe_figures/

.readthedocs.yaml

@@ -10,8 +10,19 @@ build:
   os: ubuntu-22.04
   tools:
     python: "3.12"
-  # apt_packages:
-  #  - some-package
+  apt_packages:
+    - libnss3
+    - libatk-bridge2.0-0
+    - libcups2
+    - libxcomposite1
+    - libxdamage1
+    - libxfixes3
+    - libxrandr2
+    - libgbm1
+    - libxkbcommon0
+    - libpango-1.0-0
+    - libcairo2
+    - libasound2
 
 # Build documentation in the "docs/" directory with Sphinx
 sphinx:

docs/.gitignore

@@ -4,5 +4,5 @@ reference
 _build
 jupyter_execute
 
-# VS Code
-.DS_Store
+# VsCode
+*.DS_Store

docs/api_examples/scatter_plot.ipynb

@@ -0,0 +1,116 @@
+"""
+Title: Scatter Plot Examples using VueCore
+Description:
+    This script demonstrates how to generate scatter plots using VueCore — a Python package for creating
+    interactive and static visualizations of multi-omics data. It is part of an ecosystem including ACore
+    for data processing and VueGen for automated reporting.
+
+    We showcase basic and advanced plot configurations, highlighting customization options such as grouping,
+    color mapping, annotations, and export to multiple formats.
+
+Script Structure:
+    0. Work environment setup
+    1. Basic scatter plot
+    2. Advanced scatter plot
+
+Authors:
+    Sebastián Ayala-Ruano
+Supervisors:
+    Henry Webel, Alberto Santos (Multiomics Network Analytics Group, DTU Biosustain)
+
+Institution:
+    Multiomics Network Analytics Group (MoNA),
+    Novo Nordisk Foundation Center for Biosustainability (DTU Biosustain)
+
+Project Repository:
+    https://github.com/Multiomics-Analytics-Group/vuecore
+
+License:
+    MIT License
+
+Created: 2025-06-25
+Last Updated: 2025-06-25
+"""
+
+# %%
+# 0. Work environment setup
+# 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.
+# pip install vuecore
+
+# 0.2. Importing libraries
+import os
+import pandas as pd
+import plotly.io as pio
+from vuecore.plots.basic.scatter import create_scatter_plot
+
+# Set the Plotly renderer based on the environment, default to notebook, but you can change it
+# to "browser" if you do not want to use jupyter widgets.
+pio.renderers.default = "notebook"
+
+# 0.3. Create a directory for outputs
+output_dir = "./outputs"
+os.makedirs(output_dir, exist_ok=True)
+
+# %%
+# 1. Basic Scatter Plot
+# Created sample data
+sample_df = pd.DataFrame(
+    {
+        "gene_expression": [1.2, 2.5, 3.1, 4.5, 5.2, 6.8, 3.9, 2.1],
+        "log_p_value": [0.5, 1.5, 2.0, 3.5, 4.0, 5.5, 1.8, 0.9],
+        "regulation": ["Up", "Up", "None", "Down", "Down", "Down", "None", "Up"],
+        "significance_score": [10, 20, 5, 40, 55, 80, 15, 25],
+        "gene_name": [
+            "GENE_A",
+            "GENE_B",
+            "GENE_C",
+            "GENE_D",
+            "GENE_E",
+            "GENE_F",
+            "GENE_G",
+            "GENE_H",
+        ],
+        "cell_type": ["A", "B", "A", "B", "A", "B", "A", "B"],
+    }
+)
+
+# Define output path
+file_path_png = os.path.join(output_dir, "scatter_basic.png")
+
+# Generate basic plot
+fig = create_scatter_plot(
+    data=sample_df,
+    x="gene_expression",
+    y="log_p_value",
+    file_path=file_path_png,
+)
+
+fig.show()
+
+# %%
+# 2. Advanced Scatter Plot
+# Define output path
+file_path_adv_html = os.path.join(output_dir, "scatter_advanced.html")
+
+# Generate advanced plot
+fig_advanced = create_scatter_plot(
+    data=sample_df,
+    x="gene_expression",
+    y="log_p_value",
+    group="regulation",
+    size="significance_score",
+    text="gene_name",
+    title="Advanced Gene Expression Plot",
+    x_title="Log2 Fold Change",
+    y_title="-Log10(P-value)",
+    colors={"Up": "#FF5733", "Down": "#3380FF", "None": "#33FF57"},
+    marker_opacity=0.8,
+    marker_line_width=1,
+    marker_line_color="darkgray",
+    width=900,
+    height=600,
+    file_path=file_path_adv_html,
+)
+
+fig_advanced.show()

docs/api_examples/scatter_plot.py

@@ -7,17 +7,24 @@
 :relative-images:
 ```
 
+```{toctree}
+:maxdepth: 1
+:caption: API Usage Examples
+
+api_examples/scatter_plot
+```
+
 ```{toctree}
 :maxdepth: 2
-:caption: Modules
+:caption: API Reference
 :hidden:
 
 reference/vuecore
 ```
 
 ```{toctree}
 :maxdepth: 1
-:caption: MISC:
+:caption: Extra Materials
 :hidden:
 
 README.md

docs/index.md

@@ -37,6 +37,8 @@ dependencies = [
     "webweb",
     "acore",
     "dash-cytoscape",
+    "pydantic",
+    "nbformat>=4.2.0",
 ]
 
 [project.optional-dependencies]

pyproject.toml

@@ -17,6 +17,10 @@
 import numpy as np
 import pandas as pd
 
+from .constants import PlotType, EngineType
+
+__all__ = ["PlotType", "EngineType"]
+
 plt.rcParams["figure.figsize"] = [4.0, 3.0]
 plt.rcParams["pdf.fonttype"] = 42
 plt.rcParams["ps.fonttype"] = 42

src/vuecore/__init__.py

@@ -0,0 +1,17 @@
+from enum import auto
+
+try:
+    from enum import StrEnum
+except ImportError:
+    from strenum import StrEnum
+
+
+class PlotType(StrEnum):
+    SCATTER = auto()
+    LINE = auto()
+    # Add other plot types as needed
+
+
+class EngineType(StrEnum):
+    PLOTLY = auto()
+    # Add other engines as needed

src/vuecore/constants.py

@@ -0,0 +1,8 @@
+from vuecore.engines.registry import get_builder, get_saver
+
+# Import the engine modules to trigger their registration
+from . import plotly  # noqa: F401, E402
+
+# from . import matplotlib # This is where you'd add a new engine
+
+__all__ = ["get_builder", "get_saver"]