scitex 2.14.0__py3-none-any.whl → 2.15.3__py3-none-any.whl

scitex/template/_templates/module.py

@@ -0,0 +1,53 @@
+#!/usr/bin/env python3
+"""Standard Python module template."""
+
+TEMPLATE = {
+    "name": "Python Module",
+    "description": "Standard Python module with docstring, type hints, and exports",
+    "filename": "module.py",
+    "usage": """
+Usage:
+  from module import function_name
+""",
+    "content": '''#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: "{timestamp}"
+# File: {filepath}
+
+"""
+{docstring}
+"""
+
+from typing import Optional
+
+
+def function_name(arg1, kwarg1: Optional[str] = None):
+    """
+    Function description.
+
+    Parameters
+    ----------
+    arg1 : type
+        Description of arg1.
+    kwarg1 : str, optional
+        Description of kwarg1.
+
+    Returns
+    -------
+    type
+        Description of return value.
+
+    Examples
+    --------
+    >>> result = function_name(value)
+    """
+    pass
+
+
+__all__ = ["function_name"]
+
+# EOF
+''',
+}
+
+# EOF

scitex/template/_templates/plt.py

@@ -0,0 +1,202 @@
+#!/usr/bin/env python3
+# Timestamp: 2026-01-25
+# File: src/scitex/template/_templates/plt.py
+# ----------------------------------------
+
+"""Template for stx.plt plotting module usage."""
+
+TEMPLATE = {
+    "name": "Plotting Module",
+    "description": "stx.plt usage for publication-ready figures with automatic CSV export",
+    "filename": "plot_script.py",
+    "priority": 2,
+    "content": '''#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: {timestamp}
+# File: {filepath}
+
+"""
+stx.plt - Publication-Ready Plotting
+====================================
+
+stx.plt wraps matplotlib with:
+- Automatic CSV export when saving figures (reproducibility)
+- Pre-configured paper-quality styles
+- Enhanced axis methods (set_xyt, plot_line, etc.)
+- Color palettes (COLORS injection in @stx.session)
+
+Usage Patterns
+--------------
+1. Direct API: import scitex as stx; stx.plt.subplots()
+2. With @stx.session: plt is auto-injected with proper style
+3. CLI: scitex plt <recipe.yaml> (for FigRecipe specs)
+4. MCP: plt_plot, plt_compose, plt_reproduce tools
+"""
+
+import scitex as stx
+
+# ============================================================
+# Pattern 1: Direct API Usage
+# ============================================================
+
+# Basic figure creation
+fig, ax = stx.plt.subplots()
+x = [1, 2, 3, 4, 5]
+y = [2, 4, 1, 5, 3]
+ax.plot(x, y, label="Data")
+ax.set_xyt("X Axis", "Y Axis", "My Plot")  # Enhanced: xlabel, ylabel, title
+ax.legend()
+
+# Save with auto CSV export (creates plot.png + plot.csv)
+stx.io.save(fig, "plot.png")
+
+# ============================================================
+# Pattern 2: Multiple Subplots
+# ============================================================
+
+fig, axes = stx.plt.subplots(2, 2, figsize=(10, 8))
+
+# Flatten for easier iteration
+for idx, ax in enumerate(axes.flat):
+    ax.plot([1, 2, 3], [idx, idx*2, idx*3])
+    ax.set_xyt(f"X{{idx}}", f"Y{{idx}}", f"Panel {{idx}}")
+
+fig.tight_layout()
+stx.io.save(fig, "multipanel.png")
+
+# ============================================================
+# Pattern 3: With @stx.session (Recommended)
+# ============================================================
+
+@stx.session
+def main(
+    n_points=100,
+    CONFIG=stx.INJECTED,   # Session config
+    plt=stx.INJECTED,      # Pre-configured matplotlib
+    COLORS=stx.INJECTED,   # Color palette
+    rng=stx.INJECTED,      # Random generator
+    logger=stx.INJECTED,   # Logger
+):
+    """Example plotting with session management."""
+    import numpy as np
+
+    # Generate data
+    x = np.linspace(0, 10, n_points)
+    y1 = np.sin(x) + rng.normal(0, 0.1, n_points)
+    y2 = np.cos(x) + rng.normal(0, 0.1, n_points)
+
+    # Create figure using injected plt
+    fig, ax = plt.subplots()
+
+    # Use injected COLORS for consistent styling
+    ax.plot(x, y1, color=COLORS[0], label="sin(x)")
+    ax.plot(x, y2, color=COLORS[1], label="cos(x)")
+
+    # Enhanced axis methods
+    ax.set_xyt("Time (s)", "Amplitude", "Waveform Comparison")
+    ax.legend()
+
+    # Save to CONFIG.SDIR_OUT (auto CSV export)
+    stx.io.save(fig, CONFIG.SDIR_OUT / "waveforms.png")
+    logger.info(f"Saved figure to {{CONFIG.SDIR_OUT}}")
+
+    return 0
+
+# ============================================================
+# Pattern 4: Statistical Plots
+# ============================================================
+
+def statistical_plots():
+    """Common statistical visualization patterns."""
+    import numpy as np
+
+    fig, axes = stx.plt.subplots(1, 3, figsize=(12, 4))
+
+    # Box plot
+    data = [np.random.randn(100) + i for i in range(3)]
+    axes[0].boxplot(data)
+    axes[0].set_xyt("Group", "Value", "Box Plot")
+
+    # Histogram
+    axes[1].hist(np.random.randn(1000), bins=30, edgecolor='black')
+    axes[1].set_xyt("Value", "Count", "Histogram")
+
+    # Scatter with regression
+    x = np.random.randn(50)
+    y = 2*x + np.random.randn(50)*0.5
+    axes[2].scatter(x, y, alpha=0.6)
+    axes[2].set_xyt("X", "Y", "Scatter Plot")
+
+    fig.tight_layout()
+    stx.io.save(fig, "stats_plots.png")
+
+# ============================================================
+# Pattern 5: Heatmaps and Images
+# ============================================================
+
+def heatmap_example():
+    """Heatmap visualization pattern."""
+    import numpy as np
+
+    fig, ax = stx.plt.subplots()
+
+    # Create correlation matrix
+    data = np.random.randn(10, 10)
+    corr = np.corrcoef(data)
+
+    im = ax.imshow(corr, cmap='RdBu_r', vmin=-1, vmax=1)
+    ax.set_xyt("Feature", "Feature", "Correlation Matrix")
+    fig.colorbar(im, ax=ax, label="Correlation")
+
+    stx.io.save(fig, "heatmap.png")
+
+# ============================================================
+# Key Features Summary
+# ============================================================
+
+"""
+stx.plt Key Features:
+---------------------
+1. Enhanced Axis Methods:
+   - ax.set_xyt(xlabel, ylabel, title)  # All in one call
+   - ax.plot_line(x, y, **kwargs)       # With auto data tracking
+
+2. Auto CSV Export:
+   - stx.io.save(fig, "plot.png")       # Creates plot.png + plot.csv
+   - CSV contains all plotted data for reproducibility
+
+3. Pre-configured Styles:
+   - Publication-quality fonts and sizes
+   - Consistent color palettes
+   - Grid and tick configurations
+
+4. Color Palettes (via COLORS injection):
+   - COLORS[0], COLORS[1], ... for consistent styling
+   - Colorblind-friendly by default
+
+5. Figure Recipes (advanced):
+   - YAML specifications for reproducible figures
+   - CLI: scitex plt recipe.yaml -o output.png
+   - MCP: plt_plot, plt_compose, plt_reproduce
+
+CLI Commands:
+-------------
+scitex plt <recipe.yaml>         # Render from recipe
+scitex plt --help               # Show all options
+
+MCP Tools:
+----------
+plt_plot         # Create figure from specification
+plt_compose      # Combine multiple figures
+plt_reproduce    # Reproduce from saved recipe
+plt_crop         # Crop whitespace
+"""
+
+if __name__ == "__main__":
+    main()
+''',
+}
+
+__all__ = ["TEMPLATE"]
+
+# EOF

