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

scitex/fts/_tables/_latex/_export.py

@@ -0,0 +1,279 @@
+#!/usr/bin/env python3
+# Timestamp: 2025-12-20
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/fsb/_tables/_latex/_export.py
+
+"""Main LaTeX export orchestration for FTS bundles."""
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, List, Optional, Union
+
+from ._figure_exporter import FigureExportOptions, export_figure_to_latex, generate_figure_preamble
+from ._stats_formatter import FormattedStat, format_stat_note, format_stats_for_latex
+from ._table_exporter import TableExportOptions, export_table_to_latex, generate_table_preamble
+from ._validator import LaTeXError, ValidationResult, validate_latex
+
+if TYPE_CHECKING:
+    from scitex.fts import FTS
+
+
+@dataclass
+class LaTeXExportOptions:
+    """Options for LaTeX export.
+
+    Attributes:
+        validate: Whether to validate output
+        validation_level: Validation level ("syntax", "semantic", "compile")
+        include_preamble: Include required packages in output
+        figure_options: Options for figure export
+        table_options: Options for table export
+        output_path: Where to save the .tex file
+    """
+
+    validate: bool = True
+    validation_level: str = "syntax"
+    include_preamble: bool = False
+    figure_options: Optional[FigureExportOptions] = None
+    table_options: Optional[TableExportOptions] = None
+    output_path: Optional[Path] = None
+
+
+@dataclass
+class LaTeXResult:
+    """Result of LaTeX export.
+
+    Attributes:
+        latex_code: Generated LaTeX code
+        preamble: Required preamble packages
+        validation: Validation result
+        output_path: Path where file was saved (if applicable)
+        stats: Formatted statistics (if applicable)
+    """
+
+    latex_code: str
+    preamble: str = ""
+    validation: Optional[ValidationResult] = None
+    output_path: Optional[Path] = None
+    stats: List[FormattedStat] = field(default_factory=list)
+
+    @property
+    def is_valid(self) -> bool:
+        """Check if export is valid."""
+        return self.validation is None or self.validation.is_valid
+
+    @property
+    def errors(self) -> List[LaTeXError]:
+        """Get validation errors."""
+        if self.validation:
+            return self.validation.errors
+        return []
+
+    @property
+    def warnings(self) -> List[LaTeXError]:
+        """Get validation warnings."""
+        if self.validation:
+            return self.validation.warnings
+        return []
+
+
+def export_to_latex(
+    bundle: "FTS",
+    options: Optional[LaTeXExportOptions] = None,
+) -> LaTeXResult:
+    """Export an FTS bundle to LaTeX.
+
+    Automatically detects bundle type and uses appropriate exporter.
+
+    Args:
+        bundle: FTS bundle
+        options: Export options
+
+    Returns:
+        LaTeXResult with code, validation, and metadata
+    """
+    if options is None:
+        options = LaTeXExportOptions()
+
+    node_type = bundle.node.type
+    latex_code = ""
+    preamble_parts = []
+    stats = []
+
+    # Export based on type
+    if node_type in ("figure", "plot", "image"):
+        latex_code = export_figure_to_latex(
+            bundle,
+            options=options.figure_options,
+        )
+        preamble_parts.append(generate_figure_preamble())
+
+    elif node_type == "table":
+        table_opts = options.table_options or TableExportOptions()
+        latex_code = export_table_to_latex(
+            bundle,
+            options=table_opts,
+        )
+        preamble_parts.append(
+            generate_table_preamble(
+                use_booktabs=table_opts.use_booktabs,
+                use_siunitx=table_opts.use_siunitx,
+            )
+        )
+
+    elif node_type == "stats":
+        # Stats-only bundle - format as paragraph or inline
+        if bundle.stats:
+            stats = format_stats_for_latex(bundle.stats.to_dict())
+            latex_code = _format_stats_only(stats)
+
+    else:
+        raise ValueError(f"Unsupported node type for LaTeX export: {node_type}")
+
+    # Format statistics if available (for figures/tables with stats)
+    if bundle.stats and node_type != "stats":
+        stats = format_stats_for_latex(bundle.stats.to_dict())
+        if stats:
+            note = format_stat_note(stats)
+            if note:
+                latex_code += "\n\n" + note
+
+    # Combine preamble
+    preamble = "\n\n".join(preamble_parts)
+
+    # Validate if requested
+    validation = None
+    if options.validate:
+        validation = validate_latex(latex_code, level=options.validation_level)
+
+    # Create result
+    result = LaTeXResult(
+        latex_code=latex_code,
+        preamble=preamble,
+        validation=validation,
+        stats=stats,
+    )
+
+    # Save to file if path specified
+    output_path = options.output_path
+    if output_path is None:
+        # Default to exports directory
+        exports_dir = bundle.path / "exports"
+        exports_dir.mkdir(exist_ok=True)
+        output_path = exports_dir / f"{bundle.node.id}.tex"
+
+    if output_path:
+        _save_latex(latex_code, output_path, preamble if options.include_preamble else None)
+        result.output_path = output_path
+
+    return result
+
+
+def _format_stats_only(stats: List[FormattedStat]) -> str:
+    """Format stats-only bundle as LaTeX.
+
+    Args:
+        stats: Formatted statistics
+
+    Returns:
+        LaTeX code
+    """
+    if not stats:
+        return "% No statistics to report"
+
+    lines = ["% Statistical Results", ""]
+    for stat in stats:
+        lines.append(f"% {stat.test_type}")
+        lines.append(stat.full_report)
+        lines.append("")
+
+    return "\n".join(lines)
+
+
+def _save_latex(
+    latex_code: str,
+    output_path: Path,
+    preamble: Optional[str] = None,
+) -> None:
+    """Save LaTeX code to file.
+
+    Args:
+        latex_code: LaTeX code
+        output_path: Output path
+        preamble: Optional preamble to prepend
+    """
+    output_path = Path(output_path)
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+
+    content = []
+    if preamble:
+        content.append(preamble)
+        content.append("")
+
+    content.append(latex_code)
+
+    output_path.write_text("\n".join(content), encoding="utf-8")
+
+
+def export_multiple(
+    bundles: List["FTS"],
+    output_path: Path,
+    options: Optional[LaTeXExportOptions] = None,
+) -> LaTeXResult:
+    """Export multiple bundles to a single LaTeX file.
+
+    Args:
+        bundles: List of FTS bundles
+        output_path: Output path
+        options: Export options
+
+    Returns:
+        Combined LaTeXResult
+    """
+    if options is None:
+        options = LaTeXExportOptions()
+
+    all_code = []
+    all_preamble = set()
+    all_stats = []
+    all_errors = []
+    all_warnings = []
+
+    for bundle in bundles:
+        result = export_to_latex(bundle, options)
+        all_code.append(result.latex_code)
+        if result.preamble:
+            all_preamble.add(result.preamble)
+        all_stats.extend(result.stats)
+        all_errors.extend(result.errors)
+        all_warnings.extend(result.warnings)
+
+    combined_code = "\n\n".join(all_code)
+    combined_preamble = "\n\n".join(sorted(all_preamble))
+
+    # Save combined file
+    _save_latex(combined_code, output_path, combined_preamble if options.include_preamble else None)
+
+    # Create combined validation result
+    combined_validation = ValidationResult()
+    for error in all_errors:
+        combined_validation.add_error(error)
+    for warning in all_warnings:
+        combined_validation.add_error(warning)
+
+    return LaTeXResult(
+        latex_code=combined_code,
+        preamble=combined_preamble,
+        validation=combined_validation,
+        output_path=output_path,
+        stats=all_stats,
+    )
+
+
+__all__ = [
+    "LaTeXExportOptions",
+    "LaTeXResult",
+    "export_to_latex",
+    "export_multiple",
+]
+
+# EOF

