scitex 2.8.1__py3-none-any.whl → 2.10.0__py3-none-any.whl

scitex/schema/_encoding.py

@@ -0,0 +1,273 @@
+#!/usr/bin/env python3
+# Timestamp: 2025-12-19
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/schema/_encoding.py
+
+"""
+Encoding Schema - Data to Visual Mapping for Scientific Rigor.
+
+This module defines the encoding layer that maps data columns to visual channels.
+This separation ensures scientific reproducibility by explicitly documenting
+how data is transformed into visual representation.
+
+Encoding (encoding.json) - Data→Visual Mapping:
+  - Column bindings (x, y, color, size, shape)
+  - Data transformations (log, normalize, bin)
+  - Scale types (linear, log, categorical)
+  - Missing value handling
+"""
+
+import json
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+ENCODING_VERSION = "1.0.0"
+
+
+@dataclass
+class ChannelBinding:
+    """
+    Binding from data column to visual channel.
+
+    Parameters
+    ----------
+    channel : str
+        Visual channel (x, y, color, size, shape, opacity, etc.)
+    column : str
+        Data column name
+    scale : str
+        Scale type (linear, log, sqrt, categorical, ordinal)
+    domain : list, optional
+        Data domain [min, max] or list of categories
+    range : list, optional
+        Visual range (e.g., [0, 1] for opacity, color palette for color)
+    transform : str, optional
+        Data transformation (log, sqrt, normalize, zscore, rank)
+    """
+
+    channel: str
+    column: str
+    scale: str = "linear"
+    domain: Optional[List[Any]] = None
+    range: Optional[List[Any]] = None
+    transform: Optional[str] = None
+    missing_value: Optional[str] = "drop"  # "drop", "zero", "mean", "interpolate"
+
+    def to_dict(self) -> Dict[str, Any]:
+        result = {
+            "channel": self.channel,
+            "column": self.column,
+            "scale": self.scale,
+        }
+        if self.domain is not None:
+            result["domain"] = self.domain
+        if self.range is not None:
+            result["range"] = self.range
+        if self.transform:
+            result["transform"] = self.transform
+        if self.missing_value != "drop":
+            result["missing_value"] = self.missing_value
+        return result
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "ChannelBinding":
+        return cls(**{k: v for k, v in data.items() if k in cls.__dataclass_fields__})
+
+
+@dataclass
+class TraceEncoding:
+    """
+    Encoding specification for a single trace.
+
+    Parameters
+    ----------
+    trace_id : str
+        ID of the trace this encoding applies to
+    bindings : list of ChannelBinding
+        Column to channel bindings
+    aggregate : str, optional
+        Aggregation method (mean, median, sum, count, etc.)
+    group_by : list, optional
+        Columns to group by before aggregation
+    """
+
+    trace_id: str
+    bindings: List[ChannelBinding] = field(default_factory=list)
+    aggregate: Optional[str] = None
+    group_by: Optional[List[str]] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        result = {
+            "trace_id": self.trace_id,
+            "bindings": [b.to_dict() for b in self.bindings],
+        }
+        if self.aggregate:
+            result["aggregate"] = self.aggregate
+        if self.group_by:
+            result["group_by"] = self.group_by
+        return result
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "TraceEncoding":
+        bindings = [ChannelBinding.from_dict(b) for b in data.get("bindings", [])]
+        return cls(
+            trace_id=data.get("trace_id", ""),
+            bindings=bindings,
+            aggregate=data.get("aggregate"),
+            group_by=data.get("group_by"),
+        )
+
+
+@dataclass
+class PlotEncoding:
+    """
+    Complete encoding specification for a plot.
+
+    Stored in encoding.json. Documents how data maps to visual channels
+    for scientific reproducibility.
+
+    Parameters
+    ----------
+    traces : list of TraceEncoding
+        Per-trace encoding specifications
+    data_hash : str, optional
+        Hash of source data for integrity verification
+    """
+
+    traces: List[TraceEncoding] = field(default_factory=list)
+    data_hash: Optional[str] = None
+
+    # Schema metadata
+    scitex_schema: str = "scitex.plt.encoding"
+    scitex_schema_version: str = ENCODING_VERSION
+
+    def to_dict(self) -> Dict[str, Any]:
+        result = {
+            "schema": {
+                "name": self.scitex_schema,
+                "version": self.scitex_schema_version,
+            },
+            "traces": [t.to_dict() for t in self.traces],
+        }
+        if self.data_hash:
+            result["data_hash"] = self.data_hash
+        return result
+
+    def to_json(self, indent: int = 2) -> str:
+        return json.dumps(self.to_dict(), indent=indent)
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "PlotEncoding":
+        return cls(
+            traces=[TraceEncoding.from_dict(t) for t in data.get("traces", [])],
+            data_hash=data.get("data_hash"),
+        )
+
+    @classmethod
+    def from_json(cls, json_str: str) -> "PlotEncoding":
+        return cls.from_dict(json.loads(json_str))
+
+    @classmethod
+    def from_spec_and_style(cls, spec: dict, style: dict) -> "PlotEncoding":
+        """
+        Create encoding from spec and style for backward compatibility.
+
+        Extracts column bindings from PlotSpec traces and color/size mappings
+        from PlotStyle trace overrides.
+        """
+        traces = []
+        spec_traces = spec.get("traces", [])
+        style_traces = {t.get("trace_id"): t for t in style.get("traces", [])}
+
+        for trace in spec_traces:
+            trace_id = trace.get("id", "")
+            bindings = []
+
+            # X column
+            if trace.get("x_col"):
+                bindings.append(
+                    ChannelBinding(
+                        channel="x",
+                        column=trace["x_col"],
+                    )
+                )
+
+            # Y column
+            if trace.get("y_col"):
+                bindings.append(
+                    ChannelBinding(
+                        channel="y",
+                        column=trace["y_col"],
+                    )
+                )
+
+            # Data columns (for boxplot, etc.)
+            for i, col in enumerate(trace.get("data_cols", [])):
+                bindings.append(
+                    ChannelBinding(
+                        channel=f"data_{i}",
+                        column=col,
+                    )
+                )
+
+            # Value column (for heatmap)
+            if trace.get("value_col"):
+                bindings.append(
+                    ChannelBinding(
+                        channel="value",
+                        column=trace["value_col"],
+                    )
+                )
+
+            # Vector columns (for quiver)
+            if trace.get("u_col"):
+                bindings.append(
+                    ChannelBinding(
+                        channel="u",
+                        column=trace["u_col"],
+                    )
+                )
+            if trace.get("v_col"):
+                bindings.append(
+                    ChannelBinding(
+                        channel="v",
+                        column=trace["v_col"],
+                    )
+                )
+
+            # Style overrides that are data-driven
+            style_trace = style_traces.get(trace_id, {})
+            if style_trace.get("color_by"):
+                bindings.append(
+                    ChannelBinding(
+                        channel="color",
+                        column=style_trace["color_by"],
+                    )
+                )
+            if style_trace.get("size_by"):
+                bindings.append(
+                    ChannelBinding(
+                        channel="size",
+                        column=style_trace["size_by"],
+                    )
+                )
+
+            if bindings:
+                traces.append(
+                    TraceEncoding(
+                        trace_id=trace_id,
+                        bindings=bindings,
+                    )
+                )
+
+        return cls(traces=traces)
+
+
+__all__ = [
+    "ENCODING_VERSION",
+    "ChannelBinding",
+    "TraceEncoding",
+    "PlotEncoding",
+]
+
+
+# EOF