scitex/template/_templates/scholar.py

@@ -0,0 +1,267 @@
+#!/usr/bin/env python3
+# Timestamp: 2026-01-25
+# File: src/scitex/template/_templates/scholar.py
+# ----------------------------------------
+
+"""Template for stx.scholar literature management module usage."""
+
+TEMPLATE = {
+    "name": "Scholar Module",
+    "description": "stx.scholar usage for literature management, BibTeX enrichment, and PDF downloads",
+    "filename": "scholar_script.py",
+    "priority": 4,
+    "content": '''#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: {timestamp}
+# File: {filepath}
+
+"""
+stx.scholar - Literature Management
+===================================
+
+stx.scholar provides:
+- BibTeX enrichment (DOIs, abstracts, citations, impact factors)
+- PDF downloading with institutional access support
+- Paper search across multiple databases
+- Project-based paper organization
+- CrossRef local database (167M+ papers)
+
+Usage Patterns
+--------------
+1. CLI: scitex scholar <command> [options]
+2. MCP: scholar_* tools for Claude Code integration
+3. Python API: stx.scholar.* functions
+
+Typical Workflow
+----------------
+1. Create project: scitex scholar project create myresearch
+2. Add papers from BibTeX: scitex scholar add --bibtex refs.bib --project myresearch
+3. Enrich metadata: scitex scholar enrich --project myresearch
+4. Download PDFs: scitex scholar fetch --project myresearch
+5. Search for more: scitex scholar search "machine learning EEG"
+"""
+
+import scitex as stx
+
+# ============================================================
+# Pattern 1: CLI Usage (Recommended)
+# ============================================================
+
+"""
+CLI Commands:
+-------------
+
+# Project Management
+scitex scholar project create myresearch       # Create new project
+scitex scholar project list                    # List all projects
+
+# Add Papers
+scitex scholar add --bibtex refs.bib --project myresearch
+scitex scholar add --doi "10.1038/nature12373" --project myresearch
+
+# Enrich BibTeX (add DOIs, abstracts, citations)
+scitex scholar enrich --bibtex refs.bib --output enriched.bib
+scitex scholar enrich --project myresearch
+
+# Download PDFs
+scitex scholar fetch --project myresearch
+scitex scholar fetch --doi "10.1038/nature12373" --output ./pdfs/
+
+# Search Databases
+scitex scholar search "machine learning EEG" --limit 50
+scitex scholar search "CRISPR" --source crossref --year-min 2020
+
+# Check Library Status
+scitex scholar status --project myresearch
+"""
+
+# ============================================================
+# Pattern 2: CrossRef Local Search (167M+ papers)
+# ============================================================
+
+"""
+CrossRef Local Database:
+------------------------
+Fast full-text search across 167M+ academic papers.
+Supports FTS5 query syntax: AND, OR, NOT, "exact phrases"
+
+CLI:
+----
+scitex scholar crossref search "neural network AND hippocampus"
+scitex scholar crossref get 10.1038/nature12373
+scitex scholar crossref citations 10.1038/nature12373
+
+MCP Tools:
+----------
+crossref_search(query, limit)      # Search papers
+crossref_get(doi)                  # Get metadata by DOI
+crossref_citations(doi, direction) # Get citing/cited papers
+"""
+
+# ============================================================
+# Pattern 3: Paper Caching for Research Topics
+# ============================================================
+
+"""
+Paper Cache Workflow:
+---------------------
+Build reusable collections for specific research topics.
+
+# Create cache from search query
+scitex scholar cache create epilepsy "epilepsy seizure prediction" --limit 1000
+
+# Query cached papers
+scitex scholar cache query epilepsy --year-min 2020 --limit 50
+
+# Get top cited papers
+scitex scholar cache top-cited epilepsy --n 20
+
+# Export to formats
+scitex scholar cache export epilepsy --format bibtex --output refs.bib
+scitex scholar cache export epilepsy --format csv --output papers.csv
+"""
+
+# ============================================================
+# Pattern 4: Institutional Authentication
+# ============================================================
+
+"""
+Institutional Access (OpenAthens/Shibboleth):
+---------------------------------------------
+For downloading papers requiring institutional credentials.
+
+# Check authentication status
+scitex scholar auth status
+
+# Login via OpenAthens
+scitex scholar auth login --method openathens
+
+# Logout and clear session
+scitex scholar auth logout
+"""
+
+# ============================================================
+# Pattern 5: Python API Usage
+# ============================================================
+
+def python_api_example():
+    """Direct Python API usage."""
+    from scitex.scholar import (
+        search_papers,
+        enrich_bibtex,
+        download_pdf,
+        parse_bibtex,
+    )
+
+    # Search for papers
+    results = search_papers(
+        query="machine learning EEG",
+        search_mode="crossref",
+        limit=20
+    )
+
+    # Parse BibTeX file
+    papers = parse_bibtex("references.bib")
+
+    # Enrich with metadata
+    enrich_bibtex(
+        bibtex_path="references.bib",
+        output_path="enriched.bib",
+        add_abstracts=True,
+        add_citations=True,
+        add_impact_factors=True
+    )
+
+    # Download a specific PDF
+    download_pdf(
+        doi="10.1038/nature12373",
+        output_dir="./pdfs/"
+    )
+
+# ============================================================
+# Pattern 6: With @stx.session (Research Workflow)
+# ============================================================
+
+@stx.session
+def main(
+    topic="neural networks",
+    n_papers=50,
+    CONFIG=stx.INJECTED,
+    logger=stx.INJECTED,
+):
+    """Research literature workflow."""
+    from scitex.scholar import search_papers, enrich_bibtex
+
+    # 1. Search for papers
+    logger.info(f"Searching for papers on: {{topic}}")
+    results = search_papers(
+        query=topic,
+        search_mode="crossref",
+        limit=n_papers
+    )
+
+    # 2. Save search results
+    stx.io.save(results, CONFIG.SDIR_OUT / "search_results.json")
+
+    # 3. If BibTeX exists, enrich it
+    bibtex_path = CONFIG.SDIR_OUT / "references.bib"
+    if bibtex_path.exists():
+        enrich_bibtex(
+            bibtex_path=str(bibtex_path),
+            output_path=str(CONFIG.SDIR_OUT / "enriched.bib")
+        )
+        logger.info("BibTeX enriched with metadata")
+
+    logger.info(f"Found {{len(results)}} papers")
+    return 0
+
+# ============================================================
+# MCP Tools Reference
+# ============================================================
+
+"""
+MCP Tools for Claude Code:
+--------------------------
+
+Search & Discovery:
+- scholar_search_papers(query, limit, search_mode)
+- scholar_crossref_search(query, limit, year_min, year_max)
+- scholar_crossref_get(doi)
+- scholar_crossref_citations(doi, direction)
+
+Library Management:
+- scholar_create_project(project_name, description)
+- scholar_list_projects()
+- scholar_add_papers_to_project(project, dois, bibtex_path)
+- scholar_get_library_status(project)
+
+Enrichment & Download:
+- scholar_enrich_bibtex(bibtex_path, add_abstracts, add_citations)
+- scholar_fetch_papers(project, papers, async_mode)
+- scholar_download_pdf(doi, output_dir)
+
+BibTeX Operations:
+- scholar_parse_bibtex(bibtex_path)
+- scholar_resolve_dois(titles, bibtex_path)
+- scholar_export_papers(output_path, format)
+
+Authentication:
+- scholar_authenticate(method, institution)
+- scholar_check_auth_status(method)
+- scholar_logout(method)
+
+Cache Operations:
+- cache_create(name, query, limit)
+- cache_query(name, fields, year_min, year_max)
+- cache_top_cited(name, n)
+- cache_export(name, output_path, format)
+"""
+
+if __name__ == "__main__":
+    main()
+''',
+}
+
+__all__ = ["TEMPLATE"]
+
+# EOF

