scitex 2.4.3__py3-none-any.whl → 2.5.0__py3-none-any.whl

scitex/plt/_subplots/_export_as_csv_formatters/_format_plot.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
-# Timestamp: "2025-12-01 13:30:00 (ywatanabe)"
+# Timestamp: "2025-12-08 18:45:00 (ywatanabe)"
 # File: ./src/scitex/plt/_subplots/_export_as_csv_formatters/_format_plot.py
 
 """CSV formatter for matplotlib plot() calls."""
@@ -12,6 +12,48 @@ import numpy as np
 import pandas as pd
 import xarray as xr
 
+from scitex.plt.utils._csv_column_naming import get_csv_column_name
+
+
+def _parse_tracking_id(id: str) -> tuple:
+    """Parse tracking ID to extract axes position and trace index.
+
+    Parameters
+    ----------
+    id : str
+        Tracking ID like "ax_00_plot_0" or "plot_0"
+
+    Returns
+    -------
+    tuple
+        (ax_row, ax_col, trace_index)
+    """
+    ax_row, ax_col, trace_index = 0, 0, 0
+
+    if id.startswith('ax_'):
+        parts = id.split('_')
+        if len(parts) >= 2:
+            ax_pos = parts[1]
+            if len(ax_pos) >= 2:
+                try:
+                    ax_row = int(ax_pos[0])
+                    ax_col = int(ax_pos[1])
+                except ValueError:
+                    pass
+        # Extract trace index from the rest (e.g., "plot_0" -> 0)
+        if len(parts) >= 4 and parts[2] == 'plot':
+            try:
+                trace_index = int(parts[3])
+            except ValueError:
+                pass
+    elif id.startswith('plot_'):
+        try:
+            trace_index = int(id.split('_')[1])
+        except (ValueError, IndexError):
+            pass
+
+    return ax_row, ax_col, trace_index
+
 
 def _format_plot(
     id: str,
@@ -30,7 +72,7 @@ def _format_plot(
     Parameters
     ----------
     id : str
-        Identifier prefix for the output columns (e.g., "ax_00").
+        Identifier prefix for the output columns (e.g., "ax_00_plot_0").
     tracked_dict : dict or None
         Dictionary containing tracked data. May include:
         - 'plot_df': Pre-formatted DataFrame from wrapper
@@ -41,25 +83,40 @@ def _format_plot(
     Returns
     -------
     pd.DataFrame
-        Formatted data with columns prefixed by id.
-        For 1D data: {id}_plot_x, {id}_plot_y
-        For 2D data: {id}_plot_x00, {id}_plot_y00, {id}_plot_x01, ...
+        Formatted data with columns using single source of truth naming.
+        For 1D data: ax_00_plot_0_plot_x, ax_00_plot_0_plot_y
     """
     # Check if tracked_dict is empty or not a dictionary
     if not tracked_dict or not isinstance(tracked_dict, dict):
         return pd.DataFrame()
 
+    # Parse the tracking ID to get axes position and trace index
+    ax_row, ax_col, trace_index = _parse_tracking_id(id)
+
     # For stx_line, we expect a 'plot_df' key
     if 'plot_df' in tracked_dict:
         plot_df = tracked_dict['plot_df']
         if isinstance(plot_df, pd.DataFrame):
-            # Add the id prefix to all columns
-            return plot_df.add_prefix(f"{id}_")
+            # Rename columns using single source of truth
+            renamed = {}
+            for col in plot_df.columns:
+                if col == 'plot_x':
+                    renamed[col] = get_csv_column_name('plot_x', ax_row, ax_col, trace_index=trace_index)
+                elif col == 'plot_y':
+                    renamed[col] = get_csv_column_name('plot_y', ax_row, ax_col, trace_index=trace_index)
+                else:
+                    # For other columns, just prefix with id
+                    renamed[col] = f"{id}_{col}"
+            return plot_df.rename(columns=renamed)
 
     # Handle raw args from __getattr__ proxied calls
     if 'args' in tracked_dict:
         args = tracked_dict['args']
         if isinstance(args, tuple) and len(args) > 0:
+            # Get column names from single source of truth
+            x_col = get_csv_column_name('plot_x', ax_row, ax_col, trace_index=trace_index)
+            y_col = get_csv_column_name('plot_y', ax_row, ax_col, trace_index=trace_index)
+
             # Handle single argument: plot(y) or plot(data_2d)
             if len(args) == 1:
                 args_value = args[0]
@@ -72,14 +129,14 @@ def _format_plot(
                 # 2D array: extract x and y columns
                 if hasattr(args_value, 'ndim') and args_value.ndim == 2:
                     x, y = args_value[:, 0], args_value[:, 1]
-                    df = pd.DataFrame({f"{id}_plot_x": x, f"{id}_plot_y": y})
+                    df = pd.DataFrame({x_col: x, y_col: y})
                     return df
 
                 # 1D array: generate x from indices (common case: plot(y))
                 elif hasattr(args_value, 'ndim') and args_value.ndim == 1:
                     x = np.arange(len(args_value))
                     y = args_value
-                    df = pd.DataFrame({f"{id}_plot_x": x, f"{id}_plot_y": y})
+                    df = pd.DataFrame({x_col: x, y_col: y})
                     return df
 
             # Handle two arguments: plot(x, y)
@@ -94,22 +151,20 @@ def _format_plot(
                 if hasattr(y, 'ndim') and y.ndim == 2:
                     out = OrderedDict()
                     for ii in range(y.shape[1]):
-                        out[f"{id}_plot_x{ii:02d}"] = x
-                        out[f"{id}_plot_y{ii:02d}"] = y[:, ii]
+                        x_col_i = get_csv_column_name(f'plot_x{ii:02d}', ax_row, ax_col, trace_index=trace_index)
+                        y_col_i = get_csv_column_name(f'plot_y{ii:02d}', ax_row, ax_col, trace_index=trace_index)
+                        out[x_col_i] = x
+                        out[y_col_i] = y[:, ii]
                     df = pd.DataFrame(out)
                     return df
 
                 # Handle DataFrame y
                 if isinstance(y_arg, pd.DataFrame):
-                    df = pd.DataFrame(
-                        {
-                            f"{id}_plot_x": x,
-                            **{
-                                f"{id}_plot_y{ii:02d}": np.array(y_arg[col])
-                                for ii, col in enumerate(y_arg.columns)
-                            },
-                        }
-                    )
+                    result = {x_col: x}
+                    for ii, col in enumerate(y_arg.columns):
+                        y_col_i = get_csv_column_name(f'plot_y{ii:02d}', ax_row, ax_col, trace_index=trace_index)
+                        result[y_col_i] = np.array(y_arg[col])
+                    df = pd.DataFrame(result)
                     return df
 
                 # Handle 1D arrays (most common case: plot(x, y))
@@ -117,11 +172,11 @@ def _format_plot(
                     # Flatten x if needed
                     x_flat = np.ravel(x)
                     y_flat = np.ravel(y)
-                    df = pd.DataFrame({f"{id}_plot_x": x_flat, f"{id}_plot_y": y_flat})
+                    df = pd.DataFrame({x_col: x_flat, y_col: y_flat})
                     return df
 
                 # Fallback for list-like y
-                df = pd.DataFrame({f"{id}_plot_x": np.ravel(x), f"{id}_plot_y": np.ravel(y)})
+                df = pd.DataFrame({x_col: np.ravel(x), y_col: np.ravel(y)})
                 return df
 
     # Default empty DataFrame if we can't process the input

scitex/plt/docs/FIGURE_ARCHITECTURE.md

@@ -0,0 +1,257 @@
+<!-- ---
+!-- Timestamp: 2025-12-08 16:05:55
+!-- Author: ywatanabe
+!-- File: /home/ywatanabe/proj/scitex-code/src/scitex/plt/docs/FIGURE_ARCHITECTURE.md
+!-- --- -->
+
+# Figure Architecture for scitex.plt
+
+## Terminology
+
+| Term       | Meaning                      | In Code                        |
+|------------|------------------------------|--------------------------------|
+| **Figure** | A matplotlib figure object   | `fig, ax = stx.plt.subplots()` |
+| **Axes**   | A single subplot/axes        | `ax.plot(x, y)`                |
+| **Panel**  | Used in `scitex.vis` context | See CANVAS_ARCHITECTURE.md     |
+
+## Output Format
+
+`stx.plt` outputs **3 files per figure**:
+
+```
+output_dir/
+├── 01_plot.png      # Rendered image
+├── 01_plot.json     # Metadata (dimensions, axes, traces, styles)
+└── 01_plot.csv      # Raw data (columns referenced in JSON)
+```
+
+### Save Patterns
+
+**Flat (default):**
+```python
+fig.savefig("./01_plot.png")
+# Creates: 01_plot.png, 01_plot.json, 01_plot.csv
+```
+
+**Organized by extension:**
+```python
+fig.savefig("./png/01_plot.png")
+# Creates: png/01_plot.png, json/01_plot.json, csv/01_plot.csv
+```
+
+## JSON Schema (panel.json)
+
+```json
+{
+  "metadata_version": "1.1.0",
+  "scitex": {
+    "version": "2.4.3",
+    "created_at": "2025-12-08T15:40:58.453762",
+    "created_with": "scitex.plt.subplots (mm-control)",
+    "mode": "publication",
+    "axes_size_mm": [40, 28],
+    "position_in_grid": [0, 0],
+    "style_mm": {
+      "axis_thickness_mm": 0.2,
+      "tick_length_mm": 0.8,
+      "tick_thickness_mm": 0.2,
+      "trace_thickness_mm": 0.2,
+      "marker_size_mm": 0.8,
+      "axis_font_size_pt": 7,
+      "tick_font_size_pt": 7,
+      "title_font_size_pt": 8,
+      "legend_font_size_pt": 6,
+      "font_family": "Arial",
+      "n_ticks": 4
+    }
+  },
+  "matplotlib": {
+    "version": "3.10.3"
+  },
+  "id": "01_plot",
+  "dimensions": {
+    "figure_size_mm": [80.0, 68.0],
+    "figure_size_inch": [3.15, 2.68],
+    "figure_size_px": [944, 803],
+    "axes_size_mm": [40.0, 28.0],
+    "axes_size_inch": [1.57, 1.10],
+    "axes_size_px": [472, 330],
+    "axes_position": [0.25, 0.29, 0.5, 0.41],
+    "dpi": 300
+  },
+  "margins_mm": {
+    "left": 20.0,
+    "bottom": 20.0,
+    "right": 20.0,
+    "top": 20.0
+  },
+  "axes_bbox_px": {
+    "x0": 236,
+    "y0": 236,
+    "x1": 708,
+    "y1": 566,
+    "width": 472,
+    "height": 330
+  },
+  "axes_bbox_mm": {
+    "x0": 20.0,
+    "y0": 20.0,
+    "x1": 60.0,
+    "y1": 48.0,
+    "width": 40.0,
+    "height": 28.0
+  },
+  "axes": {
+    "x": {
+      "label": "Time",
+      "unit": "s",
+      "scale": "linear",
+      "lim": [-0.31, 6.60],
+      "n_ticks": 4
+    },
+    "y": {
+      "label": "Amplitude",
+      "unit": "a.u.",
+      "scale": "linear",
+      "lim": [-1.10, 1.10],
+      "n_ticks": 4
+    }
+  },
+  "title": "ax.plot(x, y)",
+  "plot_type": "line",
+  "method": "plot",
+  "traces": [
+    {
+      "id": "sine",
+      "label": "sin(x)",
+      "color": "#0000ff",
+      "linestyle": "-",
+      "linewidth": 0.57,
+      "csv_columns": {
+        "x": "ax_00_sine_plot_x",
+        "y": "ax_00_sine_plot_y"
+      }
+    },
+    {
+      "id": "cosine",
+      "label": "cos(x)",
+      "color": "#ff0000",
+      "linestyle": "--",
+      "linewidth": 0.57,
+      "csv_columns": {
+        "x": "ax_00_cosine_plot_x",
+        "y": "ax_00_cosine_plot_y"
+      }
+    }
+  ],
+  "legend": {
+    "visible": true,
+    "loc": 0,
+    "frameon": false,
+    "labels": ["sin(x)", "cos(x)"]
+  }
+}
+```
+
+## CSV Format
+
+Column naming convention: `ax_{ax_idx}_{trace_id}_{method}_{dim}`
+
+```csv
+ax_00_sine_plot_x,ax_00_sine_plot_y,ax_00_cosine_plot_x,ax_00_cosine_plot_y
+0.0,0.0,0.0,1.0
+0.063,0.063,0.063,0.998
+0.127,0.127,0.127,0.992
+...
+```
+
+## Key Features
+
+### Publication Mode
+
+```python
+fig, ax = stx.plt.subplots(
+    fig_mm={"width": 80, "height": 68},
+    axes_mm={"width": 40, "height": 28},
+    mode="publication"
+)
+```
+
+- All dimensions in **millimeters** for publication standards
+- Consistent styling across figures
+- Automatic metadata embedding
+
+### Automatic Export
+
+On `fig.savefig()`:
+1. PNG/PDF/SVG rendered
+2. JSON metadata exported
+3. CSV data exported
+
+### Trace Tracking
+
+All plotting calls are tracked:
+
+```python
+ax.plot(x, y, id="sine", label="sin(x)")  # Tracked
+ax.scatter(x, y, id="points")              # Tracked
+ax.stx_line(x, y, id="trace")              # Tracked
+```
+
+## Supported Plot Methods
+
+### Standard Matplotlib
+- `plot`, `scatter`, `bar`, `barh`
+- `hist`, `hist2d`, `hexbin`
+- `boxplot`, `violinplot`
+- `fill_between`, `fill_betweenx`
+- `errorbar`, `contour`, `contourf`
+- `imshow`, `matshow`, `pie`
+- `quiver`, `streamplot`
+- `stem`, `step`, `eventplot`
+
+### SciTeX Extensions
+- `stx_line`, `stx_shaded_line`
+- `stx_mean_std`, `stx_mean_ci`, `stx_median_iqr`
+- `stx_kde`, `stx_ecdf`
+- `stx_box`, `stx_violin`
+- `stx_bar`, `stx_barh`
+- `stx_scatter`, `stx_scatter_hist`
+- `stx_heatmap`, `stx_conf_mat`
+- `stx_image`, `stx_imshow`
+- `stx_fillv`, `stx_contour`
+- `stx_raster`, `stx_joyplot`
+- `stx_rectangle`
+
+### Seaborn Integration
+- `sns_lineplot`, `sns_scatterplot`
+- `sns_barplot`, `sns_boxplot`, `sns_violinplot`
+- `sns_stripplot`, `sns_swarmplot`
+- `sns_histplot`, `sns_kdeplot`
+- `sns_heatmap`, `sns_jointplot`, `sns_pairplot`
+
+## Integration with scitex.vis
+
+stx.plt outputs can be used as `scitex` type panels in a canvas:
+
+```
+canvas/panels/panel_a/
+├── panel.json    # Renamed from 01_plot.json
+├── panel.csv     # Renamed from 01_plot.csv
+└── panel.png     # Renamed from 01_plot.png
+```
+
+The JSON structure is compatible - canvas.json references the panel data via relative paths with hash verification.
+
+## Summary
+
+| Aspect      | Description                        |
+|-------------|------------------------------------|
+| Output      | PNG + JSON + CSV per figure        |
+| Units       | Millimeters for publication        |
+| Tracking    | All traces tracked with IDs        |
+| Metadata    | Dimensions, styles, axes info      |
+| Data        | CSV with column references in JSON |
+| Integration | Direct use as canvas panels        |
+
+<!-- EOF -->

scitex/plt/utils/__init__.py

@@ -22,6 +22,12 @@ from ._figure_from_axes_mm import (
 )
 from ._units import inch_to_mm, mm_to_inch, mm_to_pt, pt_to_mm
 from ._collect_figure_metadata import collect_figure_metadata
+from ._csv_column_naming import (
+    get_csv_column_name,
+    get_csv_column_prefix,
+    parse_csv_column_name,
+    sanitize_trace_id,
+)
 
 __all__ = [
     "HistogramBinManager",
@@ -47,6 +53,8 @@ __all__ = [
     "cross_ref",
     "enhance_scitex_save_with_captions",
     "export_captions",
+    "get_csv_column_name",
+    "get_csv_column_prefix",
     "get_dimension_info",
     "get_scitex_config",
     "histogram_bin_manager",
@@ -57,9 +65,11 @@ __all__ = [
     "mk_patches",
     "mm_to_inch",
     "mm_to_pt",
+    "parse_csv_column_name",
     "print_dimension_info",
     "pt_to_mm",
     "quick_caption",
+    "sanitize_trace_id",
     "save_with_caption",
     "view_dimensions",
 ]

scitex/plt/utils/_collect_figure_metadata.py

@@ -349,14 +349,15 @@ def _extract_traces(ax) -> list:
         and csv_columns mapping
     """
     import matplotlib.colors as mcolors
+    from ._csv_column_naming import get_csv_column_name, sanitize_trace_id
 
     traces = []
 
     # Get axes position for CSV column naming
-    ax_pos = "00"  # Default for single axes
+    ax_row, ax_col = 0, 0  # Default for single axes
     if hasattr(ax, '_scitex_metadata') and 'position_in_grid' in ax._scitex_metadata:
         pos = ax._scitex_metadata['position_in_grid']
-        ax_pos = f"{pos[0]}{pos[1]}"
+        ax_row, ax_col = pos[0], pos[1]
 
     for i, line in enumerate(ax.lines):
         trace = {}
@@ -369,14 +370,16 @@ def _extract_traces(ax) -> list:
         label = line.get_label()
 
         # Determine trace_id for CSV column matching
+        # Use index-based ID to match CSV export (single source of truth)
+        trace_id_for_csv = None  # Will use trace_index in get_csv_column_name
+
+        # Store display id/label separately
         if scitex_id:
-            trace_id = scitex_id
+            trace["id"] = scitex_id
         elif not label.startswith('_'):
-            trace_id = label
+            trace["id"] = label
         else:
-            trace_id = f"line_{i}"
-
-        trace["id"] = trace_id
+            trace["id"] = f"line_{i}"
 
         # Label (for legend) - use label if not internal
         if not label.startswith('_'):
@@ -404,12 +407,11 @@ def _extract_traces(ax) -> list:
             trace["marker"] = marker
             trace["markersize"] = line.get_markersize()
 
-        # CSV column mapping - this is how we'll reconstruct from CSV
-        # Format matches what _export_as_csv generates: ax_{row}{col}_{id}_plot_x/y
-        # The id should match the id= kwarg passed to ax.plot()
+        # CSV column mapping - use single source of truth
+        # Uses trace_index to match what _export_as_csv generates
         trace["csv_columns"] = {
-            "x": f"ax_{ax_pos}_{trace_id}_plot_x",
-            "y": f"ax_{ax_pos}_{trace_id}_plot_y",
+            "x": get_csv_column_name("plot_x", ax_row, ax_col, trace_index=i),
+            "y": get_csv_column_name("plot_y", ax_row, ax_col, trace_index=i),
         }
 
         traces.append(trace)