From 41c8b944e9e2bc24be20fb86feba1cd4d6f6c0a3 Mon Sep 17 00:00:00 2001 From: sayalaruano Date: Thu, 18 Sep 2025 14:30:53 +0200 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Docs(src/vuecore/README.md):=20A?= =?UTF-8?q?dd=20Readme=20to=20explain=20the=20project=20structure=20and=20?= =?UTF-8?q?worflow?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- src/vuecore/README.md | 83 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 83 insertions(+) create mode 100644 src/vuecore/README.md diff --git a/src/vuecore/README.md b/src/vuecore/README.md new file mode 100644 index 0000000..721de58 --- /dev/null +++ b/src/vuecore/README.md @@ -0,0 +1,83 @@ +# VueCore: Project Structure and Workflow + +This file provides an overview of the directory structure and general workflow for VueCore. + +## Directory Structure + +VueCore is organized into several subpackages (a directory with an `__init__.py` file) +that serve to different purposes, including **user-facing API**, **plotting engines**, **data validation schemas**, and **general utilities**. Here is a brief overview of the main directories with files for the scatter plot example: + +``` +├── vuecore/ # The main source code package +│ ├── __init__.py # Package initialization +│ ├── constants.py # Global constants and enums (e.g., plot types, engine types) +│ ├── engines/ # Plotting backends (e.g., Plotly, Matplotlib) +│ │ ├── __init__.py # Manages engine registration and loading +│ │ └── plotly/ +│ │ ├── __init__.py # Registers Plotly engine +│ │ ├── saver.py # Functions for saving plots +│ │ ├── theming.py # Applies styles and themes +│ │ └── scatter.py # Generates Plotly scatter plots from a DataFrame and schema +│ ├── plots/ # User-facing API for creating plots +│ │ └── basic/ +│ │ └── scatter.py # User API for creating scatter plots +│ ├── schemas/ # Pydantic models for plot configuration validation +│ │ └── basic/ +│ │ └── scatter.py # Schema for scatter plot configuration +│ └── utils/ # Shared helper functions +│ │ ├── __init__.py +│ ├── statistics.py # Data transformation and statistical functions +│ └── doc_utils.py # Documentation utilities +├── tests/ # Unit and integration tests +│ └── test_scatter.py # Tests for the scatter plot functionality +└── docs/ # Documentation scripts and plot examples + └── api_examples/ +│ │ ├── scatter_plot.ipynb # Notebook demonstrating how to create scatter plots + └── scatter_plot.py # Script demonstrating how to create scatter plots +``` + +## Plot Generation Workflow + +The process for generating a plot in VueCore follows a clear, sequential path, ensuring data is validated and rendered efficiently: + +1. **User Interaction:** A user calls the main entry-point function from the `plots/` directory, for example, `plots.basic.scatter.create_scatter_plot`. They provide the data and any optional keyword arguments to define the plot's appearance. This can be done from any **Python script** or **Jupyter Notebook**, such as the examples provided in the `docs/api_examples` folder. +2. **Configuration Validation:** The function uses a **Pydantic schema** from the `schemas/` directory to validate the user's input. This step ensures all parameters are correctly typed and configured. +3. **Engine Selection:** The validated **configuration**, along with the **data** and chosen **engine** (e.g., Plotly), is passed to the `create_plot` factory function. This function selects the correct plotting engine and its corresponding `build` function. +4. **Plot Generation:** The engine's `build` function handles the steps of creating a plot: + + * It runs any necessary **preprocessing steps** (e.g., calculating density for color mapping). + * It calls the appropriate **plotting function** (e.g., `px.scatter`) to generate the initial figure. + * It applies **theming and styling** by calling a specific function (e.g., `apply_scatter_theme`). +5. **Return and Save:** The `build_plot` utility returns a `plotly.graph_objects.Figure` object, which is passed to the **user-facing function**. If a `file_path` was provided, the plot is saved to the specified location + +Here is a visual representation of the workflow: + +``` +User Calls API + ▼ + `vuecore/plots/basic/scatter.py` + │ + ▼ Validates configuration + `vuecore/schemas/basic/scatter.py` + │ + ▼ Calls engine-specific build function + `vuecore/engines/plotly/scatter.py:build` + │ + ▼ Delegates to generic plot builder + `vuecore/engines/plotly/plot_builder.py:build_plot` + ├───► Preprocessing (`scatter_preprocess`) + └───► Theming (`apply_scatter_theme`) + │ + ▼ Returns final plot object + `plotly.graph_objects.Figure` + │ + ▼ Saves the final plot + `vuecore/engines/plotly/saver.py` +``` + +## Tasks to Add a New Plot + +We created a [new plot PR template][new-plot-pr-template] with a checklist of all the steps to follow, which you can use with a query paramter by clicking [here][new-plot-pr-query-param]. + +[new-plot-pr-template]: https://github.com/Multiomics-Analytics-Group/vuecore/blob/main/.github/PULL_REQUEST_TEMPLATE/new_plot.md +[new-plot-pr-query-param]: https://github.com/Multiomics-Analytics-Group/vuecore/compare/main...my-branch?quick_pull=1&template=new_plot.md \ No newline at end of file