scitex/template/_templates/session.py

@@ -0,0 +1,130 @@
+#!/usr/bin/env python3
+"""Session script template - full @stx.session with all injections."""
+
+TEMPLATE = {
+    "name": "Session Script",
+    "description": "@stx.session decorated script with auto CLI, config injection, and output tracking",
+    "filename": "script.py",
+    "usage": """
+Usage:
+  python script.py                    # Run with defaults
+  python script.py --kwarg1 value     # Override parameter
+  python script.py --help             # Show auto-generated help
+
+Output Structure:
+  script_out/
+  ├── output.csv                      # stx.io.save() files go here (ROOT)
+  ├── figure.png
+  └── FINISHED_SUCCESS/<session_id>/  # Session metadata only
+""",
+    "content": '''#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: "{timestamp}"
+# File: {filepath}
+
+"""
+{docstring}
+
+Usage
+-----
+$ python {filename} --help           # Show auto-generated CLI help
+$ python {filename}                  # Run with default parameters
+$ python {filename} --kwarg1 value   # Override parameters
+
+Injected Global Variables
+-------------------------
+CONFIG : DotDict (access: CONFIG.key or CONFIG['key'])
+    Session configuration with paths and metadata.
+
+    Key Paths:
+    - CONFIG.ID        : Session ID (e.g., '2025Y-01M-20D-10h30m00s_XyZ1')
+    - CONFIG.FILE      : This script's absolute path
+    - CONFIG.SDIR_OUT  : Output ROOT directory ({filename_stem}_out/)
+                         USE THIS for stx.io.save() - files go here!
+    - CONFIG.SDIR_RUN  : Session run directory (inside RUNNING/ or FINISHED_*)
+                         Contains logs and CONFIG snapshots only
+    - CONFIG.PID       : Process ID
+    - CONFIG.ARGS      : Parsed CLI arguments as dict
+
+    YAML Config (from ./config/*.yaml):
+    - CONFIG.<FILENAME>.<key> : Values from config files
+
+plt : module
+    matplotlib.pyplot configured for session
+
+COLORS : DotDict
+    Color palette: COLORS.blue, COLORS.red, COLORS.green, etc.
+
+rng : RandomStateManager
+    Reproducible random number generator (seeded)
+
+logger : SciTeXLogger
+    Configured logger: logger.info(), logger.warning(), logger.error()
+
+Output Directory Structure
+--------------------------
+{filename_stem}_out/                    <- CONFIG.SDIR_OUT (save files here!)
+├── output.csv                          <- stx.io.save(df, "output.csv")
+├── figure.png                          <- stx.io.save(fig, "figure.png")
+├── figure.csv                          <- Auto-exported plot data
+└── FINISHED_SUCCESS/
+    └── <session_id>/                   <- CONFIG.SDIR_RUN (logs/configs)
+        ├── CONFIGS/
+        │   ├── CONFIG.pkl
+        │   └── CONFIG.yaml
+        └── logs/
+            ├── stdout.log
+            └── stderr.log
+"""
+
+import numpy as np
+import scitex as stx
+
+
+@stx.session
+def main(
+    # Uncomment and modify as needed:
+    # input_file,                  # Required argument -> CLI positional
+    # n_samples=100,               # Optional argument -> CLI --n-samples
+    # threshold=0.05,              # Optional argument -> CLI --threshold
+    # verbose=True,                # Optional argument -> CLI --verbose
+    CONFIG=stx.INJECTED,           # Auto-injected from ./config/*.yaml
+    plt=stx.INJECTED,              # Pre-configured matplotlib
+    COLORS=stx.INJECTED,           # Color palette
+    rng=stx.INJECTED,              # Random number generator
+    logger=stx.INJECTED,           # Session logger
+):
+    """
+    Script description shown in --help output.
+
+    This docstring becomes the CLI help message.
+    """
+    # Log session info
+    logger.info(f"Session ID: {{CONFIG.ID}}")
+    logger.info(f"Output dir: {{CONFIG.SDIR_OUT}}")  # Where files are saved
+
+    # Generate example data
+    x = np.linspace(0, 10, 100)
+    y = np.sin(x)
+
+    # Create figure
+    fig, ax = plt.subplots()
+    ax.plot_line(x, y, color=COLORS.blue, label="sin(x)")
+    ax.set_xyt("X", "Y", "Example Figure")
+    ax.legend_()
+
+    # Save outputs to CONFIG.SDIR_OUT (automatic)
+    stx.io.save(fig, "figure.png")       # -> {filename_stem}_out/figure.png
+    # stx.io.save(df, "results.csv")     # -> {filename_stem}_out/results.csv
+
+    return 0  # Return 0 for success
+
+
+if __name__ == "__main__":
+    main()
+
+# EOF
+''',
+}
+
+# EOF

scitex/template/_templates/session_minimal.py

@@ -0,0 +1,43 @@
+#!/usr/bin/env python3
+"""Minimal session script template."""
+
+TEMPLATE = {
+    "name": "Minimal Session Script",
+    "description": "Minimal @stx.session script with essential injections only",
+    "filename": "script.py",
+    "usage": """
+Usage:
+  python script.py
+  python script.py --help
+""",
+    "content": '''#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: "{timestamp}"
+# File: {filepath}
+
+"""
+{docstring}
+"""
+
+import scitex as stx
+
+
+@stx.session
+def main(
+    CONFIG=stx.INJECTED,
+    logger=stx.INJECTED,
+):
+    """Script description for --help."""
+    logger.info(f"Session: {{CONFIG.ID}}")
+    logger.info(f"Output: {{CONFIG.SDIR_OUT}}")
+    return 0
+
+
+if __name__ == "__main__":
+    main()
+
+# EOF
+''',
+}
+
+# EOF