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

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)

scitex/plt/utils/_csv_column_naming.py

@@ -0,0 +1,237 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: 2025-12-08
+# File: ./src/scitex/plt/utils/_csv_column_naming.py
+
+"""
+Single source of truth for CSV column naming in scitex.
+
+This module ensures consistent column naming between:
+- CSV export (_export_as_csv)
+- JSON metadata (_collect_figure_metadata)
+- GUI editors (reading CSV data back)
+
+Column naming convention:
+    ax_{row}{col}_{trace_id}_{data_type}
+
+Where:
+    - row, col: axes position in grid (e.g., "00" for single axes)
+    - trace_id: unique identifier for the trace (from label, id kwarg, or index)
+    - data_type: type of data (e.g., "plot_x", "plot_y", "hist_bins", etc.)
+"""
+
+__all__ = [
+    'get_csv_column_name',
+    'get_csv_column_prefix',
+    'parse_csv_column_name',
+    'sanitize_trace_id',
+]
+
+
+def sanitize_trace_id(trace_id: str) -> str:
+    """Sanitize trace ID for use in CSV column names.
+
+    Removes or replaces characters that could cause issues in column names.
+
+    Parameters
+    ----------
+    trace_id : str
+        Raw trace identifier (label, id kwarg, or generated)
+
+    Returns
+    -------
+    str
+        Sanitized trace ID safe for CSV column names
+    """
+    if not trace_id:
+        return "unnamed"
+
+    # Replace problematic characters
+    sanitized = str(trace_id)
+    # Keep alphanumeric, underscore, hyphen; replace others with underscore
+    result = []
+    for char in sanitized:
+        if char.isalnum() or char in ('_', '-'):
+            result.append(char)
+        elif char in (' ', '(', ')', '[', ']', '{', '}', '/', '\\', '.'):
+            result.append('_')
+        # Skip other characters
+
+    sanitized = ''.join(result)
+
+    # Remove consecutive underscores
+    while '__' in sanitized:
+        sanitized = sanitized.replace('__', '_')
+
+    # Remove leading/trailing underscores
+    sanitized = sanitized.strip('_')
+
+    return sanitized if sanitized else "unnamed"
+
+
+def get_csv_column_prefix(ax_row: int = 0, ax_col: int = 0, trace_id: str = None, trace_index: int = None) -> str:
+    """Get CSV column prefix for a trace.
+
+    Parameters
+    ----------
+    ax_row : int
+        Row position of axes in grid (default: 0)
+    ax_col : int
+        Column position of axes in grid (default: 0)
+    trace_id : str, optional
+        Trace identifier (from label or id kwarg). If None, uses trace_index.
+    trace_index : int, optional
+        Index of trace when no trace_id is provided (default: 0)
+
+    Returns
+    -------
+    str
+        Column prefix like "ax_00_sin_x_" or "ax_01_plot_0_"
+    """
+    ax_pos = f"{ax_row}{ax_col}"
+
+    if trace_id:
+        safe_id = sanitize_trace_id(trace_id)
+    elif trace_index is not None:
+        safe_id = f"plot_{trace_index}"
+    else:
+        safe_id = "plot_0"
+
+    return f"ax_{ax_pos}_{safe_id}_"
+
+
+def get_csv_column_name(
+    data_type: str,
+    ax_row: int = 0,
+    ax_col: int = 0,
+    trace_id: str = None,
+    trace_index: int = None,
+) -> str:
+    """Get full CSV column name for a data field.
+
+    Parameters
+    ----------
+    data_type : str
+        Type of data (e.g., "plot_x", "plot_y", "hist_bins", "bar_heights")
+    ax_row : int
+        Row position of axes in grid (default: 0)
+    ax_col : int
+        Column position of axes in grid (default: 0)
+    trace_id : str, optional
+        Trace identifier (from label or id kwarg)
+    trace_index : int, optional
+        Index of trace when no trace_id is provided
+
+    Returns
+    -------
+    str
+        Full column name like "ax_00_sin_x_plot_x" or "ax_01_plot_0_plot_y"
+
+    Examples
+    --------
+    >>> get_csv_column_name("plot_x", trace_id="sin(x)")
+    'ax_00_sin_x_plot_x'
+    >>> get_csv_column_name("plot_y", ax_row=1, ax_col=2, trace_index=0)
+    'ax_12_plot_0_plot_y'
+    """
+    prefix = get_csv_column_prefix(ax_row, ax_col, trace_id, trace_index)
+    return f"{prefix}{data_type}"
+
+
+def parse_csv_column_name(column_name: str) -> dict:
+    """Parse CSV column name to extract components.
+
+    Parameters
+    ----------
+    column_name : str
+        Full column name (e.g., "ax_00_sin_x_plot_x")
+
+    Returns
+    -------
+    dict
+        Dictionary with keys:
+        - ax_row: int
+        - ax_col: int
+        - trace_id: str
+        - data_type: str
+        - valid: bool (True if parsing succeeded)
+
+    Examples
+    --------
+    >>> parse_csv_column_name("ax_00_sin_x_plot_x")
+    {'ax_row': 0, 'ax_col': 0, 'trace_id': 'sin_x', 'data_type': 'plot_x', 'valid': True}
+    """
+    result = {
+        'ax_row': 0,
+        'ax_col': 0,
+        'trace_id': '',
+        'data_type': '',
+        'valid': False,
+    }
+
+    if not column_name or not column_name.startswith('ax_'):
+        return result
+
+    parts = column_name.split('_')
+    if len(parts) < 4:
+        return result
+
+    try:
+        # Parse ax position (e.g., "00" from "ax_00_...")
+        ax_pos = parts[1]
+        if len(ax_pos) >= 2:
+            result['ax_row'] = int(ax_pos[0])
+            result['ax_col'] = int(ax_pos[1])
+
+        # Last two parts are typically data_type (e.g., "plot_x", "hist_bins")
+        # Everything in between is the trace_id
+        data_type_parts = parts[-2:]  # e.g., ["plot", "x"]
+        result['data_type'] = '_'.join(data_type_parts)
+
+        # Trace ID is everything between ax_pos and data_type
+        trace_parts = parts[2:-2]
+        result['trace_id'] = '_'.join(trace_parts) if trace_parts else 'plot_0'
+
+        result['valid'] = True
+
+    except (ValueError, IndexError):
+        pass
+
+    return result
+
+
+def get_trace_columns_from_df(df, trace_id: str = None, trace_index: int = None, ax_row: int = 0, ax_col: int = 0) -> dict:
+    """Find CSV columns for a specific trace in a DataFrame.
+
+    Parameters
+    ----------
+    df : pandas.DataFrame
+        DataFrame with CSV data
+    trace_id : str, optional
+        Trace identifier to search for
+    trace_index : int, optional
+        Trace index to search for (if trace_id not provided)
+    ax_row : int
+        Row position of axes
+    ax_col : int
+        Column position of axes
+
+    Returns
+    -------
+    dict
+        Dictionary mapping data types to column names, e.g.:
+        {'plot_x': 'ax_00_sin_x_plot_x', 'plot_y': 'ax_00_sin_x_plot_y'}
+    """
+    result = {}
+    prefix = get_csv_column_prefix(ax_row, ax_col, trace_id, trace_index)
+
+    for col in df.columns:
+        if col.startswith(prefix):
+            # Extract data_type from column name
+            data_type = col[len(prefix):]
+            result[data_type] = col
+
+    return result
+
+
+# EOF

