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

scitex/fig/io/_bundle.py

@@ -132,15 +132,15 @@ def load_figz_bundle(bundle_dir: Path) -> Dict[str, Any]:
     # Load from .pltz.d directories
     for pltz_dir in bundle_dir.glob("*.pltz.d"):
         plot_name = pltz_dir.stem.replace(".pltz", "")
-        from scitex.io._bundle import load_bundle
-        result["plots"][plot_name] = load_bundle(pltz_dir)
+        from scitex.io.bundle import load
+        result["plots"][plot_name] = load(pltz_dir)
 
     # Load from .pltz ZIP files
     for pltz_zip in bundle_dir.glob("*.pltz"):
         if pltz_zip.is_file():
             plot_name = pltz_zip.stem
-            from scitex.io._bundle import load_bundle
-            result["plots"][plot_name] = load_bundle(pltz_zip)
+            from scitex.io.bundle import load
+            result["plots"][plot_name] = load(pltz_zip)
 
     return result
 
@@ -333,32 +333,58 @@ def _copy_nested_pltz_bundles(plots: Dict[str, Any], dir_path: Path) -> None:
 
     Args:
         plots: Dict mapping panel IDs to either:
-            - source_path: Path to existing .pltz.d directory
+            - source_path: Path to existing .pltz.d directory or .pltz zip
             - bundle_data: Dict with spec/data (will use save_bundle)
         dir_path: Target figz directory.
     """
     for panel_id, plot_source in plots.items():
-        target_path = dir_path / f"{panel_id}.pltz.d"
-
         if isinstance(plot_source, (str, Path)):
             # Direct copy from source path
             source_path = Path(plot_source)
-            if source_path.exists() and source_path.is_dir():
+
+            if source_path.is_dir() and str(source_path).endswith('.pltz.d'):
+                # Source is .pltz.d directory - copy as directory
+                target_path = dir_path / f"{panel_id}.pltz.d"
                 if target_path.exists():
                     shutil.rmtree(target_path)
                 shutil.copytree(source_path, target_path)
+
+            elif source_path.is_file() and str(source_path).endswith('.pltz'):
+                # Source is .pltz zip file - copy as zip file (preserving zip format)
+                target_path = dir_path / f"{panel_id}.pltz"
+                if target_path.exists():
+                    target_path.unlink()
+                shutil.copy2(source_path, target_path)
+
+            elif source_path.exists():
+                # Unknown format - try to copy as directory
+                target_path = dir_path / f"{panel_id}.pltz.d"
+                if source_path.is_dir():
+                    if target_path.exists():
+                        shutil.rmtree(target_path)
+                    shutil.copytree(source_path, target_path)
+
         elif isinstance(plot_source, dict):
             # Check if it has source_path for direct copy
             if "source_path" in plot_source:
                 source_path = Path(plot_source["source_path"])
-                if source_path.exists() and source_path.is_dir():
+                if source_path.is_file() and str(source_path).endswith('.pltz'):
+                    # .pltz zip file
+                    target_path = dir_path / f"{panel_id}.pltz"
+                    if target_path.exists():
+                        target_path.unlink()
+                    shutil.copy2(source_path, target_path)
+                elif source_path.exists() and source_path.is_dir():
+                    # .pltz.d directory
+                    target_path = dir_path / f"{panel_id}.pltz.d"
                     if target_path.exists():
                         shutil.rmtree(target_path)
                     shutil.copytree(source_path, target_path)
             else:
-                # Fallback to save_bundle (will lose images)
-                from scitex.io._bundle import save_bundle, BundleType
-                save_bundle(plot_source, target_path, bundle_type=BundleType.PLTZ)
+                # Fallback to save (will lose images)
+                from scitex.io.bundle import save, BundleType
+                target_path = dir_path / f"{panel_id}.pltz.d"
+                save(plot_source, target_path, bundle_type=BundleType.PLTZ)
 
 
 def _generate_figz_overview(dir_path: Path, spec: Dict, data: Dict, basename: str) -> None:
@@ -376,9 +402,33 @@ def _generate_figz_overview(dir_path: Path, spec: Dict, data: Dict, basename: st
     from PIL import Image
     import numpy as np
     import warnings
+    import tempfile
+    import zipfile
+
+    # Find all panel bundles (both .pltz.d directories and .pltz zip files)
+    panel_dirs = []
+    temp_dirs_to_cleanup = []
+
+    for item in dir_path.iterdir():
+        if item.is_dir() and str(item).endswith('.pltz.d'):
+            panel_dirs.append(item)
+        elif item.is_file() and str(item).endswith('.pltz'):
+            # Extract .pltz zip to temp directory for overview generation
+            temp_dir = tempfile.mkdtemp(prefix=f'scitex_overview_{item.stem}_')
+            temp_dirs_to_cleanup.append(temp_dir)
+            with zipfile.ZipFile(item, 'r') as zf:
+                zf.extractall(temp_dir)
+            # Find the extracted .pltz.d directory
+            extracted = Path(temp_dir)
+            for subitem in extracted.iterdir():
+                if subitem.is_dir() and str(subitem).endswith('.pltz.d'):
+                    panel_dirs.append(subitem)
+                    break
+            else:
+                # Use temp dir directly if no .pltz.d subfolder
+                panel_dirs.append(extracted)
 
-    # Find all panel directories
-    panel_dirs = sorted(dir_path.glob("*.pltz.d"))
+    panel_dirs = sorted(panel_dirs, key=lambda x: x.name)
     n_panels = len(panel_dirs)
 
     if n_panels == 0:
@@ -519,6 +569,13 @@ def _generate_figz_overview(dir_path: Path, spec: Dict, data: Dict, basename: st
         fig.savefig(overview_path, dpi=150, bbox_inches="tight", facecolor="white")
     plt.close(fig)
 
+    # Cleanup temp directories
+    for temp_dir in temp_dirs_to_cleanup:
+        try:
+            shutil.rmtree(temp_dir)
+        except Exception:
+            pass
+
 
 def _draw_bboxes_from_geometry(ax, geometry_data: Dict) -> None:
     """Draw bboxes from geometry data on an axes.
