figrecipe 0.7.4__py3-none-any.whl → 0.9.0__py3-none-any.whl

{figrecipe-0.7.4.dist-info → figrecipe-0.9.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: figrecipe
-Version: 0.7.4
+Version: 0.9.0
 Summary: Reproducible matplotlib wrapper with mm-precision layouts
 Project-URL: Homepage, https://github.com/ywatanabe1989/figrecipe
 Project-URL: Documentation, https://github.com/ywatanabe1989/figrecipe#readme
@@ -21,6 +21,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Scientific/Engineering :: Visualization
 Requires-Python: >=3.9
+Requires-Dist: click>=8.0.0
 Requires-Dist: matplotlib>=3.5.0
 Requires-Dist: numpy>=1.20.0
 Requires-Dist: ruamel-yaml>=0.17.0
@@ -29,12 +30,26 @@ Provides-Extra: all
 Requires-Dist: flask>=2.0.0; extra == 'all'
 Requires-Dist: pandas>=1.3.0; extra == 'all'
 Requires-Dist: pillow>=9.0.0; extra == 'all'
+Requires-Dist: playwright>=1.40.0; extra == 'all'
+Requires-Dist: pytesseract>=0.3.0; extra == 'all'
 Requires-Dist: pytest-cov>=4.0.0; extra == 'all'
 Requires-Dist: pytest>=7.0.0; extra == 'all'
+Requires-Dist: pywebview>=4.0.0; extra == 'all'
 Requires-Dist: seaborn>=0.12.0; extra == 'all'
+Provides-Extra: demo
+Requires-Dist: playwright>=1.40.0; extra == 'demo'
+Requires-Dist: pytesseract>=0.3.0; extra == 'demo'
+Provides-Extra: desktop
+Requires-Dist: flask>=2.0.0; extra == 'desktop'
+Requires-Dist: pillow>=9.0.0; extra == 'desktop'
+Requires-Dist: pyqt6-webengine>=6.0.0; extra == 'desktop'
+Requires-Dist: pyqt6>=6.0.0; extra == 'desktop'
+Requires-Dist: pywebview>=4.0.0; extra == 'desktop'
+Requires-Dist: qtpy>=2.0.0; extra == 'desktop'
 Provides-Extra: dev
 Requires-Dist: pre-commit>=3.5.0; extra == 'dev'
 Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest-xdist>=3.0.0; extra == 'dev'
 Requires-Dist: pytest>=7.0.0; extra == 'dev'
 Provides-Extra: editor
 Requires-Dist: flask>=2.0.0; extra == 'editor'
@@ -47,7 +62,7 @@ Requires-Dist: seaborn>=0.12.0; extra == 'seaborn'
 Description-Content-Type: text/markdown
 
 <!-- ---
-!-- Timestamp: 2025-12-22 14:49:10
+!-- Timestamp: 2025-12-27 02:15:07
 !-- Author: ywatanabe
 !-- File: /home/ywatanabe/proj/figrecipe/README.md
 !-- --- -->
@@ -58,51 +73,29 @@ Description-Content-Type: text/markdown
   </a>
 </p>
 
-# FigRecipe
+# FigRecipe — **Reproducible matplotlib figures with mm-precision layouts.**
 
-**Reproducible matplotlib figures with mm-precision layouts.**
-FigRecipe is a lightweight recording & reproduction layer for matplotlib,
-designed for scientific figures that must remain **editable, inspectable,
-and reproducible**.
+FigRecipe separates **what** is plotted (data) from **how** it is styled, storing both in a structured format. This enables reproducible figures with GUI editing while preserving scientific integrity, and allows AI integration in a scientifically rigorous manner. Ultimately, FigRecipe will bundle: (1) reproducible, style-editable figures, and (2) metadata such as statistical values—creating atomic, portable, and traceable scientific figure objects essential for automated research in the AI era.
 
-Part of **SciTeX™ – Research OS for reproducible science**
-https://scitex.ai
+FigRecipe is part of [**SciTeX™ (pending) – Research OS for reproducible science**](https://scitex.ai)
 
 [![PyPI version](https://badge.fury.io/py/figrecipe.svg)](https://badge.fury.io/py/figrecipe)
 [![Tests](https://github.com/ywatanabe1989/figrecipe/actions/workflows/test.yml/badge.svg)](https://github.com/ywatanabe1989/figrecipe/actions/workflows/test.yml)
 [![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
 
----
-
-## Why FigRecipe?
-
-In scientific workflows, figures are often:
-- hard to reproduce once scripts change,
-- resized manually in pixels or inches,
-- impossible to partially reuse or inspect later.
-
-**FigRecipe solves this by recording plotting calls as a structured “recipe”**,
-allowing figures to be:
-- faithfully reproduced,
-- partially re-rendered,
-- inspected for underlying data,
-- laid out in **exact millimeters** for publication.
 
 ---
 
 ## Key Features
 
-- ✅ Drop-in replacement for `matplotlib.pyplot` (use `figrecipe.pyplot` to enable recording)
-- ✅ Automatic recording of plotting calls
-- ✅ Reproduce figures from a YAML recipe
-- ✅ Extract plotted data programmatically
-- ✅ Selective reproduction of specific plots
-- ✅ Millimeter-based layout (journal-ready)
+- ✅ Drop-in replacement for `matplotlib.pyplot`—minimal migration and learning cost
+- ✅ All intermediate files use familiar formats (PNG/SVG/PDF/YAML/JSON)
+- ✅ Import/Export to integrate with your existing workflow
+- ✅ Millimeter-based layout (journal-ready)—difficult to achieve manually with matplotlib
 - ✅ Publication-quality style presets
-- ✅ Dark theme support (data colors preserved)
-- ✅ Seamless seaborn integration
-- ✅ Crop figures to content with mm margins
-- ✅ **Interactive GUI editor** with live preview
+- ✅ Dark theme support (data colors preserved), with light theme export for journal compliance
+- ✅ Research-focused features: automatic cropping, axis alignment, panel labels, and caption embedding
+- ✅ Interactive GUI editor for manual adjustments
 
 ---
 
@@ -110,20 +103,29 @@ allowing figures to be:
 
 📓 **[View Demo Notebook on nbviewer](https://nbviewer.org/github/ywatanabe1989/figrecipe/blob/main/examples/figrecipe_demo.ipynb)** (recommended)
 
-The notebook includes side-by-side comparisons of original and reproduced figures.
+<details>
+<summary><b>Demo Videos</b> — GUI Editor in action</summary>
 
-Source: [examples/figrecipe_demo.ipynb](examples/figrecipe_demo.ipynb)
+| Dark Mode | Change Color | Drag Panel |
+|:---:|:---:|:---:|
+| ![Dark Mode](examples/demo_movie/outputs/01_enable_dark_mode.gif) | ![Change Color](examples/demo_movie/outputs/02_change_element_color.gif) | ![Drag Panel](examples/demo_movie/outputs/03_drag_panel_position.gif) |
 
-### Supported Plot Types
+| Move Legend | Undo/Redo | Toggle Theme |
+|:---:|:---:|:---:|
+| ![Move Legend](examples/demo_movie/outputs/04_move_legend.gif) | ![Undo Redo](examples/demo_movie/outputs/05_undo_and_redo.gif) | ![Toggle Theme](examples/demo_movie/outputs/06_toggle_theme.gif) |
 
-FigRecipe supports 46 matplotlib plot types, organized into 9 categories:
+| Hover Feedback | Edit Labels | Zoom Controls |
+|:---:|:---:|:---:|
+| ![Hover](examples/demo_movie/outputs/07_hover_feedback.gif) | ![Edit Labels](examples/demo_movie/outputs/08_edit_labels.gif) | ![Zoom](examples/demo_movie/outputs/09_zoom_controls.gif) |
+
+</details>
 
 <details>
-<summary><b>All Plot Types</b> (click to expand)</summary>
+<summary><b>Supported Plot Types</b> — 46 matplotlib plot types in 9 categories</summary>
+
 <p align="center">
   <img src="docs/images/plot_types/all_plot_types.png" alt="All Plot Types" width="100%"/>
 </p>
-</details>
 
 | Line & Curve | Scatter | Distribution |
 |:---:|:---:|:---:|
@@ -138,6 +140,7 @@ FigRecipe supports 46 matplotlib plot types, organized into 9 categories:
 | ![Vector](docs/images/plot_types/category_vector_flow.png) | ![Spectral](docs/images/plot_types/category_spectral_signal.png) | ![Special](docs/images/plot_types/category_special.png) |
 
 Generate all plots: `python examples/demo_plot_all.py`
+</details>
 
 ## Installation
 
@@ -178,12 +181,53 @@ img_path, yaml_path, result = fr.save(fig, 'figure.png')
 # → creates: figure.png + figure.yaml
 ```
 
+<details>
+<summary><b>Supported I/O Formats</b> — Save and load are fully symmetric</summary>
+
+**Save** creates both image and recipe. **Load** finds recipe from any format:
+
+```python
+# Save examples
+fr.save(fig, 'figure.png')       # → figure.png + figure.yaml
+fr.save(fig, 'figure.yaml')      # → figure.yaml + figure.png
+fr.save(fig, 'figure_bundle/')   # → directory with recipe.yaml + figure.png
+fr.save(fig, 'figure.zip')       # → ZIP containing recipe.yaml + figure.png
+
+# Load examples (symmetric with save)
+fig, ax = fr.load('figure.png')            # ← finds figure.yaml
+fig, ax = fr.load('figure.yaml')           # ← direct
+fig, ax = fr.load('figure_bundle/')        # ← finds recipe.yaml inside
+fig, ax = fr.load('figure.zip')            # ← extracts recipe.yaml
+
+# Edit also supports all formats
+fr.edit('figure.png')  # Opens editor, finds figure.yaml
+
+# Note: fr.reproduce() is an alias for fr.load()
+```
+
+| Format | Save | Load | Notes |
+|--------|:----:|:----:|-------|
+| `.png` / `.jpg` / `.jpeg` | ✓ | ✓ | Creates/finds `.yaml` alongside |
+| `.pdf` / `.svg` | ✓ | ✓ | Creates/finds `.yaml` alongside |
+| `.tif` / `.tiff` | ✓ | ✓ | Creates/finds `.yaml` alongside |
+| `.yaml` / `.yml` | ✓ | ✓ | Creates/finds image alongside |
+| Directory (`path/`) | ✓ | ✓ | Bundle with `recipe.yaml` + image |
+| `.zip` | ✓ | ✓ | ZIP bundle with `recipe.yaml` + image |
+
+**Alternative save method:**
+```python
+fig.savefig('figure.png')                      # Same as fr.save()
+fig.savefig('figure.png', save_recipe=False)   # Image only, no recipe
+```
+
+</details>
+
 ### Reproducing a Figure
 
 ``` python
 import figrecipe as fr
 
-fig, ax = fr.reproduce('figure.yaml')
+fig, ax = fr.reproduce('figure.yaml')  # Or .png, .pdf, directory/, .zip
 ```
 
 ### Extracting Plotted Data
@@ -195,18 +239,6 @@ data = fr.extract_data('figure.yaml')
 # {'sine_wave': {'x': array([...]), 'y': array([...])}}
 ```
 
-### Millimeter-Based Layout (Publication-Ready)
-
-``` python
-fig, ax = fr.subplots(
-    axes_width_mm=60,
-    axes_height_mm=40,
-    margin_left_mm=15,
-    margin_bottom_mm=12,
-)
-```
-This guarantees consistent sizing across editors, exports, and journals.
-
 ### Style Presets
 
 ``` python
@@ -227,6 +259,47 @@ fr.load_style('/path/to/my_style.yaml')
 
 See [src/figrecipe/styles/presets/](src/figrecipe/styles/presets/) for full examples.
 
+### Millimeter-Based Layout (Publication-Ready)
+
+``` python
+fig, ax = fr.subplots(
+    axes_width_mm=60,
+    axes_height_mm=40,
+    margin_left_mm=15,
+    margin_bottom_mm=12,
+)
+```
+This guarantees consistent sizing across editors, exports, and journals.
+
+### Figure Legends (Scientific Captions)
+
+Store publication-ready figure legends as metadata (not rendered on the figure):
+
+``` python
+fig, axes = fr.subplots(1, 2)
+
+# Figure legend (main description)
+fig.set_caption(
+    "Comparison of treatment effects on neural activity. "
+    "Data represent mean ± SEM."
+)
+
+# Panel legends (A, B, C, ...)
+axes[0].set_caption("Representative traces from control condition")
+axes[1].set_caption("Quantification across subjects (n=12)")
+
+# Access captions
+print(fig.caption)       # Figure legend
+print(axes[0].caption)   # Panel A legend
+
+# Auto-generate with statistics
+fig.set_stats({"comparisons": [{"name": "A vs B", "p_value": 0.003}]})
+full_legend = fig.generate_caption(style="publication")
+# → "Comparison of... (A) Representative traces... (B) Quantification... A vs B (p=0.003)."
+```
+
+Captions are saved in the recipe YAML and displayed in the GUI editor's caption pane below the canvas—ready for copy-paste into manuscripts.
+
 ### Interactive GUI Editor
 
 ``` python
@@ -259,16 +332,11 @@ The editor provides:
 |:---:|:---:|:---:|
 | ![Axis Panel](docs/images/editor_axis_panel.png) | ![Download](docs/images/editor_download_options.png) | ![Dark Mode](docs/images/editor_dark_mode.png) |
 
-### Style Format (YAML)
+<details>
+<summary><b>Style Format (YAML)</b> — Full preset example</summary>
 
 ``` yaml
-# Timestamp: "2025-12-22 12:40:36 (ywatanabe)"
-# File: ./src/figrecipe/styles/presets/SCITEX.yaml
-# FIGRECIPE Style Preset
-# ======================
-# Publication-quality settings for scientific figures.
-# Optimized for scientific journals with Arial font.
-
+# FIGRECIPE Style Preset (SCITEX)
 axes:
   width_mm: 40
   height_mm: 28
@@ -280,113 +348,46 @@ margins:
   bottom_mm: 1
   top_mm: 1
 
-spacing:
-  horizontal_mm: 8
-  vertical_mm: 10
-
 fonts:
   family: "Arial"
   axis_label_pt: 7
   tick_label_pt: 7
   title_pt: 8
-  suptitle_pt: 8
-  legend_pt: 6
-  annotation_pt: 6
-
-padding:
-  label_pt: 2.0
-  tick_pt: 2.0
-  title_pt: 4.0
 
 lines:
   trace_mm: 0.2
   errorbar_mm: 0.2
-  errorbar_cap_mm: 0.8
 
 ticks:
   length_mm: 0.8
   thickness_mm: 0.2
   direction: "out"
-  n_ticks: 4
-
-markers:
-  size_mm: 0.8
-  scatter_mm: 0.8
-  edge_width_mm: null  # None = no border (cleaner than 0)
-
-legend:
-  frameon: false         # No frame for clean look
-  bg: null               # Background (null = use theme.legend_bg)
-  edgecolor: null        # Frame edge color
-  alpha: 1.0             # Transparency
-  loc: "best"
 
 output:
   dpi: 300
   transparent: true
   format: "pdf"
 
-behavior:
-  auto_scale_axes: true
-  hide_top_spine: true
-  hide_right_spine: true
-  grid: false
-
 theme:
   mode: "light"
   dark:
-    figure_bg: "transparent"
-    axes_bg: "transparent"
-    legend_bg: "transparent"
     text: "#d4d4d4"
     spine: "#d4d4d4"
-    tick: "#d4d4d4"
-    grid: "#3a3a3a"
   light:
-    figure_bg: "transparent"
-    axes_bg: "transparent"
-    legend_bg: "transparent"
     text: "black"
     spine: "black"
-    tick: "black"
-    grid: "#cccccc"
 
-# SciTeX Color Palette (RGB format)
 colors:
   palette:
     - [0, 128, 192]      # blue
     - [255, 70, 50]      # red
     - [20, 180, 20]      # green
-    - [230, 160, 20]     # yellow
-    - [200, 50, 255]     # purple
-    - [20, 200, 200]     # lightblue
-    - [228, 94, 50]      # orange
-    - [255, 150, 200]    # pink
-
-  # Named colors
-  white: [255, 255, 255]
-  black: [0, 0, 0]
-  blue: [0, 128, 192]
-  red: [255, 70, 50]
-  pink: [255, 150, 200]
-  green: [20, 180, 20]
-  yellow: [230, 160, 20]
-  gray: [128, 128, 128]
-  grey: [128, 128, 128]
-  purple: [200, 50, 255]
-  lightblue: [20, 200, 200]
-  brown: [128, 0, 0]
-  navy: [0, 0, 100]
-  orange: [228, 94, 50]
-
-  # Semantic
-  primary: [0, 128, 192]
-  secondary: [255, 70, 50]
-  accent: [20, 180, 20]
-
 # EOF
 ```
 
+See [src/figrecipe/styles/presets/](src/figrecipe/styles/presets/) for complete examples.
+</details>
+
 
 ### API Overview
 
@@ -394,7 +395,7 @@ colors:
 |----------------------------------|---------------------------------------------------|
 | `import figrecipe.pyplot as plt` | Drop-in replacement of `matplotlib.pyplot as plt` |
 | `import figrecipe as fr`         | Import figrecipe package                          |
-|----------------------------------|---------------------------------------------------|
+
 | Function                         |                                                   |
 |----------------------------------|---------------------------------------------------|
 | `fr.subplots()`                  | Create a recording-enabled figure                 |
@@ -406,24 +407,21 @@ colors:
 | `fr.load_style()`                | Load style preset (global)                        |
 | `fr.list_presets()`              | List available presets                            |
 | `fr.crop('fig.png')`             | Crop to content with mm margin                    |
-
-## Positioning
-
-FigRecipe focuses on *how* figures are constructed, not *what* they represent.
-
-FigRecipe provides recording, reproduction, layout fidelity, and interactive editing.
-
-Higher-level workflows (figures–tables–statistics bundle, integration with manuscript writing) are handled in:
-
-FTS (Figure-Table-Statistics Bundle) in SciTeX Ecosystem:
-https://github.com/ywatanabe1989/scitex-code
-https://scitex.ai/vis/
-https://scitex.ai/writer/
+| `fig.set_caption(text)`          | Set figure legend (metadata)                      |
+| `ax.set_caption(text)`           | Set panel legend (metadata)                       |
 
 
 ## License
 
 AGPL-3.0 See [LICENSE](LICENSE)
-.
+
+## Contact
+Yusuke Watanabe (ywatanabe@scitex.ai)
+
+<p align="center">
+  <a href="https://scitex.ai" target="_blank">
+    <img src="docs/scitex-icon-navy-inverted.png" alt="SciTeX" width="80"/>
+  </a>
+</p>
 
 <!-- EOF -->