# ures.plot - Advanced Research Plotting Library
A comprehensive, multi-backend visualization library designed for scientific research, data analysis, and machine learning, built on Polars DataFrames with matplotlib/seaborn, plotly, and HoloViews backends.
## Overview
ures.plot provides a unified interface for creating publication-quality static plots, interactive visualizations, and high-performance ML exploration charts. It supports 21+ traditional plot types plus specialized ML visualizations through a flexible dual-track backend system.
## Installation
```bash
# Core dependencies
pip install matplotlib polars numpy
# Enhanced research plotting
pip install seaborn scipy statsmodels
# Interactive visualization
pip install plotly kaleido
# ML exploration (high-performance)
pip install holoviews bokeh datashader panel
# ML analysis
pip install scikit-learn
```
## Quick Start
### Traditional Research Plotting
```python
import polars as pl
from ures.plot import ResearchPlotter, PlotConfig
# Create sample data
df = pl.DataFrame({
"x": range(10),
"y": [i**2 + i for i in range(10)],
"category": ["A"] * 5 + ["B"] * 5
})
# Initialize plotter
plotter = ResearchPlotter(backend="research") # or "interactive"
# Create configuration
config = PlotConfig(
title="Sample Plot",
xlabel="X Values",
ylabel="Y Values",
figsize=(10, 6)
)
# Create plots
fig = plotter.line_plot(df, config, "x", "y")
fig = plotter.scatter_plot(df, config, "x", "y")
fig = plotter.regression_plot(df, config, "x", "y")
```
### ML Visualization (Dual-Track System)
```python
import polars as pl
import numpy as np
from ures.plot.ml import MLVisualizer, MLPlotConfig
# Create ML data
train_data = pl.DataFrame({
"epoch": range(1, 101),
"train_loss": np.exp(-np.arange(100) * 0.05) + np.random.normal(0, 0.02, 100),
"val_loss": np.exp(-np.arange(100) * 0.03) + np.random.normal(0, 0.03, 100),
"train_acc": 1 - np.exp(-np.arange(100) * 0.04) + np.random.normal(0, 0.01, 100),
"val_acc": 1 - np.exp(-np.arange(100) * 0.035) + np.random.normal(0, 0.015, 100)
})
# Exploration mode (HoloViews - fast, interactive)
ml_viz = MLVisualizer(mode="exploration")
config = MLPlotConfig(title="Training Progress", mode="exploration")
fig = ml_viz.training_curves(train_data, config,
y_cols=["train_loss", "val_loss"])
fig.show() # Interactive plot in browser
# Publication mode (Matplotlib - high-quality, static)
ml_viz.switch_mode("publication")
pub_config = config.for_publication() # Auto-optimize for publication
fig = ml_viz.training_curves(train_data, pub_config,
y_cols=["train_loss", "val_loss"])
ml_viz.export(fig, "training_curves.pdf", pub_config)
```
## Library Structure
```
ures/plot/
├── __init__.py # Main package exports
├── ml.py # Machine learning utilities (if applicable)
backend/
├── __init__.py # Backend package exports
├── plotter.py # ResearchPlotter class and backend switching logic
├── config.py # Configuration management for plots
├── annotations.py # Annotation management system
├── color_config.py # Color scheme management
└── utils.py # Utility functions for plotting
```
## Architecture
### Class Diagram
```mermaid
classDiagram
%% Core Configuration Classes
class PlotConfig {
+figsize: Tuple[float, float]
+title: str
+xlabel: str
+ylabel: str
+x_unit: str
+y_unit: str
+color_config: ColorConfig
+annotations: AnnotationCollection
+font_config: Dict
+export_format: str
+smooth: bool
+legend: bool
}
class MLPlotConfig {
+experiment_name: str
+model_name: str
+mode: str
+enable_datashading: bool
+datashade_threshold: int
+sample_large_data: bool
+max_sample_size: int
+publication_dpi: int
+enable_hover_tools: bool
+for_publication(): MLPlotConfig
}
class ColorConfig {
+scheme: ColorScheme
+custom_colors: List[str]
+get_colors(): List[str]
+get_color(index): str
}
class AnnotationCollection {
+annotations: List[Annotation]
+add_annotation(ann: Annotation)
+add_text(text, x, y)
+add_arrow(text, x, y)
+add_box(text, x, y)
+clear()
}
%% Backend Interface
class PlotBackend {
<<abstract>>
+create_line_plot(df, config, x_col, y_col)*
+create_scatter_plot(df, config, x_col, y_col)*
+create_bar_plot(df, config, x_col, y_col)*
+create_histogram(df, config, col)*
+create_box_plot(df, config, y_col, x_col)*
+create_violin_plot(df, config, y_col, x_col)*
+create_heatmap(df, config)*
+create_regression_plot(df, config, x_col, y_col)*
+apply_annotations(fig, config)*
+export_plot(fig, filepath, config)*
}
%% Traditional Backends
class ResearchBackend {
-fig: matplotlib.Figure
-ax: matplotlib.Axes
+_setup_figure(config)
+_apply_smoothing(x_data, y_data, config)
+create_line_plot(df, config, x_col, y_col)
+create_scatter_plot(df, config, x_col, y_col)
+create_pair_plot(df, config, columns)
+create_training_curves(df, config, x_col, y_cols)
+create_confusion_matrix(y_true, y_pred, config)
}
class InteractiveBackend {
+create_line_plot(df, config, x_col, y_col)
+create_scatter_plot(df, config, x_col, y_col)
+_setup_plotly_layout(fig, config)
}
%% ML-Specific Backends
class HoloViewsMLBackend {
+_handle_large_data(df, config, x_col, y_col)
+_setup_hover_tools(element, config)
+create_training_curves(df, config, x_col, y_cols)
+create_confusion_matrix(y_true, y_pred, config)
+create_feature_importance(importance_data, config)
+create_line_plot(df, config, x_col, y_col)
+create_scatter_plot(df, config, x_col, y_col)
}
class MatplotlibMLBackend {
+_setup_ml_style()
+create_training_curves(df, config, x_col, y_cols)
+create_confusion_matrix(y_true, y_pred, config)
+create_feature_importance(importance_data, config)
+create_roc_curve(y_true, y_scores, config)
}
%% Main Interface Classes
class ResearchPlotter {
-backend_name: str
-backend: PlotBackend
+__init__(backend: str)
+switch_backend(backend: str)
+line_plot(df, config, x_col, y_col)
+scatter_plot(df, config, x_col, y_col)
+regression_plot(df, config, x_col, y_col)
+pair_plot(df, config, columns)
+export(fig, filepath, config)
}
class MLVisualizer {
-mode: str
-exploration_backend: HoloViewsMLBackend
-publication_backend: MatplotlibMLBackend
+__init__(mode: str)
+switch_mode(mode: str)
+training_curves(df, config, x_col, y_cols)
+confusion_matrix(y_true, y_pred, config)
+feature_importance(importance_data, config)
+roc_curve(y_true, y_scores, config)
+scatter_plot(df, config, x_col, y_col)
+export(fig, filepath, config)
}
%% Relationships
PlotConfig <|-- MLPlotConfig
PlotConfig *-- ColorConfig
PlotConfig *-- AnnotationCollection
PlotBackend <|-- ResearchBackend
PlotBackend <|-- InteractiveBackend
PlotBackend <|-- HoloViewsMLBackend
ResearchBackend <|-- MatplotlibMLBackend
ResearchPlotter *-- PlotBackend
MLVisualizer *-- HoloViewsMLBackend
MLVisualizer *-- MatplotlibMLBackend
ResearchPlotter ..> PlotConfig
MLVisualizer ..> MLPlotConfig
```
### Sequence Diagram - ML Dual-Track Visualization
```mermaid
sequenceDiagram
participant User
participant MLVisualizer
participant MLPlotConfig
participant HoloViews as HoloViewsMLBackend
participant Matplotlib as MatplotlibMLBackend
participant DataHandler as Large Data Handler
%% Exploration Mode Initialization
User->>MLVisualizer: MLVisualizer(mode="exploration")
MLVisualizer->>HoloViews: new HoloViewsMLBackend()
MLVisualizer->>Matplotlib: new MatplotlibMLBackend()
HoloViews->>HoloViews: configure HoloViews defaults
Matplotlib->>Matplotlib: setup ML publication styles
%% Configuration Setup
User->>MLPlotConfig: MLPlotConfig(mode="exploration", enable_datashading=True)
MLPlotConfig-->>User: config instance
%% Exploration Mode - Training Curves
User->>MLVisualizer: training_curves(large_df, config, y_cols=["train_loss", "val_loss"])
MLVisualizer->>MLVisualizer: _get_current_backend() -> HoloViewsMLBackend
MLVisualizer->>HoloViews: create_training_curves(large_df, config, ...)
HoloViews->>DataHandler: _handle_large_data(large_df, config, x_col, y_cols)
alt Large Dataset (> 50k points)
DataHandler->>DataHandler: check datashade_threshold
DataHandler->>DataHandler: enable datashading
DataHandler-->>HoloViews: (original_df, use_datashade=True)
HoloViews->>HoloViews: create hv.Curve for each y_col
HoloViews->>HoloViews: apply datashade() with color mapping
HoloViews->>HoloViews: setup interactive tools (hover, zoom)
HoloViews-->>MLVisualizer: interactive datashaded plot
else Medium Dataset
DataHandler-->>HoloViews: (sampled_df, use_datashade=False)
HoloViews->>HoloViews: create standard hv.Overlay with curves
HoloViews->>HoloViews: setup hover tools and selection
HoloViews-->>MLVisualizer: interactive standard plot
end
MLVisualizer-->>User: HoloViews interactive figure
%% Switch to Publication Mode
User->>MLVisualizer: switch_mode("publication")
MLVisualizer->>MLVisualizer: mode = "publication"
%% Publication Configuration
User->>MLPlotConfig: config.for_publication()
MLPlotConfig->>MLPlotConfig: override settings for publication
MLPlotConfig-->>User: publication_config
%% Publication Mode - Same Data
User->>MLVisualizer: training_curves(large_df, pub_config, y_cols=["train_loss", "val_loss"])
MLVisualizer->>MLVisualizer: _get_current_backend() -> MatplotlibMLBackend
MLVisualizer->>Matplotlib: create_training_curves(large_df, pub_config, ...)
Matplotlib->>Matplotlib: validate_dataframe(large_df)
Matplotlib->>Matplotlib: _setup_figure(pub_config)
Matplotlib->>Matplotlib: setup publication styling (Arial, small fonts)
loop For each y_col in y_cols
Matplotlib->>Matplotlib: sns.lineplot() or ax.plot()
Matplotlib->>Matplotlib: apply publication colors
end
Matplotlib->>Matplotlib: apply_annotations(fig, pub_config)
Matplotlib->>Matplotlib: set legend, grid, labels
Matplotlib-->>MLVisualizer: matplotlib.Figure
MLVisualizer-->>User: publication-ready figure
%% Export Publication Plot
User->>MLVisualizer: export(fig, "training_curves.pdf", pub_config)
MLVisualizer->>Matplotlib: export_plot(fig, filepath, pub_config)
Matplotlib->>Matplotlib: savefig(dpi=300, format="pdf", bbox_inches="tight")
Matplotlib-->>MLVisualizer: success
MLVisualizer-->>User: file saved
```
## Core Components
### 1. Traditional Research Plotting
**PlotConfig**: Main configuration class for standard research plots
```python
config = PlotConfig(
title="Research Results",
xlabel="Time (days)", ylabel="Response (mV)",
x_unit="days", y_unit="mV",
figsize=(12, 8),
style="whitegrid",
font_config={
"title_size": 16,
"label_size": 14,
"tick_size": 12
}
)
```
### 2. ML Dual-Track System
**MLPlotConfig**: Extended configuration for ML workflows
```python
from ures.plot.ml import MLPlotConfig
# Exploration mode - fast, interactive
config = MLPlotConfig(
title="Model Training",
mode="exploration",
enable_datashading=True,
datashade_threshold=50000,
enable_hover_tools=True
)
# Publication mode - high-quality, static
pub_config = config.for_publication() # Auto-optimizes settings
```
**Dual-Track Workflow**:
```python
from ures.plot.ml import MLVisualizer
# Exploration: HoloViews + Datashader (Speed + Interactivity)
ml_viz = MLVisualizer(mode="exploration")
# Publication: Matplotlib + Seaborn (Quality + Control)
ml_viz.switch_mode("publication")
```
### 3. Large Dataset Handling
**Automatic Data Processing**:
```python
# Large dataset (>50k points) - auto-datashading
large_df = pl.DataFrame({
"x": np.random.randn(100000),
"y": np.random.randn(100000),
"category": np.random.choice(["A", "B", "C"], 100000)
})
# Exploration mode: Uses datashading for performance
config = MLPlotConfig(enable_datashading=True, datashade_threshold=50000)
fig = ml_viz.scatter_plot(large_df, config, "x", "y", color_col="category")
# Publication mode: Samples data for quality
pub_config = config.for_publication() # Disables datashading
fig = ml_viz.scatter_plot(large_df, pub_config, "x", "y", color_col="category")
```
## Usage Examples by Component
### Traditional Research Plotting
**Line Plot with Annotations**:
```python
from ures.plot import ResearchPlotter, PlotConfig
plotter = ResearchPlotter(backend="research")
config = PlotConfig(title="Temperature Monitoring", xlabel="Time", ylabel="Temperature (°C)")
# Add annotations
config.annotations.add_arrow("Peak Temperature", x=12.5, y=42.3, xy_text=(14, 45))
config.annotations.add_box("Critical Zone", x=18, y=38,
bbox_props={"boxstyle": "round", "facecolor": "yellow"})
fig = plotter.line_plot(df, config, "time", "temperature")
```
**Correlation Analysis**:
```python
# Heatmap with custom colors
config = PlotConfig(title="Feature Correlations")
config.color_config.scheme = ColorScheme.VIRIDIS
fig = plotter.heatmap(df, config, correlation=True, annot=True)
```
### ML Exploration Mode (HoloViews)
**Interactive Training Curves**:
```python
from ures.plot.ml import MLVisualizer, MLPlotConfig
ml_viz = MLVisualizer(mode="exploration")
config = MLPlotConfig(
title="Training Progress",
mode="exploration",
enable_hover_tools=True,
enable_selection_tools=True
)
# Interactive plot with hover data
fig = ml_viz.training_curves(
train_df, config,
x_col="epoch",
y_cols=["train_loss", "val_loss", "train_acc", "val_acc"]
)
fig.show() # Opens in browser
```
**High-Performance Scatter Plot**:
```python
# Handles 100k+ points with datashading
config = MLPlotConfig(
enable_datashading=True,
datashade_threshold=10000
)
fig = ml_viz.scatter_plot(
large_embeddings_df, config,
"x", "y",
color_col="cluster_id"
)
```
**Feature Importance Visualization**:
```python
importance_data = {
"feature_1": 0.45,
"feature_2": 0.32,
"feature_3": 0.28,
# ... more features
}
fig = ml_viz.feature_importance(importance_data, config, top_n=15)
```
### ML Publication Mode (Matplotlib)
**Publication-Ready Training Curves**:
```python
ml_viz.switch_mode("publication")
pub_config = MLPlotConfig().for_publication()
fig = ml_viz.training_curves(train_df, pub_config,
y_cols=["train_loss", "val_loss"])
ml_viz.export(fig, "training_curves.pdf", pub_config)
```
**Confusion Matrix**:
```python
import numpy as np
y_true = np.array([0, 1, 2, 2, 1, 0, 1, 2])
y_pred = np.array([0, 2, 1, 2, 1, 0, 1, 2])
class_names = ["Class A", "Class B", "Class C"]
fig = ml_viz.confusion_matrix(y_true, y_pred, pub_config, class_names)
```
**ROC Curve Analysis**:
```python
# Binary classification ROC curve
y_true_binary = np.array([0, 0, 1, 1, 0, 1, 1, 0])
y_scores = np.array([0.1, 0.4, 0.35, 0.8, 0.65, 0.9, 0.7, 0.2])
fig = ml_viz.roc_curve(y_true_binary, y_scores, pub_config)
ml_viz.export(fig, "roc_curve.png", pub_config)
```
### Backend Comparison
| Feature | Research Backend | Interactive Backend | ML Exploration | ML Publication |
|---------|------------------|-------------------|----------------|----------------|
| **Library** | Matplotlib + Seaborn | Plotly | HoloViews + Datashader | Matplotlib + Seaborn |
| **Performance** | Good | Good | Excellent (100k+ points) | Good |
| **Interactivity** | None | Full | Full + Tools | None |
| **Publication Quality** | Excellent | Good | Fair | Excellent |
| **Large Data** | Limited | Limited | Optimized | Sampling |
| **Export Formats** | PNG, PDF, SVG | PNG, PDF, HTML | PNG, HTML | PNG, PDF |
### Advanced ML Workflows
**Complete ML Experiment Visualization**:
```python
from ures.plot.ml import MLVisualizer, MLPlotConfig
# Initialize dual-mode visualizer
ml_viz = MLVisualizer(mode="exploration")
# Experiment tracking
config = MLPlotConfig(
experiment_name="bert_finetuning",
model_name="bert-base-uncased",
mode="exploration"
)
# 1. Training curves (exploration)
training_fig = ml_viz.training_curves(metrics_df, config,
y_cols=["train_loss", "val_loss", "f1_score"])
# 2. Feature importance (exploration)
importance_fig = ml_viz.feature_importance(feature_weights, config)
# 3. Switch to publication mode
ml_viz.switch_mode("publication")
pub_config = config.for_publication()
# 4. Generate publication plots
final_training = ml_viz.training_curves(metrics_df, pub_config,
y_cols=["train_loss", "val_loss"])
final_confusion = ml_viz.confusion_matrix(y_test, y_pred, pub_config, class_names)
# 5. Export for paper
ml_viz.export(final_training, "figure1_training.pdf", pub_config)
ml_viz.export(final_confusion, "figure2_confusion.pdf", pub_config)
```
## Dependency Management
The library gracefully handles optional dependencies:
```python
from ures.plot.backend.deps import check_dependencies
check_dependencies()
# Output shows ML capabilities:
# Research Plotting Dependencies:
# ========================================
# - Matplotlib: ✓ (required - core plotting)
# - Polars: ✓ (required - data handling)
# - NumPy: ✓ (required - numerical operations)
#
# Optional Dependencies:
# -------------------------
# - Seaborn: ✓ (optional - enhanced research plots)
# - Plotly: ✓ (optional - interactive visualization)
# - HoloViews: ✓ (optional - ML exploration)
# - Datashader: ✓ (optional - large data visualization)
# - Scikit-learn: ✓ (optional - ML metrics)
```
## Complete Feature Matrix
### Traditional Research Plots (21 types)
| Category | Plot Types | Methods | Backend Support |
|----------|------------|---------|----------------|
| **Basic** | Line, Scatter, Bar, Histogram, Box, Violin | `line_plot()`, `scatter_plot()`, etc. | Research + Interactive |
| **Multi-dimensional** | Heatmap, Bubble, Radar, Parallel Coordinates | `heatmap()`, `bubble_plot()`, etc. | Research + Interactive |
| **Scientific** | Error Bar, Regression, Residual, Q-Q, Density, CDF | `regression_plot()`, `error_bar_plot()`, etc. | Research |
| **Advanced** | Subplot Grid, Pair Plot, Facet Grid | `pair_plot()`, `subplots_grid()`, etc. | Research |
| **Time Series** | Decomposition, ACF/PACF | `time_series_decomposition()`, `acf_pacf_plot()` | Research |
### ML-Specific Visualizations
| Category | Plot Types | Methods | Exploration | Publication |
|----------|------------|---------|-------------|-------------|
| **Training** | Training Curves, Loss Landscapes | `training_curves()` | ✓ HoloViews | ✓ Matplotlib |
| **Evaluation** | Confusion Matrix, ROC/PR Curves | `confusion_matrix()`, `roc_curve()` | ✓ Interactive | ✓ Static |
| **Interpretation** | Feature Importance, SHAP plots | `feature_importance()` | ✓ Interactive | ✓ Static |
| **Data** | Large Scatter, Embeddings | `scatter_plot()` with datashading | ✓ Optimized | ✓ Sampled |
The library provides a complete solution for both traditional research visualization and modern ML workflows, with automatic optimization for different use cases and data scales.
Raw data
{
"_id": null,
"home_page": null,
"name": "ures-visual",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "utilization, Research Tool, Python, visualization, data analysis, machine learning, data science",
"author": "stone",
"author_email": "github@stone-bo.com",
"download_url": "https://files.pythonhosted.org/packages/46/8b/f0367e236da6079cf37f6c37c63d7eee708b223429b1ccf92dbc53b92ca1/ures_visual-1.0.3.tar.gz",
"platform": null,
"description": "# ures.plot - Advanced Research Plotting Library\n\nA comprehensive, multi-backend visualization library designed for scientific research, data analysis, and machine learning, built on Polars DataFrames with matplotlib/seaborn, plotly, and HoloViews backends.\n\n## Overview\n\nures.plot provides a unified interface for creating publication-quality static plots, interactive visualizations, and high-performance ML exploration charts. It supports 21+ traditional plot types plus specialized ML visualizations through a flexible dual-track backend system.\n\n## Installation\n\n```bash\n# Core dependencies\npip install matplotlib polars numpy\n\n# Enhanced research plotting\npip install seaborn scipy statsmodels\n\n# Interactive visualization\npip install plotly kaleido\n\n# ML exploration (high-performance)\npip install holoviews bokeh datashader panel\n\n# ML analysis\npip install scikit-learn\n```\n\n## Quick Start\n\n### Traditional Research Plotting\n```python\nimport polars as pl\nfrom ures.plot import ResearchPlotter, PlotConfig\n\n# Create sample data\ndf = pl.DataFrame({\n \"x\": range(10),\n \"y\": [i**2 + i for i in range(10)],\n \"category\": [\"A\"] * 5 + [\"B\"] * 5\n})\n\n# Initialize plotter\nplotter = ResearchPlotter(backend=\"research\") # or \"interactive\"\n\n# Create configuration\nconfig = PlotConfig(\n title=\"Sample Plot\",\n xlabel=\"X Values\",\n ylabel=\"Y Values\",\n figsize=(10, 6)\n)\n\n# Create plots\nfig = plotter.line_plot(df, config, \"x\", \"y\")\nfig = plotter.scatter_plot(df, config, \"x\", \"y\")\nfig = plotter.regression_plot(df, config, \"x\", \"y\")\n```\n\n### ML Visualization (Dual-Track System)\n```python\nimport polars as pl\nimport numpy as np\nfrom ures.plot.ml import MLVisualizer, MLPlotConfig\n\n# Create ML data\ntrain_data = pl.DataFrame({\n \"epoch\": range(1, 101),\n \"train_loss\": np.exp(-np.arange(100) * 0.05) + np.random.normal(0, 0.02, 100),\n \"val_loss\": np.exp(-np.arange(100) * 0.03) + np.random.normal(0, 0.03, 100),\n \"train_acc\": 1 - np.exp(-np.arange(100) * 0.04) + np.random.normal(0, 0.01, 100),\n \"val_acc\": 1 - np.exp(-np.arange(100) * 0.035) + np.random.normal(0, 0.015, 100)\n})\n\n# Exploration mode (HoloViews - fast, interactive)\nml_viz = MLVisualizer(mode=\"exploration\")\nconfig = MLPlotConfig(title=\"Training Progress\", mode=\"exploration\")\n\nfig = ml_viz.training_curves(train_data, config,\n y_cols=[\"train_loss\", \"val_loss\"])\nfig.show() # Interactive plot in browser\n\n# Publication mode (Matplotlib - high-quality, static)\nml_viz.switch_mode(\"publication\")\npub_config = config.for_publication() # Auto-optimize for publication\n\nfig = ml_viz.training_curves(train_data, pub_config,\n y_cols=[\"train_loss\", \"val_loss\"])\nml_viz.export(fig, \"training_curves.pdf\", pub_config)\n```\n\n## Library Structure\n```\nures/plot/\n\u251c\u2500\u2500 __init__.py # Main package exports\n\u251c\u2500\u2500 ml.py # Machine learning utilities (if applicable)\nbackend/\n \u251c\u2500\u2500 __init__.py # Backend package exports\n \u251c\u2500\u2500 plotter.py # ResearchPlotter class and backend switching logic\n \u251c\u2500\u2500 config.py # Configuration management for plots\n \u251c\u2500\u2500 annotations.py # Annotation management system\n \u251c\u2500\u2500 color_config.py # Color scheme management\n \u2514\u2500\u2500 utils.py # Utility functions for plotting\n```\n\n## Architecture\n\n### Class Diagram\n```mermaid\nclassDiagram\n %% Core Configuration Classes\n class PlotConfig {\n +figsize: Tuple[float, float]\n +title: str\n +xlabel: str\n +ylabel: str\n +x_unit: str\n +y_unit: str\n +color_config: ColorConfig\n +annotations: AnnotationCollection\n +font_config: Dict\n +export_format: str\n +smooth: bool\n +legend: bool\n }\n\n class MLPlotConfig {\n +experiment_name: str\n +model_name: str\n +mode: str\n +enable_datashading: bool\n +datashade_threshold: int\n +sample_large_data: bool\n +max_sample_size: int\n +publication_dpi: int\n +enable_hover_tools: bool\n +for_publication(): MLPlotConfig\n }\n\n class ColorConfig {\n +scheme: ColorScheme\n +custom_colors: List[str]\n +get_colors(): List[str]\n +get_color(index): str\n }\n\n class AnnotationCollection {\n +annotations: List[Annotation]\n +add_annotation(ann: Annotation)\n +add_text(text, x, y)\n +add_arrow(text, x, y)\n +add_box(text, x, y)\n +clear()\n }\n\n %% Backend Interface\n class PlotBackend {\n <<abstract>>\n +create_line_plot(df, config, x_col, y_col)*\n +create_scatter_plot(df, config, x_col, y_col)*\n +create_bar_plot(df, config, x_col, y_col)*\n +create_histogram(df, config, col)*\n +create_box_plot(df, config, y_col, x_col)*\n +create_violin_plot(df, config, y_col, x_col)*\n +create_heatmap(df, config)*\n +create_regression_plot(df, config, x_col, y_col)*\n +apply_annotations(fig, config)*\n +export_plot(fig, filepath, config)*\n }\n\n %% Traditional Backends\n class ResearchBackend {\n -fig: matplotlib.Figure\n -ax: matplotlib.Axes\n +_setup_figure(config)\n +_apply_smoothing(x_data, y_data, config)\n +create_line_plot(df, config, x_col, y_col)\n +create_scatter_plot(df, config, x_col, y_col)\n +create_pair_plot(df, config, columns)\n +create_training_curves(df, config, x_col, y_cols)\n +create_confusion_matrix(y_true, y_pred, config)\n }\n\n class InteractiveBackend {\n +create_line_plot(df, config, x_col, y_col)\n +create_scatter_plot(df, config, x_col, y_col)\n +_setup_plotly_layout(fig, config)\n }\n\n %% ML-Specific Backends\n class HoloViewsMLBackend {\n +_handle_large_data(df, config, x_col, y_col)\n +_setup_hover_tools(element, config)\n +create_training_curves(df, config, x_col, y_cols)\n +create_confusion_matrix(y_true, y_pred, config)\n +create_feature_importance(importance_data, config)\n +create_line_plot(df, config, x_col, y_col)\n +create_scatter_plot(df, config, x_col, y_col)\n }\n\n class MatplotlibMLBackend {\n +_setup_ml_style()\n +create_training_curves(df, config, x_col, y_cols)\n +create_confusion_matrix(y_true, y_pred, config)\n +create_feature_importance(importance_data, config)\n +create_roc_curve(y_true, y_scores, config)\n }\n\n %% Main Interface Classes\n class ResearchPlotter {\n -backend_name: str\n -backend: PlotBackend\n +__init__(backend: str)\n +switch_backend(backend: str)\n +line_plot(df, config, x_col, y_col)\n +scatter_plot(df, config, x_col, y_col)\n +regression_plot(df, config, x_col, y_col)\n +pair_plot(df, config, columns)\n +export(fig, filepath, config)\n }\n\n class MLVisualizer {\n -mode: str\n -exploration_backend: HoloViewsMLBackend\n -publication_backend: MatplotlibMLBackend\n +__init__(mode: str)\n +switch_mode(mode: str)\n +training_curves(df, config, x_col, y_cols)\n +confusion_matrix(y_true, y_pred, config)\n +feature_importance(importance_data, config)\n +roc_curve(y_true, y_scores, config)\n +scatter_plot(df, config, x_col, y_col)\n +export(fig, filepath, config)\n }\n\n %% Relationships\n PlotConfig <|-- MLPlotConfig\n PlotConfig *-- ColorConfig\n PlotConfig *-- AnnotationCollection\n PlotBackend <|-- ResearchBackend\n PlotBackend <|-- InteractiveBackend\n PlotBackend <|-- HoloViewsMLBackend\n ResearchBackend <|-- MatplotlibMLBackend\n ResearchPlotter *-- PlotBackend\n MLVisualizer *-- HoloViewsMLBackend\n MLVisualizer *-- MatplotlibMLBackend\n ResearchPlotter ..> PlotConfig\n MLVisualizer ..> MLPlotConfig\n```\n\n### Sequence Diagram - ML Dual-Track Visualization\n```mermaid\nsequenceDiagram\n participant User\n participant MLVisualizer\n participant MLPlotConfig\n participant HoloViews as HoloViewsMLBackend\n participant Matplotlib as MatplotlibMLBackend\n participant DataHandler as Large Data Handler\n\n %% Exploration Mode Initialization\n User->>MLVisualizer: MLVisualizer(mode=\"exploration\")\n MLVisualizer->>HoloViews: new HoloViewsMLBackend()\n MLVisualizer->>Matplotlib: new MatplotlibMLBackend()\n HoloViews->>HoloViews: configure HoloViews defaults\n Matplotlib->>Matplotlib: setup ML publication styles\n\n %% Configuration Setup\n User->>MLPlotConfig: MLPlotConfig(mode=\"exploration\", enable_datashading=True)\n MLPlotConfig-->>User: config instance\n\n %% Exploration Mode - Training Curves\n User->>MLVisualizer: training_curves(large_df, config, y_cols=[\"train_loss\", \"val_loss\"])\n MLVisualizer->>MLVisualizer: _get_current_backend() -> HoloViewsMLBackend\n MLVisualizer->>HoloViews: create_training_curves(large_df, config, ...)\n\n HoloViews->>DataHandler: _handle_large_data(large_df, config, x_col, y_cols)\n\n alt Large Dataset (> 50k points)\n DataHandler->>DataHandler: check datashade_threshold\n DataHandler->>DataHandler: enable datashading\n DataHandler-->>HoloViews: (original_df, use_datashade=True)\n\n HoloViews->>HoloViews: create hv.Curve for each y_col\n HoloViews->>HoloViews: apply datashade() with color mapping\n HoloViews->>HoloViews: setup interactive tools (hover, zoom)\n HoloViews-->>MLVisualizer: interactive datashaded plot\n\n else Medium Dataset\n DataHandler-->>HoloViews: (sampled_df, use_datashade=False)\n HoloViews->>HoloViews: create standard hv.Overlay with curves\n HoloViews->>HoloViews: setup hover tools and selection\n HoloViews-->>MLVisualizer: interactive standard plot\n end\n\n MLVisualizer-->>User: HoloViews interactive figure\n\n %% Switch to Publication Mode\n User->>MLVisualizer: switch_mode(\"publication\")\n MLVisualizer->>MLVisualizer: mode = \"publication\"\n\n %% Publication Configuration\n User->>MLPlotConfig: config.for_publication()\n MLPlotConfig->>MLPlotConfig: override settings for publication\n MLPlotConfig-->>User: publication_config\n\n %% Publication Mode - Same Data\n User->>MLVisualizer: training_curves(large_df, pub_config, y_cols=[\"train_loss\", \"val_loss\"])\n MLVisualizer->>MLVisualizer: _get_current_backend() -> MatplotlibMLBackend\n MLVisualizer->>Matplotlib: create_training_curves(large_df, pub_config, ...)\n\n Matplotlib->>Matplotlib: validate_dataframe(large_df)\n Matplotlib->>Matplotlib: _setup_figure(pub_config)\n Matplotlib->>Matplotlib: setup publication styling (Arial, small fonts)\n\n loop For each y_col in y_cols\n Matplotlib->>Matplotlib: sns.lineplot() or ax.plot()\n Matplotlib->>Matplotlib: apply publication colors\n end\n\n Matplotlib->>Matplotlib: apply_annotations(fig, pub_config)\n Matplotlib->>Matplotlib: set legend, grid, labels\n Matplotlib-->>MLVisualizer: matplotlib.Figure\n MLVisualizer-->>User: publication-ready figure\n\n %% Export Publication Plot\n User->>MLVisualizer: export(fig, \"training_curves.pdf\", pub_config)\n MLVisualizer->>Matplotlib: export_plot(fig, filepath, pub_config)\n Matplotlib->>Matplotlib: savefig(dpi=300, format=\"pdf\", bbox_inches=\"tight\")\n Matplotlib-->>MLVisualizer: success\n MLVisualizer-->>User: file saved\n```\n\n## Core Components\n\n### 1. Traditional Research Plotting\n\n**PlotConfig**: Main configuration class for standard research plots\n```python\nconfig = PlotConfig(\n title=\"Research Results\",\n xlabel=\"Time (days)\", ylabel=\"Response (mV)\",\n x_unit=\"days\", y_unit=\"mV\",\n figsize=(12, 8),\n style=\"whitegrid\",\n font_config={\n \"title_size\": 16,\n \"label_size\": 14,\n \"tick_size\": 12\n }\n)\n```\n\n### 2. ML Dual-Track System\n\n**MLPlotConfig**: Extended configuration for ML workflows\n```python\nfrom ures.plot.ml import MLPlotConfig\n\n# Exploration mode - fast, interactive\nconfig = MLPlotConfig(\n title=\"Model Training\",\n mode=\"exploration\",\n enable_datashading=True,\n datashade_threshold=50000,\n enable_hover_tools=True\n)\n\n# Publication mode - high-quality, static\npub_config = config.for_publication() # Auto-optimizes settings\n```\n\n**Dual-Track Workflow**:\n```python\nfrom ures.plot.ml import MLVisualizer\n\n# Exploration: HoloViews + Datashader (Speed + Interactivity)\nml_viz = MLVisualizer(mode=\"exploration\")\n\n# Publication: Matplotlib + Seaborn (Quality + Control)\nml_viz.switch_mode(\"publication\")\n```\n\n### 3. Large Dataset Handling\n\n**Automatic Data Processing**:\n```python\n# Large dataset (>50k points) - auto-datashading\nlarge_df = pl.DataFrame({\n \"x\": np.random.randn(100000),\n \"y\": np.random.randn(100000),\n \"category\": np.random.choice([\"A\", \"B\", \"C\"], 100000)\n})\n\n# Exploration mode: Uses datashading for performance\nconfig = MLPlotConfig(enable_datashading=True, datashade_threshold=50000)\nfig = ml_viz.scatter_plot(large_df, config, \"x\", \"y\", color_col=\"category\")\n\n# Publication mode: Samples data for quality\npub_config = config.for_publication() # Disables datashading\nfig = ml_viz.scatter_plot(large_df, pub_config, \"x\", \"y\", color_col=\"category\")\n```\n\n## Usage Examples by Component\n\n### Traditional Research Plotting\n\n**Line Plot with Annotations**:\n```python\nfrom ures.plot import ResearchPlotter, PlotConfig\n\nplotter = ResearchPlotter(backend=\"research\")\nconfig = PlotConfig(title=\"Temperature Monitoring\", xlabel=\"Time\", ylabel=\"Temperature (\u00b0C)\")\n\n# Add annotations\nconfig.annotations.add_arrow(\"Peak Temperature\", x=12.5, y=42.3, xy_text=(14, 45))\nconfig.annotations.add_box(\"Critical Zone\", x=18, y=38,\n bbox_props={\"boxstyle\": \"round\", \"facecolor\": \"yellow\"})\n\nfig = plotter.line_plot(df, config, \"time\", \"temperature\")\n```\n\n**Correlation Analysis**:\n```python\n# Heatmap with custom colors\nconfig = PlotConfig(title=\"Feature Correlations\")\nconfig.color_config.scheme = ColorScheme.VIRIDIS\n\nfig = plotter.heatmap(df, config, correlation=True, annot=True)\n```\n\n### ML Exploration Mode (HoloViews)\n\n**Interactive Training Curves**:\n```python\nfrom ures.plot.ml import MLVisualizer, MLPlotConfig\n\nml_viz = MLVisualizer(mode=\"exploration\")\nconfig = MLPlotConfig(\n title=\"Training Progress\",\n mode=\"exploration\",\n enable_hover_tools=True,\n enable_selection_tools=True\n)\n\n# Interactive plot with hover data\nfig = ml_viz.training_curves(\n train_df, config,\n x_col=\"epoch\",\n y_cols=[\"train_loss\", \"val_loss\", \"train_acc\", \"val_acc\"]\n)\nfig.show() # Opens in browser\n```\n\n**High-Performance Scatter Plot**:\n```python\n# Handles 100k+ points with datashading\nconfig = MLPlotConfig(\n enable_datashading=True,\n datashade_threshold=10000\n)\n\nfig = ml_viz.scatter_plot(\n large_embeddings_df, config,\n \"x\", \"y\",\n color_col=\"cluster_id\"\n)\n```\n\n**Feature Importance Visualization**:\n```python\nimportance_data = {\n \"feature_1\": 0.45,\n \"feature_2\": 0.32,\n \"feature_3\": 0.28,\n # ... more features\n}\n\nfig = ml_viz.feature_importance(importance_data, config, top_n=15)\n```\n\n### ML Publication Mode (Matplotlib)\n\n**Publication-Ready Training Curves**:\n```python\nml_viz.switch_mode(\"publication\")\npub_config = MLPlotConfig().for_publication()\n\nfig = ml_viz.training_curves(train_df, pub_config,\n y_cols=[\"train_loss\", \"val_loss\"])\nml_viz.export(fig, \"training_curves.pdf\", pub_config)\n```\n\n**Confusion Matrix**:\n```python\nimport numpy as np\n\ny_true = np.array([0, 1, 2, 2, 1, 0, 1, 2])\ny_pred = np.array([0, 2, 1, 2, 1, 0, 1, 2])\nclass_names = [\"Class A\", \"Class B\", \"Class C\"]\n\nfig = ml_viz.confusion_matrix(y_true, y_pred, pub_config, class_names)\n```\n\n**ROC Curve Analysis**:\n```python\n# Binary classification ROC curve\ny_true_binary = np.array([0, 0, 1, 1, 0, 1, 1, 0])\ny_scores = np.array([0.1, 0.4, 0.35, 0.8, 0.65, 0.9, 0.7, 0.2])\n\nfig = ml_viz.roc_curve(y_true_binary, y_scores, pub_config)\nml_viz.export(fig, \"roc_curve.png\", pub_config)\n```\n\n### Backend Comparison\n\n| Feature | Research Backend | Interactive Backend | ML Exploration | ML Publication |\n|---------|------------------|-------------------|----------------|----------------|\n| **Library** | Matplotlib + Seaborn | Plotly | HoloViews + Datashader | Matplotlib + Seaborn |\n| **Performance** | Good | Good | Excellent (100k+ points) | Good |\n| **Interactivity** | None | Full | Full + Tools | None |\n| **Publication Quality** | Excellent | Good | Fair | Excellent |\n| **Large Data** | Limited | Limited | Optimized | Sampling |\n| **Export Formats** | PNG, PDF, SVG | PNG, PDF, HTML | PNG, HTML | PNG, PDF |\n\n### Advanced ML Workflows\n\n**Complete ML Experiment Visualization**:\n```python\nfrom ures.plot.ml import MLVisualizer, MLPlotConfig\n\n# Initialize dual-mode visualizer\nml_viz = MLVisualizer(mode=\"exploration\")\n\n# Experiment tracking\nconfig = MLPlotConfig(\n experiment_name=\"bert_finetuning\",\n model_name=\"bert-base-uncased\",\n mode=\"exploration\"\n)\n\n# 1. Training curves (exploration)\ntraining_fig = ml_viz.training_curves(metrics_df, config,\n y_cols=[\"train_loss\", \"val_loss\", \"f1_score\"])\n\n# 2. Feature importance (exploration)\nimportance_fig = ml_viz.feature_importance(feature_weights, config)\n\n# 3. Switch to publication mode\nml_viz.switch_mode(\"publication\")\npub_config = config.for_publication()\n\n# 4. Generate publication plots\nfinal_training = ml_viz.training_curves(metrics_df, pub_config,\n y_cols=[\"train_loss\", \"val_loss\"])\nfinal_confusion = ml_viz.confusion_matrix(y_test, y_pred, pub_config, class_names)\n\n# 5. Export for paper\nml_viz.export(final_training, \"figure1_training.pdf\", pub_config)\nml_viz.export(final_confusion, \"figure2_confusion.pdf\", pub_config)\n```\n\n## Dependency Management\n\nThe library gracefully handles optional dependencies:\n\n```python\nfrom ures.plot.backend.deps import check_dependencies\n\ncheck_dependencies()\n\n# Output shows ML capabilities:\n# Research Plotting Dependencies:\n# ========================================\n# - Matplotlib: \u2713 (required - core plotting)\n# - Polars: \u2713 (required - data handling)\n# - NumPy: \u2713 (required - numerical operations)\n#\n# Optional Dependencies:\n# -------------------------\n# - Seaborn: \u2713 (optional - enhanced research plots)\n# - Plotly: \u2713 (optional - interactive visualization)\n# - HoloViews: \u2713 (optional - ML exploration)\n# - Datashader: \u2713 (optional - large data visualization)\n# - Scikit-learn: \u2713 (optional - ML metrics)\n```\n\n## Complete Feature Matrix\n\n### Traditional Research Plots (21 types)\n\n| Category | Plot Types | Methods | Backend Support |\n|----------|------------|---------|----------------|\n| **Basic** | Line, Scatter, Bar, Histogram, Box, Violin | `line_plot()`, `scatter_plot()`, etc. | Research + Interactive |\n| **Multi-dimensional** | Heatmap, Bubble, Radar, Parallel Coordinates | `heatmap()`, `bubble_plot()`, etc. | Research + Interactive |\n| **Scientific** | Error Bar, Regression, Residual, Q-Q, Density, CDF | `regression_plot()`, `error_bar_plot()`, etc. | Research |\n| **Advanced** | Subplot Grid, Pair Plot, Facet Grid | `pair_plot()`, `subplots_grid()`, etc. | Research |\n| **Time Series** | Decomposition, ACF/PACF | `time_series_decomposition()`, `acf_pacf_plot()` | Research |\n\n### ML-Specific Visualizations\n\n| Category | Plot Types | Methods | Exploration | Publication |\n|----------|------------|---------|-------------|-------------|\n| **Training** | Training Curves, Loss Landscapes | `training_curves()` | \u2713 HoloViews | \u2713 Matplotlib |\n| **Evaluation** | Confusion Matrix, ROC/PR Curves | `confusion_matrix()`, `roc_curve()` | \u2713 Interactive | \u2713 Static |\n| **Interpretation** | Feature Importance, SHAP plots | `feature_importance()` | \u2713 Interactive | \u2713 Static |\n| **Data** | Large Scatter, Embeddings | `scatter_plot()` with datashading | \u2713 Optimized | \u2713 Sampled |\n\nThe library provides a complete solution for both traditional research visualization and modern ML workflows, with automatic optimization for different use cases and data scales.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A comprehensive, multi-backend visualization library designed for scientific research, data analysis, and machine learning, built on Polars DataFrames with matplotlib/seaborn, plotly, and HoloViews backends.",
"version": "1.0.3",
"project_urls": null,
"split_keywords": [
"utilization",
" research tool",
" python",
" visualization",
" data analysis",
" machine learning",
" data science"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1fb4cc17e969d045a464721c784b1e7a93f0822412636086c25cc89638766111",
"md5": "d0a15322ddb21d4348e03f73f4c766c9",
"sha256": "c14745f9fa651e20d4c79d8d81659e3fff5d1f95feae86c323c86e084bb93569"
},
"downloads": -1,
"filename": "ures_visual-1.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d0a15322ddb21d4348e03f73f4c766c9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 54493,
"upload_time": "2025-08-09T23:20:07",
"upload_time_iso_8601": "2025-08-09T23:20:07.531345Z",
"url": "https://files.pythonhosted.org/packages/1f/b4/cc17e969d045a464721c784b1e7a93f0822412636086c25cc89638766111/ures_visual-1.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "468bf0367e236da6079cf37f6c37c63d7eee708b223429b1ccf92dbc53b92ca1",
"md5": "dad38595bdd5210ee603ec879c75772c",
"sha256": "437342f26678e8cefef28bba35817b7b381f03bc9ce61a97aa8c053aba5e073d"
},
"downloads": -1,
"filename": "ures_visual-1.0.3.tar.gz",
"has_sig": false,
"md5_digest": "dad38595bdd5210ee603ec879c75772c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 51641,
"upload_time": "2025-08-09T23:20:08",
"upload_time_iso_8601": "2025-08-09T23:20:08.918398Z",
"url": "https://files.pythonhosted.org/packages/46/8b/f0367e236da6079cf37f6c37c63d7eee708b223429b1ccf92dbc53b92ca1/ures_visual-1.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-09 23:20:08",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "ures-visual"
}
JSON