scitex/fts/_tables/_latex/_figure_exporter.py

@@ -0,0 +1,153 @@
+#!/usr/bin/env python3
+# Timestamp: 2025-12-20
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/fsb/_tables/_latex/_figure_exporter.py
+
+"""Export FTS figures to LaTeX using includegraphics."""
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Optional
+
+from ._utils import escape_latex_minimal, sanitize_label
+
+if TYPE_CHECKING:
+    from scitex.fts import FTS
+
+
+@dataclass
+class FigureExportOptions:
+    """Options for figure LaTeX export.
+
+    Attributes:
+        width_mm: Figure width in mm (from node.size_mm if not specified)
+        placement: Float placement specifier (htbp, t, b, h, p, H)
+        centering: Whether to center the figure
+        include_caption: Whether to include caption
+        include_label: Whether to include label
+        pdf_path: Override path to PDF file
+        relative_path: Whether to use relative paths
+    """
+
+    width_mm: Optional[float] = None
+    placement: str = "htbp"
+    centering: bool = True
+    include_caption: bool = True
+    include_label: bool = True
+    pdf_path: Optional[str] = None
+    relative_path: bool = True
+
+
+def export_figure_to_latex(
+    bundle: "FTS",
+    options: Optional[FigureExportOptions] = None,
+) -> str:
+    """Export a figure/plot bundle to LaTeX.
+
+    Generates a figure environment with includegraphics pointing to
+    a pre-rendered PDF file.
+
+    Args:
+        bundle: FTS bundle of type 'figure' or 'plot'
+        options: Export options
+
+    Returns:
+        LaTeX code string
+    """
+    if options is None:
+        options = FigureExportOptions()
+
+    node = bundle.node
+    node_type = node.type
+
+    # Validate type
+    if node_type not in ("figure", "plot", "image"):
+        raise ValueError(f"Cannot export node type '{node_type}' as figure. Expected 'figure', 'plot', or 'image'.")
+
+    # Get width
+    width_mm = options.width_mm
+    if width_mm is None and node.size_mm:
+        width_mm = node.size_mm.width
+    if width_mm is None:
+        width_mm = 80  # Default width
+
+    # Get PDF path
+    if options.pdf_path:
+        pdf_path = options.pdf_path
+    else:
+        # Look for existing PDF export
+        pdf_path = _find_pdf_export(bundle, options.relative_path)
+
+    # Get caption
+    caption = node.name or ""
+
+    # Get label
+    label = sanitize_label(node.id)
+    label_prefix = "fig" if node_type in ("figure", "plot") else "img"
+
+    # Build LaTeX
+    lines = []
+    lines.append(f"\\begin{{figure}}[{options.placement}]")
+
+    if options.centering:
+        lines.append("    \\centering")
+
+    lines.append(f"    \\includegraphics[width={width_mm}mm]{{{pdf_path}}}")
+
+    if options.include_caption and caption:
+        escaped_caption = escape_latex_minimal(caption)
+        lines.append(f"    \\caption{{{escaped_caption}}}")
+
+    if options.include_label:
+        lines.append(f"    \\label{{{label_prefix}:{label}}}")
+
+    lines.append("\\end{figure}")
+
+    return "\n".join(lines)
+
+
+def _find_pdf_export(bundle: "FTS", relative: bool = True) -> str:
+    """Find the PDF export path for a bundle.
+
+    Args:
+        bundle: FTS bundle
+        relative: Return relative path
+
+    Returns:
+        Path string for includegraphics
+    """
+    # Check exports directory
+    exports_dir = bundle.path / "exports"
+    if exports_dir.exists():
+        # Look for PDF files
+        pdf_files = list(exports_dir.glob("*.pdf"))
+        if pdf_files:
+            pdf_path = pdf_files[0]
+            if relative:
+                # Return path relative to exports/
+                return f"exports/{pdf_path.name}"
+            return str(pdf_path)
+
+    # No PDF found - generate a placeholder path
+    bundle_name = bundle.path.stem
+    return f"exports/{bundle_name}.pdf"
+
+
+def generate_figure_preamble() -> str:
+    """Generate required LaTeX preamble for figures.
+
+    Returns:
+        Preamble code with required packages
+    """
+    return """% Required packages for figure export
+\\usepackage{graphicx}
+\\usepackage{float}  % For [H] placement specifier
+"""
+
+
+__all__ = [
+    "FigureExportOptions",
+    "export_figure_to_latex",
+    "generate_figure_preamble",
+]
+
+# EOF