scitex/schema/_figure_elements.py

@@ -0,0 +1,406 @@
+#!/usr/bin/env python3
+# Timestamp: 2025-12-19
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/schema/_figure_elements.py
+
+"""
+Figure Elements Schema - Title, Caption, and Panel Labels.
+
+This module defines figure-level text elements that appear in theme.json
+for editability while maintaining consistent styling across the figure.
+
+These elements enable auto-generation of publication-ready captions:
+  "Figure 1: Main Results. (A) Time-series analysis. (B) Frequency distribution."
+"""
+
+from dataclasses import asdict, dataclass, field
+from typing import Any, Dict, List, Optional
+
+FIGURE_ELEMENTS_VERSION = "1.0.0"
+
+
+@dataclass
+class FigureTitle:
+    """
+    Figure title specification.
+
+    Parameters
+    ----------
+    text : str
+        The main title text (e.g., "Main Results")
+    prefix : str
+        Prefix before number (e.g., "Figure", "Fig.")
+    number : int, optional
+        Figure number (None for unnumbered)
+    font_size_pt : float
+        Title font size in points
+    font_weight : str
+        Font weight (normal, bold)
+    position : str
+        Position (top, bottom)
+    visible : bool
+        Whether to render the title
+    """
+
+    text: str = ""
+    prefix: str = "Figure"
+    number: Optional[int] = None
+    font_size_pt: float = 10.0
+    font_weight: str = "bold"
+    position: str = "top"
+    visible: bool = True
+
+    def format(self, include_number: bool = True) -> str:
+        """Format the title as displayed string."""
+        if include_number and self.number is not None:
+            return f"{self.prefix} {self.number}: {self.text}"
+        elif self.text:
+            return self.text
+        return ""
+
+    def to_dict(self) -> Dict[str, Any]:
+        result = {
+            "text": self.text,
+            "prefix": self.prefix,
+            "font_size_pt": self.font_size_pt,
+            "font_weight": self.font_weight,
+            "position": self.position,
+            "visible": self.visible,
+        }
+        if self.number is not None:
+            result["number"] = self.number
+        return result
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "FigureTitle":
+        return cls(**{k: v for k, v in data.items() if k in cls.__dataclass_fields__})
+
+
+@dataclass
+class Caption:
+    """
+    Figure caption specification.
+
+    Parameters
+    ----------
+    text : str
+        Manual caption text (overrides auto-generation if set)
+    auto_generate : bool
+        Whether to auto-generate from panel descriptions
+    font_size_pt : float
+        Caption font size in points
+    position : str
+        Position (top, bottom)
+    visible : bool
+        Whether to render the caption
+    """
+
+    text: str = ""
+    auto_generate: bool = True
+    font_size_pt: float = 8.0
+    position: str = "bottom"
+    visible: bool = True
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Caption":
+        return cls(**{k: v for k, v in data.items() if k in cls.__dataclass_fields__})
+
+
+@dataclass
+class PanelLabels:
+    """
+    Panel label styling for multi-panel figures.
+
+    Controls how panel letters (A, B, C, ...) are rendered on child plots.
+
+    Parameters
+    ----------
+    style : str
+        Letter style: "uppercase" (A, B, C), "lowercase" (a, b, c),
+        "roman" (i, ii, iii), "Roman" (I, II, III)
+    format : str
+        Format template with {letter} placeholder
+    font_size_pt : float
+        Label font size in points
+    font_weight : str
+        Font weight (normal, bold)
+    position : str
+        Position on panel (top-left, top-right, bottom-left, bottom-right)
+    offset_mm : dict
+        Offset from corner {x: mm, y: mm}
+    visible : bool
+        Whether to render panel labels
+    """
+
+    style: str = "uppercase"
+    format: str = "({letter})"
+    font_size_pt: float = 12.0
+    font_weight: str = "bold"
+    position: str = "top-left"
+    offset_mm: Dict[str, float] = field(default_factory=lambda: {"x": 2.0, "y": 2.0})
+    visible: bool = True
+
+    def format_letter(self, index: int) -> str:
+        """
+        Format panel letter for given index (0-based).
+
+        Parameters
+        ----------
+        index : int
+            Zero-based panel index
+
+        Returns
+        -------
+        str
+            Formatted label like "(A)", "(B)", etc.
+        """
+        if self.style == "uppercase":
+            letter = chr(ord("A") + index)
+        elif self.style == "lowercase":
+            letter = chr(ord("a") + index)
+        elif self.style == "roman":
+            letter = _to_roman(index + 1).lower()
+        elif self.style == "Roman":
+            letter = _to_roman(index + 1)
+        else:
+            letter = chr(ord("A") + index)
+
+        return self.format.replace("{letter}", letter)
+
+    def get_letter(self, index: int) -> str:
+        """Get just the letter without formatting."""
+        if self.style == "uppercase":
+            return chr(ord("A") + index)
+        elif self.style == "lowercase":
+            return chr(ord("a") + index)
+        elif self.style == "roman":
+            return _to_roman(index + 1).lower()
+        elif self.style == "Roman":
+            return _to_roman(index + 1)
+        return chr(ord("A") + index)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "style": self.style,
+            "format": self.format,
+            "font_size_pt": self.font_size_pt,
+            "font_weight": self.font_weight,
+            "position": self.position,
+            "offset_mm": self.offset_mm,
+            "visible": self.visible,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "PanelLabels":
+        return cls(**{k: v for k, v in data.items() if k in cls.__dataclass_fields__})
+
+
+def _to_roman(num: int) -> str:
+    """Convert integer to Roman numeral."""
+    values = [
+        (1000, "M"),
+        (900, "CM"),
+        (500, "D"),
+        (400, "CD"),
+        (100, "C"),
+        (90, "XC"),
+        (50, "L"),
+        (40, "XL"),
+        (10, "X"),
+        (9, "IX"),
+        (5, "V"),
+        (4, "IV"),
+        (1, "I"),
+    ]
+    result = ""
+    for value, numeral in values:
+        while num >= value:
+            result += numeral
+            num -= value
+    return result
+
+
+@dataclass
+class PanelInfo:
+    """
+    Information about a single panel in a multi-panel figure.
+
+    Used in spec.json to store per-panel metadata that combines with
+    theme-level PanelLabels to generate captions.
+
+    Parameters
+    ----------
+    panel_id : str
+        Unique identifier for the panel (matches child ID)
+    letter : str
+        Panel letter override (auto-assigned if empty)
+    description : str
+        Description for caption generation
+    order : int
+        Display order (0-based)
+    """
+
+    panel_id: str
+    letter: str = ""
+    description: str = ""
+    order: int = 0
+
+    def to_dict(self) -> Dict[str, Any]:
+        result = {"panel_id": self.panel_id, "order": self.order}
+        if self.letter:
+            result["letter"] = self.letter
+        if self.description:
+            result["description"] = self.description
+        return result
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "PanelInfo":
+        return cls(**{k: v for k, v in data.items() if k in cls.__dataclass_fields__})
+
+
+def generate_caption(
+    title: FigureTitle,
+    caption: Caption,
+    panels: List[PanelInfo],
+    panel_labels: PanelLabels,
+) -> str:
+    """
+    Generate full figure caption from components.
+
+    Format: "Figure 1: Main Title. (A) Description A. (B) Description B."
+
+    Parameters
+    ----------
+    title : FigureTitle
+        Figure title specification
+    caption : Caption
+        Caption specification
+    panels : list of PanelInfo
+        Panel information with descriptions
+    panel_labels : PanelLabels
+        Panel label styling
+
+    Returns
+    -------
+    str
+        Complete formatted caption
+    """
+    # If manual caption is set and auto_generate is off, use it
+    if caption.text and not caption.auto_generate:
+        return caption.text
+
+    parts = []
+
+    # Add title
+    title_str = title.format()
+    if title_str:
+        parts.append(title_str)
+
+    # Sort panels by order
+    sorted_panels = sorted(panels, key=lambda p: p.order)
+
+    # Add panel descriptions
+    panel_parts = []
+    for idx, panel in enumerate(sorted_panels):
+        if panel.description:
+            letter = panel.letter or panel_labels.get_letter(idx)
+            formatted = panel_labels.format.replace("{letter}", letter)
+            panel_parts.append(f"{formatted} {panel.description}")
+
+    if panel_parts:
+        parts.append(" ".join(panel_parts))
+
+    return " ".join(parts) if parts else ""
+
+
+def generate_caption_latex(
+    title: FigureTitle,
+    caption: Caption,
+    panels: List[PanelInfo],
+    panel_labels: PanelLabels,
+) -> str:
+    """
+    Generate LaTeX-formatted figure caption.
+
+    Format: "\\textbf{Figure 1: Main Title.} (A) Description A. (B) Description B."
+
+    Returns
+    -------
+    str
+        LaTeX-formatted caption
+    """
+    parts = []
+
+    # Add bold title
+    title_str = title.format()
+    if title_str:
+        parts.append(f"\\textbf{{{title_str}}}")
+
+    # Sort and add panel descriptions
+    sorted_panels = sorted(panels, key=lambda p: p.order)
+    panel_parts = []
+    for idx, panel in enumerate(sorted_panels):
+        if panel.description:
+            letter = panel.letter or panel_labels.get_letter(idx)
+            formatted = panel_labels.format.replace("{letter}", letter)
+            panel_parts.append(f"\\textbf{{{formatted}}} {panel.description}")
+
+    if panel_parts:
+        parts.append(" ".join(panel_parts))
+
+    return " ".join(parts) if parts else ""
+
+
+def generate_caption_markdown(
+    title: FigureTitle,
+    caption: Caption,
+    panels: List[PanelInfo],
+    panel_labels: PanelLabels,
+) -> str:
+    """
+    Generate Markdown-formatted figure caption.
+
+    Format: "**Figure 1: Main Title.** (A) Description A. (B) Description B."
+
+    Returns
+    -------
+    str
+        Markdown-formatted caption
+    """
+    parts = []
+
+    # Add bold title
+    title_str = title.format()
+    if title_str:
+        parts.append(f"**{title_str}**")
+
+    # Sort and add panel descriptions
+    sorted_panels = sorted(panels, key=lambda p: p.order)
+    panel_parts = []
+    for idx, panel in enumerate(sorted_panels):
+        if panel.description:
+            letter = panel.letter or panel_labels.get_letter(idx)
+            formatted = panel_labels.format.replace("{letter}", letter)
+            panel_parts.append(f"**{formatted}** {panel.description}")
+
+    if panel_parts:
+        parts.append(" ".join(panel_parts))
+
+    return " ".join(parts) if parts else ""
+
+
+__all__ = [
+    "FIGURE_ELEMENTS_VERSION",
+    "FigureTitle",
+    "Caption",
+    "PanelLabels",
+    "PanelInfo",
+    "generate_caption",
+    "generate_caption_latex",
+    "generate_caption_markdown",
+]
+
+
+# EOF