Refactor vuecore library with an initial example for scatter plot

.gitignore

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

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,235 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "640ba1d5",
+   "metadata": {},
+   "source": [
+    "# Scatter Plot Examples\n",
+    "\n",
+    "![VueCore logo][vuecore_logo]\n",
+    "\n",
+    "[![Open In Colab][colab_badge]][colab_link]\n",
+    "\n",
+    "[VueCore][vuecore_repo] is a Python package for creating interactive and static visualizations of multi-omics data. \n",
+    "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.\n",
+    "\n",
+    "This notebook demonstrates how to generate scatter plots using plotting functions from VueCore. We showcase basic and \n",
+    "advanced plot configurations, highlighting key customization options such as grouping, color mapping, text annotations, and export \n",
+    "to multiple file formats.\n",
+    "\n",
+    "## Notebook structure\n",
+    "\n",
+    "First, we will set up the work environment by installing the necessary packages and importing the required libraries. Next, we will create \n",
+    "basic and advanced scatter plots.\n",
+    "\n",
+    "0. [Work environment setup](#0-work-environment-setup)\n",
+    "1. [Basic scatter plot](#1-basic-scatter-plot)\n",
+    "2. [Advanced scatter plot](#2-advanced-scatter-plot)\n",
+    "\n",
+    "[colab_badge]: https://colab.research.google.com/assets/colab-badge.svg\n",
+    "[colab_link]: https://colab.research.google.com/github/Multiomics-Analytics-Group/vuecore/blob/main/docs/api_examples/scatter_plot.ipynb\n",
+    "[vuecore_logo]: https://raw.githubusercontent.com/Multiomics-Analytics-Group/vuecore/main/docs/images/logo/vuecore_logo.svg\n",
+    "[Mona]: https://multiomics-analytics-group.github.io/\n",
+    "[Biosustain]: https://www.biosustain.dtu.dk/\n",
+    "[vuecore_repo]: https://github.com/Multiomics-Analytics-Group/vuecore\n",
+    "[vuegen_repo]: https://github.com/Multiomics-Analytics-Group/vuegen\n",
+    "[acore_repo]: https://github.com/Multiomics-Analytics-Group/acore"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "3b504dfb",
+   "metadata": {},
+   "source": [
+    "## 0. Work environment setup"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "f0c056a7",
+   "metadata": {},
+   "source": [
+    "### 0.1. Installing libraries and creating global variables for platform and working directory\n",
+    "\n",
+    "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."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "36246ed6",
+   "metadata": {
+    "tags": [
+     "hide-output"
+    ]
+   },
+   "outputs": [],
+   "source": [
+    "# VueCore library\n",
+    "%pip install vuecore"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "963a9529",
+   "metadata": {
+    "tags": [
+     "hide-cell"
+    ]
+   },
+   "outputs": [],
+   "source": [
+    "import os\n",
+    "\n",
+    "IN_COLAB = \"COLAB_GPU\" in os.environ"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "ee2ffd40",
+   "metadata": {
+    "tags": [
+     "hide-cell"
+    ]
+   },
+   "outputs": [],
+   "source": [
+    "# Create a directory for outputs\n",
+    "output_dir = \"outputs\"\n",
+    "os.makedirs(output_dir, exist_ok=True)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "31638f9a",
+   "metadata": {},
+   "source": [
+    "### 0.2. Importing libraries"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "06dbf6a2",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Imports\n",
+    "import pandas as pd\n",
+    "from vuecore.plots.basic.scatter import  create_scatter_plot"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "ade445fe",
+   "metadata": {},
+   "source": [
+    "## 1. Basic Scatter Plot"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "19f0277d",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Created sample data\n",
+    "sample_df = pd.DataFrame({\n",
+    "    \"gene_expression\": [1.2, 2.5, 3.1, 4.5, 5.2, 6.8, 3.9, 2.1],\n",
+    "    \"log_p_value\": [0.5, 1.5, 2.0, 3.5, 4.0, 5.5, 1.8, 0.9],\n",
+    "    \"regulation\": [\"Up\", \"Up\", \"None\", \"Down\", \"Down\", \"Down\", \"None\", \"Up\"],\n",
+    "    \"significance_score\": [10, 20, 5, 40, 55, 80, 15, 25],\n",
+    "    \"gene_name\": [\"GENE_A\", \"GENE_B\", \"GENE_C\", \"GENE_D\", \"GENE_E\", \"GENE_F\", \"GENE_G\", \"GENE_H\"],\n",
+    "    \"cell_type\": [\"A\", \"B\", \"A\", \"B\", \"A\", \"B\", \"A\", \"B\"],\n",
+    "})\n",
+    "\n",
+    "# Define output path\n",
+    "file_path_png = os.path.join(output_dir, \"scatter_basic.png\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "d0d34455",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Generate basic plot\n",
+    "fig = create_scatter_plot(\n",
+    "    data=sample_df,\n",
+    "    x=\"gene_expression\",\n",
+    "    y=\"log_p_value\",\n",
+    "    file_path=file_path_png,\n",
+    ")\n",
+    "\n",
+    "fig.show()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "f5e16637",
+   "metadata": {},
+   "source": [
+    "## 2. Advanced Scatter Plot"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "f9307e85",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Define output path\n",
+    "file_path_adv_html = os.path.join(output_dir, \"scatter_advanced.html\")\n",
+    "\n",
+    "# Generate advanced plot\n",
+    "fig_advanced = create_scatter_plot(\n",
+    "    data=sample_df,\n",
+    "    x=\"gene_expression\",\n",
+    "    y=\"log_p_value\",\n",
+    "    group=\"regulation\",\n",
+    "    size=\"significance_score\",\n",
+    "    text=\"gene_name\",\n",
+    "    title=\"Advanced Gene Expression Plot\",\n",
+    "    x_title=\"Log2 Fold Change\",\n",
+    "    y_title=\"-Log10(P-value)\",\n",
+    "    colors={\"Up\": \"#FF5733\", \"Down\": \"#3380FF\", \"None\": \"#33FF57\"},\n",
+    "    marker_opacity=0.8,\n",
+    "    marker_line_width=1,\n",
+    "    marker_line_color=\"darkgray\",\n",
+    "    width=900,\n",
+    "    height=600,\n",
+    "    file_path=file_path_adv_html,\n",
+    ")\n",
+    "\n",
+    "fig_advanced.show()"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "vuecore-dev",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.12.11"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

pyproject.toml

@@ -37,6 +37,7 @@ dependencies = [
     "webweb",
     "acore",
     "dash-cytoscape",
+    "pydantic",
 ]
 
 [project.optional-dependencies]

src/vuecore/__init__.py

@@ -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/constants.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