scitex/fts/_tables/_latex/_stats_formatter.py

@@ -0,0 +1,274 @@
+#!/usr/bin/env python3
+# Timestamp: 2025-12-20
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/fsb/_tables/_latex/_stats_formatter.py
+
+"""Format statistical results for LaTeX output."""
+
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional
+
+from ._utils import format_effect_size, format_p_value, format_statistic, significance_stars
+
+
+@dataclass
+class FormattedStat:
+    """A formatted statistical result.
+
+    Attributes:
+        test_type: Type of test (t-test, anova, etc.)
+        statistic: Formatted test statistic (e.g., "$t(48) = 2.31$")
+        p_value: Formatted p-value (e.g., ".023")
+        effect_size: Formatted effect size if available
+        stars: Significance stars
+        full_report: Complete inline report
+    """
+
+    test_type: str
+    statistic: str
+    p_value: str
+    effect_size: Optional[str] = None
+    stars: str = ""
+    full_report: str = ""
+
+
+def format_stats_for_latex(stats_dict: Dict[str, Any]) -> List[FormattedStat]:
+    """Format stats.json contents for LaTeX.
+
+    Args:
+        stats_dict: Dictionary from stats.json
+
+    Returns:
+        List of FormattedStat objects
+    """
+    results = []
+
+    analyses = stats_dict.get("analyses", [])
+    for analysis in analyses:
+        formatted = _format_analysis(analysis)
+        if formatted:
+            results.append(formatted)
+
+    return results
+
+
+def _format_analysis(analysis: Dict[str, Any]) -> Optional[FormattedStat]:
+    """Format a single analysis result.
+
+    Args:
+        analysis: Single analysis dictionary
+
+    Returns:
+        FormattedStat or None if cannot format
+    """
+    method = analysis.get("method", {})
+    result = analysis.get("results", {})
+
+    if not result:
+        return None
+
+    # Extract test info
+    test_name = method.get("name", "test")
+    variant = method.get("variant", "")
+
+    # Format statistic
+    stat_name = result.get("statistic_name", "t")
+    stat_value = result.get("statistic")
+    df = result.get("df")
+
+    if stat_value is None:
+        return None
+
+    statistic_str = format_statistic(stat_name, stat_value, df)
+
+    # Format p-value
+    p = result.get("p_value")
+    p_str = format_p_value(p) if p is not None else "---"
+    stars = significance_stars(p) if p is not None else ""
+
+    # Format effect size
+    effect = result.get("effect_size")
+    effect_str = None
+    if effect:
+        es_name = effect.get("name", "d")
+        es_value = effect.get("value")
+        ci_lower = effect.get("ci_lower")
+        ci_upper = effect.get("ci_upper")
+        if es_value is not None:
+            effect_str = format_effect_size(es_name, es_value, ci_lower, ci_upper)
+
+    # Build full report
+    full_parts = [statistic_str, f"$p = {p_str}$"]
+    if effect_str:
+        full_parts.append(effect_str)
+    full_report = ", ".join(full_parts)
+
+    # Determine test type label
+    test_type = _get_test_type_label(test_name, variant)
+
+    return FormattedStat(
+        test_type=test_type,
+        statistic=statistic_str,
+        p_value=p_str,
+        effect_size=effect_str,
+        stars=stars,
+        full_report=full_report,
+    )
+
+
+def _get_test_type_label(name: str, variant: str = "") -> str:
+    """Get human-readable test type label.
+
+    Args:
+        name: Test method name
+        variant: Test variant
+
+    Returns:
+        Human-readable label
+    """
+    labels = {
+        "t_test": "t-test",
+        "t-test": "t-test",
+        "ttest": "t-test",
+        "anova": "ANOVA",
+        "one_way_anova": "one-way ANOVA",
+        "two_way_anova": "two-way ANOVA",
+        "repeated_measures_anova": "repeated-measures ANOVA",
+        "chi_squared": "chi-squared test",
+        "chi2": "chi-squared test",
+        "fisher_exact": "Fisher's exact test",
+        "mann_whitney": "Mann-Whitney U test",
+        "wilcoxon": "Wilcoxon signed-rank test",
+        "kruskal_wallis": "Kruskal-Wallis test",
+        "friedman": "Friedman test",
+        "correlation": "correlation",
+        "pearson": "Pearson correlation",
+        "spearman": "Spearman correlation",
+        "regression": "regression",
+        "linear_regression": "linear regression",
+    }
+
+    base = labels.get(name.lower(), name)
+
+    if variant:
+        variant_labels = {
+            "independent": "independent-samples",
+            "paired": "paired-samples",
+            "one_sample": "one-sample",
+            "two_sample": "two-sample",
+            "welch": "Welch's",
+        }
+        variant_str = variant_labels.get(variant.lower(), variant)
+        return f"{variant_str} {base}"
+
+    return base
+
+
+def format_inline_stat(
+    statistic_name: str,
+    statistic_value: float,
+    p_value: float,
+    df: Optional[float] = None,
+    effect_name: Optional[str] = None,
+    effect_value: Optional[float] = None,
+    include_stars: bool = True,
+) -> str:
+    """Format a statistical result for inline reporting.
+
+    Args:
+        statistic_name: Name of test statistic (t, F, chi2, etc.)
+        statistic_value: Value of test statistic
+        p_value: P-value
+        df: Degrees of freedom
+        effect_name: Effect size name
+        effect_value: Effect size value
+        include_stars: Include significance stars
+
+    Returns:
+        LaTeX formatted inline report
+    """
+    parts = []
+
+    # Statistic
+    stat_str = format_statistic(statistic_name, statistic_value, df)
+    parts.append(stat_str)
+
+    # P-value
+    p_str = format_p_value(p_value)
+    parts.append(f"$p = {p_str}$")
+
+    # Effect size
+    if effect_name and effect_value is not None:
+        es_str = format_effect_size(effect_name, effect_value)
+        parts.append(es_str)
+
+    result = ", ".join(parts)
+
+    # Add stars
+    if include_stars:
+        stars = significance_stars(p_value)
+        if stars:
+            result += f" {stars}"
+
+    return result
+
+
+def format_stat_note(stats: List[FormattedStat]) -> str:
+    """Generate a table note explaining significance levels.
+
+    Args:
+        stats: List of formatted statistics
+
+    Returns:
+        LaTeX note string
+    """
+    has_stars = any(s.stars for s in stats)
+
+    if not has_stars:
+        return ""
+
+    # Check which levels are used
+    max_stars = max((len(s.stars) for s in stats if s.stars), default=0)
+
+    note_parts = []
+    if max_stars >= 1:
+        note_parts.append("$^{*}p < .05$")
+    if max_stars >= 2:
+        note_parts.append("$^{**}p < .01$")
+    if max_stars >= 3:
+        note_parts.append("$^{***}p < .001$")
+
+    if note_parts:
+        return "\\textit{Note.} " + ", ".join(note_parts) + "."
+
+    return ""
+
+
+def format_stats_paragraph(stats: List[FormattedStat]) -> str:
+    """Generate a results paragraph from formatted stats.
+
+    Args:
+        stats: List of formatted statistics
+
+    Returns:
+        LaTeX paragraph summarizing results
+    """
+    if not stats:
+        return ""
+
+    lines = []
+    for stat in stats:
+        line = f"The {stat.test_type} revealed {stat.full_report}."
+        lines.append(line)
+
+    return " ".join(lines)
+
+
+__all__ = [
+    "FormattedStat",
+    "format_stats_for_latex",
+    "format_inline_stat",
+    "format_stat_note",
+    "format_stats_paragraph",
+]
+
+# EOF