@@ -745,6 +802,8 @@ def _generate_figz_geometry_cache(dir_path: Path, spec: Dict, basename: str) ->
         basename: Base filename for bundle files.
     """
     from datetime import datetime
+    import tempfile
+    import zipfile
 
     cache_dir = dir_path / "cache"
     cache_dir.mkdir(parents=True, exist_ok=True)
@@ -756,11 +815,30 @@ def _generate_figz_geometry_cache(dir_path: Path, spec: Dict, basename: str) ->
         "generated_at": datetime.now().isoformat(),
     }
 
-    # Find all panel directories
-    panel_dirs = sorted(dir_path.glob("*.pltz.d"))
+    # Find all panel bundles (both .pltz.d directories and .pltz zip files)
+    panel_sources = []
+    temp_dirs_to_cleanup = []
+
+    for item in dir_path.iterdir():
+        if item.is_dir() and str(item).endswith('.pltz.d'):
+            panel_sources.append((item.stem.replace('.pltz', ''), item))
+        elif item.is_file() and str(item).endswith('.pltz'):
+            # Extract .pltz zip to temp directory
+            temp_dir = tempfile.mkdtemp(prefix=f'scitex_geom_{item.stem}_')
+            temp_dirs_to_cleanup.append(temp_dir)
+            with zipfile.ZipFile(item, 'r') as zf:
+                zf.extractall(temp_dir)
+            extracted = Path(temp_dir)
+            for subitem in extracted.iterdir():
+                if subitem.is_dir() and str(subitem).endswith('.pltz.d'):
+                    panel_sources.append((item.stem, subitem))
+                    break
+            else:
+                panel_sources.append((item.stem, extracted))
 
-    for panel_dir in panel_dirs:
-        panel_id = panel_dir.stem.replace(".pltz", "")
+    panel_sources = sorted(panel_sources, key=lambda x: x[0])
+
+    for panel_id, panel_dir in panel_sources:
 
         # Load panel geometry
         panel_geometry_path = panel_dir / "cache" / "geometry_px.json"
@@ -790,7 +868,7 @@ def _generate_figz_geometry_cache(dir_path: Path, spec: Dict, basename: str) ->
         "figure_id": basename,
         "generated_at": datetime.now().isoformat(),
         "size_mm": [size.get("width_mm", 0), size.get("height_mm", 0)],
-        "panels_count": len(panel_dirs),
+        "panels_count": len(panel_sources),
         "schema": spec.get("schema", {}),
     }
 
@@ -798,6 +876,13 @@ def _generate_figz_geometry_cache(dir_path: Path, spec: Dict, basename: str) ->
     with open(manifest_path, "w") as f:
         json.dump(manifest, f, indent=2)
 
+    # Cleanup temp directories
+    for temp_dir in temp_dirs_to_cleanup:
+        try:
+            shutil.rmtree(temp_dir)
+        except Exception:
+            pass
+
 
 def _embed_metadata_in_export(
     file_path: Path, spec: Dict[str, Any], fmt: str

scitex/fts/README.md

@@ -0,0 +1,262 @@
+<!-- ---
+!-- Timestamp: 2025-12-20 07:20:45
+!-- Author: ywatanabe
+!-- File: /home/ywatanabe/proj/scitex-code/src/scitex/fsb/README.md
+!-- --- -->
+
+# SciTeX FTS (Figure-Table-Statistics)
+
+**FTS is the single source of truth for bundle schemas in SciTeX.**
+
+FTS defines a standardized, self-contained format for reproducible scientific figures with:
+- Complete data provenance
+- Statistical analysis results
+- Visual encoding specifications
+- Theme/aesthetic configuration
+
+## Design Philosophy
+
+### Separation of Concerns
+
+FTS strictly separates:
+
+| Layer | File | Purpose | Affects Science? |
+|-------|------|---------|------------------|
+| **Node** | `spec.json` | Structure (id, type, bbox, children) | Yes |
+| **Encoding** | `encoding.json` | Data-to-Visual mapping (columns, scales) | Yes |
+| **Theme** | `theme.json` | Aesthetics (colors, fonts, lines) | No |
+| **Stats** | `stats.json` | Statistical results with provenance | Yes |
+| **Data Info** | `data_info.json` | Column metadata, units, data source | Yes |
+
+**Key insight**: Theme changes don't affect reproducibility. Encoding changes do.
+
+### Canonical vs Artifacts
+
+```
+bundle_root/
+├── canonical/           # Source of truth (editable, human-readable)
+│   ├── spec.json        # Main specification
+│   ├── data.csv         # Source data
+│   ├── encoding.json    # Data-to-visual mappings
+│   ├── theme.json       # Visual aesthetics
+│   ├── stats.json       # Statistical results
+│   ├── data_info.json   # Column metadata
+│   └── runtime.json     # Runtime configuration
+├── artifacts/           # Derived/cached (can be deleted and regenerated)
+│   ├── cache/
+│   │   ├── geometry_px.json
+│   │   └── render_manifest.json
+│   └── exports/
+│       ├── figure.svg
+│       ├── figure.png
+│       └── figure.pdf
+└── children/            # Child bundles (for multi-panel figures)
+    ├── panel_a/
+    └── panel_b/
+```
+
+## Quick Start
+
+```python
+from scitex import fts
+
+# Create a new bundle
+bundle = fts.FTS("my_plot.zip", create=True, node_type="plot", name="My Plot")
+
+# Set encoding (data-to-visual mapping)
+bundle.encoding = {
+    "traces": [
+        {
+            "trace_id": "main",
+            "data_ref": "data/experiment.csv",
+            "x": {"column": "time", "scale": "linear"},
+            "y": {"column": "amplitude", "scale": "log"},
+            "color": {"column": "condition"},
+        }
+    ]
+}
+
+# Set theme (pure aesthetics)
+bundle.theme = {
+    "colors": {"palette": ["#1f77b4", "#ff7f0e", "#2ca02c"]},
+    "typography": {"family": "Arial", "size_pt": 10},
+    "lines": {"width_pt": 1.5},
+}
+
+# Save
+bundle.save()
+```
+
+## Module Structure
+
+```
+scitex/fts/
+├── __init__.py       # Public API exports
+├── _bundle.py        # FTS class
+├── _models.py        # Core models (Node, BBox, SizeMM, Axes)
+├── _encoding.py      # Encoding models (TraceEncoding, ChannelEncoding)
+├── _theme.py         # Theme models (Theme, Colors, Typography)
+├── _stats.py         # Stats models (Analysis, StatResult, EffectSize)
+├── _data_info.py     # Data info models (DataInfo, ColumnDef)
+├── _validation.py    # JSON schema validation
+├── _conversion.py    # scitex to FTS format conversion
+└── schemas/          # JSON Schema definitions
+    ├── node.schema.json
+    ├── encoding.schema.json
+    ├── theme.schema.json
+    ├── stats.schema.json
+    └── data_info.schema.json
+```
+
+## Core Models
+
+### Node (spec.json)
+
+Structural metadata for the bundle:
+
+```python
+from scitex.fts import Node, BBox, SizeMM
+
+node = Node(
+    id="plot_001",
+    type="plot",  # figure, plot, text, shape, image
+    name="Figure 1A",
+    bbox_norm=BBox(x0=0, y0=0, x1=1, y1=1),
+    size_mm=SizeMM(width=85, height=60),  # Single column
+    children=["panel_a", "panel_b"],  # For figures
+)
+```
+
+### Encoding (encoding.json)
+
+Data-to-visual channel mappings:
+
+```python
+from scitex.fts import Encoding, TraceEncoding, ChannelEncoding
+
+encoding = Encoding(
+    traces=[
+        TraceEncoding(
+            trace_id="line_1",
+            data_ref="data/timeseries.csv",
+            x=ChannelEncoding(column="time_ms", scale="linear"),
+            y=ChannelEncoding(column="voltage_mV", scale="linear"),
+            color=ChannelEncoding(column="channel", scale="categorical"),
+        )
+    ]
+)
+```
+
+### Theme (theme.json)
+
+Pure aesthetics (doesn't affect scientific meaning):
+
+```python
+from scitex.fts import Theme, Colors, Typography
+
+theme = Theme(
+    colors=Colors(
+        palette=["#1f77b4", "#ff7f0e", "#2ca02c"],
+        background="#ffffff",
+        text="#000000",
+    ),
+    typography=Typography(
+        family="Arial",
+        size_pt=8,
+        title_size_pt=10,
+    ),
+    preset="nature",  # Named presets: nature, science, dark
+)
+```
+
+### Stats (stats/stats.json)
+
+Statistical analysis results with full provenance:
+
+```python
+from scitex.fts import Stats, Analysis, StatMethod, StatResult, EffectSize
+
+stats = Stats(
+    analyses=[
+        Analysis(
+            result_id="ttest_1",
+            method=StatMethod(
+                name="t-test",
+                variant="independent",
+                parameters={"equal_var": False},
+            ),
+            inputs={
+                "groups": ["control", "treatment"],
+                "n_per_group": [30, 28],
+            },
+            results=StatResult(
+                statistic=2.45,
+                statistic_name="t",
+                p_value=0.018,
+                df=56,
+                effect_size=EffectSize(
+                    name="cohens_d",
+                    value=0.65,
+                    ci_lower=0.12,
+                    ci_upper=1.18,
+                ),
+            ),
+        )
+    ],
+    software={"python": "3.11", "scipy": "1.11.0"},
+)
+```
+
+## Validation
+
+Validate bundles against JSON schemas:
+
+```python
+from scitex.fts import validate_bundle, validate_node
+
+# Validate entire bundle
+errors = validate_bundle("my_figure.zip")
+if errors:
+    for filename, error_list in errors.items():
+        print(f"{filename}: {error_list}")
+
+# Validate individual components
+node_errors = validate_node({"id": "test", "type": "plot", "bbox_norm": {...}})
+```
+
+## Conversion Utilities
+
+Convert between scitex internal format and FTS format:
+
+```python
+from scitex.fts import from_scitex_spec, to_scitex_spec
+
+# scitex spec to FTS format
+fts_data = from_scitex_spec(spec_dict, style_dict)
+# Returns: {"node": {...}, "encoding": {...}, "theme": {...}}
+
+# FTS bundle to scitex format
+spec, style = to_scitex_spec(bundle)
+```
+
+## Backward Compatibility
+
+FTS is also available via the legacy import path:
+
+```python
+# Old path (still works)
+from scitex import fsb  # Alias for fts
+
+# New path (preferred)
+from scitex import fts
+```
+
+## Best Practices
+
+1. **Always specify units in data_info.json** - Critical for reproducibility
+2. **Use encoding for data-driven styling** - Color by condition, size by value
+3. **Keep theme separate from encoding** - Enables style changes without data loss
+4. **Include stats provenance** - Software versions, parameters, correction methods
+5. **Use canonical/ for source files** - artifacts/ can be regenerated
+
+<!-- EOF -->

scitex/fts/TODO.md

@@ -0,0 +1,66 @@
+<!-- ---
+!-- Timestamp: 2025-12-21 11:02:24
+!-- Author: ywatanabe
+!-- File: /home/ywatanabe/proj/scitex-code/src/scitex/fts/TODO.md
+!-- --- -->
+
+## Simplify Things
+## Explict Names
+## Kinds
+### figure
+### plot
+
+#### Current
+```
+├── artifacts
+│   ├── cache
+│   │   ├── geometry_px.json
+│   │   ├── hitmap.png
+│   │   ├── hitmap.svg
+│   │   └── render_manifest.json
+│   └── exports
+│       ├── figure.pdf
+│       ├── figure.png
+│       └── figure.svg
+├── canonical
+│   ├── data_info.json
+│   ├── encoding.json
+│   ├── spec.json
+│   └── theme.json
+├── children
+└── payload
+    └── data.csv
+
+```
+
+#### Revised
+```
+├── artifacts
+│   ├── cache
+│   │   ├── coordinates/
+    
+│   │   ├── hitmap.png
+│   │   ├── hitmap.svg
+│   │   └── render_manifest.json
+│   └── exports
+│       ├── figure.pdf
+│       ├── figure.png
+│       └── figure.svg
+├── canonical
+│   ├── data_info.json
+│   ├── encoding.json
+│   ├── spec.json
+│   └── theme.json
+├── children
+└── payload
+    └── data.csv
+
+```
+
+### image
+### shape
+### stats
+### table
+### text
+
+<!-- EOF -->

scitex/fts/__init__.py

@@ -0,0 +1,90 @@
+#!/usr/bin/env python3
+# Timestamp: 2025-12-20
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/fts/__init__.py
+
+"""
+SciTeX FTS (Figure-Table-Statistics) - The single source of truth for bundle schemas.
+
+FTS defines a standardized format for reproducible scientific figures and tables:
+- Self-contained bundles with data, visualization spec, and stats
+- Clear separation: Node (structure), Encoding (data mapping), Theme (aesthetics)
+- Full provenance tracking for scientific reproducibility
+
+Usage:
+    from scitex.fts import FTS, Node, Encoding, Theme
+
+    # Create new bundle
+    bundle = FTS("my_plot.zip", create=True, node_type="plot")
+    bundle.encoding = {"traces": [{"trace_id": "t1", "x": {"column": "time"}}]}
+    bundle.save()
+
+    # Load existing bundle
+    bundle = FTS("my_plot.zip")
+    print(bundle.node.type)  # "plot"
+"""
+
+# Version
+__version__ = "1.0.0"
+
+# =============================================================================
+# Public API - What users need
+# =============================================================================
+
+# FTS class (main entry point)
+from ._bundle import FTS, create_bundle, from_matplotlib, load_bundle
+
+# Core dataclasses users interact with
+from ._bundle import Node, BBox, SizeMM, DataInfo
+from ._fig import Encoding, Theme
+from ._stats import Stats
+
+# Type enumeration
+from ._bundle import NodeType
+
+# Error classes for exception handling
+from ._bundle import (
+    BundleError,
+    BundleNotFoundError,
+    BundleValidationError,
+)
+
+# Availability flags
+FTS_AVAILABLE = True
+FTS_VERSION = __version__
+
+# Legacy aliases for backwards compatibility
+FSB = FTS
+FSB_AVAILABLE = FTS_AVAILABLE
+FSB_VERSION = FTS_VERSION
+
+__all__ = [
+    # Version
+    "__version__",
+    "FTS_AVAILABLE",
+    "FTS_VERSION",
+    # Legacy aliases
+    "FSB_AVAILABLE",
+    "FSB_VERSION",
+    "FSB",
+    # FTS class
+    "FTS",
+    "load_bundle",
+    "create_bundle",
+    "from_matplotlib",
+    # Core dataclasses
+    "Node",
+    "Encoding",
+    "Theme",
+    "Stats",
+    "BBox",
+    "SizeMM",
+    "DataInfo",
+    # Types
+    "NodeType",
+    # Errors
+    "BundleError",
+    "BundleNotFoundError",
+    "BundleValidationError",
+]
+
+# EOF