scitex 2.8.1__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
 
@@ -381,10 +381,10 @@ def _copy_nested_pltz_bundles(plots: Dict[str, Any], dir_path: Path) -> None:
                         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
+                # Fallback to save (will lose images)
+                from scitex.io.bundle import save, BundleType
                 target_path = dir_path / f"{panel_id}.pltz.d"
-                save_bundle(plot_source, target_path, bundle_type=BundleType.PLTZ)
+                save(plot_source, target_path, bundle_type=BundleType.PLTZ)
 
 
 def _generate_figz_overview(dir_path: Path, spec: Dict, data: Dict, basename: str) -> None:

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

scitex/fts/_bundle/README_IN_BUNDLE.md

@@ -0,0 +1,102 @@
+# FTS Bundle (Figure-Table-Statistics)
+
+This is a self-contained scientific figure bundle created with SciTeX.
+
+## Bundle Structure
+
+```
+bundle_root/
+├── README.md            # This file
+├── canonical/           # Source of truth (editable)
+│   ├── spec.json        # Main specification (type, id, elements)
+│   ├── data.csv         # Source data
+│   ├── encoding.json    # Data-to-visual channel mappings
+│   ├── theme.json       # Visual aesthetics (colors, fonts)
+│   ├── stats.json       # Statistical analysis results
+│   ├── data_info.json   # Column metadata and units
+│   └── runtime.json     # Runtime configuration
+├── artifacts/           # Derived files (can be regenerated)
+│   ├── cache/           # Computed values
+│   └── exports/         # Rendered outputs (PNG, SVG, PDF)
+└── children/            # Child bundles (for multi-panel figures)
+```
+
+## Key Files
+
+### canonical/spec.json
+Main specification defining the bundle structure:
+- `id`: Unique bundle identifier
+- `type`: Bundle type (figure, plot, text, etc.)
+- `bbox_norm`: Normalized bounding box (0-1 coordinates)
+- `size_mm`: Physical size in millimeters
+- `elements`: Child elements or references
+
+### canonical/encoding.json
+Data-to-visual mappings for scientific reproducibility:
+- `traces`: List of data series with column bindings
+- Each trace maps data columns to visual channels (x, y, color, size)
+
+### canonical/theme.json
+Pure visual aesthetics (can be changed without affecting data):
+- `colors`: Color palette and scheme
+- `typography`: Font settings
+- `lines`: Line styles and widths
+- `markers`: Marker styles
+
+### canonical/stats.json
+Statistical analysis results with full provenance:
+- `analyses`: List of statistical tests performed
+- Each analysis includes method, inputs, and results
+- `software`: Version information for reproducibility
+
+### canonical/data_info.json
+Metadata about data columns:
+- Column names, types, and units
+- Data source and hash for integrity
+- Basic statistics for validation
+
+## Opening This Bundle
+
+### With Python (SciTeX)
+```python
+from scitex import fsb
+
+# Load the bundle
+bundle = fsb.Bundle("path/to/this/bundle.zip")
+
+# Access components
+print(bundle.node.name)
+print(bundle.encoding)
+print(bundle.theme)
+```
+
+### With Any JSON Tool
+All files in `canonical/` are standard JSON and can be viewed/edited with any text editor or JSON tool.
+
+### Exported Figures
+Ready-to-use figures are in `artifacts/exports/`:
+- `figure.svg` - Vector format (scalable)
+- `figure.png` - Raster format (web/screen)
+- `figure.pdf` - Print format
+
+## Reproducibility
+
+This bundle contains everything needed to reproduce the figure:
+1. **Data**: Original data in `canonical/data.csv`
+2. **Encoding**: How data maps to visuals in `encoding.json`
+3. **Stats**: Statistical results with full provenance
+4. **Software**: Version info in `stats.json`
+
+To regenerate exports:
+```python
+from scitex import fsb
+bundle = fsb.Bundle("this_bundle.zip")
+# Exports will be regenerated on render
+```
+
+## License
+
+The figure and data in this bundle are subject to the license terms specified by the original author. Contact information may be found in `spec.json`.
+
+---
+*Created with [SciTeX](https://scitex.ai) FTS v1.0.0*