scitex/scholar/citation_graph/database.py

@@ -44,9 +44,16 @@ class CitationDatabase:
             read_only: If True, open in read-only mode (default)
         """
         if read_only:
-            self.conn = sqlite3.connect(f"file:{self.db_path}?mode=ro", uri=True)
+            self.conn = sqlite3.connect(
+                f"file:{self.db_path}?mode=ro",
+                uri=True,
+                check_same_thread=False  # Allow multi-threaded access (e.g., Django)
+            )
         else:
-            self.conn = sqlite3.connect(self.db_path)
+            self.conn = sqlite3.connect(
+                self.db_path,
+                check_same_thread=False
+            )
 
         self.conn.row_factory = sqlite3.Row
 

scitex/scholar/config/ScholarConfig.py

@@ -29,8 +29,22 @@ logger = getLogger(__name__)
 
 
 class ScholarConfig:
-    def __init__(self, config_path: Optional[Union[str, Path]] = None):
+    def __init__(
+        self,
+        config_path: Optional[Union[str, Path]] = None,
+        scholar_dir: Optional[Union[str, Path]] = None,
+    ):
+        """Initialize ScholarConfig.
+
+        Args:
+            config_path: Path to custom config YAML file
+            scholar_dir: Direct path to scholar directory (e.g., /data/users/alice/.scitex)
+                        This bypasses SCITEX_DIR env var for thread-safe multi-user usage.
+                        Use this in Django/multi-user environments to avoid race conditions.
+        """
         self.name = self.__class__.__name__
+        self._explicit_scholar_dir = scholar_dir  # Store for thread-safe access
+
         if config_path and Path(config_path).exists():
             config_data = self.load_yaml(config_path)
         else:
@@ -114,8 +128,14 @@ class ScholarConfig:
 
     # Path Management ----------------------------------------
     def _setup_path_manager(self, scholar_dir=None):
-        scholar_dir = self.cascade.resolve("scholar_dir", default="~/.scitex")
-        base_path = Path(scholar_dir).expanduser() / "scholar"
+        # Priority: explicit parameter > env var > config > default
+        if self._explicit_scholar_dir:
+            # Use explicitly provided path (thread-safe for multi-user)
+            base_path = Path(self._explicit_scholar_dir).expanduser() / "scholar"
+        else:
+            # Fall back to cascade resolution (uses SCITEX_DIR env var)
+            scholar_dir = self.cascade.resolve("scholar_dir", default="~/.scitex")
+            base_path = Path(scholar_dir).expanduser() / "scholar"
         self.path_manager = PathManager(scholar_dir=base_path)
